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 $AUDACITY_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)
`gpt-image-1`	Token-based ( $5.00 / 1M text input,$ 40.00 / 1M image output tokens)

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.

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

Using the SDKs

​Request parameters

​Response

​Models & pricing

​Using the SDKs

Request parameters

Response

Models & pricing

Using the SDKs