视频切片与合并接口文档

按目标时长把视频切成多段,或按序号把多段拼成一条。均为异步,完成后查询或回调。

把一条视频按目标时长切成多段,或把多段视频按序号拼成一条。两个能力都是异步任务:提交后拿到任务号,再查询结果;请求里带了回调地址时,任务结束会再 POST 同一份结果。

需要自己拿到分段、或自行决定合并顺序时使用本接口。长视频去水印不必先切开再逐片提交,直接使用视频去水印的自动切片。

方法与路径说明
POST /api/video_segment提交视频切片
POST /api/video_merge提交视频合并
GET /api/tasks/{request_id}查询任务
环境根地址
测试https://test-star-api.aiaibase.com
正式尚未上线。上线后另行通知

路径接在根地址后面。例如测试环境提交切片:

text
POST https://test-star-api.aiaibase.com/api/video_segment

请求体为 JSON,Content-Type: application/json。认证只使用请求头:

text
Authorization: Bearer {API Key}

{API Key} 只能放在服务端。文档站或业务前端如果要在浏览器里调用,必须走服务端代理,不要把 Key 写进前端包体。测试 Key 向后端索取,不要使用正式客户的 Key 做联调。

所有响应都是同一结构。业务失败默认 HTTP 200,以 success 和 error.code 判断。鉴权失败是 HTTP 401。同一调用方请求号但请求体不同,是 HTTP 409。

字段类型说明
successbool受理成功、处理中、处理成功为 true;失败为 false
dataobject成功或处理中的业务数据
messagestring失败说明
errorobject失败时的错误。含 code、message,参数错误时还有 details
meta.request_idstring平台任务号。查询任务用这个值
meta.timestampstring响应时间,例如 2026-11-03T16:04:21+08:00
json
{
  "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否stringm3u8 解密密钥地址,http 或 https。加密 m3u8 时与 m3u8_secret 至少传一个
m3u8_secret否stringm3u8 解密密钥。16 字节,写成 32 位十六进制。加密 m3u8 时与 m3u8_key_url 至少传一个
segment_second否int目标切片时长(秒),1–600,默认 10。这是目标值,实际按关键帧切
title否string任务标题,最多 200 字
bid否string业务编号,最多 200 字
client_request_id否string调用方请求号。建议必带
request_id否stringclient_request_id 的别名
task_id否stringclient_request_id 的别名
callback_url否string完成回调地址
notice_url否stringcallback_url 的别名
notify_url否stringcallback_url 的别名

普通视频文件和未加密 m3u8 不用传 m3u8_key_url、m3u8_secret。加密 m3u8 必须在这两个字段里至少传一个,由后端校验。密钥地址须为 http 或 https。密钥正文是 16 字节,写成 32 位十六进制。格式不对,或加密流两个字段都没传,提交会被拒绝。

若自行切片后再做单次去水印,用返回的 duration_ms 核对单段长度。上游默认只处理前 650 帧,完整处理需要打开 unlimited。长视频直接使用视频去水印的自动切片。

受理返回

HTTP 200。此时片段还没生成。记录 meta.request_id,用它查询进度。

json
{
  "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"
  }
}

请求示例

bash
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,至少传一个。

bash
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否stringclient_request_id 的别名
task_id否stringclient_request_id 的别名
callback_url否string完成回调地址
notice_url否stringcallback_url 的别名
notify_url否stringcallback_url 的别名

单次最多 200 段,超过返回业务码 1001。更长的视频先切成不超过 30 分钟的片段,再分段处理。

受理返回

与切片相同:data.status 为 accepted,记录 meta.request_id。

请求示例

bash
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。

bash
curl 'https://test-star-api.aiaibase.com/api/tasks/{request_id}' \
  -H 'Authorization: Bearer {API Key}'

处理中:

json
{
  "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。

json
{
  "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 秒。地址由产物服务控制,未承诺永久有效,拿到后转存到自己的存储。

json
{
  "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

成片地址同样建议转存,不要把临时地址当作永久链接写入数据库。

失败示例:

json
{
  "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业务码说明处理
2001000任务不存在,或不属于当前密钥用提交时返回的 meta.request_id
2001001参数不合法未知字段、合并超过 200 段、index 重复或取值越界、m3u8_secret 不是 32 位十六进制,或加密 m3u8 未提供密钥。看 error.details[].field
4011102缺少 Authorization补请求头
2001500服务内部错误重试。持续失败联系后端
2003600上游处理失败含源文件无法下载、格式不支持。可换源或重试
2003601上游处理超时,或任务超过 24 小时未完成换更短的片子,或重试
4094003同一调用方请求号,请求体不同换一个新的 client_request_id
2004102缺少必填参数按 error.details[].field 补字段
2004107视频、切片或 m3u8 密钥链接不合法video_url、片段地址、m3u8_key_url 使用公网可访问的 http 或 https
4015003Key 无效,或不是本环境的 Key核对 Key 与环境
2005204当前 Key 未开通该产品找后端开通权限

单价见首页透明接口定价。成功、失败、超时、取消是否计费,以该价格页为准。

测试素材(35.8 秒,1080×1920,60fps):

text
https://videos.pexels.com/video-files/39750493/16953211_1080_1920_60fps.mp4

目标 10 秒时切出 4 段,时长依次为 12500、8333、12500、2483 毫秒。再合并后成片 35817 毫秒、17062084 字节。测试环境这段素材切片和合并各约 10 秒;上游排队时会更久。

bash
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,避免重复建任务和重复扣费。