视频生成Video Generation
平台提供异步视频生成能力,支持文生视频、图生视频等多类模型。所有视频模型统一通过 OpenAI 兼容的 POST /v1/videos/generations 接口提交,通过 GET /v1/videos/generations/{task_id} 查询任务状态,无需关注不同上游的差异。The platform provides async video generation supporting text-to-video, image-to-video, and other model types. All video models are submitted through the unified OpenAI-compatible POST /v1/videos/generations endpoint, with task status queried via GET /v1/videos/generations/{task_id} — no need to deal with upstream differences.
接口与模型Endpoints & Models
| 目标Goal | 推荐接口Recommended Endpoint | 模型示例Model Examples |
|---|---|---|
| 文生视频Text-to-Video | POST /v1/videos/generations | viduq2、kling-v3、happyhorse-1.0-t2v、wan2.7-t2v |
| 图生视频Image-to-Video | POST /v1/videos/generations(携带参考图) (with a reference image) | happyhorse-1.0-i2v、happyhorse-1.0-r2v、wan2.7-i2v |
| 其他视频模型Other Video Models | POST /v1/videos/generations | kling-v2-5-turbo、kling-video-o1、doubao-seedance 系列kling-v2-5-turbo, kling-video-o1, the doubao-seedance series |
status=queued),随后轮询查询接口直至 succeeded,再取 result_url 下载视频,切勿同步等待返回。Video generation is an async task: submission returns a task ID (status=queued), then poll the query endpoint until succeeded and take result_url to download the video — never wait synchronously for the result.工作流程Workflow
提交生成Submit
携带模型与提示词发起请求,获得 task_id。Send a request with the model and prompt to get a task_id.
轮询状态Poll
用任务 ID 查询进度,直至 succeeded 或 failed。Query progress with the task ID until succeeded or failed.
下载结果Download
成功后通过 result_url 获取并下载视频。Once successful, fetch and download the video via result_url.
提交视频生成Submitting a Video Generation
请求示例(文生视频)Request Example (Text-to-Video)
curl -X POST {BASE_URL}/v1/videos/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"prompt": "一只猫在花园里弹钢琴,电影感镜头,柔和光线",
"size": "540p",
"seconds": 1
}'
请求字段说明Request Fields
| 字段Field | 必填Required | 说明Description |
|---|---|---|
model | 是Yes | 视频模型 ID,见上方「接口与模型」或模型广场Video model ID; see Endpoints & Models above or the Model Square |
prompt | 是Yes | 视频内容描述,建议包含主体、场景、运镜与光线Description of the video content; include the subject, scene, camera movement, and lighting |
size | 否No | 分辨率,如 540p / 720p / 1080P,各模型支持档位不同Resolution, e.g. 540p / 720p / 1080P; supported tiers vary by model |
seconds | 否No | 期望时长(秒),实际生成时长以模型为准Desired duration in seconds; the actual duration is determined by the model |
image_url | 图生视频时For image-to-video | 参考图地址,图生视频模型必填Reference image URL, required for image-to-video models |
响应示例Response Example
{
"code": "success",
"data": {
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
"status": "queued"
}
}
提交成功后返回任务 ID 与初始状态,可立即用任务 ID 查询进度。On success, the response returns a task ID and initial status; you can query progress with the task ID right away.
查询任务Querying a Task
查询示例Query Example
curl {BASE_URL}/v1/videos/generations/task_xxxxxxxxxxxxxxxxxxxxxxxx \
-H "Authorization: Bearer YOUR_API_KEY"
查询响应(成功示例)Query Response (Success Example)
{
"code": "success",
"data": {
"task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
"status": "succeeded",
"progress": "100%",
"result_url": "https://...mp4"
}
}
响应字段说明Response Fields
| 字段Field | 说明Description |
|---|---|
task_id | 任务 ID,查询与对账使用Task ID, used for querying and reconciliation |
status | 任务状态:queued → running → succeeded / failedTask status: queued → running → succeeded / failed |
progress | 生成进度(百分比),未完成时可用于展示Generation progress (percentage), useful for display while incomplete |
result_url | 生成视频地址,succeeded 后可用URL of the generated video, available after succeeded |
计费说明(积分计费模式)Billing (Credit-Based Mode)
viduq2、kling-v3 等模型采用积分档位计费,积分按分辨率与时长档位累计,再按每积分单价折算金额并应用账户折扣。Models such as viduq2 and kling-v3 use credit-tier billing: credits accumulate by resolution and duration tier, then convert to an amount at the per-credit price, with the account discount applied.
提示词建议Prompt Tips
- 明确主体、场景、运镜与光线,例如「一只猫在花园里弹钢琴,电影感镜头,柔和光线」。Be explicit about the subject, scene, camera movement, and lighting, e.g. "a cat playing the piano in a garden, cinematic shot, soft lighting".
- 需要排除的内容可以写进提示词,例如
no watermark, no text。Content to exclude can be written into the prompt, e.g.no watermark, no text. - 先用较低分辨率确认方向,再生成最终视频,避免浪费额度。Validate the direction at a lower resolution first, then generate the final video to avoid wasting quota.
- 图生视频时,参考图应主体清晰、构图明确,可显著提升生成质量。For image-to-video, use a reference image with a clear subject and composition to significantly improve generation quality.
注意事项Important Notes
- 视频生成是异步任务:提交后记录任务 ID,轮询查询接口直至
succeeded后取视频地址。Video generation is async: record the task ID after submission and poll the query endpoint untilsucceeded, then take the video URL. - 请求中的时长与分辨率用于生成参考,实际以模型生成结果为准,视频按实际生成秒数计费。The requested duration and resolution are for reference; the actual model output prevails, and videos are billed by actual generated seconds.
- 图生视频模型需附带参考图,不支持以视频作为参考输入。Image-to-video models require a reference image; video input as reference is not supported.
下一步Next Steps
- API 参考API Reference — 查看异步任务接口字段与请求示例。 — See async task endpoint fields and request examples.
- 计费与配额Billing & Quota — 查看积分计费模式与各模型计费方式。 — See the credit-based billing mode and per-model billing methods.