The VoiceLabs API

Five operations

Generation is asynchronous because it is GPU work: POST /v1/speech returns a generation id straight away, and polling GET /v1/generations/{id} yields an audio_url once it completes. That URL is signed and short-lived — about fifteen minutes, scoped to that one generation — so it can be handed directly to a media player, and re-polling mints a fresh one rather than reviving an expired link. Transcription, by contrast, returns its transcript on the same response.

An API key in a header

curl https://app.voicelabs.now/v1/voices \
  -H "x-api-key: vl_sandbox_your_key_here"

Send your key in x-api-key, or as Authorization: Bearer if your HTTP client only speaks bearer auth. The public API never accepts a browser session cookie — it is credential-authenticated only, which is what lets it serve a permissive CORS policy safely.

Keys are created in the developer console, on the API keys tab of your account:

# 1. Sign in at https://app.voicelabs.now/connections and open the "API keys" tab
# 2. Create a key, tick the scopes it needs, and copy the secret
#
# The secret is shown ONCE, at creation. VoiceLabs stores a SHA-256 hash of it and
# keeps only the leading characters in plain text, so a lost key is replaced, not
# recovered. Revoking a key takes effect on its very next request.

export VOICELABS_API_KEY="vl_sandbox_…"

You choose a key's scopes when you create it, and a key can do exactly what its scopes allow — nothing wider. A key without voice:generate is answered with 403 insufficient_scope on the two generation endpoints and cannot spend your allowance, which makes a read-only key safe to hand to something you would rather not trust with your quota.

An API key is one of two credentials this API accepts. The other is an OAuth 2.1 access token, for software acting on behalf of other people's VoiceLabs accounts rather than your own. It is the same authorization server the VoiceLabs MCP server uses — authorization code with PKCE and dynamic client registration — and the reference documents its endpoints under the oauth2 scheme. Both carry the same scopes and are gated by the same check.

voice:read

Read your voices, profiles, and past generations.

voice:generate

Generate speech and transcribe audio on your behalf.

Rate limits and what your plan covers

Two different budgets apply, and they are worth keeping apart. The first is a request rate: 600 requests per hour per key. Responses to an API-key request carry the IETF draft-11 RateLimit and RateLimit-Policy headers, so a client can see its remaining budget without guessing, and exceeding it returns 429 rate_limit_exceeded with a Retry-After. The headers describe a KEY'S budget, so they are absent when you authenticate with an OAuth 2.1 access token — there is no per-key counter to report.

The second is your plan's audio allowance, metered server-side in minutes of generated audio. Reading is free: listing voices, captures, and generations never draws on it. Signed-in accounts that are not subscribed get a small allowance of free generations each month — the exact figure is shown in the app — and past it, generating needs an active trial or subscription. VoiceLabs Pro is the only paid plan, and it is a flat subscription: no per-character fee, no per-generation fee, no metered overage.

The two failures are told apart on purpose. An exhausted allowance is 429 quota_exhausted, which resolves itself next period or with an upgrade; a plan that never included the capability is 403 feature_not_enabled, which only an upgrade resolves. Both carry a settings_url pointing at where to fix it.

RFC 9457 problem documents

Every error is application/problem+json with a stable code to branch on. Branch on code, not on status or on the prose in detail: several problems share a status, and detail is written for humans and may be reworded.

{
  "type": "https://voicelabs.now/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This credential does not carry the voice:generate scope.",
  "instance": "/v1/speech",
  "code": "insufficient_scope",
  "required_scope": "voice:generate"
}

Writes accept an Idempotency-Key header. Replaying the same key with the same body returns the original response byte-for-byte instead of generating a second time — so a retry after a dropped connection cannot cost you twice.

The contract, in machine form

The interactive reference and the raw document at https://app.voicelabs.now/openapi.json are generated from the very schemas the handlers validate against — not written alongside them. A change to a handler's contract that is not reflected in the document fails our build, so the reference describes the running API rather than an account of it. Point an SDK generator or an API client at that URL directly.

Prefer to let an agent do the work? VoiceLabs also runs a remote MCP server exposing the same five capabilities as tools, so Claude and other MCP clients can use your voice studio directly.