Image Generation API: GPT-Image, Seedream and Wanxiang

Choose an image workflow

Generation, reference-based creation, editing, and asynchronous tasks use different input shapes. Choose the workflow first so multipart fields do not end up in a JSON request.

Goal	Endpoint	Key input
Text to image	POST /v1/images/generations	prompt
One or multiple reference images	POST /v1/images/generations	image / images[]
Edit, mask, or bounding-box region	POST /v1/images/edits	multipart / JSON
SSE result stream	POST /v1/images/generations	stream=true
Long-running asynchronous generation	POST /v1/images/generations/tasks	Same JSON body as generations

Synchronous versus asynchronous execution does not change model capability or billing. Prefer tasks when generation may take longer, must survive connection loss, or should not hold an HTTP connection open.

Request parameters

Header parameters

AuthorizationstringRequired

API key in the format Bearer <key>.

Example:Bearer sk-zerofa-xxx

Content-TypestringRequired

Example:application/json

Body parametersapplication/json

modelstringRequired

The text-to-image model. See available models below.

Example:your-image-model-id

promptstringRequired

A description of the desired image. More detail gives greater control.

Example:A shiba inu wearing a space helmet, flat illustration

imagestring | string[]Optional

A reference image as one URL/data URI or an array of URL/data URI values.

Example:https://.../reference.png

imagesstring[] | object[]Optional

Recommended for multiple references. Accepts an array of URL/data URI strings or compatible {image_url} objects.

Example:["https://.../a.png","https://.../b.png"]

nintegerOptional

Number of images to generate, default 1.

Example:1

sizestringOptional

Output dimensions as widthxheight. gpt-image models require one of the recommended sizes below. Invalid sizes return 400 with the nearest valid value; the gateway does not adjust automatically. Other models use their own supported sizes.

Example:1024x1024

qualitystringOptional

Quality values depend on the model. gpt-image supports low, medium, high, and auto; dall-e-3 supports standard and hd. Unsupported values are ignored and the upstream default is used.

Example:high

response_formatstringOptional

url (default) returns an image link; b64_json returns base64.

Example:url

output_formatstringOptional

Output encoding: png, jpeg, or webp. The actual encoding changes only when the selected model supports it.

Example:webp

backgroundstringOptional

Background mode: auto, opaque, or transparent, depending on model capability.

Example:transparent

streambooleanOptional

Enable an OpenAI Images SSE response. Synchronous cross-provider routes emit a terminal completed event.

Example:true

partial_imagesintegerOptional

Request 0–3 partial previews with stream=true. Fast or non-streaming upstreams may return zero partial images.

Example:2

Image models use two billing modes. Most are billed by image count and resolution; some are billed by input, output, and cached tokens. Check this site's model card and pricing page for the exact mode.

Recommended sizes for gpt-image

Width and height must be divisible by 16, the long edge must be at most 3840, the aspect ratio at most 3:1, and total pixels 655,360–8,294,400. Swap width and height for portrait output.

Ratio	1K	2K	4K
1:1	1024x1024	2048x2048	2880x2880
4:3	1360x1024	2048x1536	3312x2480
3:2	1536x1024	2048x1360	3504x2336
16:9	1824x1024	2048x1152	3840x2160
21:9	2384x1024	2048x880	3840x1648

Image-to-image and multiple references (site / new-api)

Add image or images to a /v1/images/generations request to switch from text-only generation to reference-based generation. Use images for multiple references. The same JSON works when calling this site directly or through an OpenAI-compatible new-api channel.

Generate from multiple references

curl https://zerofa.ai/v1/images/generations \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "Combine the character, outfit, and setting references into a cinematic poster",
    "images": [
      "https://example.com/person.png",
      "https://example.com/outfit.png",
      "data:image/png;base64,..."
    ],
    "size": "2048x2048",
    "response_format": "url"
  }'

References may be public URLs or data URIs. Array order is preserved, so describe the purpose of image 1 and image 2 in the prompt. Limits on reference count, dimensions, and output capability depend on the model. Use native passthrough and the provider's official docs for provider-specific advanced fields.

Response

Each item in data represents one image with either url or b64_json according to response_format. url values are temporary, so download them for long-term storage.

