视频智能封面
视频截封面:客户端直传阿里云,本站签发、截帧、按张计费
视频截封面:客户把视频直传到阿里云,云能只签发上传地址、截帧和计费,文件不经过本站。
1. action=upload,传入 filename/mime/size,拿到 upload_url 与 file_id。
2. 客户端 PUT 视频到 upload_url(直传阿里云)。
3. action=cover,传入 file_id 截封面。
上游为阿里云 OSS video/snapshot(需 Bucket 开通音视频处理,H.264/H.265)。
默认截帧成功后删除源视频;传 keep_video=1 可保留。按成功封面张数扣额度。
1. action=upload,传入 filename/mime/size,拿到 upload_url 与 file_id。
2. 客户端 PUT 视频到 upload_url(直传阿里云)。
3. action=cover,传入 file_id 截封面。
上游为阿里云 OSS video/snapshot(需 Bucket 开通音视频处理,H.264/H.265)。
默认截帧成功后删除源视频;传 keep_video=1 可保留。按成功封面张数扣额度。
调用地址:https://api.ynlskj.com.cn/gateway/videocover
请求方法:POST
在其他地方怎么调用
- 请求地址用上面的调用地址,把 JSON 放在请求体里
- 方法用
POST - API Key 只能放在请求头
X-API-Key,不要写进网址,也不要写进 Query 框 - Key 在「个人中心 → API Key」里复制,登录后会自动填入你自己的 Key
参数说明
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
action |
Body JSON | 是 | upload 签发直传地址(默认)/ cover 截封面 |
filename / mime / size |
Body JSON | upload 时 | 文件名、MIME、字节数。返回 upload_url,客户端 PUT 直传阿里云 |
file_id |
Body JSON | cover 时 | upload 返回的 file_id。视频须已 PUT 到 upload_url |
count |
Body JSON | 否 | 截图张数,1–10,默认 1。按成功张数扣额度 |
interval_ms |
Body JSON | 否 | 间隔毫秒,默认 3000 |
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:截帧成功后删除源视频;传 1 保留。也可用 delete_video=0 |
acl |
Body JSON | 否 | 封面 ACL:public(默认)/ private。源视频固定 private |
X-API-Key |
Header | 是 | 你的 API Key(请求头,不要放进网址或 Query) |
请求示例
| 场景 | 示例 |
|---|---|
| 1. 签发直传 | {"action":"upload","filename":"a.mp4","mime":"video/mp4","size":11534336} |
| 2. 客户端 PUT | 把视频 PUT 到返回的 upload_url(直传阿里云,不要发到本站) |
| 3. 截 1 张封面 | {"action":"cover","file_id":"of_xxx","count":1} |
| 每隔 5 秒共 3 张 | {"action":"cover","file_id":"of_xxx","count":3,"interval_ms":5000} |
| 保留源视频 | {"action":"cover","file_id":"of_xxx","count":1,"keep_video":1} |
视频由客户端直传阿里云,云能只签发 upload_url、截帧和计费,文件不经过本站。Bucket 需开通音视频处理;仅 H.264/H.265。默认截帧成功后删除源视频。截帧按成功张数扣本接口额度。
返回说明
| 字段 | 说明 |
|---|---|
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 => '{
"action": "upload",
"filename": "demo.mp4",
"mime": "video/mp4",
"size": 11534336,
"count": 1
}',
]);
echo curl_exec($ch);
请求参数演示
{"action":"upload","filename":"demo.mp4","mime":"video/mp4","size":11534336,"count":1}
响应演示
{"ret":"ok","code":200,"errmsg":"成功","msg":"次数充足,剩余 197 张","remain_quota":197,"data":{"video_file_id":"of_0123456789abcdef0123","video_key":"videocover/20260921/of_0123456789abcdef0123.mp4","count":3,"requested":3,"format":"jpg","fast":true,"saved":true,"video_deleted":true,"video_delete_skipped":"","deducted":3,"billing_unit":"frame","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":[]}}