> ## 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.
# Overview
> Translate & Dub Video/Audio
The Translate & Dub API localizes video and audio content into another language by translating spoken content and generating dubbed speech. You can optionally add translated subtitles, synchronize video with the translated audio, or create an editable project in the Vozo web app. Depending on your settings, the API returns translated video and/or audio, an SRT subtitle file, and a project URL.
## Inputs
### Required input
* `media_type`: `video` or `audio`
* `media_url`: a publicly accessible media URL (maximum duration: 2 hours)
* `source_language`: `auto` or a supported source language code
* `target_language`: a supported target language code, with an optional locale
### Feature and export fields
#### Specifying input subtitles
| Field | Values | Description |
| --------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subtitle_url` | Publicly accessible SRT URL | Uses the supplied subtitles to improve recognition or as the final translation. Must be provided together with `subtitle_usage_type`; providing only one of these fields returns an error. Mutually exclusive with `ocr_text_box`. |
| `subtitle_usage_type` | `original`, `final_translated` | Specifies whether `subtitle_url` contains source-language subtitles or the final translated subtitles. Must be provided together with `subtitle_url` and has no default value. |
| `ocr_text_box` | `{ x, y, width, height }` | Uses the on-screen text region to improve recognition. Coordinates are normalized from 0 to 1, with the origin at the top-left. Video only; mutually exclusive with `subtitle_url`. |
#### Adding subtitles to the output video
| Field | Values | Description |
| --------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subtitle_mode` | `none`, `add`, `replace` | Controls subtitle rendering: do not render subtitles, add translated subtitles, or erase existing subtitles before rendering translated subtitles. Defaults to `none`. |
| `subtitle_style_id` | String | Applies a subtitle style copied from a project in the Vozo web app. Only applies when `subtitle_mode` is `add` or `replace`. If omitted, the built-in default subtitle style is used. 
|
| `subtitle_position_y` | Number from `0` to `1` | Sets the vertical subtitle position, from the top (`0`) to the bottom (`1`). Only applies when `subtitle_mode` is `add` or `replace`. For example, `0.75` places subtitles at 75% of the video height. See the default positioning rules below when this field is omitted. |
If `subtitle_style_id` is omitted, the built-in default style is used. It displays a single centered line using white Noto Sans Medium text at font size 14, an outside black stroke, and a subtle black shadow. The caption width is 80% of the video, with no background, active-word effect, or transition.
If `subtitle_position_y` is omitted, its value does not come from the selected subtitle style. The position is determined by `subtitle_mode`:
* For `add`, the default is `0.9` for landscape and square videos, and `0.75` for portrait videos.
* For `replace`, subtitles are placed at the original subtitle position.
#### Translation and dubbing
| Field | Values | Description |
| ---------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `speaker_number` | `{ min, max }` | Specifies the expected speaker-count range. `min` must be at least 1 and `max` cannot exceed 35. Omit it for automatic detection. |
| `voice_model` | `auto`, `real`, `native` | Selects the voice cloning model used for dubbing. Defaults to `auto`: `auto` automatically selects the best model for your content; `real` uses VoiceREAL to preserve the emotion and accent of the original voice; `native` uses VoiceNATIVE to deliver a more natural target-language accent. |
| `align_video` | Boolean | Video only. When set to `true`, automatically adjusts the video speed so the translated audio and video remain synchronized throughout. Defaults to `false`. Set it to `false` if the translated audio will be used as an additional audio track on YouTube. |
| `glossary_ids` | Array of up to 3 IDs | Applies glossaries created in the Vozo web app to keep terminology consistent. 
|
| `user_prompt` | String | Provides optional translation or dubbing instructions, such as tone, style, or terminology preferences. |
#### Project and export
| Field | Values | Description |
| --------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_mode` | `none`, `editable` | Controls whether an editable project is created in the Vozo web app. Defaults to `none`. With `editable`, a project is created and the final media is still exported according to `export_type` and made available for download. |
| `enable_proofreading` | Boolean | Enables the proofreading workflow. Defaults to `false`. When enabled, a project is always created, `project_mode` is ignored, and no final media is exported regardless of `export_type`. |
| `export_type` | `auto`, `video`, `audio`, `all` | Selects the output format. This field is required when `enable_proofreading` is `false` and has no default value. `auto` matches the input type. For audio input, `video` and `all` are not supported. |
| `callback_url` | URL | Receives a webhook whenever the job status changes. |
## Outputs
(depending on `export_type`, `project_mode`, and `enable_proofreading`):
* translated video and/or audio URL
* translated `subtitle_url` (SRT)
* `project_url` when a web dashboard project is created
## How it works
Upload your video or audio, and optional subtitle (.srt) so our servers can retrieve them.
If there is on‑screen text to translate, specify a normalized OCR box (x, y, width, height) from 0–1; origin at the top‑left of the frame.
Include source/target languages (e.g., en‑US → zh‑CN), then configure any optional subtitle, dubbing, project, timing, proofreading, and export features.
Use our webhook callback or poll the API with your task ID until processing is complete.
Retrieve translated video/audio and the translated subtitle (.srt) from the provided URLs.
## Usage Limitation
* Only users who can create API Keys may use this API.
* Studio plan is required; non‑Studio users are not allowed.
* Concurrency is limited independently from LipSync; queued requests are counted.
* Language code follows IETF BCP 47 standard, e.g., en‑US.
## API Error Codes
| Code | Description |
| ---- | ---------------------------------------------------------------- |
| 5 | Invalid request parameters. |
| 7 | No permission to request. |
| 104 | Insufficient credits. |
| 814 | Your account is not a member and is not allowed to call the API. |
| 1000 | Internal Server Error. |
| 1301 | Callback Challenge failed. |
| 1302 | API key has been revoked. |
| 1304 | API key has reached the maximum number of concurrent requests. |
| 1503 | Your account is not authorized to call the API. |
| 1305 | Only Studio plan is allowed. |
## Job Error Codes
| Code | Description |
| ----- | ------------------------------------------------------------------------- |
| 10001 | Uploaded file has no video stream |
| 10002 | Uploaded video has no audio stream |
| 10003 | Transcoding failed |
| 10004 | Failed to generate HLS output |
| 10005 | Video cropping failed |
| 10010 | Voice separation failed (speech vs. background) |
| 10020 | Automatic speech recognition (ASR) failed |
| 10021 | Multi‑speaker ASR failed |
| 10022 | Speaker diarization (Chinese) failed |
| 10023 | Failed to generate full subtitles |
| 10030 | Translation failed |
| 10031 | Mixed languages detected; aggregation failed after punctuation adjustment |
| 10032 | OCR extraction failed |
| 10033 | OCR language not supported |
| 10034 | Subtitle (SRT) alignment failed |
| 10040 | Voice cloning failed |
| 10041 | No recognized speech content |
| 10042 | No speech detected |
| 10043 | Re‑cloning voice failed |
| 10044 | Preview text for TTS is empty |
| 10045 | Failed to generate preview audio |
## Supported Languages
### Source Languages
Note: "auto" is supported to automatically detect the source language and update source language when detected.
| Code | Name |
| ------ | -------------------------------- |
| auto | Auto Detect |
| en-US | English (United States) |
| en-GB | English (United Kingdom) |
| en-AU | English (Australia) |
| en-CA | English (Canada) |
| en-GH | English (Ghana) |
| en-HK | English (Hong Kong) |
| en-IE | English (Ireland) |
| en-IN | English (India) |
| en-KE | English (Kenya) |
| en-NG | English (Nigeria) |
| en-NZ | English (New Zealand) |
| en-PH | English (Philippines) |
| en-SG | English (Singapore) |
| en-TZ | English (Tanzania) |
| en-ZA | English (South Africa) |
| zh-CN | Chinese (China, Simplified) |
| zh-HK | Chinese (Hong Kong, Traditional) |
| zh-TW | Chinese (Taiwan, Traditional) |
| es-ES | Spanish (Spain) |
| es-MX | Spanish (Mexico) |
| es-US | Spanish (United States) |
| es-AR | Spanish (Argentina) |
| es-BO | Spanish (Bolivia) |
| es-CL | Spanish (Chile) |
| es-CO | Spanish (Colombia) |
| es-CR | Spanish (Costa Rica) |
| es-CU | Spanish (Cuba) |
| es-DO | Spanish (Dominican Republic) |
| es-EC | Spanish (Ecuador) |
| es-GQ | Spanish (Equatorial Guinea) |
| es-GT | Spanish (Guatemala) |
| es-HN | Spanish (Honduras) |
| es-NI | Spanish (Nicaragua) |
| es-PA | Spanish (Panama) |
| es-PE | Spanish (Peru) |
| es-PR | Spanish (Puerto Rico) |
| es-PY | Spanish (Paraguay) |
| es-SV | Spanish (El Salvador) |
| es-UY | Spanish (Uruguay) |
| es-VE | Spanish (Venezuela) |
| ar-EG | Arabic (Egypt) |
| ar-SA | Arabic (Saudi Arabia) |
| ar-AE | Arabic (United Arab Emirates) |
| ar-MA | Arabic (Morocco) |
| ar-SY | Arabic (Syria) |
| ru-RU | Russian (Russia) |
| pt-PT | Portuguese (Portugal) |
| pt-BR | Portuguese (Brazil) |
| fr-BE | French (Belgium) |
| fr-CA | French (Canada) |
| fr-CH | French (Switzerland) |
| fr-FR | French (France) |
| de-DE | German (Germany) |
| de-AT | German (Austria) |
| de-CH | German (Switzerland) |
| ko-KR | Korean (South Korea) |
| ja-JP | Japanese (Japan) |
| hi-IN | Hindi (India) |
| tr-TR | Turkish (Turkey) |
| ur-IN | Urdu (India) |
| fil-PH | Filipino (Philippines) |
| fi-FI | Finnish (Finland) |
| cs-CZ | Czech (Czech Republic) |
| hu-HU | Hungarian (Hungary) |
| da-DK | Danish (Denmark) |
| nl-BE | Dutch (Belgium) |
| pl-PL | Polish (Poland) |
| ro-RO | Romanian (Romania) |
| sk-SK | Slovak (Slovakia) |
| sv-SE | Swedish (Sweden) |
| hr-HR | Croatian (Croatia) |
| id-ID | Indonesian (Indonesia) |
| it-IT | Italian (Italy) |
| it-CH | Italian (Switzerland) |
| bg-BG | Bulgarian (Bulgaria) |
| el-GR | Greek (Greece) |
| ms-MY | Malay (Malaysia) |
| ta-IN | Tamil (India) |
| uk-UA | Ukrainian (Ukraine) |
| sq-AL | Albanian (Albania) |
| az-AZ | Azerbaijani (Azerbaijan) |
| eu-ES | Basque (Spain) |
| bn-IN | Bengali (India) |
| bs-BA | Bosnian (Bosnia and Herzegovina) |
| yue-CN | Cantonese (China) |
| ca-ES | Catalan (Spain) |
| gl-ES | Galician (Spain) |
| gu-IN | Gujarati (India) |
| is-IS | Icelandic (Iceland) |
| kn-IN | Kannada (India) |
| kk-KZ | Kazakh (Kazakhstan) |
| lv-LV | Latvian (Latvia) |
| lt-LT | Lithuanian (Lithuania) |
| mk-MK | Macedonian (North Macedonia) |
| ml-IN | Malayalam (India) |
| mt-MT | Maltese (Malta) |
| mr-IN | Marathi (India) |
| mn-MN | Mongolian (Mongolia) |
| ne-NP | Nepali (Nepal) |
| nb-NO | Norwegian Bokmål (Norway) |
| pa-IN | Punjabi (India) |
| sl-SI | Slovenian (Slovenia) |
| so-SO | Somali (Somalia) |
| sr-RS | Serbian (Serbia) |
| sw-KE | Swahili (Kenya) |
| sw-TZ | Swahili (Tanzania) |
| uz-UZ | Uzbek (Uzbekistan) |
| vi-VN | Vietnamese (Vietnam) |
| he-IL | Hebrew (Israel) |
| fa-IR | Persian (Iran) |
| th-TH | Thai (Thailand) |
### Target Languages
| Code | Name | Locale variants |
| ---- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| en | English | en‑US, en‑GB, en‑AU, en‑CA, en‑HK, en‑KE, en‑NZ, en‑NG, en‑PH, en‑SG, en‑ZA, en‑TZ |
| zh | Chinese | zh‑CN, zh‑HK, zh‑TW, zh‑CN‑shandong, zh‑CN‑liaoning, zh‑CN‑sichuan, zh‑CN‑henan, zh‑CN‑shaanxi, zh‑CN‑GUANGXI |
| wuu | Wu Chinese | wuu‑CN |
| es | Spanish | 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 | Arabic | 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 |
| ru | Russian | ru‑RU |
| pt | Portuguese | pt‑PT, pt‑BR |
| fr | French | fr‑FR, fr‑CA, fr‑BE, fr‑CH |
| de | German | de‑DE, de‑AT, de‑CH |
| ko | Korean | ko‑KR |
| ja | Japanese | ja‑JP |
| hi | Hindi | hi‑IN |
| tr | Turkish | tr‑TR |
| fil | Filipino | fil‑PH |
| fi | Finnish | fi‑FI |
| cs | Czech | cs‑CZ |
| da | Danish | da‑DK |
| nl | Dutch | nl‑BE |
| pl | Polish | pl‑PL |
| ro | Romanian | ro‑RO |
| sk | Slovak | sk‑SK |
| sv | Swedish | sv‑SE |
| hr | Croatian | hr‑HR |
| id | Indonesian | id‑ID |
| it | Italian | it‑IT, it‑CH |
| bg | Bulgarian | bg‑BG |
| el | Greek | el‑GR |
| ms | Malay | ms‑MY |
| ta | Tamil | ta‑IN, ta‑MY, ta‑SG, ta‑LK |
| uk | Ukrainian | uk‑UA |
| th | Thai | th‑TH |
| vi | Vietnamese | vi‑VN |
| am | Amharic | am‑ET |
| bn | Bengali | bn‑IN, bn‑BD |
| as | Assamese | as |
| bs | Bosnian | bs‑BA |
| ca | Catalan | ca‑ES |
| et | Estonian | et‑EE |
| eu | Basque | eu‑ES |
| gl | Galician | gl‑ES |
| gu | Gujarati | gu |
| he | Hebrew | he‑IL |
| hu | Hungarian | hu‑HU |
| iu | Inuktitut | iu‑CANS‑CA, iu‑LATN‑CA |
| jv | Javanese | jv‑ID |
| mk | Macedonian | mk‑MK |
| mr | Marathi | mr |
| nb | Norwegian Bokmål | nb‑NO |
| ne | Nepali | ne‑NP |
| or | Oriya | or |
| pa | Punjabi | pa |
| ps | Pashto | ps‑AF |
| sl | Slovenian | sl‑SI |
| sw | Swahili | sw‑KE, sw‑TZ |
| te | Telugu | te‑IN |
| ur | Urdu | ur, ur‑IN, ur‑PK |
| zu | Zulu | zu‑ZA |