VideoPai转码管理台

接口文档

提交任务 查询与控制 上传视频 图片 模板与配置 资源管理 计算池

POST /api/jobs　提交视频或音频任务

立即返回 202，转码在后台继续。可以只写模板，也可以逐项写参数，两边一起写时，请求里出现的字段覆盖模板。模板名不区分大小写，必须是 GET /api/profiles 里的键，形如 libx264_1920。未知名字返回 400。

目标留空时，成品写到源的同一目录，文件名加 -yyMMddHHmmss（提交时的年月日时分秒）。/mnt/1.ts 得到 /mnt/1-261023143045.ts。显式填写 dest 时必须是绝对路径，且 source 也是本机路径。

请求字段

method

结束回调

视频任务和音频任务进入 succeeded 或 failed 后，向回调地址发 POST，Content-Type 为 application/json。地址上会带上 ?id=<任务ID>，正文也有同一份 ID：

{"id":"job-1b94b4288d76","state":"succeeded"}
{"id":"job-1b94b4288d76","state":"failed","error":"原因"}

配置了 web.callback_secret 时，请求头带 X-Videopai-Secret。对方返回 2xx 才算送到；其它状态或连不上会再试两次。取消不回调。图片任务不回调。回调地址在提交时确定，之后改配置不影响已经提交的任务。

留空的帧率、码率、采样率、profile、level，在探测完源文件后用最终档位 <video_format>_<video_width> 补齐。改了编码或宽度，补齐用的档位也跟着变。CRF、preset、像素格式写在模板里，由转码进程读取，不是这个请求的字段。

请求

curl -s -X POST http://127.0.0.1:8080/api/jobs \
  -H 'Content-Type: application/json' \
  -d '{"source":"/mnt/a.mp4","template":"libx264_1920","method":4,"client":"client"}'

应答 202

{
  "id": "job-1b94b4288d76",
  "uuid": "job-1b94b4288d76",
  "state": "queued",
  "kind": "video",
  "client": "client",
  "method": "direct",
  "source": "/mnt/a.mp4",
  "dest": "/mnt/a-261023143045.mp4",
  "video_format": "libx264",
  "width": "1920",
  "priority": "medium",
  "percent": 0,
  "elapsed_seconds": 0,
  "segments": 0,
  "total_segments": 1,
  "servers": null,
  "created": "2026-10-22T22:15:08+08:00"
}

请求

curl -s -X POST http://127.0.0.1:8080/api/jobs \
  -H 'Content-Type: application/json' \
  -d '{"source":"/mnt/a.mp4","dest":"/mnt/out/b.mp4","template":"libx264_1920","video_bit_rate":"4000k","audio_format":"copy","method":4}'

应答 202

{
  "id": "job-9f3c1a20b8e4",
  "uuid": "job-9f3c1a20b8e4",
  "state": "queued",
  "kind": "video",
  "client": "client",
  "method": "direct",
  "source": "/mnt/a.mp4",
  "dest": "/mnt/out/b.mp4",
  "video_format": "libx264",
  "audio_format": "copy",
  "width": "1920",
  "video_bit_rate": "4000k",
  "percent": 0,
  "elapsed_seconds": 0,
  "segments": 0,
  "total_segments": 1,
  "servers": null,
  "created": "2026-10-22T22:20:00+08:00"
}

查询、取消、重试、画质

state

queued 等待，running 转码中，succeeded 完成，failed 失败，canceled 已取消。失败原因在 error。源文件没有视频流时，视频任务会在探测阶段失败，例如 no video stream found。

请求

curl -s http://127.0.0.1:8080/api/jobs/job-1b94b4288d76

应答 200

{
  "id": "job-1b94b4288d76",
  "title": "晚间新闻",
  "priority": "high",
  "state": "running",
  "percent": 40,
  "elapsed_seconds": 125,
  "source": "/mnt/a.mp4",
  "dest": "/mnt/a-261023143045.mp4"
}

请求

curl -s 'http://127.0.0.1:8080/api/jobs?state=running&title=晚间'

应答 200

{
  "jobs": [
    {
      "id": "job-1b94b4288d76",
      "title": "晚间新闻",
      "state": "running",
      "kind": "video",
      "client": "parallel-client",
      "method": "commit",
      "source": "/mnt/a.mp4",
      "dest": "/mnt/a-261023143045.mp4",
      "percent": 40,
      "elapsed_seconds": 125,
      "segments": 3,
      "total_segments": 8,
      "servers": ["10.0.0.5"]
    }
  ]
}

请求

curl -s 'http://127.0.0.1:8080/api/jobs/job-1b94b4288d76?detail=1'

应答 200

{
  "id": "job-1b94b4288d76",
  "title": "晚间新闻",
  "state": "succeeded",
  "kind": "video",
  "method": "commit",
  "percent": 100,
  "elapsed_seconds": 96,
  "segments": 8,
  "total_segments": 8,
  "servers": ["10.0.0.5"],
  "source_info": {"format": "mov,mp4,m4a,3gp,3g2,mj2", "Width": 1920, "Height": 1080, "Seconds": 600},
  "events": [
    {"time": "2026-10-22T22:15:10+08:00", "kind": "plan", "total_segments": 8},
    {"time": "2026-10-22T22:16:40+08:00", "kind": "progress", "segments": 8, "total_segments": 8, "percent": 100}
  ]
}

