视频智能封面

上新

视频截封面:本站 OSS 视频同步截帧,按成功张数计费

视频截封面:对已上传到本站 OSS 的视频做同步截帧,支持一次截取 1–10 张,封面落盘后返回 URL。
上游为阿里云 OSS video/snapshot(需 Bucket 开通音视频处理,H.264/H.265)。
默认截帧成功后删除源视频,只保留封面,避免长期占用 OSS 存储;传 keep_video=1 可保留。
计费按成功截出的封面张数扣额度(1 张 = 1 次),与阿里云截帧计费口径一致。

流程:先调 OSS sign→PUT→confirm 上传视频,再调本接口传入 file_id 与 count。

调用地址:https://api.ynlskj.com.cn/gateway/videocover

请求方法:POST

在其他地方怎么调用

  1. 请求地址用上面的调用地址,把 JSON 放在请求体里
  2. 方法用 POST
  3. API Key 只能放在请求头 X-API-Key,不要写进网址,也不要写进 Query 框
  4. Key 在「个人中心 → API Key」里复制,登录后会自动填入你自己的 Key

参数说明

参数位置必填说明
file_idBody JSON二选一本站 OSS 已 confirm 的视频 file_id。也可用 key(client_key)
countBody JSON截图张数,1–10,默认 1。按成功张数扣额度(截几张扣几次)
interval_msBody JSON间隔毫秒,默认 3000。从 start_ms 起每隔这么久截一帧
start_msBody JSON起始毫秒,默认 0
timesBody JSON精确时间点数组(毫秒),如 [0,3000,9000],优先于 interval
modeBody JSONinterval(默认)或 avg(需传 duration_ms)
formatBody JSONjpg(默认)/ png
width / heightBody JSON输出宽高,0 表示按原视频比例
fastBody JSON1(默认)关键帧加速;0 精确时间
ar / auto_rotateBody JSON默认 1,按视频旋转元数据自动摆正(手机竖屏务必开);0 关闭
saveBody JSON1(默认)封面写入 OSS;0 仅返回临时截帧签名 URL(此时不能删源视频)
keep_videoBody JSON默认 0:截帧成功后删除源视频,省 OSS 存储;传 1 保留。也可用 delete_video=0
aclBody JSON封面 ACL:public(默认)/ private
X-API-KeyHeader你的 API Key

请求示例

场景Body 示例
截 1 张封面{"file_id":"of_xxx","count":1}
每隔 5 秒共 3 张{"file_id":"of_xxx","count":3,"interval_ms":5000,"fast":1}
指定时间点{"file_id":"of_xxx","times":[0,2000,8000],"count":3}
按视频时长均分{"file_id":"of_xxx","count":4,"mode":"avg","duration_ms":120000}
竖屏自动摆正{"file_id":"of_xxx","count":3,"ar":1}(默认已开;ar:0 关闭)

视频须先走 OSS sign → PUT → confirm。Bucket 需开通音视频处理;仅 H.264/H.265。手机竖屏常带旋转元数据,默认 ar_auto 会摆正封面。默认 save=1 且截帧成功后会删除源视频(只留封面)。计费按成功封面张数(1 张 = 1 次额度),与阿里云截帧口径一致;需要保留视频时传 keep_video=1

返回说明

字段说明
retok 成功,err 失败
data.cover_url第一张封面 URL(便于 count=1 时直接取用)
data.covers封面数组:index / time_ms / url / file_id / object_key 等
data.count / requested实际成功张数 / 请求张数
data.video_file_id源视频 file_id(删除后仍回显,便于对账)
data.video_deleted是否已删除源视频(默认成功后为 true)
data.video_delete_skipped未删除时的原因说明(空字符串表示无跳过说明)
data.deducted本次扣减的额度张数(= 成功封面数)
data.errors部分帧失败时的错误列表(成功帧仍在 covers;只对成功张扣费)
msg本站提示,如「次数充足,剩余 99 次」或「次数不足,剩余 0 次」
remain_quota本次调用后的剩余次数

可直接复制的代码

未登录时示例只显示「你的密钥」。登录后会自动填入你自己的 Key,不会展示别人的。

<?php
$ch = curl_init('https://api.ynlskj.com.cn/gateway/videocover');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['X-API-Key: 你的密钥', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{
    "file_id": "of_0123456789abcdef0123",
    "count": 3,
    "interval_ms": 5000,
    "format": "jpg",
    "fast": 1
}',
]);
echo curl_exec($ch);

请求参数演示

{"file_id":"of_0123456789abcdef0123","count":3,"interval_ms":5000,"format":"jpg","fast":1}

响应演示

{"ret":"ok","code":200,"errmsg":"成功","data":{"video_file_id":"of_0123456789abcdef0123","video_key":"demo/sample.mp4","count":3,"requested":3,"format":"jpg","fast":true,"saved":true,"cover_url":"https://bdd2025.oss-cn-chengdu.aliyuncs.com/u1/2026/09/of_coverdemo0000000001.jpg","covers":[{"index":0,"time_ms":0,"format":"jpg","file_id":"of_coverdemo0000000001","url":"https://bdd2025.oss-cn-chengdu.aliyuncs.com/u1/2026/09/of_coverdemo0000000001.jpg"},{"index":1,"time_ms":5000,"format":"jpg","file_id":"of_coverdemo0000000002","url":"https://bdd2025.oss-cn-chengdu.aliyuncs.com/u1/2026/09/of_coverdemo0000000002.jpg"},{"index":2,"time_ms":10000,"format":"jpg","file_id":"of_coverdemo0000000003","url":"https://bdd2025.oss-cn-chengdu.aliyuncs.com/u1/2026/09/of_coverdemo0000000003.jpg"}],"errors":[]}}

在线调试

登录后可在线调试。可先上传视频再截封面;上传走 OSS(扣余额),截封面扣本接口次数。

去登录