Trim Video
视频裁剪:从视频中裁剪出一段,不重新编码,输出 MP4,按裁剪时长计价。
Trim Video(产品 trim_video)从视频中裁剪出一段,输出 MP4。用 FFmpeg 处理,不经过生成模型,不重新编码:画面和声音原样复制,画质不变。一个任务输出 1 段视频,按裁剪时长计价。
创建任务
https://api.nanoapi.ai/v1/tasks用所有模型共用的创建任务接口,model 传 "trim-video"。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <API Key>,见鉴权 |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 每个新任务一个唯一字符串,建议用 UUID(1–255 个字符),见防止重复创建 |
请求体
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | trim-video |
video_url | string | 是 | 视频:画面为 H.264 或 HEVC,音频为 AAC、MP3 或无音轨,最大 500 MB。见素材 |
start_time | number | 是 | 裁剪起点,从视频开头算起的秒数,可带小数。≥ 0,且必须小于视频时长。实际从该时间点之前的关键帧开始,见实际起点会提前 |
end_time | number | 条件必填 | 与 duration 二选一。裁剪终点,从视频开头算起的秒数,至少比 start_time 晚 1 秒。超过视频时长时裁到视频结尾 |
duration | number | 条件必填 | 与 end_time 二选一。从 start_time 起裁剪的秒数,至少 1 秒。超过视频结尾时裁到视频结尾 |
webhook_url | string | 否 | 任务成功或失败时通知该地址:https,最长 2048 字符,不能指向内网、回环或保留地址。见回调 |
从一段视频中裁出第 10–15 秒:
curl https://api.nanoapi.ai/v1/tasks \
-H "Authorization: Bearer $NANOAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "trim-video",
"video_url": "https://example.com/clip.mp4",
"start_time": 10,
"end_time": 15
}'响应:200 OK,返回新建的任务(字段说明)。保存 data.id,用它获取结果;任务创建后仍可能失败,见错误。
{
"code": 200,
"message": "success",
"data": {
"object": "task",
"id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
"model": "trim-video",
"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_url": "https://example.com/clip.mp4",
"start_time": 10,
"end_time": 15
},
"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
}
}| 字段 | Trim Video |
|---|---|
outputs | 1 项 |
outputs[0].type | video |
outputs[0].url | 裁剪出的视频,MP4,画面和声音原样复制(不重新编码) |
outputs[0].preview_url | 始终为 null,请直接使用 url |
billing.billed_seconds | 始终为 null:费用按裁剪时长计算,见价格 |
input | 传入的参数 |
结果文件保存 15 天,见结果。
实际起点会提前
不重新编码时只能从关键帧开始裁:结果从 start_time 之前最近的关键帧开始,会比 start_time 早,最多早一个关键帧间隔(AI 生成的视频常见 2–5 秒)。终点基本准确,带 B 帧的视频可能早几帧。因对齐关键帧而多出的开头部分不计费。
素材
视频放在 video_url 里,以公开、可直接下载的 http(s) 链接传入(不能是网页地址):最长 4096 字符,不能指向 localhost 或内网、回环、保留地址,任务结束前必须保持可访问(有有效期的签名链接也一样)。不提供上传接口。
视频(video_url) | |
|---|---|
| 格式 | 画面为 H.264 或 HEVC;音频为 AAC 或 MP3,或无音轨 |
| 大小 | 最大 500 MB |
| 时长 | start_time 之后至少保留 1 秒(GET /v1/products 的 limits.min_duration_seconds) |
| 什么时候读取 | 创建后几秒内读取(用于计算价格):无法读取、编码不支持、超过 500 MB 时任务失败(invalid_media),start_time 之后不到 1 秒时任务失败(video_too_short),不冻结费用。处理时还会再下载一次:下载失败时任务失败(invalid_media),冻结金额全额退回 |
建议用放在你自己存储上的直链,不要直接用第三方网站的链接:源站慢或限速时,处理时的下载可能失败。
价格
费用 = round(裁剪秒数 × 每秒单价 ÷ 0.00039) × 0.00039正在读取当前价格…
- 裁剪秒数:
end_time减start_time(end_time超过视频时长时按视频结尾计算),或者duration。start_time之前多出的开头部分(见实际起点会提前)不计入。 - 总价四舍五入到 $0.00039 的整数倍。该步长不在
GET /v1/products中:trim_video这一行的price_step为null。请用整数微美元计算,见金额。
当前单价见 GET /v1/products(trim_video 产品的 prices 只有一行,billing_unit 是 second,每秒单价在 unit_price,乘以裁剪秒数即可在提交前算出费用;end_time 或 duration 超过视频结尾时,算出的仅为预估),以任务的 billing.frozen 为准;冻结和扣费规则见计费。
错误
请求错误
请求出错时返回 HTTP 错误,不会创建任务:
{
"code": 400,
"message": "Field required",
"error": {
"type": "invalid_request",
"param": "video_url",
"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": "video_too_short",
"message": "The trimmed video must be at least 1 second long. Make sure start_time is at least 1 second before the end of the video."
}
}error.type | 说明 |
|---|---|
invalid_media | 视频无法下载、编码不是 H.264 或 HEVC 画面加 AAC、MP3 音频或无音轨,或超过 500 MB |
video_too_short | start_time 之后不到 1 秒 |
invalid_request | start_time 不小于视频时长 |
insufficient_balance | 可用余额不足以支付本次费用 |
spend_limit_exceeded | 本次费用会超出 API Key 的消费限额 |
generation_failed | 生成失败 |
queue_timeout | 排队超过 30 分钟未开始 |
internal_error | 内部错误 |
程序判断请用 error.type;message 是面向开发者的英文说明,措辞可能调整。各原因的出现阶段、是否冻结过费用和 message 原文见失败原因。