Auto Dubbing

Bringing Your Own Scripts

Use subtitles when the user already has approved translations and wants them spoken word for word. If the user wants to review or correct the translation before it is spoken and has no script yet, run the proofread skill first — it returns one editable .srt per language, and the corrected files are exactly what subtitles takes (dropping its source-language file, which is an extra key here). Every rule below is checked before anything is charged, so breaking one costs a 422 and not money — but it also costs the user a round trip, and the first two are easy to get wrong:

• Cover every language, and only those languages. The key set must equal languages exactly; a missing or extra code is refused and the error names it. If the user gives you a script for two of three languages, ask for the third rather than dropping it — and remember that omitting languages altogether still means three (zh_cn, es, fr), so all three need a script.
• Target-language scripts, not source transcripts. A file of the original English lines submitted under "es" is a valid-looking script that produces a Spanish dub speaking English. The check reads the text and rejects a script whose language is not the one it was submitted under, but read what the user handed you before sending it.
• .srt or .vtt only, lower-cased extension, up to 1 MiB each. Anything else is refused.
• export_srt needs subtitles. There is nothing to align the audio against without a script, so on its own it is a 422.
• A blocked export does not fail the job. The dubbed videos are still delivered and charged; that language simply has no .srt. Report it as a missing extra, never as a failed dub, and do not re-run the job for it.
• The 202 carries subtitle_preflight — what the check made of each script — and the finished task repeats it alongside subtitle_export (per-language status, alignment_loss, issues). The pipeline stores those numbers as JSON of whatever type it recorded, so a count or a loss may arrive as a string rather than a number; do not assume one when you surface them.

Workflow Tips

• Always ask which language(s) if the user hasn't said, rather than relying on the ["zh_cn", "es", "fr"] default — that default silently bills for three languages.
• Consider lipsync=false when nobody is speaking on camera. Screen recordings, b-roll and voice-over have no mouth to match, and lip-syncing them re-renders the picture for no benefit — the original frames are returned untouched instead, at their own resolution and frame rate. Do not turn it off on a talking-head video unless the user asks: the mouths will visibly keep speaking the original language.
• Ask for scripts when the user has them. If they mention approved copy, an existing localization, or a translation they want said exactly, that is subtitles — the pipeline's own translation would overwrite it. Do not invent one: a script you wrote yourself is a translation the user never approved, spoken in their video.
• This is not the music or SFX skills (text-to-music, video-to-music, text-to-sfx, video-to-sfx). It doesn't touch music/SFX at all — it translates and re-voices existing speech.
• Set expectations on time. Tell the user up front this can take up to ~2 hours and that walking away is fine — the result is recoverable afterward.
• The free run is a preview, not the whole video. A self-serve account gets one free single-language call, and it translates only the first 15 seconds. When the result carries trial_preview, tell the user exactly that — the clip is the first 15 seconds of their video, and full_video_cost_usd is what the whole thing costs — rather than presenting the clip as the finished translation. Once that run is spent, an account without a payment method fails with trial_exhausted; check get_account_services (see account) first if unsure, and warn the user before calling.

Recovering a Timed-Out Call

If the call's own long poll is interrupted (e.g. the host itself times out or the session is closed), the error message — or the task id printed to stderr at submission time — gives you a task_id. Call get_sfx_task(task_id) — get_generation_task(task_id) on the hosted server — to check status and download finished files once ready; see task-recovery.

Output Files

One .mp4 per requested language, named dubbing-<first 8 chars of the task id>.<language>.mp4 — there's no prompt to name files after, so all dubbing output shares the task-id-based name.

With export_srt, one .srt lands beside each video under the same stem — dubbing-<first 8 chars of the task id>.<language>.srt — carrying that language's own lines re-timed against its delivered audio. A language whose export was blocked has its video and no .srt; that is reported as a note, not an error. On the CLI the SRTs follow --output the same way the videos do (--output dubbed.mp4 writes dubbed.es.mp4 and dubbed.es.srt), which is why --output may not itself end in .srt.

Free preview

When the run was the account's free 15-second preview, the task carries trial_preview in every state:

"trial_preview": {
  "preview_seconds": 15,
  "source_duration_seconds": 60.0,
  "trimmed": true,
  "languages": 1,
  "full_video_cost_usd": 3.49,
  "message": "Free preview: the first 15 seconds of your 60-second video, in 1 language. Translating the full video costs $3.49 — add funds at https://platform.sonilo.com/dashboard/billing"
}

duration_seconds is then 15, not the source's length, and the delivered .mp4 is that first 15 seconds. The MCP tool and both CLIs print the message with their other status lines; the SDKs expose it as DubbingResult.trial_preview. Relay it to the user, and offer the full run (add funds, call again — that run is billed) rather than treating the clip as the whole video.

Error Handling

Common errors: 401 invalid key, 402 insufficient balance (dubbing has no trial to exhaust — it bills immediately), 413 file too large, 422 invalid parameters or unsupported language code (rejected before any charge), 429 rate limit. See the account skill.

A 422 with code: SUBTITLE_PREFLIGHT_BLOCKED means a submitted script itself did not pass the check. The message names the blocked languages and their issue codes, and details carries the per-language report. Nothing was charged — fix or replace that script and resubmit; do not strip subtitles and run the job anyway, which would silently deliver the pipeline's own translation instead of the user's approved lines.