> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://onepin.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://onepin.ai/docs/_mcp/server.

# Quickstart

Generate your first audio: clone the starter template, give it a script and a voice, run it, download the result. Pick your lane — Python or CLI.

## 0. Prerequisites

**Python 3.10 or later** — check before anything else:

```bash
python3 --version   # must print 3.10+
```

Taking the CLI lane? You'll also want [`jq`](https://jqlang.org) (`brew install jq`) — the examples use it to pull IDs out of JSON.

> **Warning**
>
> On Python 3.9 or older, `pip install onepin` fails with a misleading `No matching distribution found for onepin` — that error means your Python is too old, not that the package is missing.

## 1. Install

```bash
pip install onepin
```

One install gives you both the `onepin` Python SDK and the `onepin` CLI. Prefer uv? `uv add onepin`. Pin a version with `pip install "onepin==0.9.0"`.

## 2. Authenticate

Create an API key: [app.onepin.ai](https://app.onepin.ai) → **Settings → API → Create new key**. It's shown once — copy it.

![Creating an API key at app.onepin.ai — Settings → API → Create new key](/docs/_fern-files/podonos.docs.buildwithfern.com/833d2377711d51ae0661e2b3397f6f4a79d33a7b936bc488ec0eadf3209927dd/docs/assets/onepin_api_key.gif)

Then log in once:

```bash
onepin login   # paste the key when prompted
```

Both the CLI and the Python SDK read the stored key automatically — nothing else to set up. For other ways to supply the key, see [Authentication](/docs/get-started/authentication).

## 3. Generate audio

#### Python

Clone the starter template (it ships with a voice), run it with your script, download the audio:

```python
import time, httpx
from onepin import OnepinClient

client = OnepinClient()   # uses the key from `onepin login`

wf = client.templates.clone("47d41a1e-18dd-480b-b1a4-e4a942c04ec9", name="My first workflow").data.id

run = client.workflows.runs.start(
    wf,
    script_text="Hello world!",
    source_language="en-us",
).data.id

while (s := client.workflows.runs.status(wf, run).data).status not in ("completed", "failed", "cancelled", "paused"):
    print(s.status); time.sleep(3)

if s.status != "completed":
    raise SystemExit(f"run ended as {s.status}")

dl = client.workflows.download_run(wf, run).data
open(dl.filename, "wb").write(httpx.get(dl.url).content)
print("saved:", dl.filename)
```

The starter speaks English. To use another language or voice, see [Workflow](/docs/workflow/overview). A run can also park in `paused` — see [Runs can pause](/docs/guides/run-a-workflow#runs-can-pause).

#### CLI

Clone the starter template (it ships with a voice), run it with your script, download the audio:

```bash
WF=$(onepin templates clone 47d41a1e-18dd-480b-b1a4-e4a942c04ec9 --name "My first workflow" --json | jq -r '.id')

RUN=$(onepin workflows run "$WF" --script "Hello world!" --source-language en-us --watch --json | jq -r '.id')

onepin workflows runs download "$WF" "$RUN" --out first-audio.zip
```

The starter speaks English. To use another language or voice, see the [CLI reference](/docs/reference/cli-reference) and [Voices & Models](/docs/get-started/voices-models).

## 4. Listen

```bash
unzip My-first-workflow_*.zip   # or first-audio.zip
# sink_preview_1/en-us/..._line_000.mp3   ← your audio, one file per script line
# manifest.csv                            ← index of the generated files
```

**You just shipped your first audio.** 🎧

## Next steps

* [Run a workflow](/docs/guides/run-a-workflow) — start, watch, and download, in Python or the CLI
* [Workflow](/docs/workflow/overview) — the node graph you just edited: node types, `voice_map`, export formats
* [Authentication](/docs/get-started/authentication) — creating a key, logging in, and scopes
* [CLI reference](/docs/reference/cli-reference) — everything scriptable from the terminal
* [MCP server](/docs/get-started/mcp-server) — do all of this from Claude or Cursor instead, in natural language
* [Agent skill](/docs/get-started/agent-skill) — or `onepin skill install`, and your coding tool drives the CLI for you