Merge Videos
多视频拼接:把 2–10 个视频首尾相接,不重新编码,输出 MP4,按各段视频的总时长计价。
Merge Videos(产品 merge_videos)把 2–10 个视频按传入的顺序首尾相接,输出 MP4。用 FFmpeg 处理,不经过生成模型,不重新编码,画质不变;因此各段视频的规格必须一致(见素材)。一个任务输出 1 段视频,按各段视频的总时长计价。
创建任务
https://api.nanoapi.ai/v1/tasks用所有模型共用的创建任务接口,model 传 "merge-videos"。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API Key>,见鉴权 |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 每个新任务一个唯一字符串,建议用 UUID(1–255 个字符),见防止重复创建 |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | merge-videos |
video_urls | string[] | 是 | 2–10 个视频,按数组顺序拼接。各段规格必须一致:画面为 H.264 或 HEVC,音频为 AAC、MP3 或无音轨,每个最大 500 MB。见素材 |
webhook_url | string | 否 | 任务成功或失败时通知该地址:https,最长 2048 字符,不能指向内网、回环或保留地址。见回调 |
拼接三段视频:
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "merge-videos",
"video_urls": [
"https://example.com/1.mp4",
"https://example.com/2.mp4",
"https://example.com/3.mp4"
]
}'响应:200 OK,返回新建的任务(字段说明)。保存 data.id,用它获取结果;任务创建后仍可能失败,见错误。
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
"model": "merge-videos",
"status": "queued",
"error": null,
"created_at": "2026-11-17T08:30:00Z"
}
}获取结果
通常几秒到几十秒完成,耗时主要在下载视频。传了 webhook_url 时通过回调获取结果,否则轮询 GET /v1/tasks/{task_id},间隔不少于 15 秒,直到 status 为 succeeded 或 failed(多个任务用列出任务的 ids 一次查询)。
上面的请求成功后(省略了其他字段,完整字段见任务对象):
{
"status": "succeeded",
"input": {
"video_urls": [
"https://example.com/1.mp4",
"https://example.com/2.mp4",
"https://example.com/3.mp4"
]
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "video",
"url": "https://cdn.nanoapi.ai/h/tk_01jb8z5q4w3e2r1t0y9u8i7o6p_1_1792831800.mp4",
"preview_url": null
}
],
"billing": {
"currency": "USD",
"frozen": "…", // 按各段视频的总时长算出的价格,见价格
"charged": "…", // 一样
"refunded": "0.00",
"billed_seconds": null
}
}| 字段 | Merge Videos |
|---|---|
outputs | 1 项 |
outputs[0].type | video |
outputs[0].url | 拼接后的视频,MP4,画面和声音原样复制(不重新编码) |
outputs[0].preview_url | 始终为 null,请直接使用 url |
billing.billed_seconds | 始终为 null:费用按各段视频的总时长计算,见价格 |
input | 传入的参数 |
结果文件保存 15 天,见结果。
素材
视频放在 video_urls 里,以公开、可直接下载的 http(s) 链接传入(不能是网页地址):最长 4096 字符,不能指向 localhost 或内网、回环、保留地址,任务结束前必须保持可访问(有有效期的签名链接也一样)。不提供上传接口。
视频(video_urls) | |
|---|---|
| 段数 | 2–10 段(GET /v1/products 的 limits.min_videos、max_videos) |
| 格式 | 画面为 H.264 或 HEVC;音频为 AAC 或 MP3,或无音轨 |
| 大小 | 每个最大 500 MB |
| 时长 | 总计至少 1 秒(limits.min_duration_seconds) |
| 什么时候读取 | 创建后几秒内读取(用于计算价格):某一段无法读取、编码不支持、超过 500 MB 时任务失败(invalid_media),各段规格不一致时任务失败(invalid_request),不冻结费用。处理时还会再下载一次:下载失败,或者此时才发现规格不一致,任务失败,冻结金额全额退回 |
各段的规格必须一致,因为拼接时不重新编码:
- 画面的编码、分辨率、帧率、像素格式、旋转角度必须相同;
- 音频的编码、采样率、声道数必须相同,且要么都有音轨,要么都没有。
同一个模型以相同设置生成的视频通常一致,Trim Video 裁剪出的片段也可以重新拼接。手机相册裁剪过的视频可能无法拼接。
规格不一致时任务按 invalid_request 失败,见错误。每次只报告第一处不一致,修正后重新创建任务才会报告下一处。
能确定是哪一段视频导致失败时(invalid_media 或 invalid_request),message 末尾会加上 The problem is with video_urls[N].(N 从 0 开始)。
建议用放在你自己存储上的直链,不要直接用第三方网站的链接:源站慢或限速时,处理时的下载可能失败。
价格
费用 = round(各段视频的总秒数 × 每秒单价 ÷ 0.00039) × 0.00039正在读取当前价格…
- 秒数:所有视频的时长之和,读取视频后才能确定。
- 总价四舍五入到 $0.00039 的整数倍。该步长不在
GET /v1/products中:merge_videos这一行的price_step为null。请用整数微美元计算,见金额。
当前单价见 GET /v1/products(merge_videos 产品的 prices 只有一行,billing_unit 是 second,每秒单价在 unit_price,乘以各段视频的总时长可以在提交前预估费用),以任务的 billing.frozen 为准;冻结和扣费规则见计费。
错误
请求错误
请求出错时返回 HTTP 错误,不会创建任务:
{
"code": 400,
"message": "Field required",
"error": {
"type": "invalid_request",
"param": "video_urls",
"details": null
},
"request_id": "rq_01jb8z9x2c4v6b8n0m1q3w5e7r"
}| HTTP 状态码 | error.type | 说明 |
|---|---|---|
| 400 | invalid_request | 缺少必填参数、取值不符合参数表的要求,或传了不支持的参数;param 指出是哪个参数 |
| 401 | invalid_api_key | API Key 无效、已删除或已重置 |
| 402 | insufficient_balance | 可用余额为 0 |
| 402 | spend_limit_exceeded | API Key 的消费限额已用满 |
| 403 | account_suspended | 账号已停用 |
| 409 | idempotency_key_reused | 同一个 Idempotency-Key 用在了请求体不同的请求上 |
| 429 | rate_limited | 请求过于频繁 |
| 500 | internal_error | 服务端错误,任务可能已创建 |
details 字段和处理方式见创建任务 → 错误。
任务失败
任务创建后仍可能失败:status 变为 failed,原因在 error 中,没有 HTTP 状态码。失败的任务不扣费,已冻结的金额全额退回。
{
"status": "failed",
"error": {
"type": "invalid_media",
"message": "The video file is too large. Each video must be at most 500 MB. The problem is with video_urls[2]."
}
}error.type | 说明 |
|---|---|
invalid_media | 某一段视频无法下载、编码不是 H.264 或 HEVC 画面加 AAC、MP3 音频或无音轨,或超过 500 MB |
video_too_short | 各段视频加起来不到 1 秒 |
invalid_request | 各段规格不一致(见素材),手机相册裁剪过的视频开头还可能有不一致的隐藏帧 |
insufficient_balance | 可用余额不足以支付本次费用 |
spend_limit_exceeded | 本次费用会超出 API Key 的消费限额 |
generation_failed | 生成失败 |
queue_timeout | 排队超过 30 分钟未开始 |
internal_error | 内部错误 |
程序判断请用 error.type;message 是面向开发者的英文说明,措辞可能调整。各原因的出现阶段、是否冻结过费用和 message 原文见失败原因。