Developer docs

Dubbing API

Send a recording or video and get it back in another language. Every dub stops at a quote. Nothing is spoken, and nothing is paid from your balance, until you confirm.

How a dub runs

  1. You start it with POST /v1/dubbing. SoundHalo transcribes the speech with word timings and cuts it into lines.
  2. It translates the lines for speaking (plain sentences sized to each line's time).
  3. It stops and quotes: status awaiting_confirmation, with the translated lines and what the dub will use.
  4. You confirm with POST /v1/dubbing/:id/confirm and the most your balance may pay.
  5. It speaks and mixes, then the dub is succeeded with 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).

OptionValuesNotes
voicecatalog voice id, personal or originalRequired. 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.
languagelanguage codeRequired 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.
backgroundnone, lowered, keepnone: 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.
formatmp3, wavAudio format. A video dub comes back as MP4.
source_languagelanguage codeThe language spoken in the file. Default: detected.
rights_confirmedtrueRequired 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):

request
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"}}'
202 response
{
  "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

StatusMeaning
transcribingTurning speech into timed text. Can take several minutes for long files.
translatingTranslating the lines.
awaiting_confirmationQuote ready. Waiting for you for up to 24 hours (quote_expires_at).
generatingSpeaking the lines. Only after you confirm.
mixingPutting the dub over the original sound or video.
succeededDone. output has the file.
failedStopped. error has a code and a message.
cancelledYou cancelled before speech started.
expiredThe 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:

FieldMeaning
billable_secondsDubbing seconds this dub counts.
by_texttrue when the count comes from the text length, not the time (see below).
plan_secondsSeconds taken from your plan's dubbing minutes.
plan_seconds_leftPlan dubbing seconds you had left when quoted.
balance_microsWhat the balance would pay. Confirm at least this.
balance_available_microsYour balance when quoted.
lines, lines_totalLines 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.)

GET /v1/dubbing/:id
{
  "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

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}'
202 response
{
  "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_micros is the most the balance may pay, from 0 to 1,000,000,000 ($1,000). It must be at least quote.balance_micros.
  • If the quote needs no balance (balance_micros is 0), you can send 0 or 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_REQUIRED and 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_confirmation with the new quote.balance_micros, a new 24-hour expiry, a warning and a new dub.awaiting_confirmation webhook. 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:

400 PAYMENT_REQUIRED
{
  "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

GET /v1/dubbing/:id
{
  "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": []
}
  • output is the finished file. Download it from download_url with the header x-asset-token: <output.asset_token>.
  • voice_track is the dub voice alone. For audio with background none it is the same file as output.
  • File access ends 30 days after the file was created (longer on paid plans, up to a year).
download
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:

StepUses
TranscriptionTranscription seconds per day. Monthly cost cap.
TranslationOne 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 removalProcessing 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_text tells 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.lines is less than quote.lines_total, and a warning says how many were left out.
  • Quotes last 24 hours.
  • Per-plan numbers: Limits and pricing.

Errors

StatusCodeWhen
400VALIDATION_ERRORMissing 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.
400PAYMENT_REQUIREDConfirm amount below the quote. Nothing was charged.
401AUTH_REQUIREDNo API key. Dubbing needs an account.
403ASSET_TOKEN_INVALIDWrong asset token.
404NOT_FOUNDNo dub with this id on your account.
409IDEMPOTENCY_CONFLICTConfirm when the dub is not waiting for confirmation.
410VALIDATION_ERRORThe quote expired. Start a new dub.
413FILE_TOO_LONGAudio over 30 minutes or video over 10 minutes.
429QUOTA_EXCEEDEDUpload or daily limit reached. Wait Retry-After seconds.
503INTERNAL_ERRORTemporarily 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.