# Generate images

> Generate one or more images from a prompt, returned as base64 data.

`POST https://api.numes.ai/api/v1/images`

Source: https://0.0.0.0:3000/docs/api-reference/media/create-image
Authorization: Bearer inference key

Images are always returned inline as base64 (`b64_json`); URL responses are not offered. Controls you set (`size`, `quality`, `output_format`, `background`, `n`) are forwarded; add `provider.require_parameters: true` to route only to endpoints that declare every one of them. With `stream: true` the response is a stream of `image_generation.*` events. Your account's [request policy](/docs/privacy/request-policy) applies to `prompt`; reference images aren't inspected. Guide: [Image generation](/docs/multimodal/image-generation).

```request
{
  "method": "POST",
  "path": "/images",
  "body": {
    "model": "author/image-model",
    "prompt": "An isometric illustration of a data center at dawn",
    "size": "1024x1024",
    "output_format": "png"
  }
}
```

```json title="Response 200"
{
  "created": 1790000000,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "media_type": "image/png" }
  ],
  "usage": {
    "input_images": 0,
    "output_images": 1,
    "input_audio_seconds": 0,
    "output_audio_seconds": 0,
    "input_characters": 0,
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "cost": 0.04
  }
}
```

```sse title="Response stream"
data: {"type":"image_generation.partial","index":0,"b64_json":"iVBORw0KGgo…","media_type":"image/png"}

data: {"type":"image_generation.completed","index":0,"b64_json":"iVBORw0KGgo…","media_type":"image/png"}

data: {"type":"image_generation.usage","usage":{"input_images":0,"output_images":1,"input_audio_seconds":0,"output_audio_seconds":0,"input_characters":0,"prompt_tokens":0,"completion_tokens":0,"total_tokens":0,"cost":0.04}}

data: [DONE]
```

## Headers

- `X-Request-Id` (string; Length 1–128): Correlation ID, not an idempotency key. Inference request IDs recorded with a generation are unique per account. A traffic-admitted request reusing a recorded ID returns 400 invalid_request. Traffic admission rejection takes precedence over this conflict, including for reused IDs; it performs no generation lookup and writes no generation, result or attempt. Rate-limit rejection returns 429 rate_limited with Retry-After; an inference limiter outage retains 500 server.

## Request body (application/json)

- `model` (string; required; Length ≤ 393; Pattern ^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$)
- `prompt` (string; required; Length 1–1 Mi)
- `n` (integer; default 1; Range 1–10)
- `size` (string)
- `resolution` (string; Length ≤ 16)
- `aspect_ratio` (string; Length ≤ 16)
- `quality` (enum<string>; one of auto, low, medium, high)
- `output_format` (enum<string>; one of png, jpeg, webp)
- `background` (enum<string>; one of auto, opaque, transparent)
- `output_compression` (integer; Range 0–100)
- `seed` (integer<int64>)
- `stream` (boolean; default false)
- `input_references` (array<string | object>; Items ≤ 16)
  - variant Option 1
  - variant Option 2
    - `image_url` (string; required)
- `provider` (object)
  - `order` (array<string>; Items ≤ 100; Item length 1–256)
  - `allow_fallbacks` (boolean; default true)
  - `require_parameters` (boolean; default false)
  - `data_collection` (enum<string>; one of allow, deny)
  - `zdr` (boolean)
  - `only` (array<string>; Items ≤ 100; Item length 1–256)
  - `ignore` (array<string>; Items ≤ 100; Item length 1–256)
  - `quantizations` (array<string>; Items ≤ 100; Item length 1–256)
  - `regions` (array<string>; Items ≤ 64; Unique items; Item pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$): Numes extension filtering endpoint-declared country or region identifiers.
  - `sort` (enum<string>; one of price, throughput, latency, quality): Deterministic provider sort. `quality` is a deliberate Numes compatibility extension that ranks endpoints by exact task-scoped content-free validation evidence; it is opt-in and never changes the default routing order.

  - `max_price` (object)
    - `prompt` (number; Range ≥ 0)
    - `completion` (number; Range ≥ 0)

## Response 200 (application/json)

- `created` (integer<int64>; required)
- `data` (array<object>; required)
  - `b64_json` (string; required; Encoding base64)
  - `media_type` (string; required)
  - `revised_prompt` (string)
- `usage` (object; required)
  - `input_images` (integer; required; Range ≥ 0)
  - `output_images` (integer; required; Range ≥ 0)
  - `input_audio_seconds` (number; required; Range ≥ 0)
  - `output_audio_seconds` (number; required; Range ≥ 0)
  - `input_characters` (integer; required; Range ≥ 0)
  - `prompt_tokens` (integer; required; Range ≥ 0)
  - `completion_tokens` (integer; required; Range ≥ 0)
  - `total_tokens` (integer; required; Range ≥ 0)
  - `cost` (number; required; Range ≥ 0)

## Response 503 (application/json)

- `error` (object; required)
  - `code` (integer; required)
  - `message` (string; required)
  - `metadata` (object)
- `openrouter_metadata` (object)

## Response default (application/json)

- `error` (object; required)
  - `code` (integer; required)
  - `message` (string; required)
  - `metadata` (object)
- `openrouter_metadata` (object)