Voca Dubbing API

Translate spoken audio into another language in the original speaker's voice. The API is asynchronous: submit a recording, poll the job, download the result. Music beds are preserved under the translated voice, and music-only stretches are never billed.

Authentication

Every request carries the two RapidAPI headers:

X-RapidAPI-Key: YOUR_KEY
X-RapidAPI-Host: voca-dubbing.p.rapidapi.com

Quick start — a complete example

1. Submit the audio

One multipart request. Only file, sourceLanguage and targetLanguage are required; everything else refines the render.

curl -X POST "https://voca-dubbing.p.rapidapi.com/v1/dubs" \
  -H "X-RapidAPI-Key: $YOUR_KEY" \
  -H "X-RapidAPI-Host: voca-dubbing.p.rapidapi.com" \
  -F "file=@episode.m4a" \
  -F "sourceLanguage=auto" \
  -F "targetLanguage=zh" \
  -F "mode=free_speed" \
  -F "caption=true" \
  -F 'keywords=["Gooaye","Mung-Kong"]'

The response is immediate:

HTTP 202
{
  "jobId": "cmsd07da10003wi5g08ilghaf",
  "status": "queued",
  "inputSeconds": 300.0,
  "billableSeconds": 301,
  "truncated": false,
  "expectedDurationSec": 180
}

billableSeconds here is a ceiling estimated from the input length — the final charge is the measured speech only. expectedDurationSec estimates the render time (excluding queue time) so you can size your first wait.

2. Poll the job — once every 60 seconds

One GET per minute is all it takes; even short episodes render for a few minutes. Status moves through queued, preprocessing, translating, synthesizing, finalizing to a terminal done, failed or cancelled.

curl "https://voca-dubbing.p.rapidapi.com/v1/dubs/cmsd07da10003wi5g08ilghaf" \
  -H "X-RapidAPI-Key: $YOUR_KEY" \
  -H "X-RapidAPI-Host: voca-dubbing.p.rapidapi.com"

When the job completes:

{
  "jobId": "cmsd07da10003wi5g08ilghaf",
  "status": "done",
  "progress": 1.0,
  "inputSeconds": 300.0,
  "outputSeconds": 300.1,
  "resultUrl": "https://…short-lived signed URL…",
  "captionsUrl": "https://…short-lived signed URL…",
  "captionsFormat": "vtt",
  "billableSeconds": 281
}

3. Download the result

Fetch resultUrl (the dubbed audio/mp4) and captionsUrl promptly — they are short-lived signed URLs. If one expires, poll the job again for fresh links, or use the stable path GET /v1/dubs/{jobId}/audio, which 302-redirects to a fresh download URL whenever the job is done.

curl -o dubbed_zh.m4a  "$resultUrl"
curl -o captions_zh.vtt "$captionsUrl"

Endpoints

Method & path	Purpose
`POST /v1/dubs`	Create a dub job (multipart upload)
`GET /v1/dubs/{jobId}`	Poll job status; fresh download URLs on every authorized poll
`GET /v1/dubs`	List your jobs — `cursor`, `page_size`, `status`, `created_after`, `created_before`
`DELETE /v1/dubs/{jobId}`	Cancel a job; cancelled jobs are never billed
`GET /v1/dubs/{jobId}/audio`	Stable download path: `302` to a fresh signed URL when `done`; `409` with `Retry-After` while rendering; `410` once expired
`GET /v1/languages`	Supported source/target language tags

POST /v1/dubs — parameters (multipart/form-data)

Field	Required	Description
`file`	yes	The audio file, up to 32 MB and 90 minutes. Upload is the only ingest path — split longer recordings into separate requests.
`sourceLanguage`	yes	Source language tag, or `auto` to detect it.
`targetLanguage`	yes	Target language tag. Must differ from the source.
`mode`	no	`synchronized` (default) — output keeps the source timeline exactly, so it stays in sync with video. `free_speed` — the translation runs at its natural length; use it for audio-only output where pacing matters more than timing.
`quality`	no	`standard` (default). `premium` is reserved and returns `403 plan_required` on current plans.
`caption`	no	`true`/`false` (default `false`). Opt-in target-language captions as WebVTT via `captionsUrl`, in both modes. In `synchronized` mode cue timing is measured; in `free_speed` it is estimated.
`keywords`	no	A JSON-array string of 1–32 proper nouns (each ≤64 characters) that appear in the audio, e.g. `["Gooaye","Mung-Kong"]`. Speech recognition is biased toward these terms, misheard soundalikes are repaired to them, and they pass through to the dub and captions verbatim — never translated. Include native-script and romanized spellings of the same name as separate entries.
`musicDetectionTh`	no	`0.2`–`1.0`, default `0.5` — how much music must be present under speech before that stretch is source-separated so the translated voice lays over the original music bed. Higher is stricter (less separation). A number out of range is a `400`; a non-number runs at the default.

Optional header: Idempotency-Key — an opaque, caller-chosen string (1–255 printable ASCII, no comma). Retrying a submit with the same key and the same parameters returns the original job instead of creating a duplicate; the same key with different parameters is 409 idempotency_conflict.

Billing

Speech, not wall-clock. Music-only stretches — intros, stings, ad-break beds, outros — are detected and skipped, and you are not billed for them. billableSeconds on the finished job reports exactly what was charged.
Charged only on delivery. Failed and cancelled jobs cost nothing.
Accumulates per second, settles per minute. Seconds add up across your jobs; each whole minute is charged as it is reached and the remainder carries to your next job. Ten short clips cost the same as one clip of the same total length.
The BASIC plan's free daily allowance is applied before anything is charged and does not accumulate across days.

Limits

Limit	Value
Maximum upload	32 MB per file
Maximum input length	90 minutes (both plans)
Concurrent jobs	1 (BASIC) / 5 (PRO)
Daily usage cap	none on either plan

Errors

Every error body is {"error": {"code": "…", "message": "…"}}. The two refusals a robust client must distinguish:

429 quota_exceeded — your plan limit (for example a second concurrent job on a one-job plan). Wait for your running job to finish.
503 resource_exhausted — the render fleet is briefly full. Retry after the Retry-After header.

HTTP	Code	Meaning
400	`invalid_request`	Malformed field or a malformed `Idempotency-Key`; the message names the field
400	`unsupported_language`	Source or target outside the supported set
401	`unauthorized`	Missing or invalid RapidAPI credentials
403	`plan_required`	Option not available on your plan
404	`not_found`	No such job on your account
409	`idempotency_conflict`	`Idempotency-Key` reused for a different submission
413	`media_too_large`	File bytes or duration over the plan ceiling
415	`unsupported_media`	Decodable but unsupported characteristics (channels, sample rate)
422	`unprocessable_media`	No decodable audio stream in the upload
429	`quota_exceeded`	Your plan's concurrency or allowance limit
503	`resource_exhausted`	Fleet at capacity — retry after `Retry-After`

A failed job carries a machine-readable error.code in the poll response (for example unprocessable_media, output_validation_failed, timeout, internal) and is never billed.

Languages

Eight languages, one tag each — regional forms are accepted and normalised. GET /v1/languages returns the current sets:

{
  "source": ["en", "zh", "ko", "de", "es", "fr", "it", "ru", "auto"],
  "target": ["en", "zh", "ko", "de", "es", "fr", "it", "ru"]
}