POST/v1/images/generations

Image Generation

Generate images from a text prompt.

OpenAI-dialect image generation (e.g. FLUX-family models).

Request body

Field	Type	Required	Notes
`model`	string	yes	An image alias.
`prompt`	string	yes	Absent → 400 `missing_prompt`; empty → 400 `empty_prompt`.
`response_format`	`b64_json`	no	Only `b64_json` is served. `"url"` is rejected with 400 `unsupported_response_format` — a recorded decision, not a gap.
`size`	string	no	Must be on the deployment allowlist (default `512x512`, `1024x1024`, `768x1344`, `1344x768`) → 400 `invalid_image_size`. Omit for the model default.
`n`	integer	no	≥ 1.
`quality`, `style`	string	no	Forwarded to the provider unchanged.
`image`	string	no	Optional base64 reference image (image-to-image). Counts toward the body cap.
`user`	string	no	Forwarded to the provider unchanged.

Body cap

The request body (including any base64 reference image) is capped at 8 MiB by default → 413 request_too_large over the limit.

Code sample

curl https://api.<domain>/v1/images/generations \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-schnell",
    "prompt": "a cat wearing sunglasses, studio lighting",
    "size": "1024x1024"
  }'

Response

{
  "created": 1724680002,
  "data": [
    { "b64_json": "AAAA…", "revised_prompt": "a cat" }
  ],
  "provider_metadata": { "provider": "vllm-staging", "actual_model": "black-forest-labs/FLUX.1-schnell" }
}

Guaranteed fields: created, data[].{b64_json, revised_prompt?}, and provider_metadata. usage appears only when the provider reported OpenAI ImageGenUsage keys (input_tokens, output_tokens, total_tokens, input_tokens_details?) — provider timing junk is dropped.

Errors

Status	Codes specific to this endpoint
400	`missing_prompt`, `empty_prompt`, `unsupported_response_format`, `invalid_image_size`
413	`request_too_large`

Plus the standard surface — see Errors.