Generate image (POST /image/generate)

Creates an image task and returns its id. Nothing in the response is an image yet. Wait for the task by polling or with a webhook, or let the SDK's image.generate() wait for you.

Always pass model. When it is omitted, the API uses auto, which is experimental. See the model field. Generate images covers sizes and the result.

Request body

modelstring

default "auto""alibaba/qwen-image-2.0""alibaba/qwen-image-2.0-pro""alibaba/qwen-image-2.1-pro""alibaba/qwen-image-3.0""alibaba/qwen-image-3.0-pro""bytedance/seedream-5.0-lite""bytedance/seedream-pro""bytedance/seedream-v5-flash"

promptstringrequired

Positive prompt.

e.g. "Cute Cat"≥ 1 characters≤ 8192 characters

negative_promptstring

≤ 8192 characters

magic_promptboolean

countinteger

default 1≥ 1≤ 20

sizeobject | string

"auto""square""portrait""landscape""portrait_tall""landscape_wide""1:1""2:3"

type"auto"required

inputs(string | object)[]

≤ 20 items

type"image"required

asstring

"auto""source""reference"

sourceobjectrequired

type"url"required
urlstringrequired: format: uri

ratingobject | boolean

true

mode"nsfw_sfw": default "nsfw_sfw"

outputobject

formatstring: "png""jpg""webp"

generate_public_access_tokenboolean

Return a short-lived public access token as public_access_token, for polling this task from browser code without your API key. Defaults to false.

webhookobject

registeredboolean

Set to false to skip the webhooks registered on the account for this task. Custom webhooks in custom are still sent.

customobject[]

≥ 1 items≤ 5 items

urlstringrequired: Receives this task's events, unsigned. Use https and a public host, and put a secret token in the query string to verify deliveries: only scheme://host is ever shown back.
e.g. "https://example.com/hooks/mynth?token=your-secret-token"

destinationstring

e.g. "bunny-prod"≥ 1 characters≤ 64 characters

metadataobject

Response

Image generation task created

dataobjectrequired

task_idstringrequired: Task ID
e.g. "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP"
estimated_coststringrequired: Estimated cost in USD reserved for this task. Work that fails is refunded, so the final cost may be lower.
e.g. "0.03"
public_access_tokenstring: Short-lived public access token for polling this task's status and result.
Safe to hand to browser code instead of your API key. Returned only when the request set generate_public_access_token: true.
e.g. "pat_eyJhbGciOi..."

Errors

A failed call names what went wrong in code, with a sentence in message. The codes, which of them are worth retrying, and how to read a validation failure are on Errors.