Image Generation

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

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). 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.

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 for the live enabled set with health state.

Response

{
  "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 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"
  }'

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);

import OpenAI from 'openai';

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 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"
  }'

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

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.