Generate image

Image generation with google/gemini-3-pro-image. It uses Gemini's native generateContent at the same address as a chat call, so the official SDKs work once their base URL points here.

It supports interleaved text and image output: one call can return both a picture and prose, ordered in parts as the model sees fit.

Authorization

header

AuthorizationstringRequired

Request

application/json

contentsarray<object>Required

Prompt and reference images. Text in parts[].text, reference images in parts[].inline_data (raw base64, no data: prefix). Reference images make it image-to-image; the endpoint does not change.

›contentsarray<object>

role"user" | "model"

Who is speaking. user is you, model is the model's own earlier reply. Optional for a single-turn request.

partsarray<object>

The pieces of this turn, in the order given. Text and reference images may be mixed in one turn.

›partsarray<object>

textstring

A text piece. Several text pieces in one turn are concatenated in order.

inline_dataobject

An inline reference image. Only inline bytes and the Files API are accepted, not URLs — a URL is dropped and noted in amux.notes.

›inline_dataobject

mime_typestring

Media type of the image, e.g. image/png, image/jpeg, image/webp.

datastring

The image bytes as base64, without the data:image/png;base64, prefix. With the prefix the upstream reads it as an invalid image.

generationConfigobjectRequired

Generation settings. The fields relevant to image output are responseModalities and the size controls. The size controls accept two equivalent forms, imageConfig and responseFormat.image. Google's documentation has used each of them in different versions; Amux supports both. When both are supplied, imageConfig takes precedence, field by field.

›generationConfigobject

responseModalitiesarray<"TEXT" | "IMAGE">Required

Required: ["TEXT", "IMAGE"]. Without it this endpoint returns text only.

responseFormatobject

Output format. Image settings live under image.

›responseFormatobject

imageobject

Size controls for the image. Both may be omitted, in which case the upstream picks its default.

›imageobject

aspectRatio"1:1" | "1:4" | "1:8" | "2:3" | "3:2" | "3:4" | "4:1" | "4:3" | "4:5" | "5:4" | "8:1" | "9:16" | "16:9" | "21:9"

Aspect ratio. This model accepts the 14 values below. An out-of-range value is dropped and noted in amux.notes, and the model falls back to its default; this endpoint, /v1/images/* and /v1/tasks all behave the same.

imageSize"1K" | "2K" | "4K"

Resolution tier. Out-of-range values are handled the same way as aspectRatio.

toolsarray<object>

Grounding with Google Search: [{ "google_search": {} }]. Billed per search query; the actual list is in groundingMetadata.webSearchQueries.

Response

200response

The result. Images and text are interleaved in parts.

Turning image output on#

generationConfig.responseModalities must be ["TEXT", "IMAGE"]. Without it the same endpoint returns text only.

What this model accepts#

Aspect ratios (14):

1:1 · 2:3 / 3:2 · 3:4 / 4:3 · 4:5 / 5:4 · 9:16 / 16:9 · 21:9 · 1:4 / 4:1 · 1:8 / 8:1

Resolutions: 1K · 2K · 4K

A value outside those sets is dropped and noted in amux.notes, after which the model falls back to its own default. This native endpoint shares one image pipeline with the OpenAI-compatible image endpoint and Amux Tasks, so all three behave the same.

An OpenAI-style pixel string in size (for example 1024x1024) is folded into an aspect ratio and a tier, constrained to the sets above, and a lossy fold is noted in amux.notes. Gemini's native body has no such field — on a native call, write the aspect ratio and the tier directly.

Reference images#

Image-to-image and text-to-image share this endpoint: put the reference into contents[].parts as an inline_data block. data is raw base64 without the data: prefix.

This model takes up to 14, of which at most 6 may be object references and 5 character references; style references are not supported.

Supplying a reference by URL is not supported — the upstream accepts inline bytes and the Files API only.

What drives the cost#

How output is billed depends on the provider: for the same model, some providers charge per token and others per image. The provider's price list on the model page is authoritative. All three call paths — this endpoint, /v1/images/* and /v1/tasks — share one image pipeline, so a given provider bills the same on all of them.

When billing is per token, image tokens and text tokens are priced differently. The two are reported separately in usageMetadata.candidatesTokensDetails, and Amux bills them as separate line items rather than charging image tokens at the text rate.

How many tokens one image costs depends on the resolution: 1120 tokens at 1K and 2K, 2000 at 4K.

For the rates themselves see the model page and pay-as-you-go pricing. They are deliberately not repeated here — providers and discounts change, and a copy in the docs would drift away from the invoice.

Grounding with Google Search#

tools: [{ "google_search": {} }] lets the model search before generating — useful when the picture has to reflect current facts.

The camelCase googleSearch that the SDKs emit is accepted too. Through the OpenAI-compatible image endpoint or Amux Tasks, the equivalent is web_search: true.

Billing is per search query, and one call may issue several. The count is the de-duplicated candidates[].groundingMetadata.webSearchQueries; empty queries are not charged.

Streaming is not supported#

Gemini streams by switching the action (:streamGenerateContent), and the official documentation gives no syntax for streaming images, so streaming requests to this model are rejected. Retry without streaming.

One call returns one image; the request body has no batch field.

Other ways to call this model#

The model is also reachable through the OpenAI-compatible image endpoint and Amux Tasks. The ranges listed on this page apply on those converted paths too.

Errors#

Errors use Gemini's error body. See Errors and retries for status values and retry semantics.

curl https://gateway.amux.ai/v1beta/models/google/gemini-3-pro-image:generateContent \
  -H "x-goog-api-key: $AMUX_API_KEY" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "<string>",
            "inline_data": {
              "mime_type": "image/png",
              "data": "<string>"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": [
        "TEXT",
        "IMAGE"
      ],
      "responseFormat": {
        "image": {
          "aspectRatio": "1:1",
          "imageSize": "1K"
        }
      }
    },
    "tools": [
      {}
    ]
  }'

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "<string>",
            "inlineData": {
              "mimeType": "image/png",
              "data": "<string>"
            }
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 0
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "IMAGE",
        "tokenCount": 0
      }
    ]
  }
}