视频智能封面

视频截封面:客户端直传阿里云,本站签发、截帧、按张计费

视频截封面:客户把视频直传到阿里云,云能只签发上传地址、截帧和计费,文件不经过本站。
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

在其他地方怎么调用

  1. 请求地址用上面的调用地址,把 JSON 放在请求体里
  2. 方法用 POST
  3. API Key 只能放在请求头 X-API-Key,不要写进网址,也不要写进 Query 框
  4. 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。默认截帧成功后删除源视频。截帧按成功张数扣本接口额度。

返回说明

字段说明
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 => '{
    "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":[]}}

在线调试

登录后可在线调试。选视频后先签发直传地址,文件直传阿里云,再截封面(截帧扣本接口次数)。

去登录