Authentication
How to create an API key, which header to send it in, and what scopes control.
There are two kinds of key and they are not interchangeable. An ACCOUNT key (svx_…) is what almost everything below uses. A PLATFORM key (sv_pk_…) is workspace-bound and only the image and video endpoints accept it. If you get a 401 saying the wrong key type was supplied, that is which one you have.
Authentication
Create an account key at Settings → API Keys. It is displayed once at creation and stored only as a hash, so copy it then — if you lose it, revoke it and mint another. Pick the narrowest scopes that cover what you are building; you can hold several keys with different scopes. API access requires a plan that includes it: on Free and Starter the Create button refuses outright, so there is no key to test with until you upgrade. A key minted on a paid plan and then downgraded keeps authenticating, but every call comes back 403 plan_limit_exceeded.
Create a key in Settings → API Keys. It is shown once, so copy it then. Every example below reads it from $SONICVOX_API_KEY.
Endpoints
Confirm a key works and see exactly what it can do — plan, credit balance, rate limit, daily allowance, and the live TTS price formula. Requires no scope, so it is the right first call after minting a key.
- Credits
- 0
# The recommended header
curl https://staging.sonicvox.ai/api/v1/account/api-limits \
-H "sv-api-key: $SONICVOX_API_KEY"
# Equivalent — all three forms are accepted
curl https://staging.sonicvox.ai/api/v1/account/api-limits \
-H "x-api-key: $SONICVOX_API_KEY"
curl https://staging.sonicvox.ai/api/v1/account/api-limits \
-H "Authorization: Bearer $SONICVOX_API_KEY"{
"plan": { "type": "scale", "name": "Professional", "api_access": true },
"credits": { "remaining": 500000, "monthly_allocation": 1850000 },
"limits": {
"rate_limit_per_minute": 100,
"daily_request_limit": 10000,
"daily_requests_used": 0,
"daily_requests_remaining": 10000,
"max_keys_per_account": 5
}
}When it fails
Every error carries type, code, message, request_id and a doc_url. Branch on type for retry policy.
| missing_api_key | No key on the request. Check the header name — a body field or query parameter will not work. |
| invalid_api_key | The key is malformed, unknown, or has been revoked. Revoked keys fail immediately and cost nothing. |
| insufficient_scope | The key is valid but lacks the scope this endpoint needs. The message names the scope required and lists what your key holds. |
| plan_limit_exceeded | The plan does not include API access. Upgrade, or use a key from an account that does. |