Gemini image generation

Gemini image generation (nicknamed Banana) uses the OpenAI Images API and returns Base64 images synchronously; the two groups differ in edit endpoint and billing.

Available models

Choosing a model: only gemini-3-pro-image offers 4K; gemini-3.1-flash-image charges the same for 1K and 2K; avoid Lite for multi-reference composition, as it is not optimized for multiple references.

How the two groups differ:

Gemini Official Direct can also call image models through /v1/chat/completions, with the image returned as a markdown-embedded data URL.

Request parameters

Generate

POST /v1/images/generations with a JSON body. Use the OpenAI Images structure; do not send a Gemini-native generateContent payload.

Allowed aspect_ratio values: 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9.

image_config has three equivalent forms. If more than one is present, the first in this order wins:

• google.image_config
• extra_body.google.image_config (the OpenAI SDK form)
• Flat top-level aspect_ratio / image_size

An explicit image_size above the model's tiers returns 400.

A WIDTHxHEIGHT size is never rejected for its ratio. It maps to the nearest official ratio, and the tier (from the long edge) is silently capped at the model's top tier with no error.

For example, 4096x4096 on gemini-3.1-flash-image returns a 2K image. A tier shorthand above the model's tiers returns 400.

n is also capped by output tier: 4K ≤ 2, 2K ≤ 5, 1K ≤ 10 (response-size limit); going over returns 400.

Reference images

Both groups take references in image / images on generations, JSON only. Each item is an http(s) URL or Data URL string; URLs must be reachable by the server and must not point to an internal address.

Gemini (all models, incl. image) compresses references over 4 MiB before generating. Officially, gemini-2.5-flash-image takes at most 3 references. Data URL example: data:image/png;base64,iVBORw0KGgo…, with a MIME type that matches the image.

Edit (Gemini (all models, incl. image) only)

POST /v1/images/edits prefers multipart/form-data and also accepts JSON (references as URL / Data URL). At least one reference image is required.

Gemini Official Direct has no such endpoint and returns 404; to edit there, send references to generations. Neither group supports mask, which returns 400.

Async

With the HTTP header Prefer: respond-async, the request immediately returns 202 Accepted and a task_id. Prefer this for 2K / 4K images so long requests are not cut off by CDN timeouts.

Response

Sync requests return OpenAI Images JSON, with the image in data[].b64_json.

{
  "created": 1760000000,
  "model": "gemini-3-pro-image",
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQ...",
      "mime_type": "image/jpeg"
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1120,
    "total_tokens": 1162
  }
}

Async tasks

Submitting returns immediately:

{
  "task_id": "imgtask_EXAMPLE",
  "status": "pending",
  "status_url": "/v1/images/tasks?task_id=imgtask_EXAMPLE"
}

Query only with the task_id query parameter; putting the task ID in the path is not supported.

The response once the task completes:

{
  "task_id": "imgtask_EXAMPLE",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "currency": "CNY",
    "cost_cny": 1.36,
    "cost_usd": 0.2
  }
}

Examples

Text to image

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A ceramic teapot on a sunlit wooden table, product photo",
    "google": {
      "image_config": { "aspect_ratio": "16:9", "image_size": "2K" }
    }
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > result.png

The curl example needs jq. If data[].mime_type is image/jpeg, rename the file to .jpg.

Edit with reference images

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "Recolor the cup in image 1 with the palette of image 2",
    "images": [
      "https://example.com/cup.png",
      "https://example.com/palette.png"
    ],
    "size": "1024x1024"
  }'

Notes

• Only Gemini (all models, incl. image) offers /v1/images/edits; with the other group, send references to generations.
• Results are Base64 and may be JPEG, so check data[].mime_type before saving.
• mask is not supported; describe the area to change in the prompt.
• Transparent output is not possible, and background: "transparent" returns 400.
• stream: true is not supported; keep the default sync mode or use async tasks.
• For 2K / 4K images, add Prefer: respond-async, or give sync requests a long client read timeout.
• Before a paid request, take the full ID from GET /v1/models with your key, and do not append a tier suffix.

Common errors

Invalid parameters return 400 before generation and are not billed.

# Gemini (all models, incl. image)
prompt must not be empty
n must be between 1 and 10 for model gemini-3-pro-image
n=3 is too large for 4K output on model gemini-3-pro-image; at most 2 images per request at this size (response size limit); lower n or send separate requests
model gemini-3.1-flash-image does not support tier 4K; supported: 1K, 2K
model gemini-3-pro-image: size "big" is not valid; expected WIDTHxHEIGHT (any aspect ratio, mapped to the nearest official tier) or 1K/2K/4K
aspect_ratio "7:3" is not supported for model gemini-3-pro-image; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_size "4K" is not supported for model gemini-3.1-flash-image; supported: 1K, 2K
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
mask is not supported for Gemini image models; remove mask and describe the region to edit in the prompt
too many reference images: at most 14 are supported for this model, got 15

# Gemini Official Direct
missing prompt
Gemini image generation does not support stream=true; send a non-streaming request
n must be at most 10
n=6 is too large for 2K output on model gemini-3.1-flash-image; at most 5 images per request at this size (response size limit); lower n or send separate requests
Images generations only accepts a JSON request body: ...
size 4K is not supported for model gemini-3.1-flash-image; supported tiers: 1K, 2K
size "banana" is not valid for model gemini-3-pro-image; use auto, WIDTHxHEIGHT (e.g. 1024x1024, mapped to the nearest supported aspect ratio and capped at the model's largest tier), or one of: 1K, 2K, 4K
image_config.aspect_ratio "7:3" is not supported; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_config.image_size "4K" is not supported for model gemini-3.1-flash-image; allowed values: 1K, 2K
mask is not supported for model gemini-3-pro-image; remove mask and describe the region to edit in the prompt
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
reference image 1: reference image exceeds the 20MB limit
reference image 1: reference image URL must not point to an internal address
reference image 1: reference image download returned HTTP 404
reference image 1: reference file is not a supported image type

Billing

Gemini (all models, incl. image) bills per image delivered; Gemini Official Direct bills by token, at the tier actually generated. Invalid parameters and partial failures are not billed; once an async task ends, usage.cost in the query response is the amount actually charged.

Prices are on each model card and in the signed-in model catalog.

Next steps

• Image generation overview
• GPT Image, Seedream, Grok Imagine images, Kling images
• API reference: Create image, Edit image, Query image task
• When something fails, check Troubleshooting