# Image Generation

> Generate images using the OpenAI-compatible /v1/images/generations endpoint, routed across Together FLUX, Workers AI, Pollinations, NVIDIA NIM, and Gemini Imagen.

Canonical: https://ai-gateway.sassmaker.com/docs/images

## Endpoint

```
POST /v1/images/generations
```

OpenAI-compatible image generation. The gateway fans out across every configured image provider and picks a healthy one based on live success rate and daily-limit headroom.

## Request Body

| Field | Type | Default | Description |
|---|---|---|---|
| `model` | string | `"auto"` | Model identifier (see [Providers](https://ai-gateway.sassmaker.com/docs/images#providers)). Use `"auto"` for health-aware routing across all enabled image models. |
| `prompt` | string | required | Text description of the image. 1–8000 chars. |
| `n` | number | `1` | Number of images to generate (1–4). Not all providers honour values greater than 1 — excess images may be ignored. |
| `size` | string | provider default | One of `"256x256"`, `"512x512"`, `"1024x1024"`, `"1024x1792"`, `"1792x1024"`. |
| `response_format` | string | `"url"` | `"url"` returns a hosted URL; `"b64_json"` returns a base64-encoded PNG/JPEG. |
| `quality` | string | — | Passed through when the provider supports it (currently a no-op for most). |
| `style` | string | — | Passed through when the provider supports it. |
| `project_id` | string | — | Optional body-level project tag. Same semantics as the `x-gateway-project-id` header. |

### Required Header

| Header | Required | Description |
|---|---|---|
| `Authorization: Bearer <GATEWAY_API_KEY>` | yes | Gateway API key. |
| `x-gateway-project-id` | yes (or in body) | 1–64 chars `[a-zA-Z0-9._:-]`. Required for analytics + rate accounting. Either send the header or include `project_id` in the JSON body. |
| `x-gateway-force-provider` | no | Pin a specific provider (`together`, `workers_ai`, `gemini`, `nvidia`, `pollinations`). Bypasses health-aware routing. |

:::caution[project_id is mandatory]
Requests without a `project_id` (via header or body) fail with `400 invalid_project_id`.
:::

## Providers

| Provider | Models | Notes |
|---|---|---|
| **Together FLUX** | `black-forest-labs/FLUX.1-schnell`, `FLUX.1.1-pro`, `FLUX.1-kontext-pro`, `FLUX.2-dev`, `FLUX.2-flex`, `FLUX.2-pro`, `FLUX.2-max` | Requires `TOGETHER_API_KEY`. Highest priority in `auto`. |
| **Gemini Imagen** | `imagen-4.0-generate-001`, `gemini-2.5-flash-image` | Requires `GEMINI_API_KEY`. |
| **Cloudflare Workers AI** | `@cf/black-forest-labs/flux-1-schnell`, `@cf/stabilityai/stable-diffusion-xl-base-1.0`, `@cf/lykon/dreamshaper-8-lcm` | No external key — uses Workers AI binding. |
| **NVIDIA NIM** | `black-forest-labs/flux.1-schnell` | Requires `NVIDIA_API_KEY`. |
| **Pollinations** | `flux`, `flux-realism`, `turbo` | No key — public free tier. Lowest priority fallback. |

Call [`GET /v1/models`](https://ai-gateway.sassmaker.com/models) for the live enabled set with health state.

## Response

```json
{
  "created": 1714000000,
  "data": [
    {
      "url": "https://cdn.example/generated-image.png",
      "revised_prompt": "A cinematic close-up of a red fox in an autumn forest"
    }
  ],
  "x_gateway": {
    "provider": "together",
    "model": "black-forest-labs/FLUX.1-schnell",
    "attempts": 1,
    "request_id": "req_abc123",
    "project_id": "my_project"
  }
}
```

When `response_format: "b64_json"`, each `data[i]` contains `b64_json` instead of `url`.

The gateway tries up to 3 candidates from the health-sorted pool before giving up with `502 provider_error`.

## Examples

### URL response (default)



### curl

```bash
curl https://ai-gateway.sassmaker.com/v1/images/generations \
  -H "Authorization: Bearer <GATEWAY_API_KEY>" \
  -H "x-gateway-project-id: my_project" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "prompt": "A cinematic close-up of a red fox in an autumn forest",
    "size": "1024x1024"
  }'
```


### JavaScript

```js
const response = await fetch('https://ai-gateway.sassmaker.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <GATEWAY_API_KEY>',
    'x-gateway-project-id': 'my_project',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'auto',
    prompt: 'A cinematic close-up of a red fox in an autumn forest',
    size: '1024x1024',
  }),
});

const data = await response.json();
console.log(data.data[0].url);
console.log('Served by:', data.x_gateway.provider, data.x_gateway.model);
```


### OpenAI SDK

```js

const client = new OpenAI({
  baseURL: 'https://ai-gateway.sassmaker.com/v1',
  apiKey: '<GATEWAY_API_KEY>',
  defaultHeaders: { 'x-gateway-project-id': 'my_project' },
});

const image = await client.images.generate({
  model: 'auto',
  prompt: 'A cinematic close-up of a red fox in an autumn forest',
  size: '1024x1024',
});

console.log(image.data[0].url);
```



### Base64 response



### curl

```bash
curl https://ai-gateway.sassmaker.com/v1/images/generations \
  -H "Authorization: Bearer <GATEWAY_API_KEY>" \
  -H "x-gateway-project-id: my_project" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs/FLUX.1-schnell",
    "prompt": "A watercolor painting of Mount Fuji at sunrise",
    "response_format": "b64_json"
  }'
```


### JavaScript

```js
const response = await fetch('https://ai-gateway.sassmaker.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <GATEWAY_API_KEY>',
    'x-gateway-project-id': 'my_project',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'imagen-4.0-generate-001',
    prompt: 'A watercolor painting of Mount Fuji at sunrise',
    response_format: 'b64_json',
  }),
});

const data = await response.json();
const pngBytes = Buffer.from(data.data[0].b64_json, 'base64');
await require('fs/promises').writeFile('out.png', pngBytes);
```



### Pin a specific provider

```bash
curl https://ai-gateway.sassmaker.com/v1/images/generations \
  -H "Authorization: Bearer <GATEWAY_API_KEY>" \
  -H "x-gateway-project-id: my_project" \
  -H "x-gateway-force-provider: workers_ai" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "@cf/black-forest-labs/flux-1-schnell",
    "prompt": "A neon cyberpunk alley at night"
  }'
```

## Error Codes

| Status | `code` | Meaning |
|---|---|---|
| 400 | `invalid_project_id` | Missing/invalid `project_id`. |
| 502 | `provider_error` | All attempted providers failed in sequence. Response message includes the last upstream error. |
| 503 | `no_image_provider` | No image provider key/binding is configured. |