API keys
- Create keys on the signed-in Developers page: soundhalo.com/app/#/developers (Spanish: /es/app/#/developers).
- A key is
sh_live_followed by 40 letters and digits. Staging keys start withsh_test_and only work onapi-staging.soundhalo.com. - The full key is shown once, when you create it. SoundHalo stores only a hash (a one-way fingerprint), so it cannot show the key again. The page keeps the first 12 characters so you can tell keys apart, plus when each was last used.
- You can have up to 10 active keys. Revoking a key stops it at once, on the next request.
Sending the key
curl https://api.soundhalo.com/v1/usage/processing \
-H "Authorization: Bearer sh_live_..." The voice list (GET /v1/generate/speech/voices) and the OpenAPI document (GET /v1/openapi.json) need no key.
A key acts as your account
There is no separate API plan. A request with your key is treated like you using the website tools while signed in:
- the same plan dubbing minutes and included lip-sync minutes,
- the same prepaid balance (shown in dollars, counted in micro-dollars),
- the same monthly cost cap and daily limits,
- the same per-file and per-request limits.
So a dub made through the API and a dub made on the website take minutes from the same pool. See Limits and pricing.
What a key cannot do
A key cannot manage access or spend money on its own. These return 403 FORBIDDEN and are done on the signed-in page instead:
- create or revoke API keys,
- add, change or test webhooks,
- approve MCP sign-ins or disconnect connected apps,
- start a payment (subscriptions and balance top-ups).
Reading your plan with GET /v1/me/billing/status works with a key. If a key leaks, the person who has it cannot make more keys, send your events somewhere else or buy anything. They can still use your minutes and balance through normal calls, so revoke a leaked key right away.
{
"request_id": "req_...",
"error": {
"code": "FORBIDDEN",
"message": "Manage API keys, webhooks and payments from your signed-in account page at soundhalo.com/app.",
...
}
} Asset and job tokens
Besides your key, files and jobs have their own tokens:
- Asset token (
atok_...): every uploaded or created file has anasset_idand anasset_token. Pass both asasset_refwhen a request uses the file. Send the token in thex-asset-tokenheader to read, download or delete the file. - Job token (
jtok_...): an async job returns ajob_token. Send it in thex-job-tokenheader to check or cancel the job.
Anyone with an asset token can download that file, so treat tokens like passwords. File access ends 30 days after the file was created (longer on paid plans, up to a year). Delete a file sooner with DELETE /v1/assets/:id.
Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | AUTH_REQUIRED | "Invalid or revoked API key", on any endpoint. Or no key on an endpoint that needs an account. |
| 403 | FORBIDDEN | The call is only allowed on the signed-in page (see above). |
| 403 | ASSET_TOKEN_INVALID | The asset token does not match the file, or the file's access has ended. |
| 503 | INTERNAL_ERROR | Keys could not be checked for a moment. Try again after Retry-After seconds if it is sent. |
A wrong key is always refused; it never falls back to anonymous use. With no key at all, some endpoints still answer as an anonymous user with small shared limits, and endpoints that need an account (dubbing, voices, lip-sync) answer 401.
Keeping keys safe
- Use keys only on a server or your own machine. Never put a key in browser code, a mobile app or a public repository.
- Use one key per app or server, with a clear name, so you can revoke one without breaking the others.
- Store keys in environment variables or a secrets manager.
- For AI apps such as ChatGPT or Claude.ai, use the MCP server's OAuth sign-in instead of pasting a key. See MCP server.