Gemini Image

Gemini Image is available through the OpenAI-compatible Chat Completions API. Client applications only need to call Cubicspaces /v1/chat/completions and set model to a Gemini image model.

Public integration uses one OpenAI-compatible format:

• 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:

{
  "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 Cubicspaces' OpenAI Chat Completions format, follow this document only. You do not need to 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.