> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Démarrer la traduction
> Téléchargez un fichier vidéo ou audio et démarrez un nouveau projet de traduction
# Démarrer la traduction
Créez un nouveau projet de traduction en téléchargeant un fichier vidéo ou audio. Le processus de traduction s'exécute de manière asynchrone en arrière-plan. Utilisez le [point de terminaison de statut](/docs/fr/api-reference/translation-status) pour suivre la progression et récupérer les résultats. Utilisez [Obtenir les détails du projet](/docs/fr/api-reference/project-details) lorsque vous avez besoin de l'historique des versions traduites ou de l'historique de la synchronisation labiale.
## Limite de concurrence
Vous pouvez exécuter jusqu'à 10 traductions simultanément par compte. Si 10 traductions sont déjà en cours, les nouvelles requêtes renvoient `CONCURRENT_TRANSLATION_LIMIT_REACHED` (HTTP 429).
## Requête
Ce point de terminaison accepte `multipart/form-data` avec un téléchargement de fichier.
### En-têtes
Votre clé API VoiceCheap. Obtenez-en une sur [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api).
### Paramètres du corps de la requête
Le fichier vidéo ou audio à traduire.
**Formats vidéo pris en charge :** `video/mp4`, `video/quicktime`, `video/x-matroska`, `video/webm`, `video/mpeg`
**Formats audio pris en charge :** `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/x-m4a`, `audio/flac`, `audio/ogg`, `audio/aac`, `audio/webm`
**Taille maximale de fichier par forfait :** Beginner 5 Go, Starter 10 Go, Creator 20 Go, Pro 30 Go, Scale 40 Go et Enterprise 60 Go.
La langue vers laquelle traduire le contenu. Doit être en minuscules.
**Valeurs autorisées (70+) :** `afrikaans`, `albanian`, `amharic`, `arabic`, `armenian`, `assamese`, `azerbaijani`, `basque`, `belarusian`, `bengali`, `bosnian`, `bulgarian`, `catalan`, `croatian`, `czech`, `danish`, `dutch`, `english`, `british english`, `estonian`, `finnish`, `french`, `french canadian`, `galician`, `german`, `greek`, `gujarati`, `hebrew`, `hindi`, `hungarian`, `icelandic`, `indonesian`, `irish`, `italian`, `japanese`, `kannada`, `kazakh`, `khmer`, `korean`, `lao`, `latvian`, `lithuanian`, `macedonian`, `malay`, `malayalam`, `mandarin`, `marathi`, `mongolian`, `nepali`, `norwegian`, `persian`, `polish`, `portuguese`, `brazilian portuguese`, `punjabi`, `romanian`, `russian`, `serbian`, `slovak`, `slovenian`, `spanish`, `swahili`, `swedish`, `tagalog`, `tamil`, `telugu`, `thai`, `turkish`, `ukrainian`, `urdu`, `vietnamese`, `welsh`, `yoruba`, `zulu`
La langue source du contenu en utilisant les codes de langue ISO (par ex. `en`, `es`, `fr`, `de`, `ja`, `zh`).
**Fortement recommandé : Laissez ce champ vide pour la détection automatique.**
Ne fournissez ce paramètre que si vous êtes sûr à 100 % que le code de langue est correct et au format ISO valide. Des codes de langue incorrects entraîneront des échecs de transcription. Notre détection automatique prend en charge plus de 80 langues et est très précise.
**Par défaut :** `auto-detect`
Un nom personnalisé pour le projet. Utile pour identifier les projets dans votre tableau de bord.
**Par défaut :** L'ID du projet sera utilisé s'il n'est pas fourni.
Un point de terminaison https qui reçoit les [événements webhook](/docs/fr/api-reference/webhooks) pour ce projet,
remplaçant le point de terminaison configuré sur votre compte.
**Par défaut :** Le point de terminaison webhook du compte, lorsqu'il est configuré.
`auto-detect` ou un entier de `1` à `32`. Un nombre de locuteurs connu peut améliorer la diarisation.
**Par défaut :** `auto-detect`
Un tableau de chaînes JSON contenant des noms, marques, acronymes ou termes spécialisés spécifiques à la requête. Ces termes sont fusionnés avec le vocabulaire enregistré du compte ou de l'équipe.
Supprimez les mots de remplissage courants de la transcription source avant la traduction.
**Par défaut :** `true`
Une transcription SRT existante dans la langue source. `originalLanguage` doit être explicite lorsque ce champ est fourni.
Indique s'il faut conserver l'audio d’arrière-plan dans la sortie.
Lorsqu'il est activé, conserve la musique d’arrière-plan, l'ambiance, les rires, les applaudissements et les sons de foule tout en supprimant uniquement la voix originale (séparation des pistes). Désactivez cette option si votre source ne contient pas d'audio d’arrière-plan.
**Par défaut :** `true`
Gardez la voix du locuteur original en sourdine sous la voix traduite.
**Par défaut :** `false`
Volume de la voix originale de `1` à `70` lorsque `keepOriginalVoice` est activé.
**Par défaut :** `30`
Mode d'isolation vocale lorsque `keepBackgroundMusic` est activé. Contrôle la qualité et les caractéristiques de la séparation vocale.
Notre traitement vocal par défaut, conçu pour une qualité audio professionnelle :
* Supprime les échos et les réverbérations
* Nettoie les imperfections techniques
* Produit une voix claire et nette
**Recommandé pour :** La plupart des projets où la qualité audio est primordiale. Idéal pour les tutoriels, le contenu éducatif, les vidéos marketing et tout contenu nécessitant une clarté vocale optimale.
Préserve les caractéristiques naturelles de l'environnement d'enregistrement :
* Maintient un son plus proche de l'enregistrement original
* Préserve les caractéristiques environnementales
**Recommandé pour :** Le contenu où l'authenticité de l'environnement est importante, comme les vlogs en extérieur, les documentaires ou le contenu où l'ambiance sonore fait partie intégrante de l'expérience.
Cette option peut créer des artefacts ou des effets inattendus dans certains cas en raison de la préservation des éléments d’arrière-plan.
**Valeurs autorisées :** `studio`, `realistic`
**Par défaut :** `studio`
Indique s'il faut générer des sous-titres pour la vidéo traduite.
Lorsqu'il est activé, ajoute des sous-titres noirs et blancs épurés de style Netflix. Utilisez `subtitlesSource` pour choisir le texte original (langue source) ou traduit (langue cible). Les sous-titres sont automatiquement synchronisés pour une lisibilité optimale.
**Remarque :** Les sous-titres incrustés nécessitent FFmpeg avec le filtre `subtitles` (libass). S'il n'est pas disponible, l'API revient à l'intégration d'une piste de sous-titres au lieu d'un style incrusté.
**Par défaut :** `false`
Choisissez la source du texte des sous-titres lorsque `subtitles` est activé.
**Valeurs autorisées :** `translated`, `original`
**Par défaut :** `translated`
**Remarque :** Si `original` est sélectionné mais que la transcription originale n'est pas disponible, les sous-titres basculent sur `translated`.
Déclencher le traitement de la synchronisation labiale une fois la traduction terminée.
* `standard` = Lip Sync
* `pro` = Lip Sync Pro
* `studio` = Lip Sync Studio
Les modes premium appliquent leurs exigences habituelles en matière de forfait, de durée et de crédits.
**Par défaut :** omettez le champ pour ignorer la synchronisation labiale.
Activer la détection du locuteur actif pour l'exécution de la synchronisation labiale demandée.
**Par défaut :** `false`
Sélecteur de synchronisation labiale hérité conservé pour la compatibilité ascendante.
* `false` = Synchronisation labiale standard (**4 minutes de crédits par minute de vidéo**)
* `true` = Lip Sync Pro (**9 minutes de crédits par minute de vidéo**)
Lip Sync Pro est disponible à partir du forfait Creator.
**Durée maximale :** 30 minutes par vidéo.
**Latence :** Le traitement de la synchronisation labiale ajoute généralement **2x à 4x** la durée de la vidéo originale.
Les e-mails de fin et d'échec de la synchronisation labiale ne sont pas envoyés pour les demandes déclenchées par l'API. Utilisez le [point de terminaison de statut](/docs/fr/api-reference/translation-status) pour
suivre la progression.
**Par défaut :** non activé (omettez le champ pour ignorer la synchronisation labiale)
**Form-data :** Envoyez les valeurs booléennes sous forme de chaînes `true` ou `false` (par ex., `-F "lipsyncPro=false"`).
Ne combinez pas `lipsyncPro` avec un `lipSyncMode` contradictoire.
Stratégie vocale : `cloning` ou `custom`.
**Par défaut :** `cloning`
Requis lorsque `voiceMode` est `custom`. La voix doit appartenir au propriétaire effectif du projet. Les identifiants de voix arbitraires ou sans propriétaire sont rejetés.
Affinez les paramètres de clonage vocal pour un contrôle avancé sur la voix générée. Transmettez sous forme de chaîne JSON lors de l'utilisation de form-data. Toutes les valeurs doivent être comprises entre 0 et 1 (avec un pas de 0,01).
Ces paramètres ne s'appliquent que lorsque `voiceMode` est `cloning`.
**Stabilité de la voix (0,00 - 1,00)**
Détermine la stabilité de la voix et le caractère aléatoire entre chaque génération.
* **Des valeurs plus faibles** permettent une gamme émotionnelle plus large mais peuvent causer une élocution étrange ou précipitée
* **Des valeurs plus élevées** produisent un résultat plus cohérent mais peuvent sembler monotones
**Par défaut :** `0.60`
**Conseil :** Pour éviter la reproduction de l'accent, utilisez `0.80`
**Similitude de la voix (0,00 - 1,00)**
Contrôle à quel point l'IA adhère à la voix originale.
* **Des valeurs plus élevées** rendent la voix clonée plus similaire à l'originale
* Si l'audio original est bruyant et que la similitude est trop élevée, des artefacts ou du bruit de fond peuvent être transférés dans la voix générée
**Par défaut :** `0.85`
**Conseil :** Pour éviter la reproduction de l'accent, utilisez `0.20`
**Amplification du locuteur (0,00 - 1,00)**
Renforce la similitude avec le locuteur original. Il s'agit d'une amélioration subtile qui augmente la ressemblance avec la voix source.
**Remarque :** Des valeurs plus élevées augmentent le temps de calcul et la latence.
**Par défaut :** `0.60`
**Conseil :** Pour éviter la reproduction de l'accent, utilisez `0.00`
**Valeurs par défaut (équilibrées) :**
```json theme={null}
{
"stability": 0.6,
"similarity": 0.85,
"speakerBoost": 0.6
}
```
**Recommandé pour éviter la reproduction de l'accent :**
```json theme={null}
{
"stability": 0.8,
"similarity": 0.2,
"speakerBoost": 0.0
}
```
Un tableau JSON de plages temporelles sources qui doivent rester dans la langue originale.
```json theme={null}
[
{ "startTime": 10.2, "endTime": 12.8 }
]
```
Les sauts temporels nécessitent une entrée vidéo et `keepBackgroundMusic=true`. Ils ne peuvent pas être combinés avec `keepOriginalVoice` et ne peuvent pas chevaucher les segments de transcription.
## Réponse
Toujours `true` pour les demandes réussies
Un message lisible par l'homme décrivant le résultat
L'identifiant unique du projet de traduction créé. Utilisez cet ID pour vérifier le statut.
Estimation approximative du traitement en minutes. L'estimation actuelle est de cinq minutes de traitement par minute de média source lancée.
## Exemples
Les règles de glossaire enregistrées et les instructions de traduction personnalisées du compte ou de l'équipe effective sont appliquées automatiquement.
```bash cURL theme={null}
curl -X POST https://api.voicecheap.ai/v1/translate \
-H "x-api-key: vc_your-api-key" \
-F "file=@video.mp4" \
-F "targetLanguage=spanish" \
-F "projectName=My Spanish Translation" \
-F "numberOfSpeakers=2" \
-F 'brandVocabulary=["VoiceCheap","SmartSync"]' \
-F "removeFillerWords=true" \
-F "keepBackgroundMusic=true" \
-F "keepOriginalVoice=false" \
-F "voiceIsolatorOption=studio" \
-F "subtitles=true" \
-F "subtitlesSource=translated" \
-F "lipSyncMode=standard" \
-F "activeSpeakerDetectionEnabled=true"
```
```typescript TypeScript theme={null}
interface StartTranslationResponse {
success: boolean;
message: string;
projectId: string;
estimatedDuration: number;
}
interface VoiceCloningSettings {
stability: number; // 0.00 - 1.00
similarity: number; // 0.00 - 1.00
speakerBoost: number; // 0.00 - 1.00
}
interface StartTranslationRequest {
targetLanguage: string;
originalLanguage?: string;
projectName?: string;
numberOfSpeakers?: 'auto-detect' | string;
brandVocabulary?: string[];
removeFillerWords?: boolean;
keepBackgroundMusic?: boolean;
keepOriginalVoice?: boolean;
originalVoiceVolume?: number;
voiceMode?: 'cloning' | 'custom';
voiceId?: string;
voiceIsolatorOption?: 'studio' | 'realistic';
subtitles?: boolean;
subtitlesSource?: 'translated' | 'original';
lipSyncMode?: 'standard' | 'pro' | 'studio';
activeSpeakerDetectionEnabled?: boolean;
voiceCloningSettings?: VoiceCloningSettings;
translationTimeSkips?: Array<{ startTime: number; endTime: number }>;
}
async function startTranslation(
file: File,
targetLanguage: string,
options?: {
originalLanguage?: string;
projectName?: string;
numberOfSpeakers?: 'auto-detect' | string;
brandVocabulary?: string[];
removeFillerWords?: boolean;
keepBackgroundMusic?: boolean;
keepOriginalVoice?: boolean;
originalVoiceVolume?: number;
voiceMode?: 'cloning' | 'custom';
voiceId?: string;
voiceIsolatorOption?: 'studio' | 'realistic';
subtitles?: boolean;
subtitlesSource?: 'translated' | 'original';
lipSyncMode?: 'standard' | 'pro' | 'studio';
activeSpeakerDetectionEnabled?: boolean;
voiceCloningSettings?: VoiceCloningSettings;
translationTimeSkips?: Array<{ startTime: number; endTime: number }>;
},
): Promise {
const formData = new FormData();
formData.append('file', file);
formData.append('targetLanguage', targetLanguage);
if (options?.projectName) {
formData.append('projectName', options.projectName);
}
if (options?.originalLanguage) {
formData.append('originalLanguage', options.originalLanguage);
}
if (options?.numberOfSpeakers) {
formData.append('numberOfSpeakers', options.numberOfSpeakers);
}
if (options?.brandVocabulary) {
formData.append('brandVocabulary', JSON.stringify(options.brandVocabulary));
}
if (options?.removeFillerWords !== undefined) {
formData.append('removeFillerWords', String(options.removeFillerWords));
}
if (options?.keepBackgroundMusic !== undefined) {
formData.append('keepBackgroundMusic', String(options.keepBackgroundMusic));
}
if (options?.keepOriginalVoice !== undefined) {
formData.append('keepOriginalVoice', String(options.keepOriginalVoice));
}
if (options?.originalVoiceVolume !== undefined) {
formData.append('originalVoiceVolume', String(options.originalVoiceVolume));
}
if (options?.voiceMode) {
formData.append('voiceMode', options.voiceMode);
}
if (options?.voiceId) {
formData.append('voiceId', options.voiceId);
}
if (options?.voiceIsolatorOption) {
formData.append('voiceIsolatorOption', options.voiceIsolatorOption);
}
if (options?.subtitles !== undefined) {
formData.append('subtitles', String(options.subtitles));
}
if (options?.subtitlesSource) {
formData.append('subtitlesSource', options.subtitlesSource);
}
if (options?.lipSyncMode) {
formData.append('lipSyncMode', options.lipSyncMode);
}
if (options?.activeSpeakerDetectionEnabled !== undefined) {
formData.append('activeSpeakerDetectionEnabled', String(options.activeSpeakerDetectionEnabled));
}
if (options?.voiceCloningSettings) {
formData.append('voiceCloningSettings', JSON.stringify(options.voiceCloningSettings));
}
if (options?.translationTimeSkips) {
formData.append('translationTimeSkips', JSON.stringify(options.translationTimeSkips));
}
const response = await fetch('https://api.voicecheap.ai/v1/translate', {
method: 'POST',
headers: {
'x-api-key': 'vc_your-api-key',
},
body: formData,
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message || 'Translation failed');
}
return response.json();
}
// Usage example
const file = document.querySelector('#fileInput')?.files?.[0];
if (file) {
const result = await startTranslation(file, 'spanish', {
projectName: 'My Spanish Translation',
keepBackgroundMusic: true,
voiceIsolatorOption: 'studio',
subtitles: true,
subtitlesSource: 'translated',
voiceCloningSettings: {
stability: 0.6,
similarity: 0.85,
speakerBoost: 0.6,
},
});
console.log('Project ID:', result.projectId);
}
```
```javascript JavaScript theme={null}
const formData = new FormData();
formData.append('file', videoFile);
formData.append('targetLanguage', 'spanish');
formData.append('projectName', 'My Spanish Translation');
formData.append('keepBackgroundMusic', 'true');
formData.append('voiceIsolatorOption', 'studio');
formData.append('subtitles', 'true');
formData.append('subtitlesSource', 'translated');
formData.append(
'voiceCloningSettings',
JSON.stringify({
stability: 0.6,
similarity: 0.85,
speakerBoost: 0.6,
}),
);
const response = await fetch('https://api.voicecheap.ai/v1/translate', {
method: 'POST',
headers: {
'x-api-key': 'vc_your-api-key',
},
body: formData,
});
const data = await response.json();
console.log('Project ID:', data.projectId);
```
```python Python theme={null}
import requests
import json
files = {'file': open('video.mp4', 'rb')}
data = {
'targetLanguage': 'spanish',
'projectName': 'My Spanish Translation',
'keepBackgroundMusic': 'true',
'voiceIsolatorOption': 'studio',
'subtitles': 'true',
'subtitlesSource': 'translated',
'voiceCloningSettings': json.dumps({
'stability': 0.60,
'similarity': 0.85,
'speakerBoost': 0.60
})
}
headers = {'x-api-key': 'vc_your-api-key'}
response = requests.post(
'https://api.voicecheap.ai/v1/translate',
headers=headers,
files=files,
data=data
)
result = response.json()
print(f"Project ID: {result['projectId']}")
```
```php PHP theme={null}
0.60,
'similarity' => 0.85,
'speakerBoost' => 0.60
]);
$postFields = [
'file' => new CURLFile('video.mp4'),
'targetLanguage' => 'spanish',
'projectName' => 'My Spanish Translation',
'keepBackgroundMusic' => 'true',
'voiceIsolatorOption' => 'studio',
'subtitles' => 'true',
'subtitlesSource' => 'translated',
'voiceCloningSettings' => $voiceCloningSettings
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.voicecheap.ai/v1/translate',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $postFields,
CURLOPT_HTTPHEADER => [
'x-api-key: vc_your-api-key'
]
]);
$response = curl_exec($curl);
$result = json_decode($response, true);
echo "Project ID: " . $result['projectId'];
```
## Exemple de réponse
```json theme={null}
{
"success": true,
"message": "Translation started successfully. Use the status endpoint to track progress.",
"projectId": "abc123-def456-ghi789",
"estimatedDuration": 15
}
```
## Erreurs
| Statut | Code | Description |
| ------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| 400 | `FILE_REQUIRED` | Aucun fichier n'a été téléchargé avec la requête |
| 400 | `INVALID_FILE_TYPE` | Le type de fichier téléchargé n'est pas pris en charge |
| 400 | `DURATION_DETECTION_FAILED` | Impossible de détecter la durée du fichier téléchargé |
| 400 | `INVALID_MULTIPART_REQUEST` | Les données de formulaire multipart sont mal formées ou dépassent les limites de champ |
| 400 | `INVALID_BOOLEAN_VALUE` | Un paramètre booléen a une valeur invalide (utilisez "true" ou "false") |
| 400 | `INVALID_JSON_FORMAT` | Le JSON voiceCloningSettings est mal formé |
| 400 | `INVALID_BRAND_VOCABULARY` | Une entrée de vocabulaire spécifique à la requête est invalide |
| 400 | `INVALID_SOURCE_SRT` | Le fichier SRT source fourni est mal formé |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt nécessite un originalLanguage explicite |
| 400 | `VOICE_ID_REQUIRED` | Le mode voix personnalisées a été sélectionné sans ID de voix |
| 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | Un ID de voix a été combiné avec le clonage vocal |
| 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | Les paramètres de clonage ont été combinés avec le mode voix personnalisées |
| 400 | `CONFLICTING_LIPSYNC_OPTIONS` | lipSyncMode est en conflit avec l'ancien lipsyncPro |
| 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | Les sauts temporels sont en conflit avec une autre option audio |
| 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | Les sauts temporels nécessitent un audio d’arrière-plan |
| 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | Un saut temporel dépasse la durée du média |
| 400 | `INVALID_TRANSLATION_TIME_SKIPS` | Un saut temporel chevauche un segment de transcription |
| 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | Des sous-titres incrustés ont été demandés pour une entrée audio |
| 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | Une synchronisation labiale a été demandée pour une entrée audio |
| 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | Des sauts temporels ont été demandés pour une entrée audio |
| 400 | `LIPSYNC_VIDEO_TOO_LONG` | Une synchronisation labiale a été demandée pour un média plus long que la durée prise en charge |
| 413 | `FILE_TOO_LARGE` | Le fichier téléchargé dépasse la limite du forfait de l'utilisateur |
| 401 | `MISSING_API_KEY` | La clé API est requise |
| 401 | `INVALID_API_KEY_FORMAT` | La clé API doit commencer par `vc_` |
| 401 | `INVALID_API_KEY` | La clé API fournie est invalide |
| 403 | `API_ACCESS_REQUIRED` | L'accès à l'API est requis pour ce compte |
| 403 | `SUBSCRIPTION_REQUIRED` | L'accès à l'API nécessite un abonnement payant |
| 403 | `INSUFFICIENT_CREDITS` | Crédits insuffisants pour traiter ce fichier |
| 403 | `CUSTOM_VOICE_ACCESS_DENIED` | La voix personnalisée n'appartient pas au propriétaire effectif du projet |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | Le mode de synchronisation labiale premium n'est pas disponible sur le forfait actuel |
| 429 | `RATE_LIMIT_EXCEEDED` | Trop de requêtes (limite : 10 requêtes par minute) |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | Trop de traductions en cours (limite : 10 traductions simultanées) |