Gemini Image

Gemini image models support two integration formats: OpenAI-compatible Chat Completions and Gemini-native generateContent. Their request fields and image response locations differ; do not mix the two formats.

OpenAI-Compatible Integration

When calling /v1/chat/completions:

• Put image size and aspect ratio options in the top-level image_config request field.
• Use snake_case fields inside image_config: aspect_ratio and image_size.
• Do not send Gemini-native generationConfig.imageConfig.
• Do not put extra_body.google.image_config in the request JSON; that is not the recommended public request format.

Endpoint

POST /v1/chat/completions

Supported Models

Model	Notes
gemini-3-pro-image-preview	Gemini 3 Pro image preview model
gemini-3.1-flash-image-preview	Gemini 3.1 Flash image preview model

Actual model availability depends on account permissions and platform configuration.

Request Example

curl https://cubicspaces.cloud/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [
      {
        "role": "user",
        "content": "Generate a realistic warm-toned photo of a cat in a cafe"
      }
    ],
    "image_config": {
      "aspect_ratio": "1:1",
      "image_size": "2K"
    },
    "stream": false
  }'

Request Parameters

Parameter	Type	Required	Notes
model	string	Yes	Gemini image model name, for example gemini-3.1-flash-image-preview
messages	array	Yes	OpenAI Chat Completions message array
stream	boolean	No	false or omitted is recommended for image generation
image_config	object	No	Top-level image options for aspect ratio and size

Response Format

Images are returned in choices[0].message.images of the OpenAI Chat Completions response:

{
  "id": "chatcmpl_123",
  "object": "chat.completion",
  "model": "gemini-3.1-flash-image-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "images": [
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,BASE64_IMAGE_DATA"
            },
            "index": 0
          }
        ]
      },
      "finish_reason": "stop"
    }
  ]
}

If the model returns both text and images, content contains the text part and images contains the generated image data. Clients should read image data from choices[].message.images[].image_url.url.

Do not parse Markdown image links from content. Cubicspaces normalizes image data that may be returned by upstream providers into message.images, while content is kept for text only.

Image Config

image_config is optional and must be placed at the top level of the request body. Do not place it inside messages, a request JSON field named extra_body, or Gemini-native request fields. Supported fields:

Field	Type	Notes
aspect_ratio	string	Image aspect ratio, for example 1:1, 16:9, 9:16
image_size	string	Image size, for example 1K, 2K, 4K

Correct format:

{
  "model": "gemini-3.1-flash-image-preview",
  "messages": [
    {
      "role": "user",
      "content": "Generate an image of a cat in a cafe"
    }
  ],
  "image_config": {
    "aspect_ratio": "16:9",
    "image_size": "4K"
  },
  "stream": false
}

Do not use this format with the OpenAI-compatible endpoint:

{
  "generationConfig": {
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "4K"
    }
  }
}

The example above is Gemini-native request syntax and does not apply to Cubicspaces' OpenAI-compatible /v1/chat/completions endpoint.

SDK Examples

Some OpenAI SDKs restrict custom top-level parameters. If that happens, use the SDK's extra_body / raw body option to merge image_config into the final top-level request body. In this section, extra_body is an SDK option, not a JSON field sent to the API.

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://cubicspaces.cloud/v1"
)

response = client.chat.completions.create(
    model="gemini-3.1-flash-image-preview",
    messages=[
        {"role": "user", "content": "Generate an image of a cat in a cafe"}
    ],
    extra_body={
        "image_config": {
            "aspect_ratio": "1:1",
            "image_size": "2K",
        }
    },
    stream=False
)

print(response.choices[0].message.images[0].image_url.url)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://cubicspaces.cloud/v1"
});

const response = await client.chat.completions.create({
  model: "gemini-3.1-flash-image-preview",
  messages: [
    { role: "user", content: "Generate an image of a cat in a cafe" }
  ],
  image_config: {
    aspect_ratio: "1:1",
    image_size: "2K"
  },
  stream: false
});

console.log(response.choices[0].message.images[0].image_url.url);

Notes

• When using OpenAI Chat Completions, do not send Gemini-native fields in the request body.
• image_config is a top-level field and uses aspect_ratio and image_size, not aspectRatio and imageSize.
• Image results are returned in message.images as data:image/...;base64,... URLs.
• Treat content as text only, not as the image output location.
• Non-streaming requests are recommended for image generation so clients can read the complete image content at once.

Gemini-Native Integration

Call Cubicspaces' Gemini-native endpoint with the model name in the URL. Use contents and generationConfig in the request body; the response retains Gemini's native structure. Authenticate with your Cubicspaces API Key in the x-goog-api-key header.

POST /v1beta/models/{model}:generateContent

Text to Image

curl "https://cubicspaces.cloud/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Generate an image of a cat in a cafe, warm colors, realistic photography"}]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'

Image to Image

Place the prompt and reference image in the same contents[].parts array. Replace BASE64_INPUT_IMAGE with the raw Base64-encoded image bytes (without a data:image/...;base64, prefix), and set mimeType to match the file. Add more inlineData parts for multiple reference images; supported counts and sizes depend on the available model.

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Keep the subject of the reference image, but use soft morning light"},
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "BASE64_INPUT_IMAGE"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
  }
}

Reading the Image

Native text and image output are both in candidates[].content.parts[]. An image part contains raw Base64 in inlineData.data and its file type in inlineData.mimeType. Do not look for OpenAI-compatible choices[].message.images in this response.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "Here is the image."},
          {"inlineData": {"mimeType": "image/png", "data": "BASE64_OUTPUT_IMAGE"}}
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

Native imageConfig uses aspectRatio and imageSize. Do not send the OpenAI-compatible top-level image_config to this endpoint. See Gemini Native API for other native fields.