Image generation

Needs a key in Authorization: Bearer or x-api-key.

The gateway creates a job, reserves the money for it (under a per-user lock, so two concurrent requests cannot both pass on the same balance), submits it to the provider and polls for up to 150s. If that is enough you get 200 with the images in b64_json; if not, 202 with { id, status, estimated_cost_usd }, and the result is fetched from GET /v1/images/jobs/{job_id}. The reserve stays in place, so the money is not released while the generation runs.

The reply never contains a provider CDN link: when the provider answers with a URL, the gateway downloads the image itself and returns base64. That is why response_format is accepted and ignored — the result is always b64_json. Unknown body fields are dropped silently too: only what the model's allowlist knows is forwarded.

About the fields. An unknown or admin-disabled model, a missing prompt, an n that is not an integer or falls outside 1–10, and a parameter value outside its own model's set are all a 400 on our side, before the provider. The aspect_ratio set depends on the model: some take more (plus 3:2, 2:3, 21:9), and some take orientation instead; a field the model does not have is dropped silently. Neither resolution nor the framing affects the price: the tariff is per image. n is not forwarded to the provider at all — it sizes the reserve, while the charge follows the number of images that came back (none came back — then n). A provider submit failure on a 5xx or the network leaves the money reserved and returns the id in the error body: the reconciler finishes the job, or releases the reserve if the provider never took it. A provider 4xx, by contrast, is a definitive rejection: the job fails at once and the reserve is released without waiting for the reconciler.

Money: a finished generation reports cost_usd, exactly what was charged; a running one reports estimated_cost_usd, the size of the reserve. A failed generation is not billed and comes back with "cost_usd": "0". Media billing is ours, kept apart from text. Errors answer in one shape; code is there when the provider gave one, and a submit rejection adds the job's id: { "error": { "message": "...", "type": "...", "code": "PROVIDER_CODE" } }.

Reference images (image-to-image, same character or style) go in the body as image — a string or an array; images, image_url, image_urls, input_image, init_image and ref_images are accepted too. A value may be a public URL, a data-URL or bare base64, and mixing the forms in one request is fine: a URL is not fetched by us and reaches the provider as a link, while base64 is decoded and sent as bytes. The gateway recognises bytes by their signature (PNG, JPEG, GIF, WebP) and caps each input at 80 MB — anything larger is a 400 before the provider is called. An input that passed our cap may still be refused by the model under its own rules: its code then arrives in error.code — FILE_TOO_LARGE for size, FILE_TYPE_NOT_ALLOWED for type. The gateway puts no limit on the number of references; how many the model actually uses is up to it. A value that parses neither as a URL nor as base64 is dropped silently: the request goes out without that reference and without an error.

A result stays retrievable for 7 days. After that the bytes move out of the database into the archive, result_url is cleared, and the same GET /v1/images/jobs/{job_id} answers { "status": "completed", "archived": true, "data": [] }. That means expired, not "the generation produced nothing" — store the images on your side as soon as you get them. The job row and its money are never deleted: retention moves the payload only.