Image generation

A certified image model, such as bfl/flux-3-image, recraft/recraft-v4.1, openai/gpt-image-2 or spacexai/grok-imagine-image. GET /v1/models lists the ones your key may use with type: "image". A team alias that names an image model works too. Chat and embedding models are refused with 400 invalid_request.

What to draw, up to 32,000 characters.

How many images, 1 to 4. Defaults to 1. Each image is billed.

WIDTHxHEIGHT, such as 1024x1024. Providers treat it as a target and may return a nearby size of the same shape. Without it the provider's default size is used. Token-priced models take only the sizes listed for them in GET /v1/pricing (image_output_tokens), such as 1024x1024, 1024x1536 and 1536x1024; others are refused with 400 invalid_request.

Images are always returned as base64 in data[].b64_json. url is refused: images are not stored, so there is no URL to give.

Options for the model's provider, passed through as given: aspect ratio, style, quality, seed and output format are set here, for example { "recraft": { "style": "vector_illustration" } } or { "blackForestLabs": { "outputFormat": "jpeg" } }. For OpenAI's gpt-image, set the quality with { "openai": { "quality": "low" } }: it decides how many tokens the image takes. See each provider's options in the AI SDK provider docs. Routing options (gateway) are ignored.

Your end user, recorded for attribution and per-end-user Directives, and not forwarded.

tags (up to ten) and session, as on chat completions. Not forwarded.

Bearer ib_live_…, or the key in x-api-key. See Authentication.

Your own correlation id, recorded on the receipt.

Groups the request with others in Logs.

Your end user, up to 256 characters; wins over the body's. See End users and tags.

Comma-separated tags for cost breakdowns, at most ten with ib.tags. Never sent upstream.

Before the call, your balance holds n images at the highest price the request can reach: the listed price for the size you ask for (or the next larger listed size), and the most expensive size, quality or style when you pass providerOptions. For a token-priced model it holds the most output tokens one image took when we measured that size and quality, with 20% headroom, at the listed output price: every quality when you don't name one, and every size when you don't name one or when the model's tokens didn't grow with size as measured. The request settles at what the provider billed. GET /v1/pricing lists each model's per_image price and its per_image_tiers, or its token prices and image_output_tokens. Look up the receipt with GET /v1/requests/:id using the X-Request-ID response header.

Models priced per image, and token-priced ones whose output tokens we measured for every size and quality they take, because their cost is known before the call. Models the gateway lists without a price (FLUX.2, Prodia, Topaz) aren't offered.

If a provider fails before answering, the request is tried once on another certified provider of the same model, never on a different model.

Model and provider allowlists, budgets, rate limits, maxRequestChargeUsd, requireZdr and requireNoTraining apply. Few image providers offer zero data retention, so a team that requires it can use only those that do. The estimated prompt counts against tokensPerMinute.

When your team keeps request content, the stored response shows each image's size, not the image.

A call has 3 minutes. Responses are not streamed, and Idempotency-Key is not supported here. To change an existing image, use image edits.