小影API 小影API

媒体工具

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

/api/media/

Service Description

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

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

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

Response Format

Every endpoint returns the same JSON envelope; the payload is always inside data: 

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}
  • code: business status code. 10000 means success; anything else is an error — see the Error Codes page for the full list.
  • msg: a human-readable message you can show to end users, but never use it for program logic.
  • data: the payload; usually null on error. Each endpoint's Response section lists its data fields.

Judge success by code, not by the HTTP status code. View all error codes

音视频分离

服务端 ffmpeg Signature Required

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

POST /api/media/av Total calls: 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，内网 / 回环地址一律拒绝。
Response Common envelope
Field Type Description
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 = 画面原样直拷）
Example response 
{
  "task_id": "0f7c2c5e-8f0e-4a6e-9a3e-2d9a6f1b7c11",
  "status": "queued",
  "progress": 0,
  "queue_position": 1,
  "ahead": 0,
  "results": {}
}
GET /api/media/av Total calls: 2

Task list

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

1-50，默认 20

Response Common envelope
Field Type Description
count int 本次返回条数
list array 任务列表（结构同「查询任务」）
GET /api/media/av/<uuid> Total calls: 2

查询任务

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

  • 建议每 1-2 秒轮询一次，progress=100 且 status=success 即完成。
  • 产物默认保留 1 小时，过期后 results 为空、下载链接失效。
Response Common envelope
Field Type Description
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 Total calls: 0

取消任务

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

  • 排队中：立即置为已取消；执行中：先返回 cancelling，后台终止 ffmpeg 后转 cancelled。
Response Common envelope

This endpoint does not document its data structure separately; see the common envelope above.

POST /api/media/av/<uuid>/retry Total calls: 0

重试任务

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

  • 重试复用同一 task_id，retry_count 加一；排队满时同样返回 20040 + ahead。
Response Common envelope

This endpoint does not document its data structure separately; see the common envelope above.

GET /api/media/av/download Total calls: 2

下载产物

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

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

  • 成功返回音视频二进制流（200 整段 / 206 分片，支持 Range）。
  • 令牌 1 小时有效，且与产物过期时间一致；无效 / 过期返回 403。
Response Common envelope

This endpoint does not document its data structure separately; see the common envelope above.

XiaoYingAPI · Unified API Aggregation Service