Image Generation

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

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

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

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

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

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

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