Generic Image Generation

/v1/images/generations is the recommended generic image entrypoint in Models Hub. For text-to-image, send model and prompt. For reference-image generation or image editing, also send images, image, or image_urls.

Supported parameters are not identical across models. Keep the unified entrypoint, but choose fields and values according to the requested model.

Endpoints

Supported Models

Generic Request Fields

Model-Specific Parameters

nano-banana Families

The nano-banana family includes nano-banana, nano-banana-2, nano-banana-2-lite, and nanp-banana-pro. Prefer images, aspect_ratio, resolution, and output_format.

{
  "model": "nano-banana-2",
  "prompt": "Replace the item in the poster with a cup",
  "images": [
    "https://example.com/input.png"
  ],
  "aspect_ratio": "4:3",
  "resolution": "2k",
  "output_format": "png",
  "enable_web_search": false,
  "enable_image_search": false
}

gpt-image-2

gpt-image-2 may use either OpenAI-compatible size parameters or tiered image parameters, depending on the active channel. Do not treat size and the nano-banana resolution tier as the same semantic field. See the Image Generation Guide for the full size rules and quality tiers.

{
  "model": "gpt-image-2",
  "prompt": "A cinematic product photo of a ceramic cup",
  "size": "1536x1024",
  "quality": "high"
}

If the active channel uses ratio and tier fields, call it like this:

{
  "model": "gpt-image-2",
  "prompt": "A cinematic product photo of a ceramic cup",
  "aspect_ratio": "4:3",
  "resolution": "2k",
  "quality": "high",
  "output_format": "png"
}

Async Image Generation (Recommended, especially for gpt-image-2)

Models such as gpt-image-2 can take a while to render synchronously (commonly 30 seconds to over 2 minutes). A synchronous call holds the connection open the whole time, so upstream jitter or a gateway/CDN timeout can surface as 500 (upstream failure passed through) or 504 (gateway timeout).

Prefer async: add the ?async=true query parameter to POST /v1/images/generations. The gateway returns a task object (with an id) immediately; you then poll the task result at a fixed interval until it succeeds. Each request stays short, avoiding long-connection timeouts entirely.

1. Submit asynchronously

curl "$MODELSOK_BASE_URL/v1/images/generations?async=true" \
  -H "Authorization: Bearer $MODELSOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a ceramic cup",
    "size": "1024x1024"
  }'

The response returns an async task object immediately; keep its id:

{
  "id": "task_xxx",
  "object": "image.task",
  "created": 1770000000,
  "model": "gpt-image-2",
  "status": "created"
}

2. Poll the task result

Call the query endpoint with the id from the previous step, polling every 3–5 seconds:

curl "$MODELSOK_BASE_URL/v1/tasks/task_xxx" \
  -H "Authorization: Bearer $MODELSOK_API_KEY"

When the task succeeds, the result contains the final image (url or b64_json, depending on response_format). If it fails, read the error and retry as needed.

Note: Synchronous calls (without ?async=true) still work and suit fast models such as the nano-banana family. For slow models like gpt-image-2, async is strongly recommended to avoid 500 / 504 timeouts on the synchronous long connection.

Image Editing

For reference-image input, prefer the images array. image also works for single-image input, but images is clearer for multi-image editing.

{
  "model": "nano-banana-2",
  "prompt": "Replace the main object in the reference poster with a cup",
  "images": [
    "https://example.com/poster.png"
  ],
  "aspect_ratio": "4:3",
  "resolution": "2k"
}

Response

Some image models return an async task ID:

{
  "id": "task_xxx",
  "object": "image.task",
  "created": 1770000000,
  "model": "nano-banana-2",
  "status": "created"
}

After the task completes, poll GET /v1/tasks/{task_id} for the final image URL (see "Async Image Generation" above). Whether the call waits synchronously and returns the OpenAI image format depends on whether the request includes ?async=true, plus the active model and channel configuration.