> ## Documentation Index
> Fetch the complete documentation index at: https://www.vozo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão Geral

> Traduzir e Dublar Vídeo/Áudio

A API de **Tradução e Dublagem** localiza conteúdo de vídeo e áudio para outro idioma, traduzindo o conteúdo falado e gerando fala dublada. Opcionalmente, você pode adicionar legendas traduzidas, sincronizar o vídeo com o áudio traduzido ou criar um projeto editável no aplicativo web da Vozo. Dependendo das suas configurações, a API retorna vídeo e/ou áudio traduzido, um arquivo de legenda SRT e uma URL do projeto.

## Entradas

### Mídia e idiomas

| Campo | Valores | Requisito | Descrição |
| - | - | - | - |
| `media_type` | `video`, `audio` | Obrigatório | Especifica se a mídia de entrada é um arquivo de vídeo ou de áudio. |
| `media_url` | URL de mídia acessível publicamente | Obrigatório | URL da mídia de entrada. A duração máxima suportada é de 2 horas. |
| `source_language` | `auto` ou um código de idioma compatível | Obrigatório | Idioma de origem da mídia de entrada. Use `auto` para detectá-lo automaticamente. |
| `target_language` | Código de idioma compatível, com localidade opcional | Obrigatório | Idioma de destino para tradução e dublagem. |

### Fontes de texto de legenda

Use estes campos se tiver texto de legendas original ou traduzido para fornecer. Caso contrário, pode ignorar esta secção.

| Field | Values | Requirement | Description |
| - | - | - | - |
| `subtitle_url` | URL SRT acessível publicamente | Opcional; emparelhado com `subtitle_usage_type`; requer plano Studio ou superior | Usa diretamente o texto no SRT fornecido como texto de origem ou texto traduzido final, conforme especificado por `subtitle_usage_type`, em vez de gerá-lo por reconhecimento de fala ou tradução. Mutuamente exclusivo com `ocr_text_box`. |
| `subtitle_usage_type` | `original`, `final_translated` | Opcional; emparelhado com `subtitle_url`; requer plano Studio ou superior | Determina como o texto SRT é usado: `original` o usa como texto de origem, enquanto `final_translated` o usa como o texto traduzido final. Não possui valor padrão. |
| `ocr_text_box` | `{ x, y, width, height }` | Opcional; somente vídeo; requer plano Studio ou superior | Detecta legendas incorporadas dentro da região especificada do Texto na tela e usa o texto detectado como texto de origem. Suporta apenas chinês e inglês; o texto detectado não pode ser usado como o texto traduzido final. As coordenadas são normalizadas de 0 a 1, com a origem no canto superior esquerdo. Mutuamente exclusivo com `subtitle_url`. |

### Tradução e dublagem

Use estes campos para personalizar modelos, definições ou requisitos de tradução e dublagem. Caso contrário, pode ignorar esta secção.

