Skip to main content
Doppiaggio del progetto

Doppiaggio del progetto

Genera le voci e mixa l’output di un progetto esistente a partire da un SRT tradotto che fornisci tu. VoiceCheap non traduce nulla su questo endpoint: niente motore di traduzione, niente riformulazione SmartSync, niente glossario. Ogni cue viene letto così com’è sul segmento corrispondente della trascrizione del progetto, poi mixato con lo sfondo originale, i sottotitoli e la sincronizzazione labiale facoltativa, esattamente come una traduzione normale. Usalo quando la traduzione è prodotta altrove (un traduttore umano, i tuoi strumenti, un flusso di automazione) e ti serve VoiceCheap solo per generare le voci. L’esecuzione è asincrona: interroga Ottieni lo stato della traduzione oppure ascolta i Webhook.

Prerequisiti

  • Il progetto deve esistere e la sua trascrizione deve essere completa: crealo con Crea progetto (solo trascrizione) o Avvia traduzione, e attendi transcriptionStatus: "success".
  • Il tuo SRT deve coprire la trascrizione del progetto: ogni segmento ha bisogno di almeno un cue e ogni cue deve cadere su un segmento. Esporta la trascrizione con Esporta trascrizione del progetto e traducila cue per cue per mantenere i timecode.
  • La richiesta viene addebitata come una traduzione dello stesso media, con lo stesso controllo dei crediti. Le modalità di sincronizzazione labiale aggiungono i soliti crediti extra.

Limite di concorrenza

La creazione dei progetti, la traduzione e il doppiaggio verificano tutti il limite di traduzioni attive dell’account (al massimo 10, eventualmente meno). Solo le traduzioni o i doppiaggi in corso occupano posti; i progetti di sola trascrizione no. Al raggiungimento del limite, l’API restituisce CONCURRENT_TRANSLATION_LIMIT_REACHED (HTTP 429). Il limite applicato è indicato in details.limit. Una seconda esecuzione per lo stesso progetto e la stessa lingua di destinazione viene rifiutata finché un’altra è in corso (TRANSLATION_ALREADY_IN_PROGRESS, HTTP 409).

Richiesta

Questo endpoint accetta un corpo JSON (Content-Type: application/json). Le opzioni booleane e numeriche vanno inviate come valori JSON, non come stringhe.

Intestazioni

string
obbligatorio
La tua chiave API VoiceCheap. Ottienine una da app.voicecheap.ai/page-api.

Parametri del percorso

string
obbligatorio
L’identificatore del progetto restituito da Crea progetto o Avvia traduzione.

Parametri del corpo

string
obbligatorio
La lingua di translatedSrt, in minuscolo, dallo stesso elenco di Avvia traduzione. Se il progetto non ha ancora un lavoro per questa lingua, ne viene creato uno e la lingua viene aggiunta al progetto.
string
obbligatorio
Il contenuto SRT finale nella lingua di destinazione (numero del cue, riga dei tempi, testo). Massimo 1.000.000 di caratteri. I cue vengono abbinati ai segmenti della trascrizione tramite i timestamp: un cue che inizia entro 50 ms dall’inizio di un segmento viene assegnato a quel segmento, altrimenti al segmento con cui si sovrappone di più. Più cue sullo stesso segmento vengono uniti con uno spazio. Tempo, parlante e ordine di ogni segmento letto provengono sempre dalla trascrizione del progetto; i tuoi timecode servono solo per l’abbinamento.
string
Un endpoint https che da questo momento riceve gli eventi webhook di questo progetto e sostituisce l’endpoint configurato sull’account.Predefinito: L’endpoint già salvato nel progetto, poi l’endpoint webhook dell’account.
boolean
Mantenere l’audio di sottofondo originale (musica, ambiente) sotto le voci generate.Predefinito: true
boolean
Mantenere la voce originale a basso volume sotto la voce generata.Predefinito: false
number
Volume della voce originale da 1 a 70 quando keepOriginalVoice è attivo.Predefinito: 30
string
Strategia vocale: cloning (clonare le voci dei parlanti del progetto) o custom (usare una voce del catalogo o la tua voce personalizzata salvata).Predefinito: cloning
string
Obbligatorio quando voiceMode è custom. Usa un ID di dubbing_voices_list: una voce del catalogo o una voce personalizzata salvata dall’account autenticato. La fatturazione del team non concede accesso alle voci salvate degli altri membri.
string
Modalità di isolamento della voce quando keepBackgroundMusic è attivo: studio o realistic.Predefinito: studio
boolean
Masterizzare i sottotitoli nel video di output. Richiede un progetto video.Predefinito: false
string
Testo dei sottotitoli quando subtitles è attivo: translated (il tuo SRT) o original (la trascrizione di origine).Predefinito: translated
string
Esegui la sincronizzazione labiale quando il doppiaggio è pronto: standard, pro o studio. Le regole di piano, durata e crediti sono le stesse di Avvia traduzione. Richiede un progetto video.Predefinito: ometti il campo per saltare la sincronizzazione labiale.
boolean
Abilita il rilevamento del parlante attivo per l’esecuzione di sincronizzazione labiale richiesta.Predefinito: false
object
Regolazione fine del clonaggio vocale, come oggetto JSON con stability e similarity tra 0 e 1. Solo con voiceMode: "cloning". Vedi Avvia traduzione per il significato di ciascun valore.
array
Intervalli del tempo sorgente da lasciare nella lingua originale, come [{ "startTime": 10.2, "endTime": 12.8 }]. Richiede un progetto video e keepBackgroundMusic: true, non può essere combinato con keepOriginalVoice e non può sovrapporsi ai segmenti della trascrizione.

