Gemini Image Generation

Overview

AIone supports Gemini image generation models, accessible through the standard OpenAI-compatible /v1/chat/completions endpoint.

These models are internally routed through the Gemini native image generation pipeline, with responses converted back to the OpenAI-compatible format. Your request format stays the same, but you can use additional image-specific parameters.

Image Model Overview

If you are unsure about a model name, refer to GET https://api.portal.aiin1.ai/v1/models and the Portal model list page.

Gemini 3.1 Flash Image — Integration Guide

gemini-3.1-flash-image-preview is the most cost-effective image generation model, supporting 4 resolution tiers (512 – 4K) controlled via the image_size parameter.

Default 1K Resolution

When image_size is omitted, images are generated at 1K (1024×1024):

curl https://api.portal.aiin1.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [
      {"role": "user", "content": "Draw a cute cat"}
    ],
    "max_tokens": 4096
  }'

Generate 2K HD Images

curl https://api.portal.aiin1.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [
      {"role": "user", "content": "Draw a cute cat"}
    ],
    "max_tokens": 4096,
    "image_size": "2K"
  }'

Generate 4K Ultra-HD Images

curl https://api.portal.aiin1.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [
      {"role": "user", "content": "Draw a cute cat"}
    ],
    "max_tokens": 4096,
    "image_size": "4K"
  }'

Note: 4K image generation can take 2-3 minutes. We strongly recommend using "stream": true — the gateway sends a keepalive heartbeat every 10 seconds, preventing intermediate network devices (NAT/firewalls/proxies) from dropping the idle TCP connection. Also set your client HTTP timeout to at least 600 seconds.

Custom Aspect Ratio + Resolution

aspect_ratio and image_size can be combined:

curl https://api.portal.aiin1.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [
      {"role": "system", "content": "You are an illustrator. Output an image suitable for a banner cover."},
      {"role": "user", "content": "Draw a cute cat"}
    ],
    "max_tokens": 4096,
    "image_size": "2K",
    "aspect_ratio": "16:9",
    "temperature": 0.8
  }'

OpenAI Python SDK Example

from openai import OpenAI
 
client = OpenAI(
    api_key="sk-nex-your-key-here",
    base_url="https://api.portal.aiin1.ai/v1",
)
 
# Generate a 2K image
response = client.chat.completions.create(
    model="gemini-3.1-flash-image-preview",
    messages=[{"role": "user", "content": "Draw a cute cat"}],
    max_tokens=4096,
    extra_body={
        "image_size": "2K",
        "aspect_ratio": "16:9",
    },
)
 
# Handle the response
# content is a string (may contain markdown-formatted inline images)
print(response.choices[0].message.content)
 
# Image data is returned via a separate images field (absent for text-only responses)
images = getattr(response.choices[0].message, "images", None)
if images:
    for img in images:
        base64_data = img["image_url"]["url"]  # data:image/jpeg;base64,...

OpenAI Node.js SDK Example

import OpenAI from "openai";
 
const client = new OpenAI({
  apiKey: "sk-nex-your-key-here",
  baseURL: "https://api.portal.aiin1.ai/v1",
});
 
const response = await client.chat.completions.create({
  model: "gemini-3.1-flash-image-preview",
  messages: [{ role: "user", content: "Draw a cute cat" }],
  max_tokens: 4096,
  // @ts-ignore — non-standard params passed via extra body
  image_size: "2K",
  aspect_ratio: "16:9",
});
 
const content = response.choices[0].message.content;
// content is a string (may contain markdown-formatted inline images)
// To programmatically extract images, use response.choices[0].message.images

Image Parameter Reference

image_size — Resolution

Controls the output image resolution. The K must be uppercase — lowercase will be rejected.

Gemini 3 Pro Image difference: gemini-3-pro-image-preview-2k and -4k are standalone model names with preset resolutions — no image_size parameter needed. gemini-3.1-flash-image-preview uses the image_size parameter to switch resolutions dynamically.

aspect_ratio — Aspect Ratio

Controls the output image aspect ratio. When omitted, the model defaults to 1:1.

Supported values:

1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1

General Request Parameters

Reference Image Input

To include a reference image, use the OpenAI-style multimodal messages.content format:

{
  "model": "gemini-3.1-flash-image-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Using this image as a composition reference, draw a cat sitting by a window"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAA..."
          }
        }
      ]
    }
  ],
  "max_tokens": 4096,
  "image_size": "2K"
}

Notes:

• Both data: URI (base64) and https:// public URLs are supported
• Public URLs are automatically downloaded by the gateway and converted to Gemini native image input (30-second timeout)
• Base64 format is recommended: Some CDNs (e.g., Alibaba Cloud) may have anti-hotlinking or format conversion issues — base64 is the most reliable method

Response Format

Image model responses include two fields: content (string) and images (array).

Text-only Response

If the model returns only text (no image generated), the response is the same as a standard text model:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Here is the model's text response"
    }
  }]
}

Response with Images

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "gemini-3.1-flash-image-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here is the generated image:\n\n![image](data:image/jpeg;base64,/9j/4AAQ...)",
        "images": [
          {
            "type": "image_url",
            "index": 0,
            "image_url": {
              "url": "data:image/jpeg;base64,/9j/4AAQ...",
              "detail": "auto"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  }
}

The two fields serve different purposes:

• content is always a string, suitable for direct display to users
• To programmatically process images (save, forward, etc.), use the images field
• Image format is typically JPEG (data:image/jpeg;base64,...). The actual format depends on the MIME type returned by the model
• The usage field is still returned, allowing you to cross-reference consumption in both the response and the console

Limitations & Notes

1. Only /v1/chat/completions is supported: Gemini image models do not support /v1/messages (Anthropic format)
2. Streaming is pseudo-streaming: stream: true is supported, but the image is returned as a single SSE event after generation completes (not token-by-token). A keepalive heartbeat is sent every 10 seconds while waiting
3. Images are returned via the images field: content is always a string. To programmatically process images, use the message.images field — do not parse the markdown in content
4. Model permissions: Ensure your API Key is authorized to access the image model
5. Timeout & keepalive: 4K image generation can take 2-3 minutes. We strongly recommend using "stream": true for 4K requests — the gateway sends a keepalive heartbeat every 10 seconds, preventing intermediate network devices (NAT/firewalls/proxies) from dropping idle TCP connections. Also set your client HTTP timeout to ≥ 600 seconds
6. image_size capitalization: Must use uppercase K ("2K", "4K"); lowercase "2k" will be rejected. 512 does not have a K suffix
7. Resolution selection difference:
   • gemini-3.1-flash-image-preview: Use image_size parameter ("512" / "1K" / "2K" / "4K")
   • gemini-3-pro-image-preview: Use model name suffix (-2k / -4k), or use the base model name for default 1K