> ## 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.
# Adicionar um idioma de destino
> Adicione um trabalho vazio no idioma de destino a um projeto existente sem iniciar uma geração de mídia paga.
Adicione um trabalho vazio no idioma de destino a um projeto existente sem iniciar uma geração de mídia paga.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/translations_add
```
## Autenticação e permissões
Envie uma chave de API VoiceCheap neste cabeçalho. Authorization: Bearer com a mesma chave de API também é aceito. Tokens de acesso OAuth são
aceitos apenas pelo MCP, não por este endpoint REST.
Permissões necessárias: `translations:write`.
É necessária uma assinatura paga ativa. As permissões não alteram funções na equipe, propriedade dos recursos, créditos de mídia ou limites do plano.
## Parâmetros
Valor de texto.
Comprimento mínimo: 1. Comprimento máximo: 200. Padrão: `^[^/\\]+$`.
Valor de texto.
Valores aceitos: "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", "pt\_brazil", "punjabi", "romanian", "russian", "serbian", "slovak", "slovenian", "spanish", "swahili", "swedish", "tagalog", "tamil", "telugu", "thai", "turkish", "ukrainian", "urdu", "vietnamese", "welsh", "yoruba", "zulu".
Opcional na camada de transporte: o servidor insere um identificador antes da validação quando ele é omitido. Forneça seu próprio UUID v4 estável para recuperar com segurança uma resposta perdida.
Formato: "uuid". Padrão: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`.
O JSON Schema abaixo preserva os nomes exatos dos campos, tipos aninhados, valores padrão, limites e valores aceitos expostos pela descoberta. Regras adicionais entre campos são listadas nas notas da operação.
```json theme={null}
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"targetLanguage": {
"type": "string",
"enum": [
"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",
"pt_brazil",
"punjabi",
"romanian",
"russian",
"serbian",
"slovak",
"slovenian",
"spanish",
"swahili",
"swedish",
"tagalog",
"tamil",
"telugu",
"thai",
"turkish",
"ukrainian",
"urdu",
"vietnamese",
"welsh",
"yoruba",
"zulu"
]
},
"requestId": {
"type": "string",
"format": "uuid",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
"description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries."
}
},
"required": ["projectId", "targetLanguage"],
"additionalProperties": false
}
```
## Idempotência
Use um UUID v4 em requestId ou no cabeçalho HTTP Idempotency-Key para cada alteração. Reutilize o mesmo identificador e argumentos idênticos após uma falha de rede. Se ambos forem fornecidos, devem ser iguais. Repetir uma requisição salva não repete a operação nem consome outra chamada mensal. Requisições com falha ou interrompidas não são reiniciadas automaticamente.
Qualquer alteração pode retornar HTTP 202 quando uma nova tentativa encontra a mesma requisição ainda em execução, mesmo que a primeira execução normalmente seja síncrona. Se a execução foi concluída, mas resultStored é false, uma nova tentativa retorna HTTP 200 com o estado salvo da requisição em vez do resultado original. Recupere a saída pela ação de histórico, resultado ou download do domínio correspondente.
## Exemplos de requisição
Substitua os identificadores de recursos e as chaves de mídia dos exemplos pelos valores retornados para sua conta. Mantenha o identificador da requisição ao tentar novamente a mesma alteração.
```bash cURL theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/translations_add' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","targetLanguage":"english","requestId":"41321bda-e243-4b6f-96a4-622cd047c991"}'
```
```javascript JavaScript theme={null}
const input = {
projectId: 'project_launch_2026',
targetLanguage: 'english',
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/translations_add', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/translations_add",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "targetLanguage": "english", "requestId": "41321bda-e243-4b6f-96a4-622cd047c991"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```
## Resposta
Uma primeira execução bem-sucedida retorna HTTP 200 com o resultado da operação em data. Uma repetição pode retornar o estado salvo da requisição. O exemplo mostra uma resposta aceita, não todos os campos opcionais.
Retorna uma nova identidade de trabalho por idioma ou a projeção completa do trabalho existente quando esse idioma de destino já existe.
```json HTTP 200 theme={null}
{
"data": {
"projectId": "project_launch_2026",
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"targetLanguage": "english"
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "translations_add",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
```json HTTP 200 replay_completed_without_result theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "translations_add",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
## Campos do resultado
| Campo | Descrição |
| - | - |
| `data.workId` | Identificador do trabalho de idioma. |
| `data.projectId` | Identificador do projeto pai. |
| `data.targetLanguage` | Idioma de destino. |
| `data.originalLanguage` | Idioma de origem. |
| `data.createdAt` | Horário de criação do trabalho de idioma normalizado para milissegundos Unix. |
| `data.isWorkWaitingForProofreading` | Estado de revisão; false quando não definido explicitamente. |
| `data.pendingSegmentIndexes` | Índices de segmentos de origem ainda pendentes de tradução; array vazio por padrão. |
| `data.versions` | Todas as versões públicas deste trabalho, ordenadas da mais recente para a mais antiga. |
| `data.versions[].workId` | Identificador do trabalho de idioma que contém esta versão. |
| `data.versions[].translatedVersionId` | Identificador de uma versão específica da saída de dublagem. |
| `data.versions[].targetLanguage` | Idioma de destino da versão, usando como alternativa o idioma do seu trabalho de idioma. |
| `data.versions[].status` | Estado da versão armazenada: not-started, in-progress, completed ou failed. |
| `data.versions[].currentStep` | Etapa opcional do fluxo de dublagem; progress é um valor numérico opcional de progresso. |
| `data.versions[].progress` | Valor opcional de progresso da dublagem. |
| `data.versions[].createdAt` | Horário de criação normalizado em milissegundos Unix; usa como alternativa o horário de criação do trabalho de idioma. |
| `data.versions[].completedAt` | Horário opcional de conclusão em milissegundos Unix. |
| `data.versions[].failedAt` | Horário opcional da falha em milissegundos Unix. |
| `data.versions[].timedOutAt` | Horário opcional de esgotamento do prazo em milissegundos Unix. |
| `data.versions[].translatedVideoUrl` | URL armazenada do vídeo traduzido ou uma string vazia quando indisponível. |
| `data.versions[].translatedAudioUrl` | URL armazenada do áudio traduzido ou uma string vazia quando indisponível. |
| `data.versions[].error` | \{code,message} opcional quando a versão falhou. |
| `data.versions[].settings` | Configurações públicas da versão: voiceCloning, uploadType, keepBackgroundMusic, keepOriginalVoice, originalVoiceVolume, subtitles, smartSync, dubbingMode, voiceIsolatorOption e, opcionalmente, translationQualityMode, cutBecauseFreeUser, originalDurationSeconds, cutDurationSeconds, voiceCloningSettings. |
| `data.versions[].settings.dubbingMode` | translate ou dub-only. SmartSync é false para versões dub-only. |
| `data.versions[].lipSync` | \{latest,history} opcional; cada entrada tem jobId, status, videoUrl, errorMessage, type, createdAt e, opcionalmente, requestedAt, retryRequestedAt, completedAt, failedAt, timedOutAt, activeSpeakerDetectionEnabled, isRetried. Os horários de sincronização labial são armazenados como strings ISO. |
| `data.versions[].dynamicSubtitles` | Objeto opcional com used, inProgress, magicZooms, magicBrolls, magicBrollsPercentage, videoUrl, errorMessage e, opcionalmente, removeSilencePace, removeBadTakes, templateName, requestedAt, rerunCount. requestedAt está em milissegundos Unix. |
| `data.versions[].publicationAttempts` | Array opcional de tentativas públicas de publicação: id, status, origin, além dos opcionais scheduledAt, processingStartedAt, publishedAt, failedAt, privacyStatus, url, videoId, errorMessage. |
| `data.versions[].publishedVideos` | Array opcional com type, videoId, privacyStatus e, opcionalmente, url, datePublished, origin, scheduledAt, plannedPublicationId. |
## O idioma de destino já tem um trabalho neste projeto.
Retorna a projeção completa do trabalho de idioma existente; nenhum trabalho adicional é criado.
```json HTTP 200 theme={null}
{
"data": {
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"projectId": "project_launch_2026",
"targetLanguage": "english",
"originalLanguage": "fr",
"createdAt": 1792152000000,
"isWorkWaitingForProofreading": true,
"pendingSegmentIndexes": [0, 1],
"versions": []
}
}
```
## Recuperar e consultar esta requisição
Use o mesmo identificador mesmo após perder a conexão. Se resultStored for false, recupere a saída pela ação correspondente de histórico, resultado ou download. Nunca inicie uma segunda geração apenas para verificar o progresso.
```bash theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"41321bda-e243-4b6f-96a4-622cd047c991","operation":"translations_add"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "translations_add",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"projectId": "project_launch_2026",
"workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24",
"targetLanguage": "english"
}
}
}
```
## Notas da operação
* Adicionar um novo idioma não inicia transcrição, tradução ou geração de fala. O novo trabalho aguarda revisão e começa com todos os índices de segmentos de origem pendentes.
* O fluxo de novo trabalho retorna exatamente projectId, workId e targetLanguage. O fluxo de trabalho existente retorna a mesma projeção de translations\_get.
* Inicie o processamento efetivo da mídia separadamente com translations\_start ou translations\_dub.
* As falhas salvas retornam códigos de erro da VoiceCheap e mensagens fixas. Use o código e o estado atual do recurso para decidir como se recuperar.
## Uso
Cada chamada bem-sucedida consome uma chamada mensal da API/MCP. Os créditos de mídia e as cotas de geração da própria operação também se aplicam.
## Erros
| Status HTTP | Código | Significado ou recuperação |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Foram fornecidas credenciais em um parâmetro de consulta access\_token ou api\_key. Envie as credenciais nos cabeçalhos. |
| 400 | `IDEMPOTENCY_CONFLICT` | O cabeçalho Idempotency-Key e o campo requestId do corpo devem ser iguais. |
| 400 | `INVALID_REQUEST_ID` | Forneça um requestId ou Idempotency-Key no formato UUID v4. |
| 400 | `VALIDATION_ERROR` | Corrija a entrada usando o esquema. Valores inválidos ou inconsistentes são rejeitados antes da execução. |
| 401 | `API_KEY_EXPIRED` | A chave de API expirou. |
| 401 | `INVALID_API_KEY` | Forneça uma chave de API válida e dentro do prazo de validade. |
| 401 | `INVALID_CREDENTIAL` | O cabeçalho Authorization está malformado ou entra em conflito com x-api-key. |
| 401 | `MISSING_CREDENTIAL` | Nenhuma credencial utilizável foi fornecida no cabeçalho, ou ela excedeu 4096 caracteres. |
| 401 | `USER_NOT_FOUND` | A conta da credencial não existe mais. |
| 403 | `ACCOUNT_UNAVAILABLE` | A conta que executa a ação ou a conta de cobrança está indisponível ou em processo de exclusão. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | O usuário da credencial pertence a mais de uma equipe, portanto o contexto de cobrança é ambíguo. |
| 403 | `FORBIDDEN` | O autor autenticado da ação não pode acessar este projeto. |
| 403 | `INSUFFICIENT_SCOPE` | Conceda todas as permissões necessárias ou escolha outra credencial. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Não foi possível verificar os limites de integração da conta. |
| 403 | `SUBSCRIPTION_REQUIRED` | Use uma assinatura paga ativa. |
| 403 | `TEAM_OWNER_NOT_FOUND` | Não foi possível encontrar a conta efetiva do proprietário da equipe. |
| 404 | `PROJECT_NOT_FOUND` | O projeto não existe na conta acessível. |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | Esta conta já tem 10 ações de integração em execução. Consulte uma requisição existente antes de iniciar outra. |
| 409 | `IDEMPOTENCY_CONFLICT` | Reutilize um identificador apenas com a mesma operação e os mesmos argumentos. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Aguarde a renovação do limite mensal ou mude de plano. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Aguarde o prazo de Retry-After, quando presente, e aumente progressivamente o intervalo entre as tentativas. |
| 500 | `INTERNAL_ERROR` | Verifique o estado da requisição salva e o histórico do recurso antes de decidir repetir uma alteração. |
| 503 | `ACTION_RESULT_UNAVAILABLE` | A ação foi executada, mas não foi possível salvar seu resultado. Inspecione o estado salvo da requisição e o histórico do recurso antes de iniciar uma nova geração. |
| 503 | `SERVER_RESTARTING` | O servidor está reiniciando. Tente novamente em breve e mantenha o mesmo identificador de requisição para uma alteração. |
```json theme={null}
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["translations:write"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.