视频生成
使用支持视频生成的 Model ID 创建任务、查询状态,再下载生成好的视频。
视频生成是异步的:请求只会创建一个任务,任务成功后才能拿到视频。开始前,请在模型页确认所选模型支持的分辨率、时长和各分辨率价格。
请求端点
视频生成用一个端点创建任务,再用三个端点跟进:
| 方法与路径 | 用途 |
|---|---|
POST /v1/videos | 创建视频生成任务 |
GET /v1/videos/{id} | 查询任务状态 |
GET /v1/videos/{id}/content | 下载生成好的视频 |
DELETE /v1/videos/{id} | 删除任务(模型接口支持时) |
所有路径都以 https://api.vergora.ai 为前缀,鉴权方式与其他请求相同(Authorization: Bearer YOUR_VERGORA_API_KEY)。只有创建任务会计费。
请求示例
POST https://api.vergora.ai/v1/videos{
"model": "YOUR_VIDEO_MODEL_ID",
"prompt": "雨夜街道上漂流的纸船,镜头缓慢推近",
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}创建成功后,响应里有任务的 id 和初始状态。保存好这个 id,后续每个请求都要用它。
采用 OpenAI 兼容视频接口的模型使用 seconds 和 size(例如 "8" 和 "1280x720"),而不是 duration、resolution 和 ratio。每个模型页的「API 调用」页签都给出了对应格式的请求示例。
请求字段
| 字段 | 说明 |
|---|---|
model | 必须是支持视频生成的 Model ID |
prompt | 描述主体、动作、场景和镜头运动 |
content | 结构化输入,模型支持时代替 prompt |
input_reference | 参考图(首帧)的 URL |
duration | 视频时长(秒) |
resolution | 输出分辨率,如 720p、1080p |
ratio | 画面比例,如 16:9(也接受 aspect_ratio) |
| 其他参数 | 只在模型明确支持时使用 |
content 可以包含文本、参考图或输入视频。其他参数包括 seed、watermark、generate_audio、camera_fixed、service_tier,只发给支持它们的模型。Seedance 2.0 / 2.5 不收 seed 和 camera_fixed,网关会替这些模型去掉。Wan 2.5 / 2.6 与 W3.0 的声音开关是 audio(布尔值,默认开),不是 generate_audio。
请求正文使用 JSON。需要输入视频时,传一个公开链接或已上传文件的 key(例如放在类型为 video_url 的 content 项里,见下文「参考图与参考视频」);视频不支持 data: URI。带输入视频的请求按模型的「带输入视频」价格计费。
参考图与参考视频
参考图或参考视频可以用下面任意一种形式给出。同一个字段三种都接受,由网关自动区分:
| 形式 | 示例 | 说明 |
|---|---|---|
| 公开链接 | https://cdn.example.com/clip.mp4 | 由模型服务方直接下载,必须能从公网访问 |
| 已上传的文件 | uploads/u42/20261112/0123…cdef.mp4 | POST /v1/uploads 返回的 key(见下文)。请求到达模型服务方之前会被换成一个临时链接 |
| 内联数据 | data:image/png;base64,… | 仅限图片,视频不接受内联数据 |
参考素材放在模型接口约定的位置:首帧图片用 input_reference,或者放进 content 里类型为 image_url、video_url 的项:
{
"model": "YOUR_VIDEO_MODEL_ID",
"content": [
{ "type": "text", "text": "同一个场景的夜晚,镜头缓慢推进" },
{
"type": "image_url",
"image_url": { "url": "https://cdn.example.com/frame.png" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "uploads/u42/20261112/0123…cdef.mp4" },
"role": "reference_video"
}
],
"resolution": "720p",
"duration": 5
}每个模型能带几份参考、是否支持参考视频,以模型页为准。每段参考视频的时长都会计入费用。
上传参考文件
文件在你本地、没有公开链接时,先上传,再使用返回的 key。
- 申请上传地址。带上文件类型和精确的字节数:
POST https://api.vergora.ai/v1/uploads{ "content_type": "video/mp4", "size": 2376873 }- 响应里有
key、upload_url、method(PUT)和需要带上的headers。按这些请求头把文件上传到upload_url。地址 15 分钟内有效,并且只接受声明的类型和大小。
{
"object": "upload",
"key": "uploads/u42/20261112/0123456789abcdef0123456789abcdef.mp4",
"upload_url": "https://…",
"method": "PUT",
"headers": { "Content-Type": "video/mp4" },
"expires_at": 1794500000
}- 在任何接受参考图或参考视频的字段里使用这个
key。
| 类型 | 支持的格式 | 大小上限 |
|---|---|---|
| 图片 | JPEG、PNG、WebP、GIF | 20 MB |
| 视频 | MP4、MOV、WebM | 200 MB |
key 只对创建它的账号有效。上传的文件必须确实是所声明类型的图片或视频,否则使用它的请求会被拒绝。上传的文件只保留有限的时间,key 失效后请重新上传。
查询任务状态
视频任务通常需要几十秒到几分钟。每隔几秒查询一次状态:
GET https://api.vergora.ai/v1/videos/{id}| 状态 | 含义 |
|---|---|
queued | 排队中 |
running / in_progress | 生成中 |
succeeded / completed | 已完成,可以下载 |
failed / cancelled | 已结束且没有视频,预扣金额全额退回 |
响应结构与模型接口保持一致。按 token 计费的模型还会返回 usage,即计费所用的 token 数。
“任务已创建”不表示视频已经生成完成。保存任务 id,便于排查失败和核对费用。
下载视频
GET https://api.vergora.ai/v1/videos/{id}/content响应正文就是视频文件(通常为 MP4)。任务成功之前,这个端点返回 409,错误码为 video_not_ready:请继续查询状态,不要循环重试下载。生成的文件只保留一段时间,任务成功后请尽快保存到自己的存储中。
费用与重试
视频模型按分辨率定价,按每秒视频或每百万 token 计费;完整价目见模型页。
- 创建任务时,先按请求中的分辨率、比例和时长(以及输入视频)从余额中预扣一笔估算金额;请求没有写明时,按 1080p、16:9、15 秒估算。
- 任务成功后,按实际用量结算(模型返回的 token 数,或生成视频的整秒数),但不会超过预扣金额:用得少,差额退回;用得多,超出部分不再扣费。
- 任务失败或被取消时,预扣金额全额退回。查询状态和下载视频不收费。
| 响应 | 含义 |
|---|---|
403 insufficient_user_quota | 余额不足以覆盖估算金额,不会创建任务 |
503 model_price_not_configured | 该模型尚未配置视频价格 |
409 video_not_ready | 任务成功前请求了下载 |
每次 POST /v1/videos 都会创建一个新任务并单独计费。超时后先在请求记录里确认是否已经创建了任务,再决定是否重新提交。