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

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)

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