> ## 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. # Iniciar traducción > Suba un archivo de video o audio e inicie un nuevo proyecto de traducción # Iniciar traducción Cree un nuevo proyecto de traducción subiendo un archivo de video o audio. El proceso de traducción se ejecuta de forma asíncrona en segundo plano. Utilice el [endpoint de estado](/docs/es/api-reference/translation-status) para realizar un seguimiento del progreso y recuperar los resultados. Utilice [Obtener detalles del proyecto](/docs/es/api-reference/project-details) cuando necesite el historial de versiones traducidas o el historial de sincronización labial. ## Límite de concurrencia Puede ejecutar hasta 10 traducciones al mismo tiempo por cuenta. Si ya hay 10 traducciones en curso, las nuevas solicitudes devuelven `CONCURRENT_TRANSLATION_LIMIT_REACHED` (HTTP 429). ## Solicitud Este endpoint acepta `multipart/form-data` con una subida de archivo. ### Encabezados Tu clave de API VoiceCheap. Obtén una en [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api). ### Parámetros del cuerpo El archivo de video o audio a traducir. **Formatos de video admitidos:** `video/mp4`, `video/quicktime`, `video/x-matroska`, `video/webm`, `video/mpeg` **Formatos de audio admitidos:** `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/x-m4a`, `audio/flac`, `audio/ogg`, `audio/aac`, `audio/webm` **Tamaño máximo de archivo por plan:** Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB y Enterprise 60 GB. El idioma al que traducir el contenido. Debe estar en minúsculas. **Valores permitidos (más de 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` El idioma de origen del contenido utilizando códigos de idioma ISO (p. ej., `en`, `es`, `fr`, `de`, `ja`, `zh`). **Altamente recomendado: Déjalo vacío para la detección automática.** Solo proporciona este parámetro si estás 100% seguro de que el código de idioma es correcto y tiene un formato ISO válido. Los códigos de idioma incorrectos provocarán fallos en la transcripción. Nuestra detección automática admite más de 80 idiomas y es altamente precisa. **Predeterminado:** `auto-detect` Un nombre personalizado para el proyecto. Útil para identificar proyectos en tu panel de control. **Predeterminado:** Se utilizará el ID del proyecto si no se proporciona. Un endpoint https que recibe los [eventos de webhook](/docs/es/api-reference/webhooks) para este proyecto, anulando el endpoint configurado en tu cuenta. **Predeterminado:** El endpoint de webhook de la cuenta, cuando hay uno configurado. `auto-detect` o un número entero de `1` a `32`. Un número conocido de hablantes puede mejorar la diarización. **Predeterminado:** `auto-detect` Una matriz de cadenas JSON de nombres, marcas, acrónimos o términos especializados específicos de la solicitud. Estos términos se combinan con el glosario guardado de la cuenta o del equipo. Elimina las muletillas comunes de la transcripción original antes de la traducción. **Predeterminado:** `true` Una transcripción SRT existente en el idioma de origen. `originalLanguage` debe ser explícito cuando se proporciona este campo. Si se debe conservar el audio de fondo en la salida. Cuando está habilitado, mantiene la música de fondo, el ambiente, las risas, los aplausos y los sonidos de la multitud mientras elimina solo la voz original (separación de pistas). Desactívalo si tu fuente no tiene audio de fondo. **Predeterminado:** `true` Mantén al hablante original en un volumen bajo debajo de la voz traducida. **Predeterminado:** `false` Volumen de la voz original de `1` a `70` cuando `keepOriginalVoice` está habilitado. **Predeterminado:** `30` Modo de aislamiento de voz cuando `keepBackgroundMusic` está habilitado. Controla la calidad y las características de la separación de voz. Nuestro procesamiento de voz predeterminado, diseñado para una calidad de audio profesional: * Elimina ecos y reverberaciones * Limpia imperfecciones técnicas * Produce una voz clara y nítida **Recomendado para:** La mayoría de los proyectos donde la calidad del audio es primordial. Ideal para tutoriales, contenido educativo, videos de marketing y cualquier contenido que requiera una claridad de voz óptima. Conserva las características naturales del entorno de grabación: * Mantiene un sonido más cercano a la grabación original * Preserva las características ambientales **Recomendado para:** Contenido donde la autenticidad del entorno es importante, como vlogs al aire libre, documentales o contenido donde el ambiente sonoro sea una parte integral de la experiencia. Esta opción puede crear artefactos o efectos inesperados en algunos casos debido a la preservación de elementos de fondo. **Valores permitidos:** `studio`, `realistic` **Predeterminado:** `studio` Si se deben generar subtítulos para el video traducido. Cuando está habilitado, añade subtítulos limpios en blanco y negro al estilo Netflix. Usa `subtitlesSource` para elegir el texto original (idioma de origen) o traducido (idioma de destino). Los subtítulos se sincronizan automáticamente para una legibilidad óptima. **Nota:** Los subtítulos incrustados requieren FFmpeg con el filtro `subtitles` (libass). Si no está disponible, la API recurre a incrustar una pista de subtítulos en lugar de un estilo quemado permanentemente. **Predeterminado:** `false` Elija la fuente del texto de los subtítulos cuando `subtitles` esté habilitado. **Valores permitidos:** `translated`, `original` **Predeterminado:** `translated` **Nota:** Si se selecciona `original` pero la transcripción original no está disponible, los subtítulos recurrirán a `translated`. Activa el procesamiento de sincronización labial una vez completada la traducción. * `standard` = Lip Sync * `pro` = Lip Sync Pro * `studio` = Lip Sync Studio Los modos premium aplican sus requisitos normales de plan, duración y créditos. **Predeterminado:** omita el campo para omitir la sincronización labial. Habilite la detección de hablante activo para la ejecución de sincronización labial solicitada. **Predeterminado:** `false` Selector de sincronización labial heredado conservado para compatibilidad con versiones anteriores. * `false` = Sincronización labial estándar (**4 minutos de créditos por 1 minuto de video**) * `true` = Lip Sync Pro (**9 minutos de créditos por 1 minuto de video**) Lip Sync Pro está disponible a partir del plan Creator. **Duración máxima:** 30 minutos por video. **Latencia:** El procesamiento de sincronización labial suele añadir **2x-4x** la duración del video original. Los correos electrónicos de finalización y error de sincronización labial no se envían para las solicitudes activadas por API. Utilice el [endpoint de estado](/docs/es/api-reference/translation-status) para realizar un seguimiento del progreso. **Predeterminado:** no habilitado (omita el campo para omitir la sincronización labial) **Form-data:** Envíe valores booleanos como cadenas `true` o `false` (p. ej., `-F "lipsyncPro=false"`). No combine `lipsyncPro` con un `lipSyncMode` conflictivo. Estrategia de voz: `cloning` o `custom`. **Predeterminado:** `cloning` Requerido cuando `voiceMode` es `custom`. La voz debe pertenecer al propietario efectivo del proyecto. Se rechazarán los ID de voz arbitrarios o sin propietario. Ajuste los parámetros de clonación de voz para un control avanzado sobre la voz generada. Pase como una cadena JSON al usar form-data. Todos los valores deben estar entre 0 y 1 (con un incremento de 0.01). Estos ajustes solo se aplican cuando `voiceMode` es `cloning`. **Estabilidad de voz (0.00 - 1.00)** Determina qué tan estable es la voz y la aleatoriedad entre cada generación. * **Los valores más bajos** permiten un rango emocional más amplio, pero pueden causar un habla extraña o apresurada * **Los valores más altos** producen una salida más consistente, pero pueden sonar monótonos **Predeterminado:** `0.60` **Consejo:** Para evitar la reproducción de acentos, use `0.80` **Similitud de voz (0.00 - 1.00)** Controla qué tan fielmente se adhiere la IA a la voz original. * **Los valores más altos** hacen que la voz clonada sea más similar a la original * Si el audio original tiene ruido y la similitud es demasiado alta, los artefactos o el ruido de fondo pueden trasladarse a la voz generada **Predeterminado:** `0.85` **Consejo:** Para evitar la reproducción de acentos, use `0.20` **Refuerzo de hablante (0.00 - 1.00)** Aumenta la similitud con el hablante original. Esta es una mejora sutil que aumenta el parecido con la voz de origen. **Nota:** Los valores más altos aumentan el tiempo de cómputo y la latencia. **Predeterminado:** `0.60` **Consejo:** Para evitar la reproducción de acentos, use `0.00` **Valores predeterminados (equilibrados):** ```json theme={null} { "stability": 0.6, "similarity": 0.85, "speakerBoost": 0.6 } ``` **Recomendado para evitar la reproducción de acentos:** ```json theme={null} { "stability": 0.8, "similarity": 0.2, "speakerBoost": 0.0 } ``` Una matriz JSON de rangos de tiempo de origen que deben permanecer en el idioma original. ```json theme={null} [ { "startTime": 10.2, "endTime": 12.8 } ] ``` Los saltos de tiempo requieren entrada de video y `keepBackgroundMusic=true`. No se pueden combinar con `keepOriginalVoice` y no pueden superponerse a los segmentos de transcripción. ## Respuesta Siempre `true` para solicitudes exitosas Un mensaje legible por humanos que describe el resultado El identificador único para el proyecto de doblaje creado. Utilice este ID para comprobar el estado. Estimación aproximada del procesamiento en minutos. La estimación actual es de cinco minutos de procesamiento por cada minuto iniciado de medio de origen. ## Ejemplos Las reglas de glosario guardadas y las instrucciones de doblaje personalizadas de la cuenta o equipo efectivo se aplican automáticamente. ```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']; ``` ## Ejemplo de respuesta ```json theme={null} { "success": true, "message": "Translation started successfully. Use the status endpoint to track progress.", "projectId": "abc123-def456-ghi789", "estimatedDuration": 15 } ``` ## Errores | Estado | Código | Descripción | | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------ | | 400 | `FILE_REQUIRED` | No se cargó ningún archivo con la solicitud | | 400 | `INVALID_FILE_TYPE` | El tipo de archivo cargado no es compatible | | 400 | `DURATION_DETECTION_FAILED` | No se pudo detectar la duración del archivo cargado | | 400 | `INVALID_MULTIPART_REQUEST` | Los datos del formulario multipart están mal formados o exceden los límites de campo | | 400 | `INVALID_BOOLEAN_VALUE` | Un parámetro booleano tiene un valor no válido (use "true" o "false") | | 400 | `INVALID_JSON_FORMAT` | El JSON de voiceCloningSettings está mal formado | | 400 | `INVALID_BRAND_VOCABULARY` | Una entrada de vocabulario específica de la solicitud no es válida | | 400 | `INVALID_SOURCE_SRT` | El SRT de origen proporcionado está mal formado | | 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt requiere un originalLanguage explícito | | 400 | `VOICE_ID_REQUIRED` | Se seleccionó el modo de voces personalizadas sin un ID de voz | | 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | Se combinó un ID de voz con clonación de voz | | 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | Se combinaron los ajustes de clonación con el modo de voces personalizadas | | 400 | `CONFLICTING_LIPSYNC_OPTIONS` | lipSyncMode entra en conflicto con el lipsyncPro heredado | | 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | Los saltos de tiempo entran en conflicto con otra opción de audio | | 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | Los saltos de tiempo requieren audio de fondo | | 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | Un salto de tiempo se extiende más allá de la duración del medio | | 400 | `INVALID_TRANSLATION_TIME_SKIPS` | Un salto de tiempo se superpone a un segmento de transcripción | | 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | Se solicitaron subtítulos incrustados para la entrada de audio | | 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | Se solicitó sincronización labial para la entrada de audio | | 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | Se solicitaron saltos de tiempo para la entrada de audio | | 400 | `LIPSYNC_VIDEO_TOO_LONG` | Se solicitó sincronización labial para medios de mayor duración que la admitida | | 413 | `FILE_TOO_LARGE` | El archivo cargado excede el límite del plan del usuario | | 401 | `MISSING_API_KEY` | Se requiere una clave API | | 401 | `INVALID_API_KEY_FORMAT` | La clave API debe comenzar con `vc_` | | 401 | `INVALID_API_KEY` | La clave API proporcionada no es válida | | 403 | `API_ACCESS_REQUIRED` | Se requiere acceso a la API para esta cuenta | | 403 | `SUBSCRIPTION_REQUIRED` | El acceso a la API requiere una suscripción de pago | | 403 | `INSUFFICIENT_CREDITS` | No hay suficientes créditos para procesar este archivo | | 403 | `CUSTOM_VOICE_ACCESS_DENIED` | La voz personalizada no pertenece al propietario efectivo del proyecto | | 403 | `LIPSYNC_MODE_ACCESS_DENIED` | El modo de sincronización labial premium no está disponible en el plan actual | | 429 | `RATE_LIMIT_EXCEEDED` | Demasiadas solicitudes (límite: 10 solicitudes por minuto) | | 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | Demasiados doblajes en curso (límite: 10 doblajes simultáneos) |