视频智能封面
上新视频截封面:本站 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。
上游为阿里云 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
在其他地方怎么调用
- 请求地址用上面的调用地址,把 JSON 放在请求体里
- 方法用
POST - API Key 只能放在请求头
X-API-Key,不要写进网址,也不要写进 Query 框 - Key 在「个人中心 → API Key」里复制,登录后会自动填入你自己的 Key
参数说明
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
file_id | Body JSON | 二选一 | 本站 OSS 已 confirm 的视频 file_id。也可用 key(client_key) |
count | Body JSON | 否 | 截图张数,1–10,默认 1。按成功张数扣额度(截几张扣几次) |
interval_ms | Body JSON | 否 | 间隔毫秒,默认 3000。从 start_ms 起每隔这么久截一帧 |
start_ms | Body JSON | 否 | 起始毫秒,默认 0 |
times | Body JSON | 否 | 精确时间点数组(毫秒),如 [0,3000,9000],优先于 interval |
mode | Body JSON | 否 | interval(默认)或 avg(需传 duration_ms) |
format | Body JSON | 否 | jpg(默认)/ png |
width / height | Body JSON | 否 | 输出宽高,0 表示按原视频比例 |
fast | Body JSON | 否 | 1(默认)关键帧加速;0 精确时间 |
ar / auto_rotate | Body JSON | 否 | 默认 1,按视频旋转元数据自动摆正(手机竖屏务必开);0 关闭 |
save | Body JSON | 否 | 1(默认)封面写入 OSS;0 仅返回临时截帧签名 URL(此时不能删源视频) |
keep_video | Body JSON | 否 | 默认 0:截帧成功后删除源视频,省 OSS 存储;传 1 保留。也可用 delete_video=0 |
acl | Body JSON | 否 | 封面 ACL:public(默认)/ private |
X-API-Key | Header | 是 | 你的 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。
返回说明
| 字段 | 说明 |
|---|---|
ret | ok 成功,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":[]}}