Onepin is a voice workflow platform that orchestrates, validates, and ships production-ready audio across 100+ TTS models. This is the official Python SDK + CLI for Onepin.
TTS turns text into speech. Onepin runs the production around it: plan the line, pick the model, generate, score, retry, ship.
- Orchestrate voice workflows as graphs — sources, generators, validators, destinations — from Python or the CLI.
- Validate every line. Word accuracy and naturalness are scored against your thresholds, with automatic retries on a miss.
- Reach 100+ TTS models through one definition: ElevenLabs, Cartesia, Google, Naver, and more, with no per-vendor rewrite.
- Ship publish-ready voice. Pull a full-run export or a single node's output straight from a run.
- Drive it from your agent. The bundled Agent Skill runs Onepin from Claude Code, Cursor, Codex, Gemini, and Copilot.
pip install onepinInstalls both the onepin Python SDK and the onepin command-line tool.
Full documentation: onepin.ai/docs
Mint an API key at app.onepin.ai/settings/api-keys, then:
onepin login
# Paste your key when prompted — validated, then saved to ~/.onepin/credentials (mode 0600)
onepin whoami # Show the active auth source, workspace UUID, and key scopes
onepin logout # Remove stored credentialsCredential resolution order: --api-key flag → ONEPIN_API_KEY env var → stored ~/.onepin/credentials.
Onepin ships an Agent Skill that teaches AI coding tools to drive the
onepin CLI for you — list and run workflows, check run status, browse voices and templates —
without leaving your editor. It works in Claude Code, Cursor, OpenAI Codex, Gemini CLI, and GitHub
Copilot. Install it with the CLI (it auto-detects which tools you have):
onepin skill install # every detected tool
onepin skill install --tool claude --tool cursor # or pick tools explicitly
onepin skill install --all # every supported tool
onepin skill install --project # into ./ (this repo) instead of your home dir
onepin skill path # show where it is / would be installed
onepin skill uninstall # remove itIn Claude Code the skill is then invocable as /onepin; other tools load it automatically when
your request is about Onepin. After the first install, restart your tool (or run /reload-plugins
in Claude Code) so it picks up the new skills directory. The skill drives the same onepin CLI, so
run onepin login first.
The Onepin API advertises the minimum SDK version it still accepts. When a response indicates your
installed onepin is below that floor, the SDK stops with a clear, copy-paste upgrade message:
onepin 0.4.1 is below the required minimum 0.5.0. Upgrade: pip install --upgrade 'onepin>=0.5.0'
The onepin CLI enforces this automatically. For programmatic use, build the client with
onepin.make_client (instead of OnePinClient directly) to get the same gate plus a corrected
User-Agent:
import onepin
client = onepin.make_client(token="op_live_...")
client.workflows.list() # raises onepin.OnePinUpgradeRequiredError if the SDK is too oldThe CLI also nudges you when a newer release is available on PyPI (surfaced through the Onepin agent
skill). Set ONEPIN_NO_UPDATE_CHECK=1 to silence the recommended-upgrade check.
The CLI groups its commands by resource. Every group prints its own command list with
onepin <group> --help, and each command lists its flags with onepin <group> <command> --help.
The examples further below are representative; the authoritative, exhaustive inventory is
generated from the live command tree (the same source as onepin schema) and kept in sync by CI:
onepin health live— Liveness probe.onepin health ready— Readiness probe.
onepin login— Validate an API key and write it to ~/.onepin/credentials.
onepin logout— Remove ~/.onepin/credentials.
onepin nodes list— List available node types.onepin nodes show <node_type>— Show a node type's detail (runtime options).
onepin provider-keys delete <provider>— Delete a provider key.onepin provider-keys list— List configured provider keys.onepin provider-keys put <provider>— Create or replace a provider key.
onepin schema— Emit the machine-readable JSON manifest of all commands.
onepin skill install— Install the Onepin agent skill (Claude Code, Cursor, Codex, Gemini, Copilot).onepin skill path— Show where the skill is or would be installed.onepin skill uninstall— Remove the installed Onepin agent skill.
onepin templates clone <template_id>— Clone a template into a new workflow.onepin templates create— Create a template.onepin templates delete <template_id>— Delete a template.onepin templates favorite <template_id>— Favorite a template.onepin templates list— List gallery templates.onepin templates show <template_id>— Show a single template.onepin templates unfavorite <template_id>— Unfavorite a template.onepin templates update <template_id>— Update a template.
onepin uploads confirm <upload_id>— Confirm an upload and attach it to a workflow.onepin uploads create— Upload a file via the presigned-S3 flow.onepin uploads delete <upload_id>— Delete an upload.
onepin usage activity— Recent workspace activity.onepin usage by-language— Usage broken down by language.onepin usage summary— Usage summary.
onepin voices favorite <voice_id>— Favorite a voice.onepin voices list— List available voices.onepin voices show <voice_id>— Show a single voice.onepin voices similar <voice_id>— List voices similar to a voice.onepin voices unfavorite <voice_id>— Unfavorite a voice.
onepin whoami— Show active auth source + workspace UUID + scopes.
onepin workflows create— Create a workflow.onepin workflows definition-schema— Print the JSON Schema for a workflow definition.onepin workflows delete <workflow_id>— Delete a workflow.onepin workflows duplicate <workflow_id>— Duplicate a workflow.onepin workflows list— List workflows in the workspace.onepin workflows preview-run <workflow_id>— Estimate cost of a run without executing.onepin workflows run <workflow_id>— Start a workflow run, optionally watching to completion.onepin workflows show <workflow_id>— Show a single workflow.onepin workflows update <workflow_id>— Update a workflow (partial patch).onepin workflows uploads <workflow_id>— List a workflow's uploads.
onepin workflows runs cancel <workflow_id> <run_id>— Cancel a running run.onepin workflows runs data <workflow_id> <run_id>— Show a run's output data.onepin workflows runs download <workflow_id> <run_id>— Download a run's full export to a file.onepin workflows runs download-node <workflow_id> <run_id> <node_id>— Download a single node's output to a file.onepin workflows runs list <workflow_id>— List runs for a workflow.onepin workflows runs overview <workflow_id> <run_id>— Show a run's node overview.onepin workflows runs show <workflow_id> <run_id>— Show a single run.onepin workflows runs status <workflow_id> <run_id>— Show a run's current status.onepin workflows runs steps <workflow_id> <run_id>— List the steps of a run.onepin workflows runs summary <workflow_id>— Summarize a workflow's runs.
onepin workspace create— Create a workspace.onepin workspace delete <workspace_id>— Delete a workspace.onepin workspace list— List workspaces.onepin workspace settings <ws_id>— Show a workspace's settings.onepin workspace show <workspace_id>— Show a workspace.onepin workspace update <workspace_id>— Update a workspace.
onepin workspace members accept <token>— Accept an invite by token.onepin workspace members invite <ws_id>— Invite a member.onepin workspace members invite-role <ws_id> <invite_id>— Change a pending invite's role.onepin workspace members list <ws_id>— List workspace members.onepin workspace members remove <ws_id> <member_id>— Remove a member.onepin workspace members revoke-invite <ws_id> <invite_id>— Revoke a pending invite.onepin workspace members set-role <ws_id> <member_id>— Change a member's role.
onepin workspace stats runs— Workspace run statistics.onepin workspace stats workflows— Workspace workflow statistics.
These apply to every command (pass them before the subcommand):
--api-key TEXT API key for this invocation (env: ONEPIN_API_KEY)
--base-url TEXT Override the API base URL (env: ONEPIN_BASE_URL)
--workspace TEXT Workspace UUID to scope requests to (env: ONEPIN_WORKSPACE_ID)
--json Emit machine-readable JSON to stdout instead of rich tables
--no-color Disable ANSI coloring
-v, --verbose Log HTTP requests/responses to stderr (auth/login flow only)
--debug Verbose logging; implies --verbose (auth/login flow only)
--version Show version and exit
--verbose/--debug only affect HTTP logging on the authentication path; they do not change
command output. Use --json for machine-consumable data on any command.
onepin login
onepin whoami
onepin logoutonepin workflows list --status running --sort updated_at --order desc
onepin workflows show <workflow_id>
onepin workflows create --name "My workflow" --definition @workflow.json
onepin workflows update <workflow_id> --name "Renamed"
onepin workflows duplicate <workflow_id>
onepin workflows preview-run <workflow_id> # estimate cost without executing
onepin workflows run <workflow_id> --watch # poll to a terminal state
onepin workflows definition-schema # JSON Schema for a definition
onepin workflows delete <workflow_id> --yesSee onepin workflows --help for the full list.
onepin workflows runs list <workflow_id>
onepin workflows runs show <workflow_id> <run_id>
onepin workflows runs status <workflow_id> <run_id>
onepin workflows runs steps <workflow_id> <run_id>
onepin workflows runs overview <workflow_id> <run_id>
onepin workflows runs data <workflow_id> <run_id>
onepin workflows runs summary <workflow_id>
onepin workflows runs cancel <workflow_id> <run_id> --yes
onepin workflows runs download <workflow_id> <run_id> --out export.zip
onepin workflows runs download-node <workflow_id> <run_id> <node_id> --out node.wavSee onepin workflows runs --help for the full list.
onepin templates list --category media --sort popular
onepin templates show <template_id>
onepin templates clone <template_id> --name "My copy"
onepin templates create --name "Starter" --definition @template.json
onepin templates favorite <template_id>See onepin templates --help for the full list (update, delete, unfavorite).
onepin voices list --provider elevenlabs --gender female --language en-us
onepin voices show <voice_id>
onepin voices similar <voice_id>
onepin voices favorite <voice_id>See onepin voices --help for the full list.
onepin uploads create --file script.txt --category script # upload + presign in one step
onepin uploads confirm <upload_id> --workflow-id <workflow_id>
onepin uploads delete <upload_id> --yesSee onepin uploads --help for the full list.
onepin workspace list
onepin workspace show <workspace_id>
onepin workspace create --name "Team"
onepin workspace update <workspace_id> --name "Renamed"
onepin workspace settings <ws_id>
onepin workspace delete <workspace_id> --yesSee onepin workspace --help for the full list.
onepin workspace members list <ws_id>
onepin workspace members invite <ws_id> --email user@example.com --role editor
onepin workspace members set-role <ws_id> <member_id> --role admin
onepin workspace members remove <ws_id> <member_id> --yes
onepin workspace members accept <token>See onepin workspace members --help for the full list (invite-role, revoke-invite).
onepin workspace stats runs --from 2026-01-01 --to 2026-02-01
onepin workspace stats workflowsonepin usage summary --range 30d
onepin usage activity --type workflow_run --limit 50
onepin usage by-language --range 90dSee onepin usage --help for the full list.
onepin provider-keys list
onepin provider-keys put <provider> --key '{"api_key": "..."}'
onepin provider-keys delete <provider> --yesStored credentials are never echoed back; reads return redacted metadata only.
onepin nodes list
onepin nodes show <node_type>onepin health live
onepin health readyonepin schema --jsonThe CLI is designed to be driven programmatically.
onepin schema --jsonschema emits a stable, machine-readable JSON manifest of every command: each entry has a
path array (the full subcommand chain, e.g. ["workflows", "runs", "download"]), its
positional args, its options (flag, type, required, default, help), and a destructive
flag. Build tooling against this manifest rather than scraping --help.
Pass --json to any command to get raw data on stdout. When --json is set, a failure
writes a structured error envelope to stderr instead of the default [CODE] message line:
{"error": {"code": "not_found", "message": "Workflow not found"}}Exit codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | API or runtime error |
| 2 | Usage error (bad flags/arguments) |
| 130 | Interrupted (SIGINT) |
# 1. Discover the available node types
onepin nodes list
# 2. Inspect the ports/options of a node type
onepin nodes show <node_type>
# 3. Get the JSON Schema a definition must satisfy ...
onepin workflows definition-schema
# ... or copy a known-good `.definition` from an existing template or workflow:
onepin templates show <template_id> --json
onepin workflows show <workflow_id> --json
# 4. Assemble your definition JSON into a file, then create the workflow
onepin workflows create --name "My workflow" --definition @workflow.json--definition accepts inline JSON or @path/to/file.json. The same flag is available on
workflows update, templates create, and templates update.
The Python SDK is generated by Fern from the OpenAPI spec.
Full per-endpoint reference: src/onepin/reference.md ·
hosted docs at onepin.ai/docs. Runnable scripts in examples/.
from onepin import OnePinClient
client = OnePinClient(token="op_...") # your API key, used as the bearer token
workflows = client.workflows.list() # paginated — iterate items directly
voices = client.voices.list()
ready = client.health.readiness()from onepin import OnePinClient
from onepin.environment import OnePinClientEnvironment
# Defaults to PROD (https://api.onepin.ai). Target the dev API instead:
client = OnePinClient(token="op_...", environment=OnePinClientEnvironment.DEV)
# ...or point at any host directly:
client = OnePinClient(token="op_...", base_url="https://dev-api.onepin.ai")import asyncio
from onepin import AsyncOnePinClient
client = AsyncOnePinClient(token="op_...")
async def main() -> None:
voices = await client.voices.list()
asyncio.run(main())from onepin import OnePinClient
from onepin.core.api_error import ApiError
client = OnePinClient(token="op_...", timeout=20.0) # client-wide timeout (default 60s)
try:
client.workflows.get(
workflow_id="wf_123",
request_options={"max_retries": 1, "timeout_in_seconds": 5},
)
except ApiError as e:
print(e.status_code, e.body)src/onepin/— Fern-generated SDK (do not hand-edit; overwritten on each regen)src/onepin/_cli/— hand-rolled Typer CLI atop the generated clientsrc/onepin/reference.md— full per-endpoint API referenceexamples/— runnable SDK snippetsscripts/post_fern.sh— restorespy.typedmarkers after Fern overwritessrc/onepin/
Onepin is a voice workflow platform: the agent layer for AI voice. It plans each line, picks a TTS model, generates the audio, validates it for accuracy and naturalness, retries on a miss, and ships the result. This package is the official Python SDK and onepin CLI for that platform.
Over 100, across providers including ElevenLabs, Cartesia, Google, and Naver. You target them through one workflow definition, so switching a model is a field change, not a rewrite.
Yes. Both are first-class providers, alongside Google, Naver, and others. List what's available with onepin voices list --provider elevenlabs (swap in any provider).
A TTS API returns whatever it generates. Onepin gates the result. You set accuracy and naturalness thresholds, the pipeline scores each line and retries the ones that miss, and only lines that clear the bar ship — across 100+ models behind one interface instead of a separate integration per vendor.
Yes. Mint an API key at app.onepin.ai/settings/api-keys, then run onepin login. See Authentication.
Yes. onepin skill install adds an Agent Skill that drives the CLI from Claude Code, Cursor, Codex, Gemini CLI, and GitHub Copilot. See Use from your AI coding tool.
MIT — see LICENSE.
Published on PyPI — latest: v0.6.0. See the changelog.