88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
Image

Gemini Image Model API

Request formats for Gemini 3.1 Flash Image, Nano Banana 2.1 and Gemini 3 Pro Image over the OpenAI-compatible and Gemini native protocols, plus aspect ratios, resolutions and reference images.

Scope

This page covers Gemini image models. For OpenAI image models, see OpenAI Image Model API; for Grok image models, see Grok Image Model API.

Key difference

Gemini image models are not OpenAI Images API models. Use /v1/chat/completions or the Gemini native /v1beta/models/{model}:generateContent, and do not send requests to /v1/images/generations or /v1/images/edits.

Models and capabilities

ModelResolutionReference imagesImages per requestBilling
gemini-3.1-flash-image1K (default) / 2K / 4K
image_config
up to 14 (data URI / public URL)always 1per request
gemini-nano-banana-2.11K (default) / 2K / 4K
image_config
up to 6 (data URI / public URL)always 1per request
gemini-3-pro-image1K (default) / 2K / 4K
image_config
up to 14 (data URI / public URL)always 1per request

Supported aspect ratios: 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9

  • All three models are billed per request, with the same price regardless of resolution or the number of reference images.
  • Each request returns only 1 image; n and candidateCount have no effect. If you need several images, send multiple requests in parallel.
  • For gemini-nano-banana-2.1, we recommend at most 6 reference images per request; any beyond that may be ignored.

The model list returned in the console is the authoritative list of available models.

Supported protocols

ProtocolEndpointRequest bodyUse case
OpenAI-compatible (recommended)POST /v1/chat/completionsmodel + messagesOpenAI SDK, unified clients and most applications
Gemini nativePOST /v1beta/models/{model}:generateContentcontents + generationConfigUsing the Gemini SDK directly, or when you need native fields

Authentication

For the OpenAI-compatible protocol, use:

Authorization: Bearer $API_KEY
Content-Type: application/json

With the Gemini native protocol you can also use the x-goog-api-key header, as Gemini clients usually do; its value is still your 88API token. Never put a real key in front-end code, logs or public examples.

Aspect ratio and resolution

Aspect ratio and resolution are set through image_config:

  • aspect_ratio: see the capability table above.
  • image_size: 1K (default), 2K or 4K. Use an uppercase K.

Output pixels for each level:

Ratio1K2K4K
1:11024x10242048x20484096x4096
2:3848x12641696x25283392x5056
3:21264x8482528x16965056x3392
3:4896x12001792x24003584x4800
4:31200x8962400x17924800x3584
4:5928x11521856x23043712x4608
5:41152x9282304x18564608x3712
9:16768x13761536x27523072x5504
16:91376x7682752x15365504x3072
21:91584x6723168x13446336x2688
  • If you omit the aspect ratio, the model chooses the framing based on the prompt; when reference images are provided, it follows the aspect ratio of the first reference image by default. If you need a fixed size, pass aspect_ratio explicitly.
  • Output may be JPEG or PNG. Save the file according to the returned MIME type rather than assuming an extension.

Text-to-image

curl https://api.88api.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "messages": [
      {
        "role": "user",
        "content": "Generate an image of an orange cat sitting by a window, natural afternoon light, realistic photography style"
      }
    ],
    "extra_body": {
      "google": {
        "image_config": {
          "aspect_ratio": "16:9",
          "image_size": "2K"
        }
      }
    }
  }'

How to write image_config

Aspect ratio and resolution must go inside extra_body.google.image_config, using the snake_case field names aspect_ratio and image_size. image_config, aspect_ratio or size at the top level of the request are ignored; camelCase names such as imageConfig or aspectRatio are rejected.

With reference images

curl https://api.88api.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Using the person in the first image as reference, create a movie poster featuring the same person" },
          { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }
        ]
      }
    ],
    "extra_body": {
      "google": { "image_config": { "aspect_ratio": "2:3", "image_size": "2K" } }
    }
  }'
  • image_url.url can be a Data URI or a public image URL. A Data URI must include the full media type prefix, for example data:image/png;base64,....
  • PNG, JPEG, WebP and GIF are supported; BMP is not. We recommend keeping each image under 7 MB.
  • Multiple reference images are used in order, so your prompt can refer to them as "the first image", "the second image" and so on.

Request fields

FieldTypeRequiredDescription
modelstringyesGemini image model name.
messagesarrayyesOpenAI Chat Completions message array, usually a single user message.
messages[].contentstring or arrayyesUse a string for plain text; use a content array when mixing text and reference images.
content[].image_url.urlstringnoReference image, as a Data URI or public URL.
extra_body.google.image_config.aspect_ratiostringnoAspect ratio.
extra_body.google.image_config.image_sizestringno1K, 2K or 4K.

Response

The image is returned as a Markdown image in choices[0].message.content:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "![image](data:image/jpeg;base64,/9j/4AAQ...)"
      },
      "finish_reason": "stop"
    }
  ]
}

Extract the data:<mime>;base64,... part from content to get the image. Do not parse the response as the data array of /v1/images/generations.

Gemini native protocol

Text-to-image

curl "https://api.88api.ai/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Generate an image of an orange cat sitting by a window, natural afternoon light, realistic photography style" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
    }
  }'

Reference images

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Using this image as reference, create a movie poster featuring the same person" },
        { "inlineData": { "mimeType": "image/png", "data": "<BASE64_DATA>" } }
      ]
    }
  ],
  "generationConfig": {
    "imageConfig": { "aspectRatio": "2:3" }
  }
}

Public images can also be passed with fileData: { "fileData": { "mimeType": "image/jpeg", "fileUri": "https://..." } }.

Response

The image is in candidates[0].content.parts[].inlineData, where mimeType is the image type and data is the Base64 content.

Streaming and timeouts

stream: true works, but the image is returned all at once in a single event, with no progressive preview. We recommend non-streaming requests and a client timeout of at least 5 minutes: 4K images usually take 30 to 60 seconds, and longer at peak times.

What not to do

# Wrong: do not use the OpenAI Images API path for Gemini image models
curl https://api.88api.ai/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "An orange cat"
  }'

Requests like this return 请使用 Gemini 原生接口调用 / please use the Gemini native API. Use the Chat Completions or native generateContent format described on this page instead.

Common errors

ErrorCause
请使用 Gemini 原生接口调用 (please use the Gemini native API)The request was sent to /v1/images/*.
extra_body.google.imageConfig is not supported, use extra_body.google.image_config insteadimage_config was written in camelCase.
mime type is not supported by GeminiThe reference image format is not supported, for example BMP.
failed to download fileThe reference image URL could not be downloaded; make sure the link is publicly accessible.
Content moderation failure messageThe prompt or reference image did not pass the safety review, or the model replied with text only and produced no image. Adjust the prompt and try again.

Failed requests like these are not charged.