Video Translate
Translate the speech in a video into another language, with a new voice and lip movements to match, priced per frame of the source video.
Video Translate (product video_translate) translates what's said in a video into one of 18 languages, dubs it with a newly generated voice and redraws the speaker's mouth to match. One task makes one video in one language, priced per frame of the source video.
Create a task
https://api.nanoapi.ai/v1/tasksUse the shared create endpoint with model: "video-translate". It usually responds in under 1 second; the source video is read and the cost frozen in the background within a few seconds. Get the result once the task has finished.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <API key>, see Authentication. |
Content-Type | Yes | application/json |
Idempotency-Key | No | A unique string for every new task, ideally a UUID (1–255 characters). See Preventing duplicate tasks. |
Body
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | video-translate. |
video_url | string | Yes | The video to translate, at most 30 seconds. See Media. |
target_language | string | Yes | The language to translate into, one of the codes below. The source language is detected automatically. |
webhook_url | string | No | Notified when the task succeeds or fails: https, up to 2048 characters, not a private, loopback or reserved address. See Webhooks. |
One task translates into one language: for several languages, create one task per language.
Target languages
target_language | Language | target_language | Language |
|---|---|---|---|
en | English | es | Spanish |
zh | Chinese (Mandarin) | de | German |
fr | French | ar | Arabic |
hi | Hindi | pl | Polish |
it | Italian | id | Indonesian |
ja | Japanese | tl | Filipino |
ko | Korean | sv | Swedish |
pt | Portuguese | fi | Finnish |
ru | Russian | tr | Turkish |
Two-letter ISO 639-1 codes in lowercase, without a region (zh, not zh-CN); Filipino is tl. Any other value returns 400 invalid_request with param "target_language".
Translate a talk into Mandarin Chinese:
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 2d8e5b1f-7a3c-4e9d-b6f0-1c4a9e7d3b58" \
-d '{
"model": "video-translate",
"video_url": "https://example.com/talk.mp4",
"target_language": "zh"
}'Response: 200 OK. data is the newly created task, with only these fields; each one is described in Create a task: Response. Keep data.id to get the result. The cost is frozen within a few seconds of creation, and the task may fail at that point (for example if the source video is longer than 30 seconds): go by what retrieving the task or the webhook tells you.
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jbm8g0j3k6n9q2v5x8a1f4h7",
"model": "video-translate",
"status": "queued",
"error": null,
"created_at": "2026-11-15T08:30:00Z"
}
}Get the result
Measured from creation to the end: about 2.5–3 minutes for a 5-second video, slower when the generation service is busy. Once the task has finished (succeeded or failed), get the result either way:
- Webhook (recommended in production): if you passed
webhook_url, the full task is pushed to it once when the task finishes. See Webhooks. - Polling: call
GET /v1/tasks/{task_id}withdata.idat most once every 15 seconds untilstatusissucceededorfailed. Check several tasks at once withidsin List tasks.
The request above, once it has succeeded (other fields left out):
{
"status": "succeeded",
"input": {
"video_url": "https://example.com/talk.mp4",
"target_language": "zh"
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "video",
"url": "https://cdn.nanoapi.ai/h/tk_01jbm8g0j3k6n9q2v5x8a1f4h7_1_1794731400.mp4",
"preview_url": "https://cdn.nanoapi.ai/h/tk_01jbm8g0j3k6n9q2v5x8a1f4h7_1_1794731400_compressed.mp4"
}
],
"billing": {
"currency": "USD",
"frozen": "…", // worked out from the source video's frames, see Pricing
"charged": "…", // the same
"refunded": "0.00",
"billed_seconds": null
}
}| Field | Video Translate |
|---|---|
outputs | One item. |
outputs[0].type | video. |
outputs[0].url | The translated video, an h264 + AAC mp4, for downloading and playing. Same size, frame rate and length as the source video. Only the speaker's mouth area is redrawn; the whole audio track is replaced by the dubbed voice. |
outputs[0].preview_url | A silent, compressed h264 mp4 at most 600 pixels wide, for thumbnails only: play url to hear the translation. null if it couldn't be made. |
billing.billed_seconds | Always null: the cost is worked out from the source video, see Pricing. |
input | The parameters you sent. |
- The voice is newly generated, not a clone of the speaker's voice.
- Results are best with one speaker whose face is clear and facing the camera.
On failure the frozen amount is returned in full and the reason is in data.error.type, see Errors. Every field is described in The task object.
Media
The video is passed as a public http(s) URL in video_url. There's no upload endpoint: host the file yourself. URLs are at most 4096 characters, must download directly and can't point to localhost or private, loopback or reserved addresses.
Source video (video_url) | |
|---|---|
| Length | At most 30 seconds (limits.max_source_video_seconds in GET /v1/products) |
| If there's a problem | Read within a few seconds of creating the task: if it can't be read, the task fails with invalid_media; over 30 seconds, with video_too_long. Nothing is frozen. Downloaded again when generation runs: if that fails, the task fails with invalid_media and the frozen amount is returned in full. |
Keep the link reachable until the task finishes, including links that expire. Use a stable direct link, such as a file on your own storage: a slow or rate-limited host can make the second download fail.
Pricing
cost = ceil(frames × price per frame ÷ price step) × price stepLoading the current prices…
- Frames: the source video's frame count, known only once the platform reads the video. The same for every
target_language; a higher frame rate costs more (60 fps costs twice as much as 30 fps). - The result is rounded up to a whole multiple of
price_step(on thevideo_translaterow ofGET /v1/products). Compute in integer micro-dollars (amount × 1,000,000), not floats: a floating-point division can land just above a whole number (0.07 / 0.01is7.000000000000001in JavaScript) and round up one step too many. - Within a few seconds of creating the task, the source video is read, the cost worked out and frozen. When the task succeeds, the frozen amount is charged; when it fails, all of it is returned. How freezing and charging work in general: Billing.
billing.billed_secondsis alwaysnull.
Example: a 10-second, 30 fps video is 300 frames, so it costs ceil(300 × the price per frame ÷ price_step) × price_step.
To show a price before submitting, read the video's length on your side, estimate the frames as duration × frame rate and apply the current prices from GET /v1/products: the video_translate product has one prices row, with billing_unit frame, the price per frame in unit_price and the rounding step in price_step. Prices change, so don't hard-code them. It's an estimate: billing.frozen on the retrieved task is what counts (it's frozen within a few seconds of creation).
Errors
Errors and failure reasons specific to this model. Every error of the create endpoint: Create a task → Errors; every failure reason: Failure reasons.
Create request errors: the request fails with an HTTP error and no task is created. param names the parameter.
| Status | error.type | When | What to do |
|---|---|---|---|
400 | invalid_request | video_url or target_language is missing (Field required, param names it). | Send both. |
400 | invalid_request | target_language isn't one of the codes above (param "target_language"), video_url isn't a public http(s) URL of at most 4096 characters, or num_outputs isn't 1. | Fix the parameter param names. |
400 | invalid_request | A parameter this model doesn't take, such as prompt (Extra inputs are not permitted). | Remove it. |
Other errors of the create endpoint (401, 402, 429 and so on): Create a task → Errors.
Task failures: the create request succeeded (200) and the task later turned failed. There's no HTTP status: the reason is the task's error.type, from retrieving the task or the webhook.
error.type | When | What to do |
|---|---|---|
invalid_media | The source video can't be read: the link doesn't open or has expired, isn't public, or isn't a video. Within a few seconds of creating the task, nothing frozen. Or it couldn't be downloaded again when generation ran: after freezing, all of it is returned. | Use a stable, public, direct link to the video (for example on your own storage) and create the task again. |
video_too_long | The source video is longer than 30 seconds (The video duration must be at most 30 seconds.). Within a few seconds of creating the task, nothing frozen. | Trim the video to 30 seconds or less and create the task again. |
insufficient_balance | Your available balance can't cover the cost worked out from the source video. Within a few seconds of creating the task, nothing frozen. | Top up, then create the task again. |
spend_limit_exceeded | This task's cost would go over one of the key's spend limits. Within a few seconds of creating the task, nothing frozen. | Raise the limit in Console → API keys, or wait for it to reset, then create the task again. |
content_policy | The video breaks the content policy. | Resubmitting it as is fails again: use a different video. |
generation_failed | Generation failed. | Create it again later. |
queue_timeout / internal_error | Not started within 30 minutes / an error on our side. | Create it again later. |
Every failed task has its frozen amount returned in full and billing.charged "0.00". Branch on error.type: the quoted messages are for display and may change, see Messages.