POST

/v1/images/generations

API reference

OpenAI-compatible endpoint for generating and editing images.

Image models are temporarily unavailable

Requests to them currently get 503 model_disabled. The format below will work again once the models are switched back on — watch GET /v1/models.

Authorization required. You are charged per generated image at the model's price. Before generation the balance must cover the price of one image, otherwise 402 insufficient_balance.

curl example

bash

curl https://api.zukko.pro/v1/images/generations \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai-gpt-image-2-text-to-image",
    "prompt": "A cinematic travel poster for Kyoto in autumn",
    "size": "1024x1024",
    "quality": "high"
  }'

Request — text-to-image

JSON

bash

{
  "model": "openai-gpt-image-2-text-to-image",
  "prompt": "A cinematic travel poster for Kyoto in autumn",
  "size": "1024x1024",
  "quality": "high"
}

Request — edit

For edit / reference models, pass the input images in images: public URLs or data URLs (data:image/png;base64,...).

JSON

bash

{
  "model": "openai-gpt-image-2-edit",
  "prompt": "Make the sky sunset orange",
  "images": [
    "https://example.com/photo.jpg"
  ]
}

Request — base64 response

To get the image in the response body instead of a link, send response_format: "b64_json". data[] then contains b64_json instead of url.

JSON

json

{
  "model": "openai-gpt-image-2-text-to-image",
  "prompt": "A cinematic travel poster for Kyoto in autumn",
  "response_format": "b64_json"
}

Parameters

Parameter

Type

Required

Description

model

string

Yes

Image model ID (see the list below)

prompt

string

Yes

Text description of the image or the edit

images

array

Conditional

URLs or data URLs of the input images. Required for edit models; reference models need images or video_clips

response_format

string

"b64_json" — return the image as base64 instead of a link

size

string

Size for GPT Image, e.g. 1024x1024

quality

string

Quality for GPT Image: low | medium | high

output_format

string

File format for GPT Image, e.g. png

moderation

string

Moderation level for GPT Image

integer

Number of images (if the model supports it)

seed

integer

Seed for reproducibility (if the model supports it)

aspect_ratio

string

Aspect ratio for Nano Banana, e.g. 1:1

resolution

string

Resolution for Nano Banana: 1k | 2k | 4k

Response

JSON

bash

{
  "created": 1735689600,
  "model": "openai-gpt-image-2-text-to-image",
  "data": [
    {
      "url": "https://cdn.example.com/outputs/result.png"
    }
  ]
}

Response fields

Field

Type

Description

created

integer

Unix timestamp of the response

model

string

ID of the Zukko model that served the request

data

array

Array of results

data[].url

string

URL of the generated image

data[].b64_json

string

The image as base64 — instead of url when response_format: "b64_json" is sent

Available models

model

Mode

Name

openai-gpt-image-2-text-to-image

text-to-image

GPT Image 2

openai-gpt-image-2-edit

edit

GPT Image 2 Edit

openai-gpt-image-1.5-text-to-image

text-to-image

GPT Image 1.5

openai-gpt-image-1.5-edit

edit

GPT Image 1.5 Edit

nano-banana-2-text-to-image-developer

text-to-image

Nano Banana 2 Developer

nano-banana-2-text-to-image

text-to-image

Nano Banana 2

nano-banana-2-edit-developer

edit

Nano Banana 2 Edit

nano-banana-2-reference-to-image-developer

reference

Nano Banana 2 Reference

nano-banana-2-lite-text-to-image-developer

text-to-image

Nano Banana 2 Lite

nano-banana-2-lite-edit-developer

edit

Nano Banana 2 Lite Edit

Errors

401 — missing or invalid API key
400 invalid_request_error — missing prompt, or no images for an edit model
402 insufficient_balance — the balance does not cover one image
404 model_not_found — unknown image model id
503 model_disabled — the model is temporarily switched off (currently all image models)
503 image_provider_unavailable — the image generation service is unavailable
503 image_provider_busy — the image generation service is overloaded, retry later
502 image_generation_failed — generation failed, retry the request
504 image_generation_timeout — generation took longer than 3 minutes

POST /v1/chat/completions

POST /v1/messages