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 two that matter for images are responseModalities and responseFormat.image.

›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. The native endpoint forwards the body as-is — an out-of-range value is the upstream's to judge and usually comes back as a 400. Called through /v1/images/* or /v1/tasks, an out-of-range value is dropped by Amux and noted in amux.notes.

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

The native endpoint forwards the body as-is — a value outside those sets is the upstream's to judge, and usually comes back as a 400. Amux does not drop it for you: a native call means what you send is what goes out.

Called through the OpenAI-compatible image endpoint or Amux Tasks, the body is rendered by us, and on those two paths an out-of-range value is dropped and noted in amux.notes, after which the upstream falls back to its own default.

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

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#

Output is billed by token, and 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.

Billing is per search query, and one call may issue several. The actual list is in candidates[].groundingMetadata.webSearchQueries.

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
      }
    ]
  }
}