What the API does
- Dubbing: send a recording or video, get it back in another language. It stops at a quote, and nothing is spoken or paid until you confirm. Dubbing guide.
- Transcription: speech to text with timestamps, right away or as a job you check later.
- Caption translation: translate timed lines and keep their times and order.
- Text to speech: 92 voices in 26 languages, MP3 or WAV.
- Voice-over and mix: turn timed lines into one voice track, then lay it over a video or recording.
- Voice cloning: your own voice, after a recorded consent sentence. Lip-sync: match a speaker's mouth to new audio.
- Webhooks: signed events when a job finishes or a dub is ready to confirm. Webhooks.
- MCP server: connect Claude, ChatGPT or another AI app so it can dub and voice files for you. MCP (Model Context Protocol) is the standard way AI apps call outside tools. MCP setup.
Basics
| Base URL | https://api.soundhalo.com |
|---|---|
| Staging | https://api-staging.soundhalo.com, with its own sh_test_ keys. Staging calls real providers too. |
| Auth | Authorization: Bearer sh_live_.... See Authentication. |
| Format | JSON in, JSON out. File uploads use multipart/form-data. |
| Money | Amounts are micro-dollars: 1,000,000 = $1, so 250000 is $0.25. |
| OpenAPI | GET /v1/openapi.json (OpenAPI 3.1, for code generators and API tools) |
Every answer uses the same envelope. Successful calls look like { request_id, status, operation, result, job, receipt, warnings }. Errors look like { request_id, error: { code, message, details, retryable } }, and a 429 or 503 also sends a Retry-After header with the seconds to wait.
Quick start
1. Create a key
Sign in and open soundhalo.com/app/#/developers. Name the key and copy it. It is shown once. Keep it on your server, never in a web page or app that other people can open.
export SOUNDHALO_API_KEY="sh_live_..." 2. Check what you have left
curl https://api.soundhalo.com/v1/usage/processing \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" The result shows your plan, dubbing.remaining_seconds this month, today's allowances (speech, synthesis, clone, transform), monthly.remaining_percent of your monthly cost cap and your prepaid balance in credits.balance_micros. Reading it costs nothing.
3. Turn text into speech
Pick a voice from GET /v1/generate/speech/voices (no key needed), then:
curl https://api.soundhalo.com/v1/generate/speech \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"text":"Welcome to SoundHalo. This short recording tests the dubbing API. Each line should come back in Spanish, spoken by a new voice."},"options":{"voice":"en-US-michael","format":"mp3"}}' {
"request_id": "req_REDACTED",
"status": "completed",
"operation": "generate.speech",
"result": {
"output_asset": {
"asset_id": "ast_6e64b0faaeaf86bbbce16fc2fe6fdea5",
"asset_token": "atok_REDACTED",
"mime_type": "audio/mpeg",
"size_bytes": 107543,
"duration_sec": 8.874,
"download_url": "https://api.soundhalo.com/v1/assets/ast_6e64b0faaeaf86bbbce16fc2fe6fdea5/download"
},
"characters": 127,
"format": "mp3",
"synthetic": true,
"voice": {
"id": "en-US-michael",
"name": "Michael",
"language": "en-US"
}
},
"job": null,
"receipt": null,
"warnings": []
} This used 127 of today's text to speech characters. It never uses your balance. Download the file with its asset token:
curl -o speech.mp3 \
-H "x-asset-token: atok_REDACTED" \
https://api.soundhalo.com/v1/assets/ast_6e64b0faaeaf86bbbce16fc2fe6fdea5/download Your first dub
A dub has two halves. First SoundHalo transcribes and translates your file and gives you a quote. Then you confirm the quote, and only then is anything spoken or paid from your balance.
1. Upload the file
curl https://api.soundhalo.com/v1/assets \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-F "file=@interview.mp3" Keep result.asset_ref (an asset_id and an asset_token). Uploads count toward a daily limit (3 files a day on Free; see Limits).
2. Start the dub
curl https://api.soundhalo.com/v1/dubbing \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"asset_ref":{"asset_id":"ast_...","asset_token":"atok_..."}},"options":{"voice":"es-dora","format":"mp3"}}' You get 202 and a dub_id with status transcribing. The voice sets the language: es-dora speaks Spanish.
3. Wait for the quote
curl https://api.soundhalo.com/v1/dubbing/dub_a550d99c9a0ba49ec77094a7de4fc0c9 \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" Check every 10 seconds or so, or use the dub.awaiting_confirmation webhook. When status is awaiting_confirmation, the dub has the translated lines and a quote. This is the quote for a real 9-second recording on an account with no dubbing minutes left:
{
"billable_seconds": 10,
"by_text": false,
"plan_seconds": 0,
"plan_seconds_left": 0,
"balance_micros": 41667,
"balance_available_micros": 19874999,
"lines": 3,
"lines_total": 3
} The last line ends at 9.86 seconds, so the dub counts 10 seconds. None come from the plan, so the balance would pay 41,667 micro-dollars: 10 seconds at $0.25 a minute, about $0.04.
4. Confirm
curl https://api.soundhalo.com/v1/dubbing/dub_a550d99c9a0ba49ec77094a7de4fc0c9/confirm \
-H "Authorization: Bearer $SOUNDHALO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"max_balance_micros":41667}' max_balance_micros is the most your balance may pay. It must be at least quote.balance_micros, and SoundHalo never takes more. The dub moves to generating, then succeeded. Its output has a download_url and an asset_token for the download header.
Without a key
The free tools and the anonymous endpoints in the getting started guide still work without an account. They share small limits per network (30 POST requests an hour per IP address). Dubbing, voice cloning, lip-sync, webhooks and the MCP server need an account.
Where to go next
- Authentication: keys, what a key may not do, errors.
- API reference: every endpoint with what it uses and real examples.
- Dubbing: statuses, the quote, money protection, errors.
- Webhooks: events, payloads and signature checks.
- MCP server: Claude Code, Claude.ai, ChatGPT and more.
- Limits and pricing: per plan and per call.