Risposta

boolean
obbligatorio
Sempre true per le richieste riuscite.
string
obbligatorio
Una conferma leggibile.
string
obbligatorio
Il progetto che viene doppiato.
string
obbligatorio
Il lavoro di traduzione usato per targetLanguage. Corrisponde a workId negli endpoint di stato, dettagli e trascrizione.
number
obbligatorio
Stima approssimativa dell’elaborazione in minuti: cinque minuti di elaborazione per ogni minuto iniziato del media sorgente.
Response

Seguire l’esecuzione

Il progetto passa al flusso translation non appena parte il doppiaggio, quindi Ottieni lo stato della traduzione segue la nuova esecuzione: status passa da processing a success (con translatedVideoUrl e translatedAudioUrl) oppure a failed (con error). I webhook project.translation.completed e project.translation.failed vengono inviati con lo stesso targetLanguage. In Ottieni dettagli del progetto, la versione tradotta riporta settings.dubbingMode: "dub-only" e settings.smartSync: false. Gli errori di allineamento compaiono dopo l’accettazione della richiesta POST. L’endpoint di stato restituisce status: "failed" con error.code e error.message; il webhook project.translation.failed contiene lo stesso codice e messaggio. TRANSLATED_SRT_UNMATCHED_CUES indica nel messaggio i numeri dei cue senza corrispondenza e TRANSLATED_SRT_MISSING_SEGMENTS gli indici dei segmenti senza cue. Queste risposte asincrone non includono un campo details strutturato. Correggi l’SRT e richiama l’endpoint: la versione non riuscita resta nella cronologia e ne viene creata una nuova.

Controllare il ritmo

Esporta la trascrizione tradotta in JSON con Esporta trascrizione del progetto. Ogni segmento include finalSpeedFactor, il rapporto tra il parlato generato e la finestra del segmento. Accorcia i cue che restano sopra circa 1.3, poi esegui di nuovo il doppiaggio con l’SRT rivisto.

Flusso di esempio

Un’automazione tipica (per esempio uno scenario n8n o Make) concatena gli endpoint come segue:
  1. POST /v1/projects con il media, targetLanguage e un originalLanguage esplicito (solo trascrizione).
  2. Interroga GET /v1/translate/{projectId}/status finché transcriptionStatus è success, oppure attendi il webhook project.created.
  3. POST /v1/projects/{projectId}/transcript con { "source": "original", "outputFormat": "srt" } e traduci i cue mantenendo numerazione e timecode.
  4. POST /v1/projects/{projectId}/dub con l’SRT tradotto.
  5. Interroga l’endpoint di stato finché status è success, oppure attendi project.translation.completed.
  6. Scarica translatedVideoUrl (oppure lipSync.videoUrl se è stata richiesta la sincronizzazione labiale).
  7. DELETE /v1/translate/{projectId} quando gli output sono salvati dalla tua parte.

Errori

Gli errori di allineamento rilevati durante l’esecuzione (TRANSLATED_SRT_UNMATCHED_CUES, TRANSLATED_SRT_MISSING_SEGMENTS) sono restituiti dall’endpoint di stato e dal webhook di errore, non da questa richiesta.