Video Dubbing
Dub a video into Cantonese (or Mandarin / English): the speech is transcribed, translated and re-voiced line by line in matching voices, then mixed back over the original background sound, with optional burned-in subtitles. Dubbing runs in the background: create a job, poll its status, then download the result. Videos dubbed through the API are watermark-free and private to your account.
Authentication
Send your API key in a header on every request: Authorization: Bearer YOUR_API_KEY (or x-api-key: YOUR_API_KEY). The upload is multipart, so the key cannot be sent as a form field here.
1. Create a dubbing job
POST https://cantonese.ai/api/video-dubbing/create with multipart/form-data:
| Parameter | Type | Required | Description |
|---|---|---|---|
| video | file | Yes | The video to dub (mp4, mov, webm, mkv…), at most 100 MB, with an audio track. |
| voice_lang | string | No | Language of the voice-over: yue (Cantonese, default), zh (Mandarin) or en (English). |
| src_lang | string | No | Spoken language of the video: auto (default), en or zh. |
| subtitles | boolean | No | true (default) also makes a copy with burned-in subtitles and an .srt file; false for the voice-over only. |
| subtitle_lang | string | No | Subtitle language: zh-Hant (default, written Traditional Chinese), zh-Hans, yue (spoken Cantonese), en or source (the original language). |
| lip_sync | boolean | No | Beta: re-sync the speakers' mouths to the dub. Default false; makes the job slower. |
Response:
{ "success": true, "request_id": "6f1c2d3e-0a4b-4c5d-8e9f-0123456789ab" }One job runs at a time per account: wait for it to finish before creating the next one.
2. Poll the job
GET https://cantonese.ai/api/video-dubbing/get-result?id=REQUEST_ID (every 10–30 s). The useful fields of data:
| Field | Description |
|---|---|
| status | pending → processing → completed or failed |
| stage, progress | The current step (e.g. translating, voicing) and 0–100 progress |
| jobs_ahead, eta_at | Queue position and the estimated finish time (ISO 8601), when known |
| duration_s | Length of the video in seconds (what the job counts) |
| final_video_url, subtitled_video_url | Preview copies of the dub (with the website watermark); use download-clean below for the watermark-free files |
| subtitles_srt_url | The subtitles as an .srt file (when subtitles = true) |
| lines | The dubbed script: one entry per line with its timing, original text and translation |
| error_code, error_message | Why a job failed (e.g. NO_SPEECH, TOO_LONG); failed jobs do not use minutes |
A job takes a few minutes per minute of video, plus any queue time.
3. Download the result
GET https://cantonese.ai/api/video-dubbing/download-clean?id=REQUEST_ID&version=dubbed returns the watermark-free dubbed video (video/mp4). Use version=subtitled for the copy with burned-in subtitles.
Example
# 1. Upload a video and start dubbing (the key goes in the Authorization header)
curl -X POST "https://cantonese.ai/api/video-dubbing/create" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "[email protected];type=video/mp4" \
-F "voice_lang=yue" \
-F "subtitles=true" \
-F "subtitle_lang=zh-Hant"
# -> {"success":true,"request_id":"REQUEST_ID"}
# 2. Poll until data.status is "completed" (or "failed")
curl "https://cantonese.ai/api/video-dubbing/get-result?id=REQUEST_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
# 3. Download the watermark-free dubbed video (version=subtitled for the copy with burned-in subtitles)
curl -L "https://cantonese.ai/api/video-dubbing/download-clean?id=REQUEST_ID&version=dubbed" \
-H "Authorization: Bearer YOUR_API_KEY" \
--fail-with-body --output dubbed.mp4
Usage and limits
GET https://cantonese.ai/api/video-dubbing/get-usage returns your plan's API allowance in api: limit_s, used_s and left_s (seconds of video this billing period), max_video_s (the longest video one job may be) and period_end.
Errors
Errors are JSON: { "success": false, "code": "...", "message": "..." }.
| Status | code | Meaning |
|---|---|---|
| 400 | BAD_FILE / BAD_INPUT | Not a readable video, no audio track, or an invalid parameter |
| 400 | TOO_LONG | The video is longer than your plan's longest video (or the minutes left) |
| 401 | NOT_LOGGED_IN | Missing or invalid API key |
| 403 | PLAN_REQUIRED | Your plan does not include the video dubbing API |
| 409 | JOB_IN_PROGRESS | You already have a job running; its request_id is included |
| 413 | TOO_LARGE | The upload is larger than 100 MB |
| 429 | QUOTA_EXCEEDED | This billing period's dubbing minutes are used up (frees_at = when they renew) |
| 500 | FAILED | The job could not be started; try again |