How a dub runs
- You start it with
POST /v1/dubbing. SoundHalo transcribes the speech with word timings and cuts it into lines. - It translates the lines for speaking (plain sentences sized to each line's time).
- It stops and quotes: status
awaiting_confirmation, with the translated lines and what the dub will use. - You confirm with
POST /v1/dubbing/:id/confirmand the most your balance may pay. - It speaks and mixes, then the dub is
succeededwith a file to download.
The steps are the same ones the translate audio and video dubbing tools run, with the same allowances. Voices are synthetic; there is no lip-sync in a dub (see lip-sync for that).
Start a dub
POST /v1/dubbing with an API key. The input is a file you uploaded (input.asset_ref) or a public https link (input.source_url, imported like POST /v1/assets, so it counts as an upload).
| Option | Values | Notes |
|---|---|---|
voice | catalog voice id, personal or original | Required. A catalog voice's language is the dub language (list them with GET /v1/generate/speech/voices). personal is your cloned voice. original clones each speaker in the file from their own speech. |
language | language code | Required with personal and original: one of en-US, en-GB, es, fr, de, it, pt-BR, pt-PT, ja, zh, ru, tr, pl, nl, vi, id, ar. With a catalog voice, leave it out or match the voice. |
background | none, lowered, keep | none: the dub track only (default for audio). lowered: the original sound about 15 dB quieter under the dub (default for video). keep: video only; removes the original speech and keeps music and effects under the dub. |
format | mp3, wav | Audio format. A video dub comes back as MP4. |
source_language | language code | The language spoken in the file. Default: detected. |
rights_confirmed | true | Required with original: you confirm you have the right to dub the people in the recording with copies of their voices. |
Real request and response (the token is replaced):
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_6e64b0faaeaf86bbbce16fc2fe6fdea5","asset_token":"atok_REDACTED"}},"options":{"voice":"es-dora","format":"mp3"}}' {
"request_id": "req_REDACTED",
"status": "completed",
"operation": "dubbing.create",
"result": {
"dub": {
"dub_id": "dub_a550d99c9a0ba49ec77094a7de4fc0c9",
"status": "transcribing",
"created_at": "2026-11-16T01:56:02.719Z",
"updated_at": "2026-11-16T01:56:02.719Z",
"source": {
"asset_id": "ast_6e64b0faaeaf86bbbce16fc2fe6fdea5",
"media": "audio",
"duration_sec": 8.874
},
"options": {
"voice": "es-dora",
"language": "es",
"target_language": "es-419",
"background": "none",
"format": "mp3"
},
"quote": null,
"quote_expires_at": null,
"confirmed_max_balance_micros": null,
"lines": null,
"output": null,
"voice_track": null,
"error": null,
"warnings": []
}
},
"job": null,
"receipt": null,
"warnings": []
} The response has a Location header, /v1/dubbing/dub_.... Read the dub there with GET. Check every 10 seconds or so, or subscribe to the dub.awaiting_confirmation webhook. A dub is kept for 30 days after it ends.
Voice choices
- Catalog voice: one voice for every line.
- personal: your own cloned voice. You need to create it first.
- original: the transcription labels speakers, and each speaker is cloned from up to about 15 seconds of their own speech. A speaker with less than 2 seconds of clear speech uses the first speaker's voice. If nobody has 2 seconds, the dub fails before any speech. For video, when the model hears music or other background under a speaker's clip, the background is removed first, so the clone does not copy it.
Statuses
| Status | Meaning |
|---|---|
transcribing | Turning speech into timed text. Can take several minutes for long files. |
translating | Translating the lines. |
awaiting_confirmation | Quote ready. Waiting for you for up to 24 hours (quote_expires_at). |
generating | Speaking the lines. Only after you confirm. |
mixing | Putting the dub over the original sound or video. |
succeeded | Done. output has the file. |
failed | Stopped. error has a code and a message. |
cancelled | You cancelled before speech started. |
expired | The quote was not confirmed within 24 hours. Start again for a new quote. |
The quote
When the status is awaiting_confirmation, dub.lines holds every line with its times, the original text (source) and the translation (text), and dub.quote says what speaking it will use:
| Field | Meaning |
|---|---|
billable_seconds | Dubbing seconds this dub counts. |
by_text | true when the count comes from the text length, not the time (see below). |
plan_seconds | Seconds taken from your plan's dubbing minutes. |
plan_seconds_left | Plan dubbing seconds you had left when quoted. |
balance_micros | What the balance would pay. Confirm at least this. |
balance_available_micros | Your balance when quoted. |
lines, lines_total | Lines that will be spoken, out of all lines found. Fewer means the plan's per-dub limits cut the end; warnings says so. |
This dub is from a real staging run: a 9-second English recording dubbed into Spanish, on an account with no plan minutes left. The last line ends at 9.86 seconds, so the dub counts 10 seconds: $0.25 a minute for 10 seconds is 41,667 micro-dollars, about $0.04. (The run was made before a fix to how quotes measure length, so its first quote said 9 seconds; billable_seconds and balance_micros below show what the quote gives now.)
{
"request_id": "req_REDACTED",
"status": "completed",
"operation": "dubbing.get",
"result": {
"dub": {
"dub_id": "dub_a550d99c9a0ba49ec77094a7de4fc0c9",
"status": "awaiting_confirmation",
"created_at": "2026-11-16T01:56:02.719Z",
"updated_at": "2026-11-16T01:57:07.373Z",
"source": {
"asset_id": "ast_6e64b0faaeaf86bbbce16fc2fe6fdea5",
"media": "audio",
"duration_sec": 8.874
},
"options": {
"voice": "es-dora",
"language": "es",
"target_language": "es-419",
"background": "none",
"format": "mp3"
},
"quote": {
"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
},
"quote_expires_at": "2026-11-17T01:57:07.373Z",
"confirmed_max_balance_micros": null,
"lines": [
{
"start_sec": 0.06,
"end_sec": 1.88,
"source": "Welcome to Sound Halo.",
"text": "Bienvenido a Sound Halo."
},
{
"start_sec": 1.88,
"end_sec": 5.06,
"source": "This short recording tests the dubbing API.",
"text": "Esta breve grabación prueba la API de doblaje."
},
{
"start_sec": 5.06,
"end_sec": 9.86,
"source": "Each line should come back in Spanish, spoken by a new voice.",
"text": "Cada línea debe volver en español, con una nueva voz."
}
],
"output": null,
"voice_track": null,
"error": null,
"warnings": []
}
},
"job": null,
"receipt": null,
"warnings": []
} Show the lines and the quote to the person paying before you confirm. You cannot edit lines through the API yet; to change the script, use the website tool or call voice-over yourself with your own lines.
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}' {
"request_id": "req_REDACTED",
"status": "completed",
"operation": "dubbing.confirm",
"result": {
"dub": {
"dub_id": "dub_a550d99c9a0ba49ec77094a7de4fc0c9",
"status": "generating",
"created_at": "2026-11-16T01:56:02.719Z",
"updated_at": "2026-11-16T02:02:06.215Z",
"source": {
"asset_id": "ast_6e64b0faaeaf86bbbce16fc2fe6fdea5",
"media": "audio",
"duration_sec": 8.874
},
"options": {
"voice": "es-dora",
"language": "es",
"target_language": "es-419",
"background": "none",
"format": "mp3"
},
"quote": {
"billable_seconds": 9,
"by_text": false,
"plan_seconds": 0,
"plan_seconds_left": 0,
"balance_micros": 41667,
"balance_available_micros": 19874999,
"lines": 3,
"lines_total": 3
},
"quote_expires_at": null,
"confirmed_max_balance_micros": 41667,
"lines": [
{
"start_sec": 0.06,
"end_sec": 1.88,
"source": "Welcome to Sound Halo.",
"text": "Bienvenido a Sound Halo."
},
{
"start_sec": 1.88,
"end_sec": 5.06,
"source": "This short recording tests the dubbing API.",
"text": "Esta breve grabación prueba la API de doblaje."
},
{
"start_sec": 5.06,
"end_sec": 9.86,
"source": "Each line should come back in Spanish, spoken by a new voice.",
"text": "Cada línea debe volver en español, con una nueva voz."
}
],
"output": null,
"voice_track": null,
"error": null,
"warnings": [
"This dub counts 1 minutes and you have 0 dubbing minutes left this month. It now needs $0.05 from your balance, more than the $0.04 you confirmed. Confirm the new amount to continue. Minutes reset on December 1, 2026 (UTC). Nothing was sent to a provider."
]
}
},
"job": null,
"receipt": null,
"warnings": []
} This response is from a real staging run made before a fix to how quotes measure length. In that run the first quote was too low, so the response still carries the warning from the re-quote (see money protection), and billable_seconds still shows the first quote's 9. A dub confirmed at its first quote has an empty warnings list.
max_balance_microsis the most the balance may pay, from 0 to 1,000,000,000 ($1,000). It must be at leastquote.balance_micros.- If the quote needs no balance (
balance_microsis 0), you can send0or an empty body. - You may send more than the quote, for example to allow for minutes used elsewhere before the dub speaks. The ledger still takes only what the dub needs.
Money protection
- Nothing is spoken before you confirm. Speech is the only step that can use the balance. Transcription and translation use only your daily allowances.
- Never more than you confirmed. The amount you send is passed to the ledger (the account's record of minutes and balance), which refuses to take more.
- Too small is refused, uncharged. A confirm below the quote returns
400 PAYMENT_REQUIREDand the dub keeps waiting. - A changed amount asks again. If, when the dub is about to speak, it needs more than you confirmed (for example because plan minutes were used by another dub in the meantime), nothing is spoken or charged. The dub goes back to
awaiting_confirmationwith the newquote.balance_micros, a new 24-hour expiry, a warning and a newdub.awaiting_confirmationwebhook. Confirm again with the new amount. - No double charges on retry. Each dub's speech step carries one request id, so a repeat after a lost answer is refused instead of charged again.
- A failed speech step gives back. If the speech step fails and returns no audio, its dubbing minutes and balance are given back. If the outcome is unknown, for example after a timeout, they stay used.
A real "too small" answer, from the same run:
{
"request_id": "req_REDACTED",
"error": {
"code": "PAYMENT_REQUIRED",
"message": "This dub needs up to 37500 micro-dollars ($0.04) from your balance. Confirm with max_balance_micros of at least 37500. Nothing was charged.",
"details": {
"balance_needed_micros": 37500,
"dub": {
"dub_id": "dub_a550d99c9a0ba49ec77094a7de4fc0c9",
"status": "awaiting_confirmation",
"created_at": "2026-11-16T01:56:02.719Z",
"updated_at": "2026-11-16T01:57:07.373Z",
"source": {
"asset_id": "ast_6e64b0faaeaf86bbbce16fc2fe6fdea5",
"media": "audio",
"duration_sec": 8.874
},
"options": {
"voice": "es-dora",
"language": "es",
"target_language": "es-419",
"background": "none",
"format": "mp3"
},
"quote": {
"billable_seconds": 9,
"by_text": false,
"plan_seconds": 0,
"plan_seconds_left": 0,
"balance_micros": 37500,
"balance_available_micros": 19874999,
"lines": 3,
"lines_total": 3
},
"quote_expires_at": "2026-11-17T01:57:07.373Z",
"confirmed_max_balance_micros": null,
"lines": [
{
"start_sec": 0.06,
"end_sec": 1.88,
"source": "Welcome to Sound Halo.",
"text": "Bienvenido a Sound Halo."
},
{
"start_sec": 1.88,
"end_sec": 5.06,
"source": "This short recording tests the dubbing API.",
"text": "Esta breve grabación prueba la API de doblaje."
},
{
"start_sec": 5.06,
"end_sec": 9.86,
"source": "Each line should come back in Spanish, spoken by a new voice.",
"text": "Cada línea debe volver en español, con una nueva voz."
}
],
"output": null,
"voice_track": null,
"error": null,
"warnings": []
}
},
"retryable": true
}
} The result
{
"request_id": "req_REDACTED",
"status": "completed",
"operation": "dubbing.get",
"result": {
"dub": {
"dub_id": "dub_a550d99c9a0ba49ec77094a7de4fc0c9",
"status": "succeeded",
"created_at": "2026-11-16T01:56:02.719Z",
"updated_at": "2026-11-16T02:02:15.680Z",
"source": {
"asset_id": "ast_6e64b0faaeaf86bbbce16fc2fe6fdea5",
"media": "audio",
"duration_sec": 8.874
},
"options": {
"voice": "es-dora",
"language": "es",
"target_language": "es-419",
"background": "none",
"format": "mp3"
},
"quote": {
"billable_seconds": 9,
"by_text": false,
"plan_seconds": 0,
"plan_seconds_left": 0,
"balance_micros": 41667,
"balance_available_micros": 19874999,
"lines": 3,
"lines_total": 3
},
"quote_expires_at": null,
"confirmed_max_balance_micros": 41667,
"lines": [
{
"start_sec": 0.06,
"end_sec": 1.88,
"source": "Welcome to Sound Halo.",
"text": "Bienvenido a Sound Halo."
},
{
"start_sec": 1.88,
"end_sec": 5.06,
"source": "This short recording tests the dubbing API.",
"text": "Esta breve grabación prueba la API de doblaje."
},
{
"start_sec": 5.06,
"end_sec": 9.86,
"source": "Each line should come back in Spanish, spoken by a new voice.",
"text": "Cada línea debe volver en español, con una nueva voz."
}
],
"output": {
"asset_id": "ast_084264082f2686e047d80949cd759894",
"asset_token": "atok_REDACTED",
"mime_type": "audio/mpeg",
"size_bytes": 143347,
"duration_sec": 8.874,
"download_url": "https://api.soundhalo.com/v1/assets/ast_084264082f2686e047d80949cd759894/download"
},
"voice_track": {
"asset_id": "ast_084264082f2686e047d80949cd759894",
"asset_token": "atok_REDACTED",
"mime_type": "audio/mpeg",
"size_bytes": 143347,
"duration_sec": 8.874,
"download_url": "https://api.soundhalo.com/v1/assets/ast_084264082f2686e047d80949cd759894/download"
},
"error": null,
"warnings": [
"This dub counts 1 minutes and you have 0 dubbing minutes left this month. It now needs $0.05 from your balance, more than the $0.04 you confirmed. Confirm the new amount to continue. Minutes reset on December 1, 2026 (UTC). Nothing was sent to a provider."
]
}
},
"job": null,
"receipt": null,
"warnings": []
} outputis the finished file. Download it fromdownload_urlwith the headerx-asset-token: <output.asset_token>.voice_trackis the dub voice alone. For audio with backgroundnoneit is the same file asoutput.- File access ends 30 days after the file was created (longer on paid plans, up to a year).
curl -o dub.mp3 \
-H "x-asset-token: atok_REDACTED" \
https://api.soundhalo.com/v1/assets/ast_084264082f2686e047d80949cd759894/download Cancel
POST /v1/dubbing/:id/cancel works while the dub is transcribing, translating or awaiting_confirmation. It returns {"cancelled": true, "dub": {...}}. Transcription and translation already done stay counted. After speech starts it returns "cancelled": false and the dub continues.
What a dub uses
A dub uses the same allowances as calling each step yourself:
| Step | Uses |
|---|---|
| Transcription | Transcription seconds per day. Monthly cost cap. |
| Translation | One of the day's translation files and its characters. Monthly cost cap. |
| Speech (after confirm) | Dubbing minutes, then the balance. Also text to speech characters per day (catalog voices) or cloned-voice cost per day (personal, original). |
Speaker clips (original) | One processing job. |
| Mixing and music removal | Processing seconds and jobs per day. No provider cost. |
How dubbing minutes are counted
- The dub length is the longer of the source and the end of the last line.
- Billable minutes are the longer of the dub length and its text at 4,000 characters a minute (bytes for cloned voices). Normal speech is about 1,000 a minute, so this only matters for very dense scripts.
by_texttells you when it applied. - Plan dubbing minutes are used first. After that, the balance pays $0.25 a minute, counted per second and rounded up.
- Each dub counts again if you make it again.
Limits
- Audio up to 30 minutes, video up to 10 minutes.
- The plan's translation limit (characters per file) and voice-over limits (characters and lines per request) apply to one dub. If the script is longer, only the leading lines that fit are dubbed,
quote.linesis less thanquote.lines_total, and a warning says how many were left out. - Quotes last 24 hours.
- Per-plan numbers: Limits and pricing.
Errors
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing input or voice, unknown voice, a language that does not match the voice, cloned voice without language, original without rights_confirmed, no personal voice yet, keep on audio. |
| 400 | PAYMENT_REQUIRED | Confirm amount below the quote. Nothing was charged. |
| 401 | AUTH_REQUIRED | No API key. Dubbing needs an account. |
| 403 | ASSET_TOKEN_INVALID | Wrong asset token. |
| 404 | NOT_FOUND | No dub with this id on your account. |
| 409 | IDEMPOTENCY_CONFLICT | Confirm when the dub is not waiting for confirmation. |
| 410 | VALIDATION_ERROR | The quote expired. Start a new dub. |
| 413 | FILE_TOO_LONG | Audio over 30 minutes or video over 10 minutes. |
| 429 | QUOTA_EXCEEDED | Upload or daily limit reached. Wait Retry-After seconds. |
| 503 | INTERNAL_ERROR | Temporarily unavailable. Try again. |
A dub that fails after it started has status failed and an error, for example PROCESSING_FAILED ("No timed speech was found in the source, so there is nothing to dub."), TEXT_TOO_LONG (the first line alone is over the plan's limit) or the code of the step that failed, such as QUOTA_EXCEEDED when a daily allowance ran out. A job.failed webhook is sent with the dub.