| Campo | Valores | Requisito | Descrição |
| - | - | - | - |
| `speaker_number` | `{ min, max }` | Opcional | Especifica o intervalo esperado de número de locutores. `min` deve ser pelo menos 1 e `max` não pode exceder 35. Omita este campo para detecção automática. |
| `voice_model` | `auto`, `real`, `native` | Opcional | Seleciona o modelo de clonagem de voz usado para dublagem. O padrão é `auto`: `auto` seleciona automaticamente o melhor modelo para o seu conteúdo; `real` usa VoiceREAL para preservar a emoção e o sotaque da voz original; `native` usa VoiceNATIVE para oferecer um sotaque mais natural no idioma de destino. |
| `selected_voice_id` | String | Opcional | Usa uma voz específica da Biblioteca de Vozes no aplicativo web da Vozo para dublagem. Quando este campo é fornecido, ele substitui `voice_model`: a API ignora a clonagem automática de voz e usa a voz selecionada para gerar o áudio dublado. ![Image](https://mintcdn.com/vozo/1CKzcnsK5IeqtcUf/images/image-11.png?fit=max\&auto=format\&n=1CKzcnsK5IeqtcUf\&q=85\&s=49b19170ed246ec4d64cbc5c6676b376) |
| `align_video` | Boolean | Opcional; apenas vídeo | Quando definido como `true`, ajusta automaticamente a velocidade do vídeo para que o áudio traduzido e o vídeo permaneçam sincronizados durante todo o conteúdo. O padrão é `false`. Defina como `false` se o áudio traduzido for usado como uma faixa de áudio adicional no YouTube. |
| `glossary_ids` | Array de até 3 IDs | Opcional; requer o plano Studio ou superior | Aplica glossários criados no aplicativo web da Vozo para manter a terminologia consistente. ![Glossary Pn](https://mintcdn.com/vozo/sj4I9dYZwuKc04yr/images/glossary_ids.jpg?fit=max\&auto=format\&n=sj4I9dYZwuKc04yr\&q=85\&s=35c7b79a4eadaa526c8c09b43b92e666) |
| `user_prompt` | String | Opcional | Fornece instruções de tradução ou dublagem, como preferências de tom, estilo ou terminologia. |

### Saída de legendas

Use estes campos se quiser adicionar legendas traduzidas ao vídeo ou apagar e substituir as legendas existentes. Caso contrário, pode ignorar esta secção.

| Field | Values | Requirement | Description |
| - | - | - | - |
| `subtitle_mode` | `none`, `add`, `replace` | Opcional | Controla a renderização das legendas: não renderizar legendas, adicionar legendas traduzidas ou apagar legendas existentes antes de renderizar as legendas traduzidas. O padrão é `none`. |
| `subtitle_style_id` | String | Opcional; aplica-se com `add` ou `replace` | Aplica um estilo de legenda copiado de um projeto no aplicativo web da Vozo. Se omitido, será usado o estilo de legenda padrão integrado. ![Subtitle Style ID Pn](https://mintcdn.com/vozo/fWvdwDyxU-DjjZ00/images/subtitle_id.jpeg?fit=max\&auto=format\&n=fWvdwDyxU-DjjZ00\&q=85\&s=649a7eaf112a1bab8bfe268c7876c9e6) |
| `subtitle_position_y` | Número de `0` a `1` | Opcional; aplica-se com `add` ou `replace` | Define a posição vertical da legenda, da parte superior (`0`) até a parte inferior (`1`). Por exemplo, `0.75` posiciona as legendas em 75% da altura do vídeo. Veja as regras de posicionamento abaixo. Quando `enable_proofreading` é `true` e `subtitle_mode` é `replace`, este campo não tem efeito. |

> [!NOTE]
>
> Se `subtitle_style_id` for omitido, será usado o estilo padrão integrado. Ele exibe uma única linha centralizada usando texto branco Noto Sans Medium no tamanho de fonte 14, com contorno externo preto e uma sombra preta sutil. A largura da legenda é 80% do vídeo, sem fundo, efeito de palavra ativa ou transição.
>
> Se `subtitle_position_y` for omitido, seu valor não virá do estilo de legenda selecionado. A posição é determinada por `subtitle_mode`:
>
> * Para `add`, o padrão é `0,9` para vídeos horizontais e quadrados, e `0,75` para vídeos verticais.
> * Para `replace`, as legendas são posicionadas na posição original da legenda.
>
> Quando `enable_proofreading` for `true` e `subtitle_mode` for `replace`, a posição da legenda permanecerá na região onde as legendas originais foram apagadas após a dublagem ser concluída no projeto. Qualquer valor especificado em `subtitle_position_y` será ignorado.

### Projeto e saída

| Campo | Valores | Requisito | Descrição |
| - | - | - | - |
| `project_mode` | `none`, `editable` | Opcional | Controla se um projeto editável é criado no aplicativo web da Vozo. O padrão é `none`. Com `editable`, um projeto é criado e a mídia final ainda é exportada de acordo com `export_type` e disponibilizada para download. |
| `enable_proofreading` | Boolean | Opcional; requer o plano Studio ou superior | Ativa o fluxo de revisão. O padrão é `false`. Quando ativado, um projeto é sempre criado, `project_mode` é ignorado e nenhuma mídia final é exportada, independentemente de `export_type`. Se usado com `subtitle_mode: replace`, a posição da legenda permanecerá na região original de remoção das legendas após a dublagem do projeto ser concluída, e `subtitle_position_y` será ignorado. |
| `export_type` | `auto`, `video`, `audio`, `all` | Condicional; obrigatório quando `enable_proofreading` é `false` | Seleciona o formato de saída e não tem valor padrão. `auto` corresponde ao tipo de entrada. Para entrada de áudio, `video` e `all` não são compatíveis. |
| `callback_url` | URL | Opcional | Recebe um webhook sempre que o status da tarefa muda. |

## Saídas

(dependendo de `export_type`, `project_mode` e `enable_proofreading`):

* URL de vídeo e/ou áudio traduzido
* `subtitle_url` traduzida (SRT)
* `project_url` quando um projeto é criado no Painel de Controle web

## Como funciona

**1. Hospede seus recursos em uma URL acessível publicamente**

Envie seu vídeo ou áudio, junto com quaisquer recursos opcionais, para que nossos servidores possam recuperá-los.

**2. Envie uma solicitação de API**

Forneça as entradas obrigatórias e quaisquer configurações opcionais necessárias para a tarefa.

**3. Aguarde ou consulte o status**

Use nosso callback de webhook ou consulte a API com o ID da sua tarefa até que o processamento seja concluído.

**4. Baixe as saídas**

Recupere o vídeo/áudio traduzido e a legenda traduzida (.srt) a partir das URLs fornecidas.

## Limitações de uso

* Somente usuários que podem criar chaves de API podem usar esta API.
* O limite de simultaneidade padrão é de 10 tarefas. O limite é compartilhado por todos os membros de uma equipe. Consulte [Limites de simultaneidade](https://www.vozo.ai/docs/pt/api_reference/get_started.md#concurrency-limits) para mais detalhes.
* O código de idioma segue o padrão IETF BCP 47, por exemplo, en‑US.

## Códigos de erro da API

| Código | Descrição |
| - | - |
| 5 | Parâmetros de solicitação inválidos. |
| 7 | Sem permissão para solicitar. |
| 104 | Créditos insuficientes. |
| 814 | Sua conta não é membro e não tem permissão para chamar a API. |
| 1000 | Erro interno do servidor. |
| 1301 | Falha no Callback Challenge. |
| 1302 | A chave de API foi revogada. |
| 1304 | A chave de API atingiu o número máximo de solicitações simultâneas. |
| 1503 | Sua conta não está autorizada a chamar a API. |

## Códigos de erro da tarefa

| Código | Descrição |
| - | - |
| 10001 | O arquivo enviado não possui fluxo de vídeo |
| 10002 | O vídeo enviado não possui fluxo de áudio |
| 10003 | Falha na transcodificação |
| 10004 | Falha ao gerar a saída HLS |
| 10005 | Falha no recorte do vídeo |
| 10010 | Falha na separação de voz (fala vs. fundo) |
| 10020 | Falha no reconhecimento automático de fala (ASR) |
| 10021 | Falha no ASR com múltiplos locutores |
| 10022 | Falha na diarização de locutores (chinês) |
| 10023 | Falha ao gerar legendas completas |
| 10030 | Falha na tradução |
| 10031 | Idiomas mistos detectados; falha na agregação após ajuste de pontuação |
| 10032 | Falha na extração por OCR |
| 10033 | Idioma de OCR não compatível |
| 10034 | Falha no alinhamento da legenda (SRT) |
| 10040 | Falha na clonagem de voz |
| 10041 | Nenhum conteúdo de fala reconhecido |
| 10042 | Nenhuma fala detectada |
| 10043 | Falha na reclonagem de voz |
| 10044 | O texto de pré-visualização para TTS está vazio |
| 10045 | Falha ao gerar o áudio de pré-visualização |

## Idiomas compatíveis

### Idiomas de origem

Observação: "auto" é compatível para detectar automaticamente o idioma de origem e atualizar o idioma de origem quando detectado.

| Code | Name |
| - | - |
| auto | Detecção Automática |
| en-US | Inglês (Estados Unidos) |
| en-GB | Inglês (Reino Unido) |
| en-AU | Inglês (Austrália) |
| en-CA | Inglês (Canadá) |
| en-GH | Inglês (Gana) |
| en-HK | Inglês (Hong Kong) |
| en-IE | Inglês (Irlanda) |
| en-IN | Inglês (Índia) |
| en-KE | Inglês (Quênia) |
| en-NG | Inglês (Nigéria) |
| en-NZ | Inglês (Nova Zelândia) |
| en-PH | Inglês (Filipinas) |
| en-SG | Inglês (Singapura) |
| en-TZ | Inglês (Tanzânia) |
| en-ZA | Inglês (África do Sul) |
| zh-CN | Chinês (China, Simplificado) |
| zh-HK | Chinês (Hong Kong, Tradicional) |
| zh-TW | Chinês (Taiwan, Tradicional) |
| es-ES | Espanhol (Espanha) |
| es-MX | Espanhol (México) |
| es-US | Espanhol (Estados Unidos) |
| es-AR | Espanhol (Argentina) |
| es-BO | Espanhol (Bolívia) |
| es-CL | Espanhol (Chile) |
| es-CO | Espanhol (Colômbia) |
| es-CR | Espanhol (Costa Rica) |
| es-CU | Espanhol (Cuba) |
| es-DO | Espanhol (República Dominicana) |
| es-EC | Espanhol (Equador) |
| es-GQ | Espanhol (Guiné Equatorial) |
| es-GT | Espanhol (Guatemala) |
| es-HN | Espanhol (Honduras) |
| es-NI | Espanhol (Nicarágua) |
| es-PA | Espanhol (Panamá) |
| es-PE | Espanhol (Peru) |
| es-PR | Espanhol (Porto Rico) |
| es-PY | Espanhol (Paraguai) |
| es-SV | Espanhol (El Salvador) |
| es-UY | Espanhol (Uruguai) |
| es-VE | Espanhol (Venezuela) |
| ar-EG | Árabe (Egito) |
| ar-SA | Árabe (Arábia Saudita) |
| ar-AE | Árabe (Emirados Árabes Unidos) |
| ar-MA | Árabe (Marrocos) |
| ar-SY | Árabe (Síria) |
| ru-RU | Russo (Rússia) |
| pt-PT | Português (Portugal) |
| pt-BR | Português (Brasil) |
| fr-BE | Francês (Bélgica) |
| fr-CA | Francês (Canadá) |
| fr-CH | Francês (Suíça) |
| fr-FR | Francês (França) |
| de-DE | Alemão (Alemanha) |
| de-AT | Alemão (Áustria) |
| de-CH | Alemão (Suíça) |
| ko-KR | Coreano (Coreia do Sul) |
| ja-JP | Japonês (Japão) |
| hi-IN | Hindi (Índia) |
| tr-TR | Turco (Turquia) |
| ur-IN | Urdu |
| fil-PH | Filipino (Filipinas) |
| fi-FI | Finlandês (Finlândia) |
| cs-CZ | Tcheco (República Tcheca) |
| hu-HU | Húngaro (Hungria) |
| da-DK | Dinamarquês (Dinamarca) |
| nl-BE | Holandês (Bélgica) |
| nl-NL | Holandês (Países Baixos) |
| pl-PL | Polonês (Polônia) |
| ro-RO | Romeno (Romênia) |
| sk-SK | Eslovaco (Eslováquia) |
| sv-SE | Sueco (Suécia) |
| hr-HR | Croata (Croácia) |
| id-ID | Indonésio (Indonésia) |
| it-IT | Italiano (Itália) |
| it-CH | Italiano (Suíça) |
| bg-BG | Búlgaro (Bulgária) |
| el-GR | Grego (Grécia) |
| ms-MY | Malaio (Malásia) |
| ta-IN | Tâmil (Índia) |
| uk-UA | Ucraniano (Ucrânia) |
| sq-AL | Albanês (Albânia) |
| az-AZ | Azerbaijano (Azerbaijão) |
| eu-ES | Basco (Espanha) |
| bn-IN | Bengali (Índia) |
| bs-BA | Bósnio (Bósnia e Herzegovina) |
| yue-CN | Cantonês (China) |
| ca-ES | Catalão (Espanha) |
| gl-ES | Galego (Espanha) |
| gu-IN | Gujarati (Índia) |
| is-IS | Islandês (Islândia) |
| kn-IN | Kannada (Índia) |
| kk-KZ | Cazaque (Cazaquistão) |
| lv-LV | Letão (Letônia) |
| lt-LT | Lituano (Lituânia) |
| mk-MK | Macedônio (Macedônia do Norte) |
| ml-IN | Malaiala (Índia) |
| mt-MT | Maltês (Malta) |
| mr-IN | Marathi (Índia) |
| mn-MN | Mongol (Mongólia) |
| ne-NP | Nepali (Nepal) |
| nb-NO | Norueguês Bokmål (Noruega) |
| pa-IN | Punjabi (Índia) |
| sl-SI | Esloveno (Eslovênia) |
| so-SO | Somali (Somália) |
| sr-RS | Sérvio (Sérvia) |
| sw-KE | Suaíli (Quênia) |
| sw-TZ | Suaíli (Tanzânia) |
| uz-UZ | Usbeque (Uzbequistão) |
| vi-VN | Vietnamita (Vietnã) |
| he-IL | Hebraico (Israel) |
| fa-IR | Persa (Irã) |
| th-TH | Tailandês (Tailândia) |
| my-MM | Birmanês (Myanmar) |

### Idiomas de destino

| Code | Name | Locale variants |
| - | - | - |
| en | Inglês | en-US, en-GB, en-AU, en-CA, en-HK, en-KE, en-NZ, en-NG, en-PH, en-SG, en-ZA, en-TZ, en-IE, en-IN |
| zh | Chinês | zh-CN, zh-HK, zh-TW, zh-CN-shandong, zh-CN-liaoning, zh-CN-sichuan, zh-CN-henan, zh-CN-shaanxi, zh-CN-GUANGXI, zh-wuu |
| es | Espanhol | es-ES, es-MX, es-US, es-AR, es-BO, es-CL, es-CO, es-CR, es-CU, es-DO, es-EC, es-SV, es-GQ, es-GT, es-HN, es-NI, es-PA, es-PY, es-PE, es-PR, es-UY, es-VE |
| ar | Árabe | ar-DZ, ar-BH, ar-IQ, ar-JO, ar-KW, ar-LB, ar-LY, ar-MA, ar-OM, ar-QA, ar-SY, ar-TN, ar-AE, ar-YE, ar-EG, ar-SA |
| ru | Russo | |
| pt | Português | pt-PT, pt-BR |
| fr | Francês | fr-FR, fr-CA, fr-BE, fr-CH |
| de | Alemão | de-DE, de-AT, de-CH, de-GSW |
| ko | Coreano | |
| ja | Japonês | |
| hi | Hindi | |
| tr | Turco | |
| fil | Filipino | |
| fi | Finlandês | |
| cs | Tcheco | |
| da | Dinamarquês | |
| nl | Holandês | nl-BE, nl-NL |
| pl | Polonês | |
| ro | Romeno | |
| sk | Eslovaco | |
| sv | Sueco | |
| hr | Croata | |
| id | Indonésio | |
| it | Italiano | |
| bg | Búlgaro | |
| el | Grego | |
| ms | Malaio | |
| ta | Tâmil | ta-IN, ta-MY, ta-SG, ta-LK |
| uk | Ucraniano | |
| th | Tailandês | |
| vi | Vietnamita | |
| am | Amárico | |
| bn | Bengali | bn-BD |
| as | Assamês | |
| bs | Bósnio | |
| ca | Catalão | |
| et | Estoniano | |
| eu | Basco | |
| gl | Galego | |
| gu | Gujarati | |
| he | Hebraico | |
| hu | Húngaro | |
| iu | Inuktitut | iu-CANS-CA, iu-LATN-CA |
| jv | Javanês | |
| mk | Macedônio | |
| mr | Marathi | |
| nb | Norueguês Bokmål | |
| ne | Nepali | |
| or | Oriya | |
| pa | Punjabi | |
| ps | Pashto | |
| sl | Esloveno | |
| sw | Suaíli | sw-KE, sw-TZ |
| te | Telugu | |
| ur | Urdu | ur-IN, ur-PK |
| zu | Zulu | |
| af | Africâner | |
| az | Azerbaijano | |
| cy | Galês | |
| fa | Persa | |
| ga | Irlandês | |
| hy | Armênio | |
| is | Islandês | |
| ka | Georgiano | |
| kk | Cazaque | |
| km | Khmer | |
| kn | Kannada | |
| lo | Lao | |
| lt | Lituano | |
| lv | Letão | |
| ml | Malaiala | |
| mn | Mongol | |
| mt | Maltês | |
| my | Birmanês | |
| si | Cingalês | |
| so | Somali | |
| sq | Albanês | |
| sr | Sérvio | |
| su | Sudanês | |
| uz | Usbeque | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.