Image generation

The gateway also generates images: an OpenAI-compatible endpoint sits alongside chat completions, authenticated with the same API key (as Authorization: Bearer or x-api-key) and governed by the same per-client rate limits as every other /v1 route. Requests are synchronous — multi-image or high-quality generations can take tens of seconds, so set client timeouts accordingly.

curl https://api.aireserve.com/v1/images/generations \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image",
    "prompt": "A watercolor painting of a fox in a snowy forest",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

Request parameters

Field	Required	Description
`model`	yes	Image model ID — see the table below
`prompt`	yes	Text description of the desired image(s); 1–32,000 characters
`n`	no	Number of images to generate — integer 1–10 (model-dependent)
`size`	no	Dimensions as a `"WxH"` string (e.g. `1024x1024`); supported values differ per model
`quality`	no	Provider-specific quality tier (e.g. `standard`, `hd`, `low`, `high`)
`response_format`	no	`url` (default) — a signed download link — or `b64_json` — inline base64 bytes
`user`	no	End-user identifier forwarded to the provider for abuse attribution

Response

The response follows the OpenAI images shape — created (unix seconds), a data array with one entry per generated image, and an optional usage object on token-priced models:

{
  "created": 1752000000,
  "data": [
    {
      "url": "https://storage.googleapis.com/…?X-Goog-Signature=…",
      "revised_prompt": "A watercolor painting of a fox…"
    }
  ],
  "usage": { "input_tokens": 12, "output_tokens": 1024, "total_tokens": 1036 }
}

With response_format: "url" (the default), each image is stored by the gateway and returned as a signed download URL valid for ~24 hours — download promptly and persist on your side.
With response_format: "b64_json", each entry carries the base64-encoded PNG bytes inline instead.
revised_prompt appears when the provider rewrites your prompt before generating.

Models & pricing

Model	Pricing
`gemini-2.5-flash-image`	Token-based (≈ $0.039 / image)
`gemini-3.1-flash-image`	$0.50 / 1M input tokens,$ 3.00 / 1M output tokens, plus up to $0.151 / image at 4K resolution
`gpt-image-1`	Token-based ( $5.00 / 1M text input,$ 40.00 / 1M image output tokens)
`qwen-image-3.0`	Per-image ($0.03 / image, 1K and 2K)
`qwen-image-3.0-pro`	Per-image ($0.075 / image)
`nano-banana-2`	Per-image ($0.08 / image at 1K; served by fal)
`flux-2-flex`	Per-megapixel ( $0.05 / MP of the requested `size`, rounded up to whole megapixels — 1024x1024 is$ 0.05, 2048x2048 is $0.20; served by fal)
`grok-imagine-image`	Per-image ($0.02 / image; served by fal)

Token-based models report token counts in the response usage object. Every request’s cost is metered against your key exactly like chat traffic and counts toward the same spend caps. The fal-served models accept n (1–4 for nano-banana-2) and size as "WxH" (256–4096 per side, at most 2048x2048 pixels).

Image editing

POST /v1/images/edits edits existing images: send model, a prompt describing the change, and images — one to nine public HTTPS URLs. The response is a job (202, { id, status }); poll GET /v1/images/edits/{id} until status is succeeded and read the output URL from result. Editing is billed per output image at the provider’s list price (plus a per-input fee where the provider charges one).

Model	Inputs	Approximate pricing
`nano-banana-2-edit`	up to 8 images	$0.08 / image
`flux-2-flex-edit`	up to 4 images	$0.05 / MP on output and input (billed as$ 0.20 + $0.10 per input)
`qwen-image-2-pro-edit`	1–3 images	$0.075 / image
`grok-imagine-image-edit`	up to 4 images	$0.02 / image +$ 0.002 per input
`bria-background-remove`	1 image, no prompt	$0.018 / image
`topaz-image-upscale`	1 image, no prompt (2× upscale)	$0.32 / image (fal tiers by output megapixels)

All image-editing models are served by fal in the United States.

Qwen Image 3. The qwen-image-3.0 family is served by Alibaba Cloud Model Studio and is China-hosted under the gateway’s provider-jurisdiction labeling — organizations must have the China-hosted model opt-in enabled to use it, same as the Qwen chat models. These models accept only n and size of the optional parameters (quality, style, and other provider-specific fields are ignored), and qwen-image-3.0-pro carries a low upstream rate limit (5 requests / minute) — expect 429s under parallel load and retry with backoff.

Imagen retirement. Google is shutting down the entire Imagen family on August 17, 2026, and the whole line is now delisted from the gateway: imagen-4, imagen-4-fast, and imagen-4-ultra IDs all return errors. The migration target is gemini-2.5-flash-image (GA, token-based, ≈ $0.039 / image); gpt-image-1 also remains available.

Reliability. Upstream image backends occasionally stall with a 503 for a few minutes. There is deliberately no automatic fallback to a different image model — silently swapping models would change output style and quality — so callers should retry instead. The SDKs already retry 503s with jittered backoff up to their configured retry budget.

Using the SDKs

All five SDKs ship an image-generation helper as of SDK v0.4.0, with the same auth, error mapping (401 → AccessDeniedException, 402 → ServiceQuotaExceededException, 429 → ThrottlingException), and retry policy as Converse:

result = client.images.generate(
    model="gemini-2.5-flash-image",
    prompt="A watercolor painting of a fox in a snowy forest",
)
print(result["data"][0]["url"])   # signed download URL, valid ~24 h

# Inline bytes instead: response_format="b64_json" → result["data"][0]["b64_json"]

const result = await client.images.generate({
  model: "gemini-2.5-flash-image",
  prompt: "A watercolor painting of a fox in a snowy forest",
});
console.log(result.data[0].url); // signed download URL, valid ~24 h

// Inline bytes instead: responseFormat: "b64_json" → result.data[0].b64Json

out, err := client.GenerateImage(ctx, &audacityruntime.GenerateImageInput{
    Model:  audacity.String("gemini-2.5-flash-image"),
    Prompt: audacity.String("A watercolor painting of a fox in a snowy forest"),
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(out.Data[0].Url) // signed download URL, valid ~24 h

// Inline bytes instead: ResponseFormat: audacity.String("b64_json") → out.Data[0].B64Json

GenerateImageResponse result = client.generateImage(b -> b
    .model("gemini-2.5-flash-image")
    .prompt("A watercolor painting of a fox in a snowy forest"));

System.out.println(result.data().get(0).url()); // signed download URL, valid ~24 h

// Inline bytes instead: .responseFormat("b64_json") → result.data().get(0).b64Json()

let result = client.generate_image()
    .model("gemini-2.5-flash-image")
    .prompt("A watercolor painting of a fox in a snowy forest")
    .send()
    .await?;

println!("{}", result.data[0].url.as_deref().unwrap()); // signed URL, valid ~24 h

// Inline bytes instead: .response_format("b64_json") → result.data[0].b64_json

Errors reuse the chat-completions codes: 400 invalid_request_error for a malformed body, 401 invalid_api_key, 402 usage_cap_exceeded when a spend cap is reached (never retried), and 429 rate_limit_exceeded with a Retry-After header. See Errors & retries for the full exception mapping in each SDK.

Getting started

Connect your tool

Models

Capabilities

Migrate

Data & privacy

Request parameters

Response

Models & pricing

Image editing

Using the SDKs

​Request parameters

​Response

​Models & pricing

​Image editing

​Using the SDKs

Request parameters

Response

Models & pricing

Image editing

Using the SDKs