Video Translate
视频翻译:把视频里说的话翻译成另一种语言重新配音,口型对上新的配音,按源视频的帧数计价。
Video Translate(产品 video_translate)把视频里说的话翻译成 18 种语言之一,用新生成的声音配音,并重画说话人的嘴型,让口型对上新的配音。一个任务出 1 段视频、翻成 1 种语言,按源视频的帧数计价。
创建任务
https://api.nanoapi.ai/v1/tasks用所有模型共用的创建任务接口,model 传 "video-translate"。接口通常不到 1 秒返回,几秒内在后台读取源视频、冻结费用;任务结束后获取结果。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API Key>,见鉴权 |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 每个新任务一个唯一字符串,建议用 UUID(1–255 个字符),见防止重复创建 |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | video-translate |
video_url | string | 是 | 要翻译的视频,最长 30 秒,见素材 |
target_language | string | 是 | 翻译成哪种语言,取值见下表。源语言会自动识别 |
webhook_url | string | 否 | 任务成功或失败时通知该地址:https,最长 2048 字符,不能指向内网、回环或保留地址。见回调 |
一个任务只翻成一种语言,要翻成多种语言请每种语言创建一个任务。
目标语言
target_language | 语言 | target_language | 语言 |
|---|---|---|---|
en | 英语 | es | 西班牙语 |
zh | 中文(普通话) | de | 德语 |
fr | 法语 | ar | 阿拉伯语 |
hi | 印地语 | pl | 波兰语 |
it | 意大利语 | id | 印尼语 |
ja | 日语 | tl | 菲律宾语 |
ko | 韩语 | sv | 瑞典语 |
pt | 葡萄牙语 | fi | 芬兰语 |
ru | 俄语 | tr | 土耳其语 |
语言代码是 ISO 639-1 的两个字母,全小写,不带地区(zh,不是 zh-CN);菲律宾语用 tl。传了表里没有的值返回 400 invalid_request,param 为 "target_language"。
把一段演讲翻译成中文(普通话):
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"
}'响应:200 OK。data 是刚创建的任务,只有下面这几个字段,各字段的含义见创建任务的返回。保存 data.id,用它获取结果。创建后几秒内才冻结费用,任务可能在这时失败(例如源视频超过 30 秒),以查询或回调的结果为准。
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jbm8g0j3k6n9q2v5x8a1f4h7",
"model": "video-translate",
"status": "queued",
"error": null,
"created_at": "2026-11-15T08:30:00Z"
}
}获取结果
实测从创建到结束:5 秒的视频约 2.5–3 分钟,生成服务忙时会更慢。任务结束(成功或失败)后用下面任一方式拿结果:
- 回调(生产环境推荐):创建时传了
webhook_url,任务结束时会把完整的任务推送一次,见回调。 - 轮询:用
data.id调用GET /v1/tasks/{task_id},间隔 15 秒以上,直到status为succeeded或failed;多个任务用列出任务的ids一次查询。
上面的请求成功后(省略了其他字段):
{
"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": "…", // 按源视频的帧数算出的价格,见价格
"charged": "…", // 一样
"refunded": "0.00",
"billed_seconds": null
}
}| 字段 | Video Translate |
|---|---|
outputs | 1 项 |
outputs[0].type | video |
outputs[0].url | 翻译后的视频,mp4(h264 + AAC),用于下载和播放。尺寸、帧率、时长和源视频一样。画面只重画说话人的嘴部区域,整条音轨换成翻译后的配音 |
outputs[0].preview_url | 无声的压缩版 mp4(h264),宽最多 600,只用作缩略图:要听翻译后的配音请播放 url。生成不了预览时为 null |
billing.billed_seconds | 一直是 null:费用按源视频计算,见价格 |
input | 你传的参数 |
- 配音是新生成的声音,不是克隆原来说话人的声音。
- 画面里只有一个人说话、正脸清晰时效果最好。
失败时冻结的钱全额退回,原因在 data.error.type,见错误。完整的字段见任务对象。
素材
视频以公开的 http(s) 链接放在 video_url 里提交。不提供上传接口,请自行托管文件。链接最长 4096 字符,必须能直接下载,不能指向 localhost 或内网、回环、保留地址。
源视频(video_url) | |
|---|---|
| 时长 | 最长 30 秒(GET /v1/products 的 limits.max_source_video_seconds) |
| 有问题时 | 创建后几秒内读取:读不了时任务失败(invalid_media),超过 30 秒时任务失败(video_too_long),不冻结费用。生成时还会再下载一次:下载失败时任务失败(invalid_media),冻结的钱全额退回 |
任务结束前链接要保持可访问,有有效期的链接也不能提前过期。请用稳定的直链,例如放在你自己的存储上:源站慢或限速时,生成时的第二次下载可能失败。
价格
费用 = ceil(源视频帧数 × 每帧单价 ÷ 取整步长) × 取整步长正在读取当前价格…
- 帧数:源视频的帧数,平台读取视频后才知道。和
target_language无关;帧率越高越贵(60 帧是 30 帧的两倍)。 - 结果向上取整到
price_step(GET /v1/products里video_translate那一行的字段)的整数倍。请用整数微美元(金额 × 1,000,000)计算,不要用浮点数:浮点除法可能比整数多出一点点(JavaScript 里0.07 / 0.01是7.000000000000001),向上取整时就多算一档。 - 创建后几秒内读取源视频、算出价格再冻结。成功后扣冻结的金额,失败全额退回。冻结和扣费的通用规则见计费。
billing.billed_seconds一直是null。
例:10 秒、30 帧的视频是 300 帧,费用是 ceil(300 × 每帧单价 ÷ price_step) × price_step。
想在提交前显示价格:自己读出视频的时长,帧数按时长 × 帧率估算,用 GET /v1/products 返回的当前单价计算:video_translate 产品的 prices 只有一行,billing_unit 是 frame,每帧单价在 unit_price,取整步长在 price_step。价格会调整,不要写死。算出来的是预估,实际费用以查询任务返回的 billing.frozen 为准(创建后几秒内冻结)。
错误
这个模型特有的错误和失败原因。创建任务的全部错误见创建任务 → 错误,全部失败原因见失败原因。
创建请求出错:请求返回 HTTP 错误,任务不会创建。param 是对应的参数名。
| 状态码 | error.type | 何时出现 | 怎么处理 |
|---|---|---|---|
400 | invalid_request | 没传 video_url 或 target_language(Field required,param 是缺的那个) | 两个都要传 |
400 | invalid_request | target_language 不是上表里的语言代码(param 为 "target_language"),video_url 不是公开的 http(s) 链接或者超过 4096 字符,或者 num_outputs 不是 1 | 按 param 改正 |
400 | invalid_request | 传了这个模型没有的参数,例如 prompt(Extra inputs are not permitted) | 去掉这个参数 |
创建接口的其他错误(401、402、429 等)见创建任务 → 错误。
任务失败:创建请求成功(200),任务之后变成 failed。这种情况没有 HTTP 状态码,原因在任务的 error.type,通过查询任务或回调拿到。
error.type | 何时出现 | 怎么处理 |
|---|---|---|
invalid_media | 源视频读不了:链接打不开或已过期、不是公网地址,或者不是视频。创建后几秒内出现,不冻结费用。也可能是生成时再次下载失败,这时已经冻结过费用,全额退回 | 换成稳定、能公开直接下载的视频链接(例如放在你自己的存储上),重新创建 |
video_too_long | 源视频超过 30 秒(The video duration must be at most 30 seconds.)。创建后几秒内出现,不冻结费用 | 把视频裁到 30 秒以内,重新创建 |
insufficient_balance | 可用余额不够按源视频算出的费用。创建后几秒内出现,不冻结费用 | 充值后重新创建 |
spend_limit_exceeded | 加上这个任务的费用会超出 Key 的消费限额。创建后几秒内出现,不冻结费用 | 在控制台 → API Keys 调高限额,或者等限额重置后重新创建 |
content_policy | 视频不符合内容政策 | 原样重新提交还会失败,请换一段视频 |
generation_failed | 生成失败 | 稍后重新创建 |
queue_timeout / internal_error | 排队超过 30 分钟未开始 / 内部错误 | 稍后重新创建 |
所有失败的任务都已全额退回冻结金额,billing.charged 为 "0.00"。程序判断请用 error.type:括号里的 message 用于展示,措辞可能调整,见每种原因的 message。