> ## 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 Tradução
> Envie um arquivo de vídeo ou áudio e inicie um novo projeto de tradução
# Iniciar Tradução
Crie um novo projeto de tradução enviando um arquivo de vídeo ou áudio. O processo de tradução é executado de forma assíncrona em segundo plano. Use o [endpoint de status](/docs/pt/api-reference/translation-status) para acompanhar o progresso e recuperar resultados. Use [Obter Detalhes do Projeto](/docs/pt/api-reference/project-details) quando precisar do histórico da versão traduzida ou do histórico de sincronização labial.
## Limite de Simultaneidade
Você pode executar até 10 traduções ao mesmo tempo por conta. Se 10 traduções já estiverem em andamento, novas solicitações retornam `CONCURRENT_TRANSLATION_LIMIT_REACHED` (HTTP 429).
## Solicitação
Este endpoint aceita `multipart/form-data` com um upload de arquivo.
### Cabeçalhos
Sua chave de API VoiceCheap. Obtenha uma em [app.voicecheap.ai/page-api](https://app.voicecheap.ai/page-api).
### Parâmetros do corpo
O arquivo de vídeo ou áudio a ser traduzido.
**Formatos de vídeo suportados:** `video/mp4`, `video/quicktime`, `video/x-matroska`, `video/webm`, `video/mpeg`
**Formatos de áudio suportados:** `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/x-m4a`, `audio/flac`, `audio/ogg`, `audio/aac`, `audio/webm`
**Tamanho máximo de arquivo por plano:** Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB e Enterprise 60 GB.
O idioma para o qual o conteúdo será traduzido. Deve estar em letras minúsculas.
**Valores permitidos (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`
O idioma de origem do conteúdo usando códigos de idioma ISO (por exemplo, `en`, `es`, `fr`, `de`, `ja`, `zh`).
**Altamente recomendado: Deixe este campo vazio para detecção automática.**
Forneça este parâmetro apenas se tiver 100% de certeza de que o código do idioma está correto e no formato ISO válido. Códigos de idioma incorretos causarão falhas na transcrição. Nossa detecção automática suporta mais de 80 idiomas e é altamente precisa.
**Padrão:** `auto-detect`
Um nome personalizado para o projeto. Útil para identificar projetos em seu painel.
**Padrão:** O ID do projeto será usado se não for fornecido.
Um endpoint https que recebe a [eventos de webhook](/docs/pt/api-reference/webhooks) para este projeto,
substituindo o endpoint configurado em sua conta.
**Padrão:** O endpoint de webhook da conta, quando um estiver configurado.
`auto-detect` ou um número inteiro de `1` a `32`. Uma contagem de falantes conhecida pode melhorar a diarização.
**Padrão:** `auto-detect`
Uma matriz de strings JSON de nomes, marcas, siglas ou termos especializados específicos da solicitação. Esses termos são mesclados com o glossário salvo da conta ou da equipe.
Remova palavras de preenchimento comuns da transcrição de origem antes da tradução.
**Padrão:** `true`
Uma transcrição SRT existente no idioma de origem. `originalLanguage` deve ser explícito quando este campo for fornecido.
Se deve preservar o áudio de fundo na saída.
Quando ativado, mantém música de fundo, ambiente, risadas, aplausos e sons de multidão, removendo apenas a voz original (separação de stems). Desative se sua fonte não tiver áudio de fundo.
**Padrão:** `true`
Mantenha o falante original em volume baixo sob a voz traduzida.
**Padrão:** `false`
Volume da voz original de `1` a `70` quando `keepOriginalVoice` estiver ativado.
**Padrão:** `30`
Modo de isolamento de voz quando `keepBackgroundMusic` estiver ativado. Controla a qualidade e as características da separação de voz.
Nosso processamento de voz padrão, projetado para qualidade de áudio profissional:
* Remove ecos e reverberações
* Limpa imperfeições técnicas
* Produz uma voz clara e nítida
**Recomendado para:** A maioria dos projetos onde a qualidade do áudio é fundamental. Ideal para tutoriais, conteúdo educacional, vídeos de marketing e qualquer conteúdo que exija clareza de voz ideal.
Preserva as características naturais do ambiente de gravação:
* Mantém um som mais próximo da gravação original
* Preserva as características ambientais
**Recomendado para:** Conteúdo onde a autenticidade do ambiente é importante, como vlogs ao ar livre, documentários ou conteúdo onde o ambiente sonoro seja parte integrante da experiência.
Esta opção pode criar artefatos ou efeitos inesperados em alguns casos devido à preservação de elementos de fundo.
**Valores permitidos:** `studio`, `realistic`
**Padrão:** `studio`
Se deve gerar legendas para o vídeo traduzido.
Quando ativado, adiciona legendas limpas em preto e branco no estilo Netflix. Use `subtitlesSource` para escolher o texto original (idioma de origem) ou traduzido (idioma de destino). As legendas são sincronizadas automaticamente para uma legibilidade ideal.
**Nota:** Legendas embutidas (hard-burned) exigem FFmpeg com o filtro `subtitles` (libass). Se não estiver disponível, a API recorrerá à incorporação de uma faixa de legenda em vez de usar o estilo embutido.
**Padrão:** `false`
Escolha a fonte do texto das legendas quando `subtitles` estiver ativado.
**Valores permitidos:** `translated`, `original`
**Padrão:** `translated`
**Nota:** Se `original` for selecionado, mas a transcrição original não estiver disponível, as legendas usarão `translated` como alternativa.
Aciona o processamento de sincronização labial após a conclusão da dublagem.
* `standard` = Lip Sync
* `pro` = Lip Sync Pro
* `studio` = Lip Sync Studio
Os modos premium aplicam seus requisitos normais de plano, duração e créditos.
**Padrão:** omita o campo para ignorar a sincronização labial.
Ativa a detecção de orador ativo para a execução de sincronização labial solicitada.
**Padrão:** `false`
Seletor de sincronização labial legado mantido para compatibilidade com versões anteriores.
* `false` = Sincronização labial padrão (**4 minutos de créditos por 1 minuto de vídeo**)
* `true` = Lip Sync Pro (**9 minutos de créditos por 1 minuto de vídeo**)
Lip Sync Pro está disponível a partir do plano Creator.
**Duração máxima:** 30 minutos por vídeo.
**Latência:** O processamento de sincronização labial normalmente adiciona **2x-4x** a duração do vídeo original.
E-mails de conclusão e falha de sincronização labial não são enviados para solicitações acionadas por API. Use o [status endpoint](/docs/pt/api-reference/translation-status) para
acompanhar o progresso.
**Padrão:** não ativado (omita o campo para ignorar a sincronização labial)
**Form-data:** Envie valores booleanos como strings `true` ou `false` (por exemplo, `-F "lipsyncPro=false"`).
Não combine `lipsyncPro` com um `lipSyncMode` conflitante.
Estratégia de voz: `cloning` ou `custom`.
**Padrão:** `cloning`
Obrigatório quando `voiceMode` é `custom`. A voz deve pertencer ao proprietário efetivo do projeto. IDs de voz arbitrários ou sem proprietário são rejeitados.
Ajuste os parâmetros de clonagem de voz para controle avançado sobre a voz gerada. Passe como uma string JSON ao usar form-data. Todos os valores devem estar entre 0 e 1 (com incremento de 0,01).
Estas configurações aplicam-se apenas quando `voiceMode` é `cloning`.
**Estabilidade da voz (0,00 - 1,00)**
Determina quão estável é a voz e a aleatoriedade entre cada geração.
* **Valores mais baixos** permitem uma gama emocional mais ampla, mas podem causar uma fala estranha ou apressada
* **Valores mais altos** produzem uma saída mais consistente, mas podem soar monótonos
**Padrão:** `0.60`
**Dica:** Para evitar a reprodução de sotaque, use `0.80`
**Similaridade da voz (0,00 - 1,00)**
Controla o quanto a IA adere à voz original.
* **Valores mais altos** tornam a voz clonada mais semelhante à original
* Se o áudio original for ruidoso e a similaridade for muito alta, artefatos ou ruído de fundo podem ser transferidos para a voz gerada
**Padrão:** `0.85`
**Dica:** Para evitar a reprodução de sotaque, use `0.20`
**Reforço do orador (0,00 - 1,00)**
Aumenta a similaridade com o orador original. Este é um aprimoramento sutil que aumenta a semelhança com a voz de origem.
**Nota:** Valores mais altos aumentam o tempo de processamento e a latência.
**Padrão:** `0.60`
**Dica:** Para evitar a reprodução de sotaque, use `0.00`
**Valores padrão (equilibrados):**
```json theme={null}
{
"stability": 0.6,
"similarity": 0.85,
"speakerBoost": 0.6
}
```
**Recomendado para evitar a reprodução de sotaque:**
```json theme={null}
{
"stability": 0.8,
"similarity": 0.2,
"speakerBoost": 0.0
}
```
Uma matriz JSON de intervalos de tempo de origem que devem permanecer no idioma original.
```json theme={null}
[
{ "startTime": 10.2, "endTime": 12.8 }
]
```
Pulos de tempo exigem entrada de vídeo e `keepBackgroundMusic=true`. Eles não podem ser combinados com `keepOriginalVoice` e não podem sobrepor segmentos de transcrição.
## Resposta
Sempre `true` para solicitações bem-sucedidas
Uma mensagem legível por humanos descrevendo o resultado
O identificador único para o projeto de tradução criado. Use este ID para verificar o status.
Estimativa aproximada de processamento em minutos. A estimativa atual é de cinco minutos de processamento por minuto iniciado de mídia de origem.
## Exemplos
Regras de glossário salvas e instruções de tradução personalizadas da conta ou equipe efetiva são aplicadas 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'];
```
## Exemplo de Resposta
```json theme={null}
{
"success": true,
"message": "Translation started successfully. Use the status endpoint to track progress.",
"projectId": "abc123-def456-ghi789",
"estimatedDuration": 15
}
```
## Erros
| Status | Código | Descrição |
| ------ | ----------------------------------------------- | --------------------------------------------------------------------------------- |
| 400 | `FILE_REQUIRED` | Nenhum arquivo foi enviado com a solicitação |
| 400 | `INVALID_FILE_TYPE` | O tipo de arquivo enviado não é suportado |
| 400 | `DURATION_DETECTION_FAILED` | Não foi possível detectar a duração do arquivo enviado |
| 400 | `INVALID_MULTIPART_REQUEST` | Os dados do formulário multipart estão malformados ou excedem os limites de campo |
| 400 | `INVALID_BOOLEAN_VALUE` | Um parâmetro booleano tem um valor inválido (use "true" ou "false") |
| 400 | `INVALID_JSON_FORMAT` | O JSON voiceCloningSettings está malformado |
| 400 | `INVALID_BRAND_VOCABULARY` | Uma entrada de vocabulário específica da solicitação é inválida |
| 400 | `INVALID_SOURCE_SRT` | O SRT de origem fornecido está malformado |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt requer um originalLanguage explícito |
| 400 | `VOICE_ID_REQUIRED` | O modo de vozes personalizadas foi selecionado sem um ID de voz |
| 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | Um ID de voz foi combinado com clonagem de voz |
| 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | As configurações de clone foram combinadas com o modo de vozes personalizadas |
| 400 | `CONFLICTING_LIPSYNC_OPTIONS` | lipSyncMode entra em conflito com o lipsyncPro legado |
| 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | Pulos de tempo entram em conflito com outra opção de áudio |
| 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | Pulos de tempo requerem áudio de fundo |
| 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | Um pulo de tempo se estende além da duração da mídia |
| 400 | `INVALID_TRANSLATION_TIME_SKIPS` | Um pulo de tempo se sobrepõe a um segmento de transcrição |
| 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | Legendas embutidas foram solicitadas para entrada de áudio |
| 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | Sincronização labial foi solicitada para entrada de áudio |
| 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | Pulos de tempo foram solicitados para entrada de áudio |
| 400 | `LIPSYNC_VIDEO_TOO_LONG` | Sincronização labial foi solicitada para mídia com duração superior à suportada |
| 413 | `FILE_TOO_LARGE` | O arquivo enviado excede o limite do plano do usuário |
| 401 | `MISSING_API_KEY` | A chave de API é necessária |
| 401 | `INVALID_API_KEY_FORMAT` | A chave de API deve começar com `vc_` |
| 401 | `INVALID_API_KEY` | A chave de API fornecida é inválida |
| 403 | `API_ACCESS_REQUIRED` | O acesso à API é necessário para esta conta |
| 403 | `SUBSCRIPTION_REQUIRED` | O acesso à API requer uma assinatura paga |
| 403 | `INSUFFICIENT_CREDITS` | Créditos insuficientes para processar este arquivo |
| 403 | `CUSTOM_VOICE_ACCESS_DENIED` | A voz personalizada não pertence ao proprietário efetivo do projeto |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | O modo de sincronização labial premium não está disponível no plano atual |
| 429 | `RATE_LIMIT_EXCEEDED` | Muitas solicitações (limite: 10 solicitações por minuto) |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | Muitas traduções em andamento (limite: 10 traduções simultâneas) |