API 参考

Sandcut 故意把公开 API 面控制得很小。

鉴权

所有处理请求都需要 Bearer Token：

Authorization: Bearer <token>

接口列表

Endpoint	Method	用途
/health	GET	健康检查
/doc	GET	人类可读的项目元信息
/openapi.json	GET	工具友好的 OpenAPI Schema
/video/process	POST	媒体处理主入口

POST /video/process

请求体

{
  "input_url": "https://example.com/video.mp4",
  "ffmpeg_args": ["-vf", "scale=640:360", "-c:v", "libx264", "-c:a", "aac"],
  "seek": {
    "mode": "hybrid",
    "start": 30,
    "duration": 8
  }
}

多路输入文件

当 FFmpeg 需要多个远程输入源时，请使用 inputs：

{
  "inputs": [
    "https://example.com/intro.mp4",
    "https://example.com/main.mp4"
  ],
  "ffmpeg_args": [
    "-filter_complex",
    "[0:v][1:v]concat=n=2:v=1:a=0[v]",
    "-map",
    "[v]"
  ]
}

input_url 和 inputs 只能二选一，不能同时出现。

seek 对象

字段	类型	必填	说明
mode	string	否	fast、accurate、hybrid，默认 accurate
start	number	是	非负的起始秒数
duration	number	否	裁剪时长（秒）
end	number	否	duration 的替代项，必须大于 start

duration 和 end 只能二选一。

成功响应

{
  "success": true,
  "outputUrl": "https://cdn.example.com/output/20260313/uuid.mp4",
  "size": 395768,
  "sizeKnown": true,
  "input": {
    "size": 8212301,
    "sizeKnown": true,
    "probeMethod": "HEAD"
  },
  "seek": {
    "mode": "hybrid",
    "startSeconds": 30,
    "durationSeconds": 8
  },
  "timing": {
    "total": 4972,
    "container": 3819,
    "upload": 771
  }
}

如果是多输入请求，响应里还会包含 inputs 数组，用于描述每一路输入的探测结果。

错误格式

{
  "error": {
    "code": 3003,
    "message": "Video size exceeds limit",
    "details": "Input is 300000000 bytes, limit is 209715200 bytes"
  }
}

校验规则

• input_url 必须是 http 或 https
• inputs 最多支持 8 路远程输入 URL
• 私网 IP、localhost 和内部 metadata 域名会被拒绝
• ffmpeg_args 不允许包含嵌套输入参数，如 -i
• 原始 seek 参数，如 -ss、-to 不允许放进 ffmpeg_args
• 危险协议前缀，如 pipe:、file: 会被拒绝
• 全局 seek 只适用于单输入请求

Schema

工具接入或客户端生成可直接使用 /openapi.json。