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
| Model | Resolution | Reference images | Images per request | Billing |
|---|---|---|---|---|
gemini-3.1-flash-image | 1K (default) / 2K / 4Kimage_config | up to 14 (data URI / public URL) | always 1 | per request |
gemini-nano-banana-2.1 | 1K (default) / 2K / 4Kimage_config | up to 6 (data URI / public URL) | always 1 | per request |
gemini-3-pro-image | 1K (default) / 2K / 4Kimage_config | up to 14 (data URI / public URL) | always 1 | per 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;
nandcandidateCounthave 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
| Protocol | Endpoint | Request body | Use case |
|---|---|---|---|
| OpenAI-compatible (recommended) | POST /v1/chat/completions | model + messages | OpenAI SDK, unified clients and most applications |
| Gemini native | POST /v1beta/models/{model}:generateContent | contents + generationConfig | Using the Gemini SDK directly, or when you need native fields |
Authentication
For the OpenAI-compatible protocol, use:
Authorization: Bearer $API_KEY
Content-Type: application/jsonWith 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),2Kor4K. Use an uppercaseK.
Output pixels for each level:
| Ratio | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 2:3 | 848x1264 | 1696x2528 | 3392x5056 |
| 3:2 | 1264x848 | 2528x1696 | 5056x3392 |
| 3:4 | 896x1200 | 1792x2400 | 3584x4800 |
| 4:3 | 1200x896 | 2400x1792 | 4800x3584 |
| 4:5 | 928x1152 | 1856x2304 | 3712x4608 |
| 5:4 | 1152x928 | 2304x1856 | 4608x3712 |
| 9:16 | 768x1376 | 1536x2752 | 3072x5504 |
| 16:9 | 1376x768 | 2752x1536 | 5504x3072 |
| 21:9 | 1584x672 | 3168x1344 | 6336x2688 |
- 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_ratioexplicitly. - Output may be JPEG or PNG. Save the file according to the returned MIME type rather than assuming an extension.
OpenAI-compatible protocol (recommended)
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.urlcan be a Data URI or a public image URL. A Data URI must include the full media type prefix, for exampledata: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
| Field | Type | Required | Description |
|---|---|---|---|
model | string | yes | Gemini image model name. |
messages | array | yes | OpenAI Chat Completions message array, usually a single user message. |
messages[].content | string or array | yes | Use a string for plain text; use a content array when mixing text and reference images. |
content[].image_url.url | string | no | Reference image, as a Data URI or public URL. |
extra_body.google.image_config.aspect_ratio | string | no | Aspect ratio. |
extra_body.google.image_config.image_size | string | no | 1K, 2K or 4K. |
Response
The image is returned as a Markdown image in choices[0].message.content:
{
"choices": [
{
"message": {
"role": "assistant",
"content": ""
},
"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
| Error | Cause |
|---|---|
请使用 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 instead | image_config was written in camelCase. |
mime type is not supported by Gemini | The reference image format is not supported, for example BMP. |
failed to download file | The reference image URL could not be downloaded; make sure the link is publicly accessible. |
| Content moderation failure message | The 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.
OpenAI Image Model API
Endpoints, sizes, quality levels, reference images and transparent backgrounds for the gpt-image-2, gpt-image-2.5 and az-gpt-image image model families.
Grok Image Model API
Text-to-image and image editing endpoints, aspect ratios, resolutions, reference images and errors for the Grok Imagine image models (grok-imagine-image, 2.0, quality, edit).