Images

Three endpoints, one price per image. The model is always <provider>/<model>, for example openai/gpt-image-1-mini or openrouter/google/gemini-3.1-flash-image-preview.

Cloudflare Workers AI models (cloudflare-ai/@cf/black-forest-labs/flux-1-schnell and five more) generate only: n: 1, 1024x1024, no streaming. cloudflare-ai/@cf/black-forest-labs/flux-2-dev needs an API key.

Gemini models (gemini/gemini-3.1-flash-image, gemini/gemini-3.1-flash-lite-image, gemini/gemini-3-pro-image, gemini/gemini-nano-banana-2.1) are the same: n: 1, 1024x1024, no streaming. gemini/gemini-3-pro-image and gemini/gemini-nano-banana-2.1 need an API key.

OpenRouter's aspect_ratio, resolution and seed reach openrouter/* models on all three endpoints (on a multipart edit, seed as a number). On any other provider they are a 400 before anything is held, never silently dropped.

1curl https://api.aile.sh/v1/images/generations \
2-H "Authorization: Bearer $AILE_KEY" \
3-H "Content-Type: application/json" \
4-d '{ "model": "openai/gpt-image-1-mini", "prompt": "a lighthouse at dusk" }'

Billing

• One unit per image returned. An edit bills at the same per-image price as a generation of that model. On openai/gpt-image-*, each source image and the mask also add an input price to every image returned (pricing.max_usd_per_input_image on /v1/models). That price is a fixed worst-case figure charged in full, not reduced to the provider's reported usage; on gpt-image-2 it is several times the measured cost. openai/gpt-image-1-mini refuses input_fidelity other than low. On openrouter/bytedance-seed/seedream-5-0-pro, each source image adds $0.003 at list to an edit.
• A response with no image is a 502 and is not charged.
• A provider refusal you can fix (400, 404, 413, 422 …) passes through. One about the sharer's account is a 502 saying you were not charged.
• A 502 or 504 arrives as 503 with the real code in x-aile-status.
• Input images go to the provider as sent. file_id references are refused.
• OpenRouter's sharer-cost fields (usage.cost, cost_details, is_byok) are removed from buffered answers.
• A key's pins and the routing headers choose the sharer here too. x-aile-provider must match the model's prefix, and x-aile-max-price does not apply to a per-image price.
• Where the deployment enables keyless x402, it covers all three endpoints: up to 4 images per request (more is a 400, and fewer arriving than paid for is not charged), base64 only, no streaming.

Slow requests

A keyed request with no answer after 25 seconds is committed to 200 and sent a space every 15 seconds (SSE keepalives when it streams) until the image arrives, up to 120 seconds. It carries x-aile-edge-hold, x-aile-capacity: nodeless and x-aile-blind: false in place of the other x-aile-* headers (the stake-funded discount's are kept, even on a failure, which is not charged), and a failure after that is a 200 carrying the error body (an SSE error frame when streaming). A keyless request is never held: with no image 30 seconds after its payment is verified (the default), it is voided with a 504 and not charged.

Resolution tiers

Some models are priced per resolution tier: FLUX.3 Image, Seedream 4.5, Seedream 5.0 Flash, Lite and Pro, Hy Image 3.5 Preview and Nano Banana 2.1 on OpenRouter (send resolution, e.g. "2K"), and FLUX.3 Image and Seedream 5.0 Flash and Pro on NanoGPT and Seedream 4.5, 5.0 Lite and 5.0 Pro on BytePlus (send the tier as size, e.g. "2k"). You pay that tier's price; with no tier you get, and pay for, the model's default (1K; 2K on Seedream 4.5 and 5.0 Lite). A pixel size, or a tier the model does not list (Hy Image 3.5 Preview and Nano Banana 2.1 have no 1.5K, Nano Banana 2.1 no 512, Seedream 4.5 and 5.0 Lite no 1K and Seedream 5.0 Pro no 4K), is a 400. Listings show the dearest tier. Seedream 4.5, 5.0 Flash and 5.0 Lite cost the same at every tier; Seedream 5.0 Pro is $0.045 at 1K (and at BytePlus's 1.5K) and $0.09 at 2K at list. nanogpt/seedream-v4.5 and nanogpt/seedream-v5.0-lite take one of five pixel sizes as size instead (2048x2048 by default; the 400 names them).

Watermark

ByteDance Ark (byteplus, volcengine, doubao) images come without Ark's visible "AI generated" mark. Send x-aile-image-watermark: on to keep it.

Hosted URLs

Images come back as base64 by default. Where the deployment enables hosted images, send response_format: "url" or the header x-aile-image-store: url on /v1/images/generations for a hosted URL (x-aile-image-store: none always wins); otherwise the answer stays base64. Hosted images expire. /v1/images and /v1/images/edits always answer base64.

Streaming

stream: true streams GPT image models (openai/gpt-image-*, openrouter/openai/*) as server-sent events, on all three endpoints (an edit's multipart stream=true too). You pay for each finished image delivered, and a stream that delivers none is a 200 that bills nothing. partial_images is not supported, and a streamed image is always base64. Streaming needs an API key.