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:

$
python3 --version   # must print 3.10+

Taking the CLI lane? You’ll also want jq (brew install jq) — the examples use it to pull IDs out of JSON.

1. Install

$
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 → Settings → API → Create new key. It’s shown once — copy it.

Then log in once:

$
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.

3. Generate audio

1
import time, httpx
2
from onepin import OnepinClient
3
4
client = OnepinClient()   # uses the key from `onepin login`
5
6
wf = client.templates.clone("47d41a1e-18dd-480b-b1a4-e4a942c04ec9", name="My first workflow").data.id
7
8
run = client.workflows.runs.start(
9
    wf,
10
    script_text="Hello world!",
11
    source_language="en-us",
12
).data.id
13
14
while (s := client.workflows.runs.status(wf, run).data).status not in ("completed", "failed", "cancelled"):
15
    print(s.status); time.sleep(3)
16
17
dl = client.workflows.download_run(wf, run).data
18
open(dl.filename, "wb").write(httpx.get(dl.url).content)
19
print("saved:", dl.filename)

4. Listen

$
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 — start, watch, and download, in Python or the CLI
• Workflow — the node graph you just edited: node types, voice_map, export formats
• Authentication — creating a key, logging in, and scopes
• CLI reference — everything scriptable from the terminal