创建任务

这是对外生成能力最核心的创建接口。

创建的任务、扣费和生成结果均归属于 API Key 对应的团队工作空间，不能通过请求头切换归属。

你不需要分别记图片接口和视频接口。当前推荐直接调用：

POST /v1/generations

服务端会根据你传入的 model 自动判断这是图片任务还是视频任务。

接口概览

Authorizations

所有对外生成接口都使用 API Key Bearer 鉴权。

Authorization: Bearer sk_yeehoo_your_api_key
Content-Type: application/json
Idempotency-Key: gen-demo-001

Header 说明

Body

先看最常用、最该传的字段。

通用必填字段

图片任务常用字段

适用于当前公开图片模型。具体字段与枚举以 GET /v1/models 返回的 schema.fields 为准。

视频任务常用字段

适用于当前公开视频模型。具体字段必须以 GET /v1/models 返回的模型 schema 为准。

参数由模型 schema 决定。GET /v1/models 的每个模型对象都包含 schema.fields，其中有类型、必填、默认值、枚举 options 和部分数量限制。不要把某个模型的参数照搬到其他模型。

Kling V3 Omni 和 Kling Video O1 的参考视频使用 reference_videos 与 input_video_duration。Kling V3 Omni 包含参考视频时必须设置 audio=false；Kling Video O1 不支持音频字段。Gemini Omni Flash 当前只开放 duration=10。

外部参考视频和音频 URL

当前公开上传接口只支持图片。reference_videos 和 reference_audios 需要使用你方托管的 HTTPS URL：服务端无需 Cookie 或自定义 Header 即可下载，URL 在任务完成前持续有效，响应 Content-Type 与真实文件一致。建议使用至少数小时有效的签名 URL；不要传本地路径、blob: URL 或仅浏览器登录后可访问的地址。具体格式、大小和时长限制以模型 schema.fields 及上游校验结果为准。

Response

创建成功后返回提交回执。它不是完整任务对象；请使用 task_id 调用 GET /v1/tasks/{task_id} 获取状态、模型、结果和错误。

创建成功响应示例

{
  "created": 1784779200,
  "task_id": "task_01jxyz...",
  "object": "generation.task",
  "progress": 0,
  "billing_transaction_id": "bt_01jxyz..."
}

响应字段说明

成功后的下一步

1. 记录 task_id
2. 调用 GET /v1/tasks/{task_id} 轮询任务状态
3. 或者提前给 API Key 配置 webhook，等待 task.succeeded / task.failed / task.canceled

轮询和回调怎么选