{
  "created": 1715961234,
  "data": [
    { "url": "https://.../generated.png" }
  ]
}

Use response_format=url for server-side mirroring and browser display. b64_json makes the response much larger and is best for small batches that must stay inline. The format does not change generation quality.

Edit images (image to image)

POST/v1/images/edits

Upload reference images with multipart/form-data and provide a prompt. In addition to the standard OpenAI mask, bbox_list=[[[x1,y1,x2,y2]], ...] is available as a rectangular-region extension. Each outer entry maps to one input image, coordinates are absolute source-image pixels, and each image accepts at most two boxes. mask and bbox_list are mutually exclusive. OpenAI routes convert first-image boxes to a mask, while Wan 2.7 uses bbox_list natively; unsupported models return an explicit error. The upstream controls output dimensions, which may not exactly match size.

Image edit · curl

curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=your-image-model-id" \
  -F "prompt=Replace the background with a starry night sky" \
  -F "size=1024x1024" \
  -F "image=@source.png;type=image/png"

# 精确矩形区域编辑：bbox_list 按 image/image[] 的顺序对齐
curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=wan2.7-image-pro" \
  -F "prompt=替换框选区域内的物体" \
  -F "image=@source.png;type=image/png" \
  -F 'bbox_list=[[[120,80,640,720]]]'

JSON multi-image edit · OpenAI / new-api compatible

curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "融合两张参考图的构图和材质",
    "images": [
      {"image_url": "https://example.com/reference-1.png"},
      {"image_url": "data:image/png;base64,..."}
    ],
    "input_fidelity": "high",
    "output_format": "webp",
    "response_format": "url"
  }'

JSON edits accept images[].image_url as a public URL or data URI. This platform does not expose a Files API, so file_id is unsupported; use multipart/form-data for local files.

Streaming image responses

stream=true returns standard OpenAI Images SSE events. The unified router always emits image_generation.completed or image_edit.completed; partial_image events depend on the supply route and may be absent.

SSE

curl -N https://zerofa.ai/v1/images/generations \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "A shiba inu wearing a space helmet, flat illustration",
    "stream": true,
    "partial_images": 2
  }'

# 终态事件：event: image_generation.completed
# data: {"type":"image_generation.completed","b64_json":"..."}

Tool models through OpenAI Images Edits

The same POST /v1/images/edits endpoint also handles background removal and image upscaling. Use background-removal-1 for a transparent PNG, or image-upscale, image-upscale-2x, and image-upscale-4x for super-resolution.

Image upscale target priority is size > long_side/short_side > scale > default 2x. size, scale, long_side, and short_side are ZeroFA-compatible extensions.

Background removal and upscale · OpenAI Images Edits

# Background removal
curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=background-removal-1" \
  -F "prompt=Remove the background and preserve the subject" \
  -F "image=@source.png;type=image/png"

# Image upscale: size > long_side/short_side > scale > default 2x
curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=image-upscale" \
  -F "prompt=Upscale while preserving all details" \
  -F "image=@source.png;type=image/png" \
  -F "size=2048x1536" \
  -F "response_format=url"

Asynchronous generation

In addition to synchronous generation, submit an asynchronous image task and poll for the result.

status	Meaning
submitted	The task is durable and waiting for background dispatch.
running	The upstream accepted the task and is generating.
succeeded	The task succeeded and data contains the final images.
failed	The task failed and error.message contains the public reason.

POST/v1/images/generations/tasks

Task submission is not charged. The body matches /v1/images/generations and immediately returns an id with submitted status.

① Submit

curl https://zerofa.ai/v1/images/generations/tasks \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "A shiba inu wearing a space helmet, flat illustration",
    "size": "3840x2160"
  }'
# → {"id":"<task-id>","model":"your-image-model-id","status":"submitted"}

GET/v1/images/generations/tasks/{id}

Poll every few seconds until succeeded or failed. Success returns OpenAI-style data and is billed once by actual image count; repeated polling does not charge twice. Failures and timeouts are free, and temporary image URLs should be downloaded promptly.

② Poll

