> ## 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.
# Avvia traduzione
> Carica un file video o audio e avvia un nuovo progetto di traduzione
# Avvia traduzione
Crea un nuovo progetto di traduzione caricando un file video o audio. Il processo di traduzione viene eseguito in modo asincrono in background. Utilizza l'[endpoint di stato](/docs/it/api-reference/translation-status) per monitorare l'avanzamento e recuperare i risultati. Utilizza [Ottieni dettagli del progetto](/docs/it/api-reference/project-details) quando hai bisogno della cronologia delle versioni tradotte o della cronologia della sincronizzazione labiale.
## Limite di concorrenza
Puoi eseguire fino a 10 traduzioni contemporaneamente per account. Se 10 traduzioni sono già in corso, le nuove richieste restituiscono `CONCURRENT_TRANSLATION_LIMIT_REACHED` (HTTP 429).
## Richiesta
Questo endpoint accetta `multipart/form-data` con un caricamento di file.
### Intestazioni
La tua chiave API VoiceCheap. Ottienine una da [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api).
### Parametri del corpo
Il file video o audio da tradurre.
**Formati video supportati:** `video/mp4`, `video/quicktime`, `video/x-matroska`, `video/webm`, `video/mpeg`
**Formati audio supportati:** `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/x-m4a`, `audio/flac`, `audio/ogg`, `audio/aac`, `audio/webm`
**Dimensione massima del file per piano:** Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB e Enterprise 60 GB.
La lingua in cui tradurre il contenuto. Deve essere in minuscolo.
**Valori consentiti (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 lingua di origine del contenuto utilizzando i codici lingua ISO (es. `en`, `es`, `fr`, `de`, `ja`, `zh`).
**Fortemente consigliato: lasciare vuoto per il rilevamento automatico.**
Fornisci questo parametro solo se sei sicuro al 100% che il codice lingua sia corretto e nel formato ISO valido. Codici lingua errati causeranno errori di trascrizione. Il nostro rilevamento automatico supporta oltre 80 lingue ed è altamente accurato.
**Predefinito:** `auto-detect`
Un nome personalizzato per il progetto. Utile per identificare i progetti nella tua dashboard.
**Predefinito:** Se non fornito, verrà utilizzato l'ID progetto.
Un endpoint https che riceve gli [eventi webhook](/docs/it/api-reference/webhooks) per questo progetto,
sovrascrivendo l'endpoint configurato sul tuo account.
**Predefinito:** L'endpoint webhook dell'account, quando configurato.
`auto-detect` o un numero intero da `1` a `32`. Un numero noto di parlanti può migliorare la diarizzazione.
**Predefinito:** `auto-detect`
Un array di stringhe JSON di nomi, marchi, acronimi o termini specialistici specifici della richiesta. Questi termini vengono uniti al glossario salvato dell'account o del team.
Rimuovi le comuni parole riempitive dalla trascrizione di origine prima della traduzione.
**Predefinito:** `true`
Una trascrizione SRT in lingua originale esistente. `originalLanguage` deve essere esplicito quando viene fornito questo campo.
Indica se preservare l'audio di sottofondo nell'output.
Se abilitato, mantiene la musica di sottofondo, l'ambiente, le risate, gli applausi e i suoni della folla rimuovendo solo la voce originale (separazione delle tracce). Disattiva se la tua sorgente non ha audio di sottofondo.
**Predefinito:** `true`
Mantieni la voce originale a basso volume sotto la voce tradotta.
**Predefinito:** `false`
Volume della voce originale da `1` a `70` quando `keepOriginalVoice` è abilitato.
**Predefinito:** `30`
Modalità di isolamento vocale quando `keepBackgroundMusic` è abilitato. Controlla la qualità e le caratteristiche della separazione vocale.
La nostra elaborazione vocale predefinita, progettata per una qualità audio professionale:
* Rimuove echi e riverberi
* Pulisce le imperfezioni tecniche
* Produce una voce chiara e nitida
**Consigliato per:** La maggior parte dei progetti in cui la qualità audio è fondamentale. Ideale per tutorial, contenuti educativi, video di marketing e qualsiasi contenuto che richieda una chiarezza vocale ottimale.
Preserva le caratteristiche naturali dell'ambiente di registrazione:
* Mantiene un suono più vicino alla registrazione originale
* Preserva le caratteristiche ambientali
**Consigliato per:** Contenuti in cui l'autenticità dell'ambiente è importante, come vlog all'aperto, documentari o contenuti in cui l'atmosfera sonora è parte integrante dell'esperienza.
Questa opzione potrebbe creare artefatti o effetti imprevisti in alcuni casi a causa della conservazione degli elementi di sottofondo.
**Valori consentiti:** `studio`, `realistic`
**Predefinito:** `studio`
Indica se generare sottotitoli per il video tradotto.
Se abilitato, aggiunge sottotitoli puliti in bianco e nero in stile Netflix. Usa `subtitlesSource` per scegliere il testo originale (lingua di origine) o tradotto (lingua di destinazione). I sottotitoli sono sincronizzati automaticamente per una leggibilità ottimale.
**Nota:** I sottotitoli impressi richiedono FFmpeg con il filtro `subtitles` (libass). Se non disponibile, l'API ripiegherà sull'incorporamento di una traccia sottotitoli invece dello stile impresso.
**Predefinito:** `false`
Scegli la fonte del testo dei sottotitoli quando `subtitles` è abilitato.
**Valori consentiti:** `translated`, `original`
**Predefinito:** `translated`
**Nota:** Se viene selezionato `original` ma la trascrizione originale non è disponibile, i sottotitoli ripiegheranno su `translated`.
Avvia l'elaborazione della sincronizzazione labiale al termine della traduzione.
* `standard` = Lip Sync
* `pro` = Lip Sync Pro
* `studio` = Lip Sync Studio
Le modalità premium applicano i requisiti standard di piano, durata e crediti.
**Predefinito:** omettere il campo per saltare la sincronizzazione labiale.
Abilita il rilevamento del parlante attivo per l'esecuzione della sincronizzazione labiale richiesta.
**Predefinito:** `false`
Selettore di sincronizzazione labiale legacy mantenuto per compatibilità con le versioni precedenti.
* `false` = Sincronizzazione labiale standard (**4 minuti di crediti per 1 minuto di video**)
* `true` = Lip Sync Pro (**9 minuti di crediti per 1 minuto di video**)
Lip Sync Pro è disponibile a partire dal piano Creator.
**Durata massima:** 30 minuti per video.
**Latenza:** L'elaborazione della sincronizzazione labiale aggiunge solitamente **2x-4x** la durata del video originale.
Le email di completamento e fallimento della sincronizzazione labiale non vengono inviate per le richieste attivate tramite API. Utilizza l'[endpoint di stato](/docs/it/api-reference/translation-status) per
monitorare l'avanzamento.
**Predefinito:** non abilitato (omettere il campo per saltare la sincronizzazione labiale)
**Form-data:** Invia i valori booleani come stringhe `true` o `false` (es. `-F "lipsyncPro=false"`).
Non combinare `lipsyncPro` con un `lipSyncMode` in conflitto.
Strategia vocale: `cloning` o `custom`.
**Predefinito:** `cloning`
Obbligatorio quando `voiceMode` è `custom`. La voce deve appartenere al proprietario effettivo del progetto. Gli ID vocali arbitrari o non posseduti vengono rifiutati.
Ottimizza i parametri di clonazione vocale per un controllo avanzato sulla voce generata. Passa come stringa JSON quando utilizzi form-data. Tutti i valori devono essere compresi tra 0 e 1 (con incrementi di 0,01).
Queste impostazioni si applicano solo quando `voiceMode` è `cloning`.
**Stabilità vocale (0,00 - 1,00)**
Determina quanto è stabile la voce e la casualità tra ogni generazione.
* **Valori più bassi** consentono una gamma emotiva più ampia ma possono causare un parlato strano o affrettato
* **Valori più alti** producono un output più coerente ma possono risultare monotoni
**Predefinito:** `0.60`
**Suggerimento:** Per evitare la riproduzione dell'accento, usa `0.80`
**Somiglianza vocale (0,00 - 1,00)**
Controlla quanto fedelmente l'IA aderisce alla voce originale.
* **Valori più alti** rendono la voce clonata più simile all'originale
* Se l'audio originale è rumoroso e la somiglianza è troppo alta, artefatti o rumore di fondo potrebbero essere trasferiti nella voce generata
**Predefinito:** `0.85`
**Suggerimento:** Per evitare la riproduzione dell'accento, usa `0.20`
**Potenziamento del parlante (0,00 - 1,00)**
Aumenta la somiglianza con il parlante originale. Si tratta di un miglioramento sottile che incrementa la somiglianza con la voce sorgente.
**Nota:** Valori più alti aumentano il tempo di calcolo e la latenza.
**Predefinito:** `0.60`
**Suggerimento:** Per evitare la riproduzione dell'accento, usa `0.00`
**Valori predefiniti (bilanciati):**
```json theme={null}
{
"stability": 0.6,
"similarity": 0.85,
"speakerBoost": 0.6
}
```
**Consigliato per evitare la riproduzione dell'accento:**
```json theme={null}
{
"stability": 0.8,
"similarity": 0.2,
"speakerBoost": 0.0
}
```
Un array JSON di intervalli di tempo sorgente che dovrebbero rimanere nella lingua originale.
```json theme={null}
[
{ "startTime": 10.2, "endTime": 12.8 }
]
```
I salti temporali richiedono un input video e `keepBackgroundMusic=true`. Non possono essere combinati con `keepOriginalVoice` e non possono sovrapporsi ai segmenti di trascrizione.
## Risposta
Sempre `true` per le richieste riuscite
Un messaggio leggibile dall'utente che descrive il risultato
L'identificativo univoco per il progetto di traduzione creato. Usa questo ID per controllare lo stato.
Stima approssimativa dell'elaborazione in minuti. La stima attuale è di cinque minuti di elaborazione per ogni minuto di file multimediale sorgente avviato.
## Esempi
Le regole del glossario salvate e le istruzioni di traduzione personalizzate dell'account o del team effettivo vengono applicate automaticamente.
```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'];
```
## Esempio di risposta
```json theme={null}
{
"success": true,
"message": "Translation started successfully. Use the status endpoint to track progress.",
"projectId": "abc123-def456-ghi789",
"estimatedDuration": 15
}
```
## Errori
| Stato | Codice | Descrizione |
| ----- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 400 | `FILE_REQUIRED` | Nessun file è stato caricato con la richiesta |
| 400 | `INVALID_FILE_TYPE` | Il tipo di file caricato non è supportato |
| 400 | `DURATION_DETECTION_FAILED` | Impossibile rilevare la durata del file caricato |
| 400 | `INVALID_MULTIPART_REQUEST` | I dati del modulo multipart sono malformati o superano i limiti di campo |
| 400 | `INVALID_BOOLEAN_VALUE` | Un parametro booleano ha un valore non valido (usa "true" o "false") |
| 400 | `INVALID_JSON_FORMAT` | Il JSON voiceCloningSettings è malformato |
| 400 | `INVALID_BRAND_VOCABULARY` | Una voce del glossario specifica per la richiesta non è valida |
| 400 | `INVALID_SOURCE_SRT` | Il file SRT sorgente fornito è malformato |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt richiede un originalLanguage esplicito |
| 400 | `VOICE_ID_REQUIRED` | La modalità voci personalizzate è stata selezionata senza un ID voce |
| 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | Un ID voce è stato combinato con la clonazione vocale |
| 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | Le impostazioni di clonazione sono state combinate con la modalità voci personalizzate |
| 400 | `CONFLICTING_LIPSYNC_OPTIONS` | lipSyncMode è in conflitto con la versione precedente lipsyncPro |
| 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | I salti temporali sono in conflitto con un'altra opzione audio |
| 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | I salti temporali richiedono audio di sottofondo |
| 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | Un salto temporale si estende oltre la durata del file multimediale |
| 400 | `INVALID_TRANSLATION_TIME_SKIPS` | Un salto temporale si sovrappone a un segmento di trascrizione |
| 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | Sono stati richiesti sottotitoli impressi per l'input audio |
| 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | È stata richiesta la sincronizzazione labiale per l'input audio |
| 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | Sono stati richiesti salti temporali per l'input audio |
| 400 | `LIPSYNC_VIDEO_TOO_LONG` | La sincronizzazione labiale è stata richiesta per file multimediali più lunghi della durata supportata |
| 413 | `FILE_TOO_LARGE` | Il file caricato supera il limite del piano dell'utente |
| 401 | `MISSING_API_KEY` | La chiave API è richiesta |
| 401 | `INVALID_API_KEY_FORMAT` | La chiave API deve iniziare con `vc_` |
| 401 | `INVALID_API_KEY` | La chiave API fornita non è valida |
| 403 | `API_ACCESS_REQUIRED` | L'accesso API è richiesto per questo account |
| 403 | `SUBSCRIPTION_REQUIRED` | L'accesso API richiede un abbonamento a pagamento |
| 403 | `INSUFFICIENT_CREDITS` | Crediti insufficienti per elaborare questo file |
| 403 | `CUSTOM_VOICE_ACCESS_DENIED` | La voce personalizzata non è di proprietà del proprietario effettivo del progetto |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | La modalità di sincronizzazione labiale premium non è disponibile nel piano attuale |
| 429 | `RATE_LIMIT_EXCEEDED` | Troppe richieste (limite: 10 richieste al minuto) |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | Troppe traduzioni in corso (limite: 10 traduzioni simultanee) |