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.

The video dubbing API needs a paid plan (Lite or above). Each plan includes dubbed minutes per billing period and a longest video: see pricing. A job counts the length of the uploaded video; failed jobs are not counted.

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:

ParameterTypeRequiredDescription
videofileYesThe video to dub (mp4, mov, webm, mkv…), at most 100 MB, with an audio track.
voice_langstringNoLanguage of the voice-over: yue (Cantonese, default), zh (Mandarin) or en (English).
src_langstringNoSpoken language of the video: auto (default), en or zh.
subtitlesbooleanNotrue (default) also makes a copy with burned-in subtitles and an .srt file; false for the voice-over only.
subtitle_langstringNoSubtitle language: zh-Hant (default, written Traditional Chinese), zh-Hans, yue (spoken Cantonese), en or source (the original language).
lip_syncbooleanNoBeta: 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:

FieldDescription
statuspending → processing → completed or failed
stage, progressThe current step (e.g. translating, voicing) and 0–100 progress
jobs_ahead, eta_atQueue position and the estimated finish time (ISO 8601), when known
duration_sLength of the video in seconds (what the job counts)
final_video_url, subtitled_video_urlPreview copies of the dub (with the website watermark); use download-clean below for the watermark-free files
subtitles_srt_urlThe subtitles as an .srt file (when subtitles = true)
linesThe dubbed script: one entry per line with its timing, original text and translation
error_code, error_messageWhy 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

to auto-fill your API key in the code examples below.
# 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": "..." }.

StatuscodeMeaning
400BAD_FILE / BAD_INPUTNot a readable video, no audio track, or an invalid parameter
400TOO_LONGThe video is longer than your plan's longest video (or the minutes left)
401NOT_LOGGED_INMissing or invalid API key
403PLAN_REQUIREDYour plan does not include the video dubbing API
409JOB_IN_PROGRESSYou already have a job running; its request_id is included
413TOO_LARGEThe upload is larger than 100 MB
429QUOTA_EXCEEDEDThis billing period's dubbing minutes are used up (frees_at = when they renew)
500FAILEDThe job could not be started; try again