上传视频

POST /api/jobs/upload

multipart/form-data。一个 file 部分，加上和 POST /api/jobs 相同的字段（表单里都是字符串）。服务端决定目标路径，调用方不传 dest。默认方法是切片后合并（method 为 2）。

分片上传

大文件先 POST /api/uploads/init，再按片 PUT，最后 POST .../complete 合并并提交任务。

请求

curl -s -X POST http://127.0.0.1:8080/api/uploads/init \
  -H 'Content-Type: application/json' \
  -d '{"name":"短片.mp4","size":16777216,"chunk_size":8388608,"fields":{"template":"libx265_source","method":"2"}}'

应答 202

{
  "id": "up-1b94b4288d76aabbccddeeff00112233",
  "name": "短片.mp4",
  "chunk_size": 8388608,
  "count": 2
}

每一片 PUT 的应答是 {"received":0,"bytes":8388608}。查进度的应答：

{
  "id": "up-1b94b4288d76aabbccddeeff00112233",
  "name": "短片.mp4",
  "size": 16777216,
  "chunk_size": 8388608,
  "count": 2,
  "received": [0],
  "missing": [1]
}

POST .../complete 在分片齐全时返回 202 和任务对象，与提交任务的应答相同。缺片时：

{"error":"1 of 2 chunks are still missing","missing":[1]}

图片

POST /api/images/sync　按路径同步转码

读完再返回，成功 200。适合单张图。

GET /api/image　CDN 回源直出

本机绝对路径读图，响应体直接是压缩后的图片，不创建任务。支持 ETag、Cache-Control、If-None-Match（304）和 Range；重编码结果缓存在 <web.upload_dir>/image-live-cache/。参数：src（必填）、template、fmt、q、chroma、w、h、max、target_bytes、perceptual、lossless、keep_color_type。

curl -u admin:*** -o a.webp \
  'http://127.0.0.1:8080/api/image?src=/data/a.jpg&template=webp_q90&q=82&w=1600'

POST /api/images　上传一张图

multipart/form-data，同步返回。有 template 时以模板为准，下面的字段可覆盖模板里的同名项。

POST /api/images/batch　整目录

在本机目录上批量转码，返回 202 和一条批量任务。进度用任务查询接口看。

GET /api/images/{name} 下载一次上传转码留下的结果文件。name 是返回里的文件名，不是任意路径。

请求

curl -s -X POST http://127.0.0.1:8080/api/images/sync \
  -H 'Content-Type: application/json' \
  -d '{"source":"/mnt/1.jpeg","template":"heic_q60"}'

应答 200

{
  "job_id": "pic-1",
  "source": "/mnt/1.jpeg",
  "dest": "/mnt/1-261023143045.heic",
  "src_bytes": 275086,
  "dst_bytes": 91402,
  "saving_percent": 66.77,
  "quality": {
    "vmaf": 95.12,
    "psnr": 41.85,
    "ssim": 0.9941,
    "took_seconds": 0.42
  }
}

quality 是转码后立刻对比源图与产物得到的画质，只含 vmaf / psnr / ssim / took_seconds。单帧 VMAF 需要本机 ffmpeg 带 libvmaf；没有该滤镜时可能只有 PSNR 和 SSIM。

请求

curl -s -u admin:*** -F file=@/mnt/1.jpeg -F template=webp_q90 \
  http://127.0.0.1:8080/api/images

应答 200

{
  "template": "webp_q90",
  "format": "WebP",
  "format_name": "webp",
  "src_bytes": 275086,
  "dst_bytes": 91402,
  "saving_percent": 66.77,
  "quality_used": 90,
  "attempts": 1,
  "kept_original": false,
  "download": "/api/images/1-opt.webp"
}

请求

curl -s -X POST http://127.0.0.1:8080/api/images/batch \
  -H 'Content-Type: application/json' \
  -d '{"src_dir":"/data/图片库","out_dir":"/data/图片库/输出","template":"webp_q90","jobs":8}'

应答 202

{
  "job_id": "job-b92b895a685c",
  "state": "running",
  "src_dir": "/data/图片库",
  "out_dir": "/data/图片库/输出",
  "template": "webp_q90",
  "total": 120,
  "workers": 8,
  "manifest": "/data/图片库/输出/manifest.csv",
  "status": "/api/jobs/job-b92b895a685c"
}

模板与配置

视频模板里的字段

图片模板里的字段

音频模板里的字段

资源管理

资源管理页可在「本地导入」上传文件，或在「云资源池导入」里粘贴地址／选用输入池；池本身在「云资源池配置」里维护。HTTP/FTP 只读输入，成品写本机或不经输出池回写远端；OSS/S3 可写回对象旁。视频和音频提交走 POST /api/jobs，图片走 POST /api/images/sync：本机成品文件名加 -yyMMddHHmmss。

计算池