Tutorials

Dubbing

Dubbing is supported natively on POST /v2/generate. Pass the dubParams object alongside your normal generation request and Sync will extract audio from the video input, dub it into the target language, and run lipsync on the dubbed result — all as one job.

A video with audio is sufficient for dubbing to work — video input alone (with an embedded audio track) is acceptable. You do not need to supply a separate audio input; any audio inputs in the input array are ignored when dubParams is present. You must pass the dub parameters (dubParams) to enable dubbing.

When to use dubbing

  • Native dubParams flow (this page): single API call, recommended for standard translation-plus-lipsync workflows.
  • Manual orchestration: when you need custom control over transcription, TTS voice cloning, or intermediate steps, see the Translation/Dubbing tutorial which wires ElevenLabs, OpenAI, and Sync together manually.

Workflow

1

Prepare a video with audio

Ensure your source file is a video whose audio track you want translated. No separate audio input is required.

2

Pick a target language

Choose one of the supported targetLang codes (see the DubLanguage enum in the API Reference for the full list).

3

Send the generation request

Include dubParams in the request body. sourceLang defaults to auto and numSpeakers defaults to 0 (auto-detect), so only targetLang is required.

4

Poll for completion

Poll GET /v2/generate/{id} until status is COMPLETED; the outputUrl will contain the dubbed and lipsynced video.

DubDto fields

See the full API reference for dubParams.

  • targetLang (DubLanguage, required): target language code for dubbing, e.g. es, fr, ja.
  • sourceLang (DubSourceLanguage, optional, default auto): source language code, or auto to let the engine detect it.
  • numSpeakers (integer, optional, default 0): number of speakers in the source video. 0 enables auto-detection; otherwise set a value between 1 and 50.

Request examples

1import { SyncClient } from "@sync.so/sdk";
2
3const sync = new SyncClient();
4
5const response = await sync.generations.create({
6  model: "lipsync-2",
7  input: [
8    { type: "video", url: "https://assets.sync.so/docs/example-video.mp4" }
9  ],
10  dubParams: {
11    targetLang: "es"
12  }
13});
1from syncsdk import Sync
2
3client = Sync()
4
5response = client.generations.create(
6    model="lipsync-2",
7    input=[
8        {"type": "video", "url": "https://assets.sync.so/docs/example-video.mp4"}
9    ],
10    dub_params={
11        "target_lang": "es"
12    },
13)
$curl -X POST https://api.sync.so/v2/generate \
>  -H "x-api-key: $SYNC_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "model": "lipsync-2",
>    "input": [
>      { "type": "video", "url": "https://assets.sync.so/docs/example-video.mp4" }
>    ],
>    "dubParams": {
>      "targetLang": "es"
>    }
>  }'

Behavior notes

  • When dubParams is provided, audio is extracted from the video input, dubbed via ElevenLabs into the target language, and lipsync is run against the dubbed audio.
  • Any audio inputs in the input array are ignored when dubbing is enabled — pass only the video input.
  • A probed audio duration is required on the source video; dubbing requests without a decodable audio track are rejected.
  • Billing is reported per dubbed output minute. See the Billing page for details.

See also