Image generation

Gateway generates images two ways, depending on the model:

• Dedicated image models (e.g. openai/gpt-image-2, xai/grok-imagine-image) use POST /v1/images/generations.
• Hybrid chat+image models (Google’s Nano Banana family: google/gemini-2.5-flash-image, google/gemini-3.1-flash-image, google/gemini-3-pro-image) generate images inline in a normal /v1/responses conversation.

Model availability and pricing come from GET /v1/models: image-capable models list image in their output modalities.

Dedicated endpoint

$
curl -X POST https://api-gateway.merge.dev/v1/images/generations \
>
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "model": "openai/gpt-image-2",
>
    "prompt": "a lighthouse at dawn, watercolor",
>
    "size": "1024x1024"
>
  }'

The image arrives as base64 in the JSON response (data[0].b64_json), not raw bytes. Some vendors also support response_format: "url"; xAI models always return base64 through Gateway.

Inline images in chat (hybrid models)

Hybrid models generate images as content blocks in a chat response. Pass modalities: ["text", "image"] and use the typed input form:

$
curl -X POST https://api-gateway.merge.dev/v1/responses \
>
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "model": "google/gemini-3.1-flash-image",
>
    "input": [{
>
      "type": "message",
>
      "role": "user",
>
      "content": [{"type": "input_text", "text": "draw a small blue star"}]
>
    }],
>
    "modalities": ["text", "image"]
>
  }'

Image blocks appear alongside text blocks in output[].content[] with base64 data.

Pricing

Image models bill one of two ways. The pricing block on GET /v1/models tells you which:

• Per token (unit: per_token): image output is metered in image-output tokens (reported as usage.image_output_tokens), so cost scales with resolution automatically
• Per image (unit: per_image): a flat rate per generated image, with optional resolution tiers under output_per_image_by_resolution

Next steps