小影API 小影API

媒体工具

音视频分离：任意视频一键拆成「纯音频」和「无声画面」，异步排队处理，支持上传或直链。

/api/media/

服務說明

媒体工具提供音视频分离能力：给一个视频（本地上传或公网直链），产出两份文件——只保留音轨的音频、以及去掉音轨的无声画面。

处理默认全部走 stream copy（不重编码）：抽音轨 / 去音轨通常几秒完成，画面与音质零损失；只有把音频转成 mp3、或源编码装不进 mp4/webm 容器时才会转码。

所有处理都是异步任务：提交后立即返回 task_id，按任务查询进度；完成后返回带 1 小时时效令牌的下载地址，可直接在浏览器或下载工具里打开。任务带排队机制（默认 2 个并发、20 个排队），排队满时提交会直接告知前面还有几个任务。

響應格式

所有接口返回同一個 JSON 信封，業務數據都在 data 裡： 

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}
  • code：業務狀態碼，10000 表示成功；其餘為各類錯誤，完整清單見「錯誤碼」頁。
  • msg：給人看的提示文案，可直接展示給終端用戶，但不要用它做邏輯判斷。
  • data：業務數據；出錯時通常為 null。各接口 data 的具體字段見該接口的「響應說明」。

判斷成功與否請看 code，不要依賴 HTTP 狀態碼。 查看完整錯誤碼

音视频分离

服务端 ffmpeg 需簽名

提交任务 → 轮询状态 → 下载音频 / 无声视频。

POST /api/media/av 累計調用 2 次

提交分离任务

提交一个音视频分离任务，立即返回 task_id 与排队位次。

公网 http/https 直链（支持 m3u8）；与 file 二选一

本地视频；与 url 二选一，单文件上限 200MB

直链要求 Referer 时填写（如抖音 CDN，不带会 403）

copy = 直接复制音轨到对应容器；mp3 = 转码为 mp3

  • 请求体为 multipart/form-data（上传文件）或表单（直链）。
  • 并发 2 个、排队上限 20 个；排满时返回 20040 并在 data.ahead 告知前面还有几个。
  • url 会做 SSRF 校验：只允许公网 http/https，内网 / 回环地址一律拒绝。
響應說明 外層統一格式
字段 類型 說明
task_id string 任务 ID（UUID），后续查询 / 取消 / 重试都用它
status string queued 排队中 / running 执行中 / success 成功 / failed 失败 / cancelled 已取消 / expired 已过期
progress int 进度 0-100
queue_position int 排队位次（1 = 队首；非排队状态为 0）
ahead int 提交 / 重试时：前面还有几个任务在排队
error string 失败原因（成功时为空串）
retry_count int 已重试次数
create_time string 创建时间（ISO 8601）
started_time string 开始执行时间；未开始为 null
finished_time string 完成时间；未完成或执行中为 null
expire_time string 产物过期时间（默认完成后 1 小时）；到期文件自动删除
results object 产物下载信息：audio / video 两键，可能只有其一
results.audio.url string 音频下载地址（带 1 小时时效令牌，可直接在浏览器打开）
results.audio.format string 音频容器格式（m4a / mp3 / ogg / flac …）
results.audio.size int 音频文件大小（字节）
results.audio.reencoded bool 音频是否经过转码（默认 false = 原音轨直拷）
results.video.url string 无声视频下载地址（带令牌）
results.video.format string 视频容器格式（mp4 / webm）
results.video.size int 视频文件大小（字节）
results.video.reencoded bool 视频是否重编码（默认 false = 画面原样直拷）
返回示例 
{
  "task_id": "0f7c2c5e-8f0e-4a6e-9a3e-2d9a6f1b7c11",
  "status": "queued",
  "progress": 0,
  "queue_position": 1,
  "ahead": 0,
  "results": {}
}
GET /api/media/av 累計調用 2 次

任務列表

列出本接入项目最近的任务（默认 20 条）。

1-50，默认 20

響應說明 外層統一格式
字段 類型 說明
count int 本次返回条数
list array 任务列表（结构同「查询任务」）
GET /api/media/av/<uuid> 累計調用 2 次

查询任务

按 task_id 查询状态、进度与产物下载地址。

  • 建议每 1-2 秒轮询一次，progress=100 且 status=success 即完成。
  • 产物默认保留 1 小时，过期后 results 为空、下载链接失效。
響應說明 外層統一格式
字段 類型 說明
task_id string 任务 ID（UUID），后续查询 / 取消 / 重试都用它
status string queued 排队中 / running 执行中 / success 成功 / failed 失败 / cancelled 已取消 / expired 已过期
progress int 进度 0-100
queue_position int 排队位次（1 = 队首；非排队状态为 0）
ahead int 提交 / 重试时：前面还有几个任务在排队
error string 失败原因（成功时为空串）
retry_count int 已重试次数
create_time string 创建时间（ISO 8601）
started_time string 开始执行时间；未开始为 null
finished_time string 完成时间；未完成或执行中为 null
expire_time string 产物过期时间（默认完成后 1 小时）；到期文件自动删除
results object 产物下载信息：audio / video 两键，可能只有其一
results.audio.url string 音频下载地址（带 1 小时时效令牌，可直接在浏览器打开）
results.audio.format string 音频容器格式（m4a / mp3 / ogg / flac …）
results.audio.size int 音频文件大小（字节）
results.audio.reencoded bool 音频是否经过转码（默认 false = 原音轨直拷）
results.video.url string 无声视频下载地址（带令牌）
results.video.format string 视频容器格式（mp4 / webm）
results.video.size int 视频文件大小（字节）
results.video.reencoded bool 视频是否重编码（默认 false = 画面原样直拷）
POST /api/media/av/<uuid>/cancel 累計調用 0 次

取消任务

取消排队中或执行中的任务。

  • 排队中：立即置为已取消；执行中：先返回 cancelling，后台终止 ffmpeg 后转 cancelled。
響應說明 外層統一格式

該接口未單獨聲明 data 結構，以上述外層統一格式為準。

POST /api/media/av/<uuid>/retry 累計調用 0 次

重试任务

失败 / 已取消 / 已过期的任务重新排队（沿用原参数）。

  • 重试复用同一 task_id，retry_count 加一；排队满时同样返回 20040 + ahead。
響應說明 外層統一格式

該接口未單獨聲明 data 結構，以上述外層統一格式為準。

GET /api/media/av/download 累計調用 2 次

下载产物

用查询接口下发的时效令牌下载音频 / 无声视频（免项目签名）。

由提交 / 查询接口的 results.*.url 携带

  • 成功返回音视频二进制流（200 整段 / 206 分片，支持 Range）。
  • 令牌 1 小时有效，且与产物过期时间一致；无效 / 过期返回 403。
響應說明 外層統一格式

該接口未單獨聲明 data 結構，以上述外層統一格式為準。

小影API · 通用 API 聚合服務