Skip to main content
Doblar el proyecto

Doblar el proyecto

Genere las voces y mezcle la salida de un proyecto existente a partir de un SRT traducido que usted proporciona. VoiceCheap no traduce nada en este endpoint: ni motor de traducción, ni reformulación SmartSync, ni glosario. Cada cue se locuta literalmente sobre el segmento correspondiente de la transcripción del proyecto y después se mezcla con el fondo original, los subtítulos y la sincronización labial opcional, igual que una traducción normal. Úselo cuando la traducción se produce en otro lugar (un traductor humano, sus propias herramientas, un flujo de automatización) y solo necesita VoiceCheap para generar las voces. La ejecución es asíncrona: consulte Obtener estado de la traducción o escuche los Webhooks.

Requisitos previos

  • El proyecto debe existir y su transcripción debe estar completa: créelo con Crear proyecto (solo transcripción) o Iniciar traducción, y espere transcriptionStatus: "success".
  • Su SRT debe cubrir la transcripción del proyecto: cada segmento necesita al menos un cue, y cada cue debe caer sobre un segmento. Exporte la transcripción con Exportar transcripción del proyecto y tradúzcala cue por cue para conservar los códigos de tiempo.
  • La solicitud se factura como una traducción del mismo medio, con la misma comprobación de créditos. Los modos de sincronización labial añaden sus créditos extra habituales.

Límite de concurrencia

La creación de proyectos, la traducción y el doblaje comprueban el límite de traducciones activas de su cuenta (10 como máximo, posiblemente menos). Solo las traducciones o los doblajes en curso ocupan plazas; los proyectos de solo transcripción no. Al alcanzar el límite, la API devuelve CONCURRENT_TRANSLATION_LIMIT_REACHED (HTTP 429). El límite aplicado aparece en details.limit. También se rechaza una segunda ejecución para el mismo proyecto e idioma de destino mientras haya otra en curso (TRANSLATION_ALREADY_IN_PROGRESS, HTTP 409).

Solicitud

Este endpoint acepta un cuerpo JSON (Content-Type: application/json). Las opciones booleanas y numéricas se envían como valores JSON, no como cadenas.

Encabezados

string
requerido
Tu clave de API VoiceCheap. Obtén una en app.voicecheap.ai/page-api.

Parámetros de ruta

string
requerido
El identificador del proyecto devuelto por Crear proyecto o Iniciar traducción.

Parámetros del cuerpo

string
requerido
El idioma de translatedSrt, en minúsculas, de la misma lista que Iniciar traducción. Si el proyecto aún no tiene un trabajo para este idioma, se crea uno y el idioma se añade al proyecto.
string
requerido
El contenido SRT final en el idioma de destino (número de cue, línea de tiempo, texto). Máximo 1.000.000 de caracteres. Los cues se emparejan con los segmentos de la transcripción por marcas de tiempo: un cue que empieza dentro de 50 ms del inicio de un segmento se asigna a ese segmento; si no, al segmento con el que más se solapa. Varios cues en un mismo segmento se unen con un espacio. El tiempo, el locutor y el orden de cada segmento locutado proceden siempre de la transcripción del proyecto; sus códigos de tiempo solo sirven para el emparejamiento.
string
Un endpoint https que recibe a partir de ahora los eventos de webhook de este proyecto y sustituye el endpoint configurado en la cuenta.Predeterminado: El endpoint ya guardado en el proyecto y, después, el endpoint de webhook de la cuenta.
boolean
Conservar el audio de fondo original (música, ambiente) bajo las voces generadas.Predeterminado: true
boolean
Mantener la voz original en bajo volumen bajo la voz generada.Predeterminado: false
number
Volumen de la voz original de 1 a 70 cuando keepOriginalVoice está activado.Predeterminado: 30
string
Estrategia de voz: cloning (clonar a los hablantes del proyecto) o custom (usar una voz del catálogo o tu voz personalizada guardada).Predeterminado: cloning
string
Obligatorio cuando voiceMode es custom. Usa un ID de dubbing_voices_list: una voz del catálogo o una voz personalizada guardada por la cuenta autenticada. La facturación del equipo no da acceso a las voces guardadas de otro miembro.
string
Modo de aislamiento de voz cuando keepBackgroundMusic está activado: studio o realistic.Predeterminado: studio
boolean
Incrustar subtítulos en el vídeo de salida. Requiere un proyecto de vídeo.Predeterminado: false
string
Texto de los subtítulos cuando subtitles está activado: translated (su SRT) u original (la transcripción de origen).Predeterminado: translated
string
Ejecutar la sincronización labial cuando el doblaje esté listo: standard, pro o studio. Las reglas de plan, duración y créditos son las mismas que en Iniciar traducción. Requiere un proyecto de vídeo.Predeterminado: omita el campo para saltar la sincronización labial.
boolean
Activar la detección del locutor activo para la ejecución de sincronización labial solicitada.Predeterminado: false
object
Ajuste fino del clonado de voz, como objeto JSON con stability y similarity entre 0 y 1. Solo con voiceMode: "cloning". Consulte Iniciar traducción para orientar cada valor.
array
Intervalos del tiempo de origen que permanecen en el idioma original, como [{ "startTime": 10.2, "endTime": 12.8 }]. Requiere un proyecto de vídeo y keepBackgroundMusic: true, no puede combinarse con keepOriginalVoice y no puede solaparse con segmentos de la transcripción.

