Kling Video V3
三种模型使用相同的 PopGo 视频任务接口；图片数量、首尾帧语义和输出规格分别如下。参考视频、参考音频均未在当前接入协议中开放。服务文档的“音频”列不能当作音频参考字段的声明。
模型差异
| 模型 | 图片 | 输出音轨（服务文档） | 分辨率 |
|---|---|---|---|
kling-video-v3 | 最多 2 张；第 1 张首帧、第 2 张尾帧 | 支持 | 720p / 1080p / 4K |
kling-video-v3-omni | 最多 7 张参考图 | 支持 | 720p / 1080p / 4K |
kling-video-v3-turbo | 仅 1 张首帧 | 不支持音频 | 720p / 1080p |
字段与默认值
| 字段 | 类型 | 规则 |
|---|---|---|
model | string | 必填，使用上表的公开模型 ID |
prompt | string | 必填，描述主体、动作和镜头 |
seconds / duration | integer | 整数 3–15 秒；建议显式填写，界面默认 5 秒 |
resolution | string | 按模型选 720p / 1080p / 4K；界面默认 720p，服务文档默认 4K，Turbo 不可用 4K |
aspect_ratio | string | 16:9 / 9:16 / 1:1；默认 16:9，图生场景见下文 |
reference_images | object[] | 对象数组，每项使用 url 或 image_url；可传公网 HTTP(S) URL 或完整图片 Data URL |
优先使用 reference_images
直接 API 调用使用下方对象数组。PopGo 兼容层也处理画布上传的本地图片和首尾帧字段，但客户端不要同时提交多套同义字段。公网 URL 是可选来源，本地图片可编码为完整 Data URL；分享页、需要登录的地址和本地文件路径不等于图片 URL。
curl -X POST https://api.popgo.site/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL",
"prompt": "A person turns toward the camera",
"seconds": 5,
"resolution": "720p",
"reference_images": [
{"url": "YOUR_IMAGE_URL"}
]
}'
文生视频：省略 reference_images。参考图：按数组顺序提交。标准版两张图是首帧/尾帧，不是两个普通风格参考；Omni 的多图用于主体或风格参考；Turbo 超过一张图会被拒绝。
比例与输出规格
服务文档记录，标准版使用 1024×1536 首帧时，成片为 2352×3524，比例跟第一张图。需要固定画幅时，先把参考图裁剪为目标比例；不要以为 aspect_ratio 能强制覆盖所有图生场景。当前画布首帧模式隐藏比例控件。
服务文档实测的 Omni 5 秒、4K 示例为 3840×2160、24 fps、约 5.042 秒、8.9 Mbps、5.6 MB。这是一次输出观察，不是每次生成的固定码率或大小保证。
不支持与未确认的字段
当前三个模型不开放 reference_video、video_reference、reference_audio 或动作控制素材流程。generate_audio 表示输出音轨，不能替代音频素材；当前画布预设没有开放此输出参数开关。不要根据 Omni 名称推断动作控制。
quality 等未列明字段可能被静默忽略，HTTP 200 不能证明字段生效；seed、watermark 等参数也不能仅凭通用视频惯例认为有效。新增字段应先有当前接口的明确说明，再核对生成结果。
任务状态的四个注意点
- 服务文档记录 progress 可能一直是 0，直到 completed 才变为 100；不要据此认定卡死或伪造中间百分比。
- 轮询里的 model 可能为空；保存提交时使用的模型 ID。
- 响应可能没有 usage；以 PopGo 用量与账单记录判断计费，不从缺失字段推断免费。
- 响应可能不含分辨率、时长、帧率；下载后探测实际媒体规格。时间戳也不适合作为准确耗时依据。
文档中的三次生成耗时约为 140、200、420 秒。建议每 10 秒查询、保留至少 15 分钟等待窗口；这不是时效承诺。等待超时后继续查原任务，不要重新提交。
错误与修正
| 现象 | 处理 |
|---|---|
| 400 参数错误 | 对照时长、比例、分辨率和图片数量白名单；不原样重试 |
| 404 模型或任务不存在 | 检查公开模型 ID、令牌模型权限及 PopGo 返回的任务 ID |
| 503 暂无可用账号 / 502 临时服务错误 | 有限退避；创建请求超时先核对是否已产生任务 |
| 生成成功但没参考图片 | 核对 reference_images 是否真正提交、素材是否可读取，再对比首帧或主体；任务 ID 不证明参考生效 |
| Turbo 使用 4K 或音频参数 | 删除不支持参数，改用 720p / 1080p |
完成后使用 PopGo 的 /content 代理下载，或使用响应给出的可用结果地址。下载大视频应留足超时；不要向第三方结果域名发送 PopGo API Key。完整的轮询、下载和重试示例见视频任务流程。计费以模型与价格为准。