curl https://zerofa.ai/v1/images/generations/tasks/<task-id> \
  -H "Authorization: Bearer sk-zerofa-xxx"
# running   → {"id":"...","status":"running"}
# succeeded → {"id":"...","status":"succeeded",
#              "data":[{"url":"https://.../4k.png"}]}

Start polling every 2–3 seconds and back off gradually. Retry network failures and 5xx responses; fix request parameters, permissions, or insufficient balance before submitting again.

Available models

See text-to-image models in the Model Catalog and filter for Image. Prices vary by model, size, and billing mode.

Request and response bodies

Use the examples below to verify the request and response structures. To send a request, select Debug at the top of the page.

curl https://zerofa.ai/v1/images/generations \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "A shiba inu wearing a space helmet, flat illustration",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

Response · 200

{
  "created": 1715961234,
  "data": [
    { "url": "https://.../generated.png" }
  ]
}

Choose an image workflow

Generation, reference-based creation, editing, and asynchronous tasks use different input shapes. Choose the workflow first so multipart fields do not end up in a JSON request.

Goal	Endpoint	Key input
Text to image	POST /v1/images/generations	prompt
One or multiple reference images	POST /v1/images/generations	image / images[]
Edit, mask, or bounding-box region	POST /v1/images/edits	multipart / JSON
SSE result stream	POST /v1/images/generations	stream=true
Long-running asynchronous generation	POST /v1/images/generations/tasks	Same JSON body as generations

Request parameters

Header parameters

AuthorizationstringRequired

API key in the format Bearer <key>.

Example:Bearer sk-zerofa-xxx

Content-TypestringRequired

Example:application/json

Body parametersapplication/json

modelstringRequired

The text-to-image model. See available models below.

Example:your-image-model-id

promptstringRequired

A description of the desired image. More detail gives greater control.

Example:A shiba inu wearing a space helmet, flat illustration

imagestring | string[]Optional

A reference image as one URL/data URI or an array of URL/data URI values.

Example:https://.../reference.png

imagesstring[] | object[]Optional

Recommended for multiple references. Accepts an array of URL/data URI strings or compatible {image_url} objects.

Example:["https://.../a.png","https://.../b.png"]

nintegerOptional

Number of images to generate, default 1.

Example:1

sizestringOptional

Example:1024x1024

qualitystringOptional

Quality values depend on the model. gpt-image supports low, medium, high, and auto; dall-e-3 supports standard and hd. Unsupported values are ignored and the upstream default is used.

Example:high

response_formatstringOptional

url (default) returns an image link; b64_json returns base64.

Example:url

output_formatstringOptional

Output encoding: png, jpeg, or webp. The actual encoding changes only when the selected model supports it.

Example:webp

backgroundstringOptional

Background mode: auto, opaque, or transparent, depending on model capability.

Example:transparent

streambooleanOptional

Enable an OpenAI Images SSE response. Synchronous cross-provider routes emit a terminal completed event.

Example:true

partial_imagesintegerOptional

Request 0–3 partial previews with stream=true. Fast or non-streaming upstreams may return zero partial images.

Example:2

Recommended sizes for gpt-image

Width and height must be divisible by 16, the long edge must be at most 3840, the aspect ratio at most 3:1, and total pixels 655,360–8,294,400. Swap width and height for portrait output.

Ratio	1K	2K	4K
1:1	1024x1024	2048x2048	2880x2880
4:3	1360x1024	2048x1536	3312x2480
3:2	1536x1024	2048x1360	3504x2336
16:9	1824x1024	2048x1152	3840x2160
21:9	2384x1024	2048x880	3840x1648

Image-to-image and multiple references (site / new-api)

Generate from multiple references

curl https://zerofa.ai/v1/images/generations \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "Combine the character, outfit, and setting references into a cinematic poster",
    "images": [
      "https://example.com/person.png",
      "https://example.com/outfit.png",
      "data:image/png;base64,..."
    ],
    "size": "2048x2048",
    "response_format": "url"
  }'

Response

Each item in data represents one image with either url or b64_json according to response_format. url values are temporary, so download them for long-term storage.

{
  "created": 1715961234,
  "data": [
    { "url": "https://.../generated.png" }
  ]
}