Respuesta

boolean
requerido
Siempre true en las solicitudes correctas.
string
requerido
Una confirmación legible.
string
requerido
El proyecto que se está doblando.
string
requerido
El trabajo de traducción usado para targetLanguage. Coincide con workId en los endpoints de estado, detalles y transcripción.
number
requerido
Estimación aproximada del procesamiento en minutos: cinco minutos de procesamiento por cada minuto iniciado del medio de origen.
Response

Seguimiento de la ejecución

El proyecto pasa al flujo translation en cuanto empieza el doblaje, así que Obtener estado de la traducción sigue la nueva ejecución: status pasa de processing a success (con translatedVideoUrl y translatedAudioUrl) o a failed (con error). Los webhooks project.translation.completed y project.translation.failed se envían con el mismo targetLanguage. En Obtener detalles del proyecto, la versión traducida informa settings.dubbingMode: "dub-only" y settings.smartSync: false. Los fallos de alineación aparecen después de aceptar la solicitud POST. El endpoint de estado devuelve status: "failed" con error.code y error.message; el webhook project.translation.failed lleva el mismo código y mensaje. TRANSLATED_SRT_UNMATCHED_CUES indica en el mensaje los números de cue sin correspondencia, y TRANSLATED_SRT_MISSING_SEGMENTS los índices de segmento sin cue. Estas respuestas asíncronas no incluyen un campo details estructurado. Corrija el SRT y vuelva a llamar al endpoint: la versión fallida permanece en el historial y se crea una nueva.

Comprobar el ritmo

Exporte la transcripción traducida como JSON con Exportar transcripción del proyecto. Cada segmento incluye finalSpeedFactor, la relación entre el habla generada y la ventana del segmento. Acorte los cues que queden aproximadamente por encima de 1.3 y vuelva a ejecutar el doblaje con el SRT revisado.

Flujo de ejemplo

Una automatización típica (por ejemplo un escenario de n8n o Make) encadena los endpoints así:
  1. POST /v1/projects con el medio, targetLanguage y un originalLanguage explícito (solo transcripción).
  2. Consulte GET /v1/translate/{projectId}/status hasta que transcriptionStatus sea success, o espere el webhook project.created.
  3. POST /v1/projects/{projectId}/transcript con { "source": "original", "outputFormat": "srt" } y traduzca los cues conservando la numeración y los códigos de tiempo.
  4. POST /v1/projects/{projectId}/dub con el SRT traducido.
  5. Consulte el endpoint de estado hasta que status sea success, o espere project.translation.completed.
  6. Descargue translatedVideoUrl (o lipSync.videoUrl si se solicitó sincronización labial).
  7. DELETE /v1/translate/{projectId} cuando las salidas estén guardadas de su lado.

Errores

Los fallos de alineación detectados mientras se ejecuta la operación (TRANSLATED_SRT_UNMATCHED_CUES, TRANSLATED_SRT_MISSING_SEGMENTS) los devuelven el endpoint de estado y el webhook de fallo, no esta solicitud.