功能介绍
S2V-01 使用人物面部参考图保持主体形象，不是把参考图固定为第一帧。当前仅支持一个人物主体、该主体一张参考图。
鉴权与操作步骤
所有请求发送到 https://top.qingyuntop.ai。在请求头填写 Authorization: Bearer YOUR_API_KEY，将 YOUR_API_KEY 替换为青云TOP API 控制台创建的 API Key；Bearer 与密钥之间保留一个空格。
- 携带鉴权请求头，按本页参数创建任务。
- 保存返回的任务标识，查询至成功后下载视频。创建成功仅表示任务已受理。
JSON 请求使用 Content-Type: application/json。示例中的占位密钥需替换为你的 API Key。实际业务请在服务端保存密钥，不要放进公开网页。
创建接口与参数
POST /v1/videos。使用 model=S2V-01、6 秒、720P；在 metadata.subject_reference 数组中放一个对象：type 固定为 character，image 为仅含一个图片地址的字符串数组。建议填写 prompt，最多 2000 字符。
图片支持 JPG/JPEG/PNG/WebP，小于 20 MB，短边大于 300 px，宽高比 2:5 至 5:2。可用图片 URL 或官方支持的图片 data URL。不要用首帧字段代替人物参考字段，也不要把 subject_reference 放在请求顶层。
运行示例前
cURL 示例使用 Bash 换行语法；Python 需要安装 requests；Node.js 使用 20 或更高版本，将代码保存为 .mjs。带素材的示例必须把 https://example.com/... 替换为上游能直接读取的真实 HTTPS 文件地址，不是网页地址或本机文件路径。
代码示例
curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "S2V-01",
"prompt": "参考人物微笑看向镜头，保持人物身份一致，柔和自然光。",
"seconds": 6,
"resolution": "720P",
"metadata": {
"subject_reference": [
{
"type": "character",
"image": [
"https://example.com/portrait.jpg"
]
}
]
}
}'返回结果与下一步
返回的 id 是本站任务 ID，请原样保存。通过视频任务查询与下载等待 status=completed 后获取 MP4。不要从 ID 猜测厂商任务号，也不要把 progress=100 或存在 completed_at 当作成功条件。