Edit images (image to image)

POST/v1/images/edits

Image edit · curl

curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=your-image-model-id" \
  -F "prompt=Replace the background with a starry night sky" \
  -F "size=1024x1024" \
  -F "image=@source.png;type=image/png"

# 精确矩形区域编辑：bbox_list 按 image/image[] 的顺序对齐
curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=wan2.7-image-pro" \
  -F "prompt=替换框选区域内的物体" \
  -F "image=@source.png;type=image/png" \
  -F 'bbox_list=[[[120,80,640,720]]]'

JSON multi-image edit · OpenAI / new-api compatible

curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "融合两张参考图的构图和材质",
    "images": [
      {"image_url": "https://example.com/reference-1.png"},
      {"image_url": "data:image/png;base64,..."}
    ],
    "input_fidelity": "high",
    "output_format": "webp",
    "response_format": "url"
  }'

JSON edits accept images[].image_url as a public URL or data URI. This platform does not expose a Files API, so file_id is unsupported; use multipart/form-data for local files.

Streaming image responses

SSE

curl -N https://zerofa.ai/v1/images/generations \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "A shiba inu wearing a space helmet, flat illustration",
    "stream": true,
    "partial_images": 2
  }'

# 终态事件：event: image_generation.completed
# data: {"type":"image_generation.completed","b64_json":"..."}

Tool models through OpenAI Images Edits

Image upscale target priority is size > long_side/short_side > scale > default 2x. size, scale, long_side, and short_side are ZeroFA-compatible extensions.

Background removal and upscale · OpenAI Images Edits

# Background removal
curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=background-removal-1" \
  -F "prompt=Remove the background and preserve the subject" \
  -F "image=@source.png;type=image/png"

# Image upscale: size > long_side/short_side > scale > default 2x
curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=image-upscale" \
  -F "prompt=Upscale while preserving all details" \
  -F "image=@source.png;type=image/png" \
  -F "size=2048x1536" \
  -F "response_format=url"

Asynchronous generation

In addition to synchronous generation, submit an asynchronous image task and poll for the result.

status	Meaning
submitted	The task is durable and waiting for background dispatch.
running	The upstream accepted the task and is generating.
succeeded	The task succeeded and data contains the final images.
failed	The task failed and error.message contains the public reason.

POST/v1/images/generations/tasks

Task submission is not charged. The body matches /v1/images/generations and immediately returns an id with submitted status.

① Submit

curl https://zerofa.ai/v1/images/generations/tasks \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "A shiba inu wearing a space helmet, flat illustration",
    "size": "3840x2160"
  }'
# → {"id":"<task-id>","model":"your-image-model-id","status":"submitted"}

GET/v1/images/generations/tasks/{id}

② Poll

curl https://zerofa.ai/v1/images/generations/tasks/<task-id> \
  -H "Authorization: Bearer sk-zerofa-xxx"
# running   → {"id":"...","status":"running"}
# succeeded → {"id":"...","status":"succeeded",
#              "data":[{"url":"https://.../4k.png"}]}

Start polling every 2–3 seconds and back off gradually. Retry network failures and 5xx responses; fix request parameters, permissions, or insufficient balance before submitting again.

Available models

See text-to-image models in the Model Catalog and filter for Image. Prices vary by model, size, and billing mode.

Request and response bodies

Use the examples below to verify the request and response structures. To send a request, select Debug at the top of the page.

curl https://zerofa.ai/v1/images/generations \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model-id",
    "prompt": "A shiba inu wearing a space helmet, flat illustration",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

Response · 200

{
  "created": 1715961234,
  "data": [
    { "url": "https://.../generated.png" }
  ]
}

Generate images

Choose an image workflow

Request parameters

Image-to-image and multiple references (site / new-api)

Response

Edit images (image to image)

Streaming image responses

Tool models through OpenAI Images Edits

Asynchronous generation

Available models

Request and response bodies

Generate images

Choose an image workflow

Request parameters

Image-to-image and multiple references (site / new-api)

Response

Edit images (image to image)

Streaming image responses

Tool models through OpenAI Images Edits

Asynchronous generation

Available models

Request and response bodies