视频切片与合并接口文档
按目标时长把视频切成多段,或按序号把多段拼成一条。均为异步,完成后查询或回调。
把一条视频按目标时长切成多段,或把多段视频按序号拼成一条。两个能力都是异步任务:提交后拿到任务号,再查询结果;请求里带了回调地址时,任务结束会再 POST 同一份结果。
需要自己拿到分段、或自行决定合并顺序时使用本接口。长视频去水印不必先切开再逐片提交,直接使用视频去水印的自动切片。
| 方法与路径 | 说明 |
|---|---|
POST /api/video_segment | 提交视频切片 |
POST /api/video_merge | 提交视频合并 |
GET /api/tasks/{request_id} | 查询任务 |
| 环境 | 根地址 |
|---|---|
| 测试 | https://test-star-api.aiaibase.com |
| 正式 | 尚未上线。上线后另行通知 |
路径接在根地址后面。例如测试环境提交切片:
POST https://test-star-api.aiaibase.com/api/video_segment请求体为 JSON,Content-Type: application/json。认证只使用请求头:
Authorization: Bearer {API Key}{API Key} 只能放在服务端。文档站或业务前端如果要在浏览器里调用,必须走服务端代理,不要把 Key 写进前端包体。测试 Key 向后端索取,不要使用正式客户的 Key 做联调。
所有响应都是同一结构。业务失败默认 HTTP 200,以 success 和 error.code 判断。鉴权失败是 HTTP 401。同一调用方请求号但请求体不同,是 HTTP 409。
| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 受理成功、处理中、处理成功为 true;失败为 false |
data | object | 成功或处理中的业务数据 |
message | string | 失败说明 |
error | object | 失败时的错误。含 code、message,参数错误时还有 details |
meta.request_id | string | 平台任务号。查询任务用这个值 |
meta.timestamp | string | 响应时间,例如 2026-11-03T16:04:21+08:00 |
{
"success": false,
"message": "视频地址必填",
"error": {
"code": 4102,
"message": "视频地址必填",
"details": [{ "field": "video_url", "message": "视频地址必填" }]
},
"meta": { "request_id": "…", "timestamp": "…" }
}调用方请求号:
- 字段可用
client_request_id,也可用别名request_id、task_id。建议每次提交都带。 - 这是调用方自己的单号,和响应里的
meta.request_id不是同一个值。 - 同一密钥下,相同调用方请求号且请求体完全一致时,返回第一次的任务结果,不会重复扣费。
- 同一密钥下,调用方请求号相同但请求体不同,返回 HTTP 409,业务码
4003。
回调地址三选一:callback_url、notice_url、notify_url,效果相同。有回调也可以继续轮询。
把一条视频按目标时长切成多段,返回每段地址和时长。实际按关键帧切,时长以结果里的 duration_ms 为准。video_url 可以是视频文件,也可以是 m3u8。加密 m3u8 还要带解密密钥。
- 方法:
POST - 路径:
/api/video_segment
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
video_url | 是 | string | 视频地址,http 或 https,公网可访问。支持视频文件和 m3u8 |
m3u8_key_url | 否 | string | m3u8 解密密钥地址,http 或 https。加密 m3u8 时与 m3u8_secret 至少传一个 |
m3u8_secret | 否 | string | m3u8 解密密钥。16 字节,写成 32 位十六进制。加密 m3u8 时与 m3u8_key_url 至少传一个 |
segment_second | 否 | int | 目标切片时长(秒),1–600,默认 10。这是目标值,实际按关键帧切 |
title | 否 | string | 任务标题,最多 200 字 |
bid | 否 | string | 业务编号,最多 200 字 |
client_request_id | 否 | string | 调用方请求号。建议必带 |
request_id | 否 | string | client_request_id 的别名 |
task_id | 否 | string | client_request_id 的别名 |
callback_url | 否 | string | 完成回调地址 |
notice_url | 否 | string | callback_url 的别名 |
notify_url | 否 | string | callback_url 的别名 |
普通视频文件和未加密 m3u8 不用传 m3u8_key_url、m3u8_secret。加密 m3u8 必须在这两个字段里至少传一个,由后端校验。密钥地址须为 http 或 https。密钥正文是 16 字节,写成 32 位十六进制。格式不对,或加密流两个字段都没传,提交会被拒绝。
若自行切片后再做单次去水印,用返回的 duration_ms 核对单段长度。上游默认只处理前 650 帧,完整处理需要打开 unlimited。长视频直接使用视频去水印的自动切片。
受理返回
HTTP 200。此时片段还没生成。记录 meta.request_id,用它查询进度。
{
"success": true,
"data": {
"client_request_id": "seg-20261103-001",
"status": "accepted"
},
"meta": {
"request_id": "d26ee65f-b00c-44ea-b867-119ec9126444",
"timestamp": "2026-11-03T16:04:21+08:00"
}
}请求示例
curl -X POST 'https://test-star-api.aiaibase.com/api/video_segment' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"video_url": "https://your-cdn.com/input.mp4",
"segment_second": 10,
"client_request_id": "seg-20261103-001",
"title": "第 1 集切片"
}'加密 m3u8 示例。m3u8_secret 可以代替 m3u8_key_url,至少传一个。
curl -X POST 'https://test-star-api.aiaibase.com/api/video_segment' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"video_url": "https://cdn.example.com/playlist.m3u8",
"m3u8_key_url": "https://cdn.example.com/keys/enc.key",
"segment_second": 10,
"client_request_id": "seg-20261109-001"
}'把多段视频按 index 升序拼成一条。服务端会再排序一次,调用方不必先排好。
- 方法:
POST - 路径:
/api/video_merge
各片段需为同一来源,编码、分辨率、帧率一致。同一次切片产出的片段满足这个条件。混合不同规格可能失败或出坏片。合并只做拼接,不改编码、不加字幕。
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
segments | 是 | array | 片段列表,1–200 条。也可以传 JSON 数组字符串 |
segments[].index | 是 | int | 序号,必须唯一。服务端按 index 升序合并 |
segments[].url | 是 | string | 片段地址,http 或 https |
title | 否 | string | 任务标题,最多 200 字 |
bid | 否 | string | 业务编号,最多 200 字 |
client_request_id | 否 | string | 调用方请求号。建议必带 |
request_id | 否 | string | client_request_id 的别名 |
task_id | 否 | string | client_request_id 的别名 |
callback_url | 否 | string | 完成回调地址 |
notice_url | 否 | string | callback_url 的别名 |
notify_url | 否 | string | callback_url 的别名 |
单次最多 200 段,超过返回业务码 1001。更长的视频先切成不超过 30 分钟的片段,再分段处理。
受理返回
与切片相同:data.status 为 accepted,记录 meta.request_id。
请求示例
curl -X POST 'https://test-star-api.aiaibase.com/api/video_merge' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"segments": [
{"index": 0, "url": "https://your-cdn.com/segment_0.mp4"},
{"index": 1, "url": "https://your-cdn.com/segment_1.mp4"}
],
"client_request_id": "merge-20261103-001",
"title": "第 1 集成片"
}'- 方法:
GET - 路径:
/api/tasks/{request_id} request_id:提交时返回的meta.request_id
只能查询当前密钥自己的任务。别人的任务,或任务不存在,返回业务码 1000。
curl 'https://test-star-api.aiaibase.com/api/tasks/{request_id}' \
-H 'Authorization: Bearer {API Key}'处理中:
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "seg-20261103-001"
},
"meta": { "request_id": "…", "timestamp": "…" }
}完成判定
完成条件是 success 为 true,且 data.out_data 存在且不为空。success 为 false 表示失败,看 error.code。
受理响应里 data.status 是字符串 accepted。完成结果里可能带数字 status(例如 2),这是上游业务码,只用于排查。提交时若已返回 accepted,之后的失败落在查询响应里,不会再有一次同步报错。
建议 3–5 秒轮询一次。页面离开后可以停,下次用同一个 request_id 继续查。任务最长等待 24 小时,超时记为失败,业务码 3601。
{
"success": true,
"data": {
"client_request_id": "seg-20261103-001",
"task_type": "video_segment",
"segment_count": 4,
"out_data": [
"https://fs-stg.aiaipic.win/video-segment/…/segment_0.mp4",
"https://fs-stg.aiaipic.win/video-segment/…/segment_1.mp4"
],
"segments": [
{
"index": 0,
"url": "https://fs-stg.aiaipic.win/…/segment_0.mp4",
"start_ms": 0,
"duration_ms": 12500,
"size": 4807229
},
{
"index": 1,
"url": "https://fs-stg.aiaipic.win/…/segment_1.mp4",
"start_ms": 12500,
"duration_ms": 8333,
"size": 3349335
}
],
"status": 2,
"error": null,
"error_code": "SUCCESS"
},
"meta": { "request_id": "…", "timestamp": "…" }
}| 字段 | 说明 |
|---|---|
out_data | 各分段地址,顺序与 index 一致 |
segments[].index | 序号 |
segments[].url | 分段地址 |
segments[].start_ms | 在原片中的起始毫秒 |
segments[].duration_ms | 本段时长(毫秒) |
segments[].size | 本段字节数 |
segment_count | 片段数量 |
error_code | 成功时为 SUCCESS |
segment_second 只是目标。要 10 秒时,实际可能是 12.5 秒。地址由产物服务控制,未承诺永久有效,拿到后转存到自己的存储。
{
"success": true,
"data": {
"client_request_id": "merge-20261103-001",
"task_type": "video_merge",
"out_data": ["https://fs-stg.aiaipic.win/video-merge/…/output.mp4"],
"segment_count": 4,
"duration_ms": 35817,
"size": 17062084,
"is_watermark": false,
"error": null,
"error_code": "SUCCESS"
},
"meta": { "request_id": "…", "timestamp": "…" }
}| 字段 | 说明 |
|---|---|
out_data | 成片地址,通常 1 个 |
segment_count | 参与合并的片段数量 |
duration_ms | 成片时长(毫秒) |
size | 成片字节数 |
is_watermark | 是否加水印,固定 false |
error_code | 成功时为 SUCCESS |
成片地址同样建议转存,不要把临时地址当作永久链接写入数据库。
失败示例:
{
"success": false,
"message": "视频任务失败",
"error": { "code": 3600, "message": "视频任务失败" },
"meta": { "request_id": "…", "timestamp": "…" }
}请求体带了 callback_url、notice_url 或 notify_url 时,任务进入终态后,服务端向该地址 POST 一份与查询任务相同的 JSON。没有回调地址时不会 POST。
| 项 | 值 |
|---|---|
| 方法 | POST |
| 请求体 | 与 GET /api/tasks/{request_id} 的响应 JSON 相同 |
| 成功条件 | 回调地址返回 HTTP 2xx |
| 重试 | 非 2xx 或连接失败时,30 秒后重试,最多 4 次 |
用 meta.request_id 或 data.client_request_id 对应自己的业务单。重复推送按同一任务号幂等处理。
| HTTP | 业务码 | 说明 | 处理 |
|---|---|---|---|
| 200 | 1000 | 任务不存在,或不属于当前密钥 | 用提交时返回的 meta.request_id |
| 200 | 1001 | 参数不合法 | 未知字段、合并超过 200 段、index 重复或取值越界、m3u8_secret 不是 32 位十六进制,或加密 m3u8 未提供密钥。看 error.details[].field |
| 401 | 1102 | 缺少 Authorization | 补请求头 |
| 200 | 1500 | 服务内部错误 | 重试。持续失败联系后端 |
| 200 | 3600 | 上游处理失败 | 含源文件无法下载、格式不支持。可换源或重试 |
| 200 | 3601 | 上游处理超时,或任务超过 24 小时未完成 | 换更短的片子,或重试 |
| 409 | 4003 | 同一调用方请求号,请求体不同 | 换一个新的 client_request_id |
| 200 | 4102 | 缺少必填参数 | 按 error.details[].field 补字段 |
| 200 | 4107 | 视频、切片或 m3u8 密钥链接不合法 | video_url、片段地址、m3u8_key_url 使用公网可访问的 http 或 https |
| 401 | 5003 | Key 无效,或不是本环境的 Key | 核对 Key 与环境 |
| 200 | 5204 | 当前 Key 未开通该产品 | 找后端开通权限 |
单价见首页透明接口定价。成功、失败、超时、取消是否计费,以该价格页为准。
测试素材(35.8 秒,1080×1920,60fps):
https://videos.pexels.com/video-files/39750493/16953211_1080_1920_60fps.mp4目标 10 秒时切出 4 段,时长依次为 12500、8333、12500、2483 毫秒。再合并后成片 35817 毫秒、17062084 字节。测试环境这段素材切片和合并各约 10 秒;上游排队时会更久。
BASE='https://test-star-api.aiaibase.com'
KEY='{API Key}'
curl -X POST "$BASE/api/video_segment" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-d '{"video_url":"https://videos.pexels.com/video-files/39750493/16953211_1080_1920_60fps.mp4","segment_second":10,"client_request_id":"seg-001"}'
curl "$BASE/api/tasks/{request_id}" -H "Authorization: Bearer $KEY"
curl -X POST "$BASE/api/video_merge" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-d '{"segments":[{"index":0,"url":"{seg0}"},{"index":1,"url":"{seg1}"}],"client_request_id":"merge-001"}'重试提交时带同一个 client_request_id,避免重复建任务和重复扣费。