# Image generation

`POST /v1/images/generations` has two declared response modes, selected by the model catalog. Always inspect the model metadata and handle the documented response. Both modes accept `model`, `prompt`, optional top-level `image` reference URL, `size`, and `n`. These are normalized platform fields; provider adapters translate them to a certified model schema.

```sh
curl https://xxxrouter.com/v1/images/generations \
  -H "Authorization: Bearer $XXXROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: sample-image-request-001' \
  -d '{"model":"seedream-4.5","prompt":"A ceramic cup in natural light","size":"2048x2048","n":1}'
```

## Synchronous model: HTTP 200

```json
{"request_id":"req_demo_sync","model":"seedream-4.5","response_mode":"sync","status":"succeeded","data":[{"url":"https://assets.xxxrouter.example/demo/cup.png"}],"billing":{"status":"settled","currency":"USD","amount":"0.030000"}}
```

The image arrives in the original HTTP response. No provider task ID or follow-up task polling is required. The amount above is a demo, not a quote. Slow synchronous execution remains synchronous; a client timeout is not proof of failure or permission to resubmit.

## Asynchronous model: HTTP 202

Select `nano-banana-pro` or `flux-2-pro` to receive:

```json
{"request_id":"req_demo_async","task_id":"task_demo_01","model":"nano-banana-pro","response_mode":"async","status":"running"}
```

Poll [the task endpoint](/docs?page=tasks&lang=en) until terminal. Do not read `202` as completed output. A shared image route does not imply all models are OpenAI Images compatible. Configured routes submit real requests. Missing credentials never trigger a simulated paid result.

[Reference inputs](/docs?page=uploads&lang=en) · [Errors](/docs?page=errors&lang=en)

The current service supports n=1 only. image is allowed only when the model parameters include it.

Successful responses return the original generated-media URL unchanged. The original host controls availability, expiry and browser cross-origin behavior. Save results before expiry; querying a completed task returns the saved URL and does not renew it. Request metadata and result URLs may be retained for recovery; generated-media bytes are never retained.