Image generation / edit

The gateway exposes OpenAI-compatible POST /v1/images/generations and POST /v1/images/edits (multipart). Auth matches Chat (user sk-…). Models need an active OpenAI-protocol route and Image pricing on the catalog entry.

Prerequisite

Finish Providers (with Images generations endpoints) and Models. Field contracts live in the GitHub reference · image-models.

What to do in Admin

1. Provider: add keys for OpenAI or a compatible upstream. endpoints.openai.base can derive …/images/generations, or set a full images.generations URL. For Seedream-style hosts without OpenAI edits, do not set base (avoids a dead derived edits URL).
2. Models: import or create an image preset (output includes image). Set image_billing_mode:
   • token: meter from upstream image / text token usage (e.g. GPT Image).
   • per_image: catalog price per image (e.g. Seedream), with optional reference-image input price.
3. Routes: add an OpenAI, active route for that model.
4. Validate: Playground probes one route (no user billing); Simulator hits real Proxy → check Request logs for billing_kind / image counts and charges.

Filter Models by Image first: /img identifies per-image billing and /M identifies token billing. Open the model editor to review the complete price profile.

How success, cancellation, and failure are billed

• token uses real usage from a successful response; the entry estimate is only a budget preflight.
• per_image charges confirmed output images from a successful response, plus optional reference-image input cost.
• Client cancellation, Gateway timeout, explicit upstream 4xx / 5xx, network failures, and empty results do not charge, but still produce a zero-cost log for diagnosis.
• A legacy image block without an explicit image_billing_mode is no longer billable. A legacy profile with valid image_* Token prices still resolves as token.

Upgrading old image pricing

For built-in image models with old Postgres pricing, run node scripts/db/migrate-image-billing-modes.mjs --dry-run before --apply. The script automates known built-in model IDs only; review MySQL, D1, and custom models manually.

Model listing

• Default authenticated GET /v1/models returns LLMs only — not pure image-generation models. Pass kind=image or kind=all when needed.
• Portals should use public GET /catalog/models (no user key). It is not a drop-in replacement for /v1/models.

Minimal client call

curl -sS "$GATEWAY_URL/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"a watercolor fox","size":"1024x1024"}'

Next

• Agent Tools
• Routing · Simulator