Merge Audio Video
音视频合并:用一段音频替换视频原来的声音,输出 mp4,按视频画面的时长计价。
Merge Audio Video(产品 merge_audio_video)用一段音频替换视频原来的声音,输出 mp4。用 FFmpeg 处理,不经过生成模型,一般几秒到几十秒就能完成。一个任务出 1 段视频,按视频画面的时长计价,和音频无关。
创建任务
https://api.nanoapi.ai/v1/tasks用所有模型共用的创建任务接口,model 传 "merge-audio-video"。接口通常不到 1 秒返回,几秒内在后台读取视频、冻结费用;任务结束后获取结果。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API Key>,见鉴权 |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 每个新任务一个唯一字符串,建议用 UUID(1–255 个字符),见防止重复创建 |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | merge-audio-video |
video_url | string | 是 | 视频,1–60 秒。支持 mp4、mov、m4v、webm、mkv,暂不支持 gif。见素材 |
audio_url | string | 是 | 音频,支持 mp3、wav、m4a、aac、ogg、flac。也可以传带音轨的视频,取它的第一条音轨。见素材 |
start_offset | number | 否 | 音频从视频的第几秒开始,单位秒,可以带小数,在这之前是静音。不传时从头开始(0)。不能小于 0,要小于视频时长(最大不到 60) |
webhook_url | string | 否 | 任务成功或失败时通知该地址:https,最长 2048 字符,不能指向内网、回环或保留地址。见回调 |
给一段视频换上配音,配音从第 1.5 秒开始:
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c3a9e-2b7d-4e58-9a0c-d4e8b2f71c35" \
-d '{
"model": "merge-audio-video",
"video_url": "https://example.com/clip.mp4",
"audio_url": "https://example.com/voice.mp3",
"start_offset": 1.5
}'响应:200 OK。data 是刚创建的任务,只有下面这几个字段,各字段的含义见创建任务的返回。保存 data.id,用它获取结果。创建后几秒内才冻结费用,任务可能在这时失败(例如视频超过 60 秒),以查询或回调的结果为准。
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
"model": "merge-audio-video",
"status": "queued",
"error": null,
"created_at": "2026-11-15T08:30:00Z"
}
}获取结果
一般几秒到几十秒结束,主要花在下载素材上。任务结束(成功或失败)后用下面任一方式拿结果:
- 回调(生产环境推荐):创建时传了
webhook_url,任务结束时会把完整的任务推送一次,见回调。 - 轮询:用
data.id调用GET /v1/tasks/{task_id},间隔 15 秒以上,直到status为succeeded或failed;多个任务用列出任务的ids一次查询。
上面的请求成功后(省略了其他字段):
{
"status": "succeeded",
"input": {
"video_url": "https://example.com/clip.mp4",
"audio_url": "https://example.com/voice.mp3",
"start_offset": 1.5
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "video",
"url": "https://cdn.nanoapi.ai/h/tk_01jb8z5q4w3e2r1t0y9u8i7o6p_1_1792658900.mp4",
"preview_url": null
}
],
"billing": {
"currency": "USD",
"frozen": "…", // 按视频画面的时长算出的价格,见价格
"charged": "…", // 一样
"refunded": "0.00",
"billed_seconds": null
}
}| 字段 | Merge Audio Video |
|---|---|
outputs | 1 项 |
outputs[0].type | video |
outputs[0].url | 合并后的视频,mp4,时长和视频画面一样。画面是 h264 / HEVC 的原样保留,不重新编码,画质不变;其他编码(VP9、AV1 等)转成 h264。声音统一转成 AAC |
outputs[0].preview_url | 一直是 null:这个模型没有预览,直接用 url |
billing.billed_seconds | 一直是 null:费用按视频画面的时长计算,见价格 |
input | 你传的参数 |
- 音频比视频长时,多出的部分截掉;比视频短时,后面补静音。音频不用自己裁。
- 视频原来的声音直接去掉,不和新音频混在一起。
- 结果文件保存 15 天,需要长期使用请及时下载,见结果。
失败时冻结的钱全额退回,原因在 data.error.type,见错误。完整的字段见任务对象。
素材
视频和音频以公开的 http(s) 链接放在 video_url、audio_url 里提交。不提供上传接口,请自行托管文件。链接最长 4096 字符,必须能直接下载,不能是网页地址,也不能指向 localhost 或内网、回环、保留地址。
视频(video_url) | 音频(audio_url) | |
|---|---|---|
| 格式 | mp4、mov、m4v、webm、mkv,暂不支持 gif | mp3、wav、m4a、aac、ogg、flac;或者带音轨的视频,取第一条音轨 |
| 时长 | 1–60 秒(GET /v1/products 的 limits.min_source_video_seconds、max_source_video_seconds) | 按视频画面的时长截掉多出的部分或补静音 |
| 什么时候读取 | 创建后几秒内读取(算价格):读不了时任务失败(invalid_media),超过 60 秒、不到 1 秒时任务失败(video_too_long / video_too_short),不冻结费用。处理时还会再下载一次:下载失败时任务失败(invalid_media),冻结的钱全额退回 | 处理时才读取:下载不到、格式不支持、传的视频没有音轨时任务失败(invalid_media),冻结的钱全额退回 |
任务结束前链接要保持可访问,有有效期的链接也不能提前过期。建议用放在你自己存储上的直链,不要直接用第三方网站的链接:源站慢或限速时,处理时的下载可能失败。
价格
费用 = round(视频画面的秒数 × 每秒单价 ÷ 0.00039) × 0.00039正在读取当前价格…
- 秒数:视频画面(视频轨)的时长,平台读取视频后才知道。和音频、
start_offset无关。 - 总价四舍五入到 $0.00039 的整数倍。这个步长不在
GET /v1/products里:merge_audio_video那一行的price_step是null。请用整数微美元(金额 × 1,000,000)计算,不要用浮点数。 - 创建后几秒内读取视频、算出价格再冻结。成功后扣冻结的金额,失败全额退回。冻结和扣费的通用规则见计费。
billing.billed_seconds一直是null。
想在提交前显示价格:自己读出视频的时长,用 GET /v1/products 返回的当前单价计算:merge_audio_video 产品的 prices 只有一行,billing_unit 是 second,每秒单价在 unit_price。价格会调整,不要写死。算出来的是预估,实际费用以查询任务返回的 billing.frozen 为准(创建后几秒内冻结)。
错误
这个模型特有的错误和失败原因。创建任务的全部错误见创建任务 → 错误,全部失败原因见失败原因。
创建请求出错:请求返回 HTTP 错误,任务不会创建。param 是对应的参数名。
| 状态码 | error.type | 何时出现 | 怎么处理 |
|---|---|---|---|
400 | invalid_request | 没传 video_url 或 audio_url(Field required,param 是缺的那个) | 两个都要传 |
400 | invalid_request | start_offset 小于 0、不小于 60,或者不是数字(param 为 "start_offset");video_url、audio_url 不是公开的 http(s) 链接或者超过 4096 字符;num_outputs 不是 1 | 按 param 改正 |
400 | invalid_request | 传了这个模型没有的参数,例如 audio_urls、prompt(Extra inputs are not permitted) | 去掉这个参数 |
创建接口的其他错误(401、402、429 等)见创建任务 → 错误。
任务失败:创建请求成功(200),任务之后变成 failed。这种情况没有 HTTP 状态码,原因在任务的 error.type,通过查询任务或回调拿到。
error.type | 何时出现 | 怎么处理 |
|---|---|---|
invalid_media | 视频读不了:下载不到、格式不支持、没有画面(gif 也是这样),message 说明是哪一种。创建后几秒内出现,不冻结费用 | 换成能公开直接下载、格式支持的视频,重新创建 |
video_too_long | 视频超过 60 秒(The video duration must be at most 60 seconds.)。创建后几秒内出现,不冻结费用 | 把视频裁到 60 秒以内,重新创建 |
video_too_short | 视频不到 1 秒(The video duration must be at least 1 second.)。创建后几秒内出现,不冻结费用 | 换一段更长的视频 |
invalid_request | start_offset 不小于视频时长(start_offset must be less than the duration of the video.)。创建后几秒内出现,不冻结费用 | 把 start_offset 改小,重新创建 |
insufficient_balance | 可用余额不够按视频算出的费用。创建后几秒内出现,不冻结费用 | 充值后重新创建 |
spend_limit_exceeded | 加上这个任务的费用会超出 Key 的消费限额。创建后几秒内出现,不冻结费用 | 在控制台 → API Keys 调高限额,或者等限额重置后重新创建 |
invalid_media | 音频用不了:下载不到、格式不支持、传的视频没有音轨(The audio could not be used. Make sure audio_url is a publicly downloadable audio file, or a video with an audio track.)。或者处理时视频再次下载失败。这时已经冻结过费用,全额退回 | 换成稳定、能公开直接下载的链接(例如放在你自己的存储上),重新创建 |
content_policy | 视频内容未通过审核 | 原样重新提交还会失败,请换一段视频 |
generation_failed | 处理失败 | 稍后重新创建 |
queue_timeout / internal_error | 排队超过 30 分钟未开始 / 内部错误 | 稍后重新创建 |
所有失败的任务都已全额退回冻结金额,billing.charged 为 "0.00"。程序判断请用 error.type:括号里的 message 用于展示,措辞可能调整,见每种原因的 message。