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://free-ai-gateway.sarthakagrawal927.workers.dev/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://free-ai-gateway.sarthakagrawal927.workers.dev/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://free-ai-gateway.sarthakagrawal927.workers.dev/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://free-ai-gateway.sarthakagrawal927.workers.dev/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://free-ai-gateway.sarthakagrawal927.workers.dev/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://free-ai-gateway.sarthakagrawal927.workers.dev/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.