> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# Guide API du doublage vidéo

> Guide pas à pas pour créer un pipeline de doublage vidéo avec l'API lip sync de sync. labs. Combinez TTS et lipsync pour un doublage vidéo multilingue en Python ou TypeScript.

Le doublage vidéo combine un audio traduit avec une vidéo lipsync pour que le contenu doublé paraisse naturel dans la langue cible. Vous pouvez soit utiliser le flux de doublage intégré de Sync Labs avec `dubParams`, soit fournir vous-même l'audio traduit et utiliser Sync Labs pour l'étape lipsync.

## Prérequis

* Une [clé API Sync Labs](https://sync.so/settings/api-keys)
* Une vidéo source (URL ou asset uploadé)
* Pour le doublage intégré: audio source dans le fichier vidéo
* Pour le doublage manuel: audio traduit dans la langue cible (d'un service TTS ou d'un comédien voix)

Installez le SDK pour votre langage:

```bash
# Python
pip install syncsdk

# TypeScript
npm i @sync.so/sdk
```

Définissez votre clé API:

```bash
export SYNC_API_KEY="your-api-key"
```

## Doublage API intégré avec `dubParams`

Utilisez `dubParams` quand vous voulez que Sync Labs extraie l'audio source de la vidéo, le traduise et le double via ElevenLabs, puis exécute le lipsync sur le résultat doublé. C'est le chemin le plus simple quand votre vidéo d'entrée contient déjà l'audio source.

Quand `dubParams` est présent:

* fournissez une seule entrée `video` avec audio
* définissez `dubParams.targetLang` sur le code langue cible, comme `"es"`, `"fr"` ou `"hi"`
* définissez éventuellement `dubParams.sourceLang`, omettez-le ou utilisez `"auto"` pour la détection automatique de la langue source
* `dubParams.numSpeakers` est obsolète et ignoré, Doublage v2 détecte automatiquement les intervenants
* n'incluez pas d'entrée audio séparée pour la piste traduite, les entrées audio sont ignorées quand le doublage est activé

**`dub_with_params.ts`**

```typescript dub_with_params.ts
import { SyncClient } from "@sync.so/sdk";

const sync = new SyncClient();

const response = await sync.generations.create({
    input: [
        {
            type: "video",
            url: "https://your-cdn.com/original-video-with-audio.mp4",
        },
    ],
    model: "lipsync-2",
    dubParams: {
        providerName: "elevenlabs",
        targetLang: "es",
        sourceLang: "auto",
    },
});

console.log(`Dubbing job submitted: ${response.id}`);
```

> **Note**
>
> Le doublage intégré s'appuie sur ElevenLabs. Si la vidéo n'a pas d'audio source exploitable, fournissez plutôt votre propre audio traduit et suivez le pipeline manuel ci-dessous.

## Pipeline de doublage manuel

#### Préparer l'audio traduit

Générez l'audio traduit avec un service synthèse vocale comme ElevenLabs, Google Cloud TTS ou Amazon Polly. Vous pouvez aussi utiliser un comédien voix. L'audio doit être hébergé sur une URL publique accessible.

Si vous avez déjà un fichier audio traduit, uploadez-le sur votre service d'hébergement et récupérez l'URL.

#### Envoyer à l'API Sync Labs

Envoyez la vidéo source et l'audio traduit à l'API Sync Labs. L'API génère de nouveaux mouvements de lèvres correspondant à l'audio traduit.

**`dub.ts`**

```typescript dub.ts
import { SyncClient } from "@sync.so/sdk";

const sync = new SyncClient();

// Source video with original language
const videoUrl = "https://your-cdn.com/original-video.mp4";
// Translated audio in target language
const dubbedAudioUrl = "https://your-cdn.com/translated-audio-spanish.wav";

const response = await sync.generations.create({
    input: [
        { type: "video", url: videoUrl },
        { type: "audio", url: dubbedAudioUrl },
    ],
    model: "lipsync-2",
    options: { sync_mode: "cut_off" },
});

const jobId = response.id;
console.log(`Dubbing job submitted: ${jobId}`);
```

**`dub.py`**

```python dub.py
import time
from sync import Sync
from sync.common import Audio, Video, GenerationOptions

sync = Sync()

# Source video with original language
video_url = "https://your-cdn.com/original-video.mp4"
# Translated audio in target language
dubbed_audio_url = "https://your-cdn.com/translated-audio-spanish.wav"

response = sync.generations.create(
    input=[
        Video(url=video_url),
        Audio(url=dubbed_audio_url),
    ],
    model="lipsync-2",
    options=GenerationOptions(sync_mode="cut_off"),
)

job_id = response.id
print(f"Dubbing job submitted: {job_id}")
```

#### Interroger jusqu'à la fin

Vérifiez le statut de génération jusqu'à sa fin. Pour les systèmes de production, utilisez des [webhooks](/api-reference/guides/webhooks) au lieu du polling.

```typescript
let generation = await sync.generations.get(jobId);
while (!["COMPLETED", "FAILED", "REJECTED"].includes(generation.status)) {
    console.log(`Status: ${generation.status}`);
    await new Promise((r) => setTimeout(r, 10000));
    generation = await sync.generations.get(jobId);
}

if (generation.status === "COMPLETED") {
    console.log(`Dubbed video ready: ${generation.outputUrl}`);
} else {
    console.log(`Dubbing failed for job ${jobId}`);
}
```

```python
generation = sync.generations.get(job_id)
while generation.status not in ["COMPLETED", "FAILED", "REJECTED"]:
    print(f"Status: {generation.status}")
    time.sleep(10)
    generation = sync.generations.get(job_id)

if generation.status == "COMPLETED":
    print(f"Dubbed video ready: {generation.output_url}")
else:
    print(f"Dubbing failed for job {job_id}")
```

#### Télécharger la vidéo doublée

`output_url` (Python) ou `outputUrl` (TypeScript) contient un lien direct vers la vidéo doublée. Téléchargez-la ou passez-la à votre pipeline de livraison.

## Utiliser l'intégration ElevenLabs

Sync Labs propose une intégration ElevenLabs intégrée qui gère synthèse vocale et lipsync dans un seul appel API. Au lieu de générer l'audio séparément, vous passez directement le texte traduit.

**`dub_with_elevenlabs.ts`**

```typescript dub_with_elevenlabs.ts
import { SyncClient } from "@sync.so/sdk";

const sync = new SyncClient();

const response = await sync.generations.create({
    input: [
        {
            type: "video",
            url: "https://your-cdn.com/original-video.mp4",
        },
        {
            type: "text",
            provider: {
                name: "elevenlabs",
                voiceId: "EXAVITQu4vr4xnSDxMaL",
                script: "Hola, bienvenidos a nuestra plataforma. Hoy les mostraremos las nuevas funciones.",
                stability: 0.5,
                similarityBoost: 0.75,
            },
        },
    ],
    model: "lipsync-2",
    options: { sync_mode: "cut_off" },
});

console.log(`Job ID: ${response.id}`);
```

**`dub_with_elevenlabs.py`**

```python dub_with_elevenlabs.py
from sync import Sync
from sync.common import Video, TTS, GenerationOptions

sync = Sync()

response = sync.generations.create(
    input=[
        Video(url="https://your-cdn.com/original-video.mp4"),
        TTS(
            provider={
                "name": "elevenlabs",
                "voiceId": "EXAVITQu4vr4xnSDxMaL",
                "script": "Hola, bienvenidos a nuestra plataforma. Hoy les mostraremos las nuevas funciones.",
                "stability": 0.5,
                "similarityBoost": 0.75,
            }
        ),
    ],
    model="lipsync-2",
    options=GenerationOptions(sync_mode="cut_off"),
)

print(f"Job ID: {response.id}")
```

> **Note**
>
> Le champ `script` a un maximum de 5 000 caractères par génération. Pour des scripts plus longs, découpez-les en segments. Voir la page [Integrations](/docs/product/integrations) pour les détails de configuration ElevenLabs.

## Langues prises en charge

Les modèles lipsync de Sync Labs sont agnostiques à la langue. Ils fonctionnent avec de l'audio dans n'importe quelle langue, les modèles analysent les formes de bouche à partir de la forme d'onde audio, pas de la langue elle-même. Si votre audio traduit est clair et bien produit, la sortie lipsync correspondra.

Pour le flux `dubParams` intégré, choisissez un des codes `targetLang` pris en charge dans l'API Reference. Si vous avez besoin d'une langue hors de cette liste ou de plus de contrôle sur la traduction, générez ou enregistrez l'audio traduit séparément et utilisez le pipeline manuel ci-dessus.

Pour un walkthrough complet d'un pipeline de traduction (transcription, traduction, TTS et lipsync), voir le [guide API de traduction vidéo](/tutorials/video-translation-api-guide).

## Doublage multi-intervenants

Pour les vidéos avec plusieurs intervenants, utilisez la segments API pour assigner différentes pistes audio à différentes plages de temps. Chaque segment peut référencer une entrée audio distincte avec une voix différente.

```python
from sync import Sync
from sync.common import Audio, Video

sync = Sync()

response = sync.generations.create(
    input=[
        Video(url="https://your-cdn.com/interview.mp4"),
        Audio(url="https://your-cdn.com/speaker-a-spanish.wav", ref_id="speaker_a"),
        Audio(url="https://your-cdn.com/speaker-b-spanish.wav", ref_id="speaker_b"),
    ],
    segments=[
        {"startTime": 0, "endTime": 15, "audioInput": {"refId": "speaker_a"}},
        {"startTime": 15, "endTime": 30, "audioInput": {"refId": "speaker_b"}},
    ],
    model="lipsync-2",
)
```

Voir le [guide des segments](/developer-guides/segments) pour la documentation complète et plus d'exemples.

## Conseils de performance

#### Utiliser des webhooks en production

Remplacez le polling par des [webhooks](/api-reference/guides/webhooks) pour les pipelines de production. Vous recevez une notification POST à la fin du job, ce qui évite des appels API inutiles.

#### Utiliser le traitement par lots pour du doublage en volume

Vous doublez toute une bibliothèque vidéo? La [API de lots](/api-reference/guides/batch-processing) permet d'envoyer jusqu'à 500 générations en une seule opération avec un délai de 24 heures.

#### Choisir le bon modèle

Utilisez **[lipsync-2](/models/lipsync)** pour la plupart des jobs de doublage. Utilisez **[sync-3](/models/sync-3)** pour du doublage qualité production, des scènes complexes, des obstructions, des angles de profil ou une sortie 4K. Passez à **[lipsync-2-pro](/models/lipsync)** quand vous avez besoin de détails faciaux premium à un prix inférieur à sync-3.

#### Aligner la durée audio

Définissez `sync_mode` pour contrôler ce qui se passe quand les durées audio et vidéo diffèrent. `cut_off` coupe l'audio excédentaire. `bounce` boucle la vidéo pour correspondre à la durée audio. Voir [mode Sync](/developer-guides/sync-mode) pour la matrice de comportement complète.