Amux AI

Generate Content (image)

Last updated September 2, 2026

Generate images over the Gemini generateContent protocol — same address as a chat call, usable with the official SDKs.

Image models use exactly the same address as a chat call: POST /v1beta/models/{model}:generateContent. Whether an image comes back is decided by generationConfig.responseModalities in the request body. There is no separate image endpoint.

Authentication and path rules follow the chat endpoint: x-goog-api-key: <your Amux key> or ?key= on the URL, and the slash in the model name is not escaped.

POSThttps://gateway.amux.ai/v1beta/models/{model}:generateContent

Authorization

header
AuthorizationstringRequired

An Amux key created in the console. This is the header the Gemini SDKs send natively.

Content-TypestringRequiredDefault "application/json"

Always application/json.

Request

application/json
modelstringRequired

Canonical ID, written into the path. Do not escape the slash in vendor/model.

contentsarray<object>Required

Prompt and reference images. Text goes in parts[].text, reference images in parts[].inline_data (raw base64, no data: prefix). Text-to-image and image-to-image share one endpoint; the only difference is whether reference images are present.

›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.

›inline_dataobject
mime_typestring

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

datastring

Raw base64 bytes, without the data: prefix.

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 the same endpoint returns text only.

imageConfigobject

Size controls for the image; this form is recommended. Both fields may be omitted, in which case the model uses its own default.

›imageConfigobject
aspectRatiostring

Aspect ratio. The accepted set differs per model — see the model pages. An out-of-range value is dropped and noted in amux.notes, and the model falls back to its default. All three paths behave the same — this endpoint, /v1/images/* and /v1/tasks.

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

Resolution tier. The accepted set differs per model — see the model pages.

responseFormatobject

A form equivalent to imageConfig, also accepted by Amux. When both are supplied, imageConfig takes precedence.

›responseFormatobject
imageobject

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

›imageobject
aspectRatiostring

Aspect ratio. The accepted set differs per model — see the model pages. An out-of-range value is dropped and noted in amux.notes, and the model falls back to its default. All three paths behave the same.

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

Resolution tier. The accepted set differs per model — see the model pages.

toolsarray<object>

Grounding with Google Search: [{ "google_search": {} }]; the camelCase googleSearch that the SDKs emit is accepted too. Not every image model supports it — on those that do not, the parameter is dropped and explained in amux.notes. Billed per search query, counted as the de-duplicated groundingMetadata.webSearchQueries (empty queries are not charged). Through /v1/images/* or /v1/tasks the equivalent is web_search: true.

Response

200response

The generated result.

Turning image output on

responseModalities must be ["TEXT", "IMAGE"]. Without it the same endpoint returns text only — the most common form of "the call worked but there is no image".

Output dimensions are controlled by generationConfig.responseFormat.image, which has two fields:

  • aspectRatio — the picture's aspect ratio
  • imageSize — the resolution tier: 512 / 1K / 2K / 4K (the smallest carries no px — the official wording is that the K must be uppercase, and this tier has no K suffix)

The accepted set for both differs per model. See the model pages under Images for what each one takes — for example gemini-3-pro-image. This endpoint forwards the body as-is — a value a given model does not accept is the upstream's to judge, and usually comes back as a 400. 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.

Reference images

Image-to-image and text-to-image share this one endpoint. The only difference is whether contents[].parts carries an inline_data block:

{
  "parts": [
    { "text": "Recolour this cat to orange" },
    { "inline_data": { "mime_type": "image/jpeg", "data": "<base64>" } }
  ]
}

data is raw base64 without the data: prefix. The maximum number of reference images differs per model.

Supplying a reference image by URL is not supported: the upstream accepts inline bytes and the Files API only, so a URL is dropped and noted in amux.notes.

Response shape

Images and text are interleaved in candidates[].content.parts — images in inlineData, the model's commentary in text. Collecting every artifact means walking the whole parts array; reading only the first entry will miss some.

In usageMetadata, image and text tokens are split by modality in candidatesTokensDetails. The two are priced up to an order of magnitude apart, and Amux bills them as separate line items rather than charging image tokens at the text rate.

Unsupported capabilities

  • Streaming. Gemini streams by switching the action (:streamGenerateContent), and the official documentation gives no syntax for streaming images. Streaming requests to image models are therefore rejected — retry without streaming.
  • Multiple images per call. The request body has no batch field; one call returns one image.

Grounding with Google Search

tools: [{ "google_search": {} }] lets the model search before generating. Not every image model supports it — those that do not are rejected upstream.

Billing is per search query: a single call may issue several, and the actual list is in candidates[].groundingMetadata.webSearchQueries.

Other ways to call these models

The same models are reachable through the OpenAI-compatible image endpoint and Amux Tasks. Those paths go through protocol conversion, so parameters unique to this protocol are intersected per the parameter support matrix; anything dropped is likewise recorded in amux.notes.

Errors

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

cURL
curl https://gateway.amux.ai/v1beta/models/google/gemini-3-pro-image:generateContent \
  -H "x-goog-api-key: $AMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "<string>",
            "inline_data": {
              "mime_type": "image/png",
              "data": "<string>"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": [
        "TEXT",
        "IMAGE"
      ],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      },
      "responseFormat": {
        "image": {
          "aspectRatio": "16:9",
          "imageSize": "2K"
        }
      }
    },
    "tools": [
      {}
    ]
  }'
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "<string>",
            "inlineData": {
              "mimeType": "image/png",
              "data": "<string>"
            }
          }
        ]
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "<string>"
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 0
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "IMAGE",
        "tokenCount": 0
      }
    ]
  }
}