Create Task | Yeehoo Developers

Submit a unified image or video generation task; the server infers the task family from model and returns a task ID.

This is the main public async media task creation endpoint.

Created tasks, charges, and generated assets belong to the API key's team workspace and cannot be reassigned with request headers.

You do not need separate image and video create APIs. Call:

POST /v1/generations

The server decides whether the task is image or video based on model.

Overview

Item	Description
Route	`POST /v1/generations`
Auth	`Authorization: Bearer sk_yeehoo_xxx`
Idempotency	Strongly recommended via `Idempotency-Key`
Request body	`application/json`
Response	`201 Created` + task object
Result retrieval	Poll `GET /v1/tasks/{task_id}` or wait for webhook

Integration Note

Do not treat this as a synchronous result endpoint. A successful create response usually means the task was accepted, not completed.

Authorizations

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

Header notes

Header	Required	Description
`Authorization`	Yes	`Bearer sk_yeehoo_xxx`
`Content-Type`	Yes	Must be `application/json`
`Idempotency-Key`	Strongly recommended	Prevents duplicate task creation during retries

Body

Required fields

Field	Type	Required	Example	Description
`model`	`string`	Yes	`gpt-image-2`	Target model. The server maps it to image or video automatically
`prompt`	`string`	Yes	`A cinematic fashion poster...`	Generation instruction

Common image fields

Applies to current public image models. Use schema.fields from GET /v1/models as the source of supported fields and enums.

Field	Type	Required	Default	Example	Description
`reference_images`	`string[]`	No	-	`["https://.../ref1.png"]`	Reference image URLs. Call Upload Reference Image to get a hosted URL.
`aspect_ratio`	`string`	No	`auto`	`1:1`	Output aspect ratio
`resolution`	`string`	No	Model-specific	`1K`	Output resolution
`n`	`integer`	No	`1`	`2`	Number of images requested
`quality`	`string`	No	Model-specific	`low`	Send only when declared by the model schema; regular `gpt-image-2` does not support it

Common video fields

Applies to current public video models. Supported fields must come from the selected model's schema in GET /v1/models.

Field	Type	Required	Default	Example	Description
`reference_images`	`string[]`	No	-	`["https://.../ref.png"]`	Reference image URLs, up to 9 for Seedance 2 models
`reference_videos`	`string[]`	No	-	`["https://.../ref.mp4"]`	Reference video URLs, up to 3; may enable input-video billing
`input_video_duration`	`number`	No	Output duration	`8`	Actual processed input-video seconds
`reference_audios`	`string[]`	No	-	`["https://.../ref.mp3"]`	Reference audio URLs, up to 3
`generate_audio`	`boolean`	No	`true`	`true`	Whether to generate audio
`audio`	`boolean`	No	`false`	`false`	Kling generated-audio switch; send only when declared by the schema
`mode`	`string`	No	Model-specific	`pro`	Kling quality tier, commonly `std`, `pro`, or `4k`
`first_frame_image_url`	`string`	No	-	`https://.../first.png`	First-frame image URL; send only when declared by the schema
`last_frame_image_url`	`string`	No	-	`https://.../last.png`	Last-frame image URL; send only when declared by the schema
`aspect_ratio`	`string`	No	Model-specific	`16:9`	Video aspect ratio
`resolution`	`string`	No	Model-specific	`720p`	Video resolution
`duration`	`integer`	No	Model-specific	`5`	Duration in seconds

Parameters are model-schema driven. Each model returned by GET /v1/models includes schema.fields with types, required/default values, enum options, and some limits. Do not copy fields between models.

Kling V3 Omni and Kling Video O1 use reference_videos with input_video_duration. With reference videos, Kling V3 Omni requires audio=false; Kling Video O1 has no audio field. Gemini Omni Flash currently exposes only duration=10.

External reference video and audio URLs

The public upload endpoint currently accepts images only. Host reference_videos and reference_audios on HTTPS URLs that Yeehoo can download without cookies or custom headers, remain valid until the task completes, and return the correct Content-Type. Prefer signed URLs valid for several hours. Do not send local paths, blob: URLs, or browser-session-only resources. Limits follow the selected model's schema.fields and upstream validation.

Response

A successful create call returns a submission receipt, not the full task object. Fetch GET /v1/tasks/{task_id} for status, model, result, and error fields.

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

Response fields

Field	Type	Description
`task_id`	`string`	Task ID used for polling and webhook reconciliation
`created`	`integer`	Unix creation timestamp
`object`	`string`	Always `generation.task`
`progress`	`integer`	Progress at submission response time
`billing_transaction_id`	`string`	Billing transaction ID for reconciliation; use `task_id` for task lookup
`data`	`array`	May appear only if work has already completed; normally absent for async tasks

What to do next

Store task_id
Poll GET /v1/tasks/{task_id}
Or configure webhook delivery and wait for task.succeeded, task.failed, or task.canceled