创建任务 | Yeehoo Developers

统一提交图片或视频生成任务；服务端会根据 model 自动识别任务类型并返回 task_id。

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

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

POST /v1/generations

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

接口概览

项	说明
路由	`POST /v1/generations`
鉴权	`Authorization: Bearer sk_yeehoo_xxx`
幂等	建议传 `Idempotency-Key`，避免重复下单
请求体	`application/json`
返回	`201 Created` + 任务对象
结果获取	轮询 `GET /v1/tasks/{task_id}` 或等待 webhook

接入提醒

不要把这个接口当成同步返回图片或视频结果的接口。创建成功只代表任务已入队，最终内容要看任务终态。

Authorizations

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

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

Header	必填	说明
`Authorization`	是	固定格式 `Bearer sk_yeehoo_xxx`
`Content-Type`	是	固定为 `application/json`
`Idempotency-Key`	强烈建议	同一次业务提交保持同一个值，防止网络重试导致重复创建任务

Body

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

通用必填字段

字段	类型	必填	示例	说明
`model`	`string`	是	`gpt-image-2`	指定具体模型。服务端根据模型判断是图片任务还是视频任务
`prompt`	`string`	是	`A cinematic fashion poster...`	生成指令，建议直接写清主体、风格、构图、光线、镜头感

图片任务常用字段

适用于当前公开图片模型：gpt-image-2、nano-banana-2、nano-banana-pro

字段	类型	必填	默认值	示例	说明
`reference_images`	`string[]`	否	-	`["https://.../ref1.png"]`	参考图 URL 列表，适合做风格参考或局部重绘
`aspect_ratio`	`string`	否	`auto`	`1:1`	输出宽高比
`resolution`	`string`	否	模型相关	`1K`	输出分辨率
`n`	`integer`	否	`1`	`2`	本次任务希望生成的图片数量

视频任务常用字段

适用于当前公开视频模型，例如 sora-2、seedance-2

字段	类型	必填	默认值	示例	说明
`first_frame_image_url`	`string`	否	-	`https://.../cover.png`	首帧图或起始参考图
`reference_mode`	`string`	否	模型默认	`first_frame`	参考图使用方式，具体以模型支持为准
`aspect_ratio`	`string`	否	模型默认	`16:9`	视频宽高比
`resolution`	`string`	否	模型默认	`720p`	视频清晰度，具体枚举取决于模型
`duration`	`integer`	否	模型默认	`5`	视频时长，单位通常为秒

Response

创建成功后，服务端通常会先返回一个任务对象。

创建成功响应示例

{
  "task_id": "task_01jxyz...",
  "object": "task",
  "kind": "image",
  "model": "gpt-image-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1784779200,
  "completed_at": 0
}

响应字段说明

字段	类型	说明
`task_id`	`string`	后续轮询和 webhook 对账的核心 ID
`object`	`string`	对象类型，通常为 `task`
`kind`	`string`	任务类型，通常为 `image` 或 `video`
`model`	`string`	本次实际执行的模型
`status`	`string`	当前状态，如 `queued`、`running`、`succeeded`、`failed`
`progress`	`integer`	任务进度百分比，终态通常为 `100` 或保留终态值
`created_at`	`integer`	创建时间戳
`completed_at`	`integer`	完成时间戳；未完成时可能为空值或 `0`
`result`	`object`	终态成功时返回的结果内容
`error`	`object`	终态失败时返回的错误对象

成功后的下一步

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

轮询和回调怎么选

场景	建议
本地联调	先只接轮询，排查最直观
正式生产	轮询保底，webhook 做异步通知
要求强一致	收到 webhook 后仍建议按 `task_id` 再查一次任务详情