Images API

OpenAI-compatible image generation, so an OpenAI client pointed at Console works unchanged.

Generate

POST /api/client/v1/images/generations

Request

{
  "model": "gpt-image-2",
  "prompt": "A watercolor fox reading a book under a streetlamp",
  "n": 1,
  "size": "1024x1024",
  "quality": "high",
  "response_format": "b64_json"
}

Parameters

Field	Type	Required	Description
model	string	Yes	Model key from the Model Hub. Must be a model in the image category.
prompt	string	Yes	Text description of the desired image.
n	number	No	Number of images to generate. Must be positive.
size	string	No	e.g. 1024x1024. Forwarded as-is to the upstream model.
quality	string	No	e.g. standard, hd, high — depends on the upstream model.
style	string	No	Forwarded as-is (DALL·E-style models).
background	string	No	e.g. transparent, opaque (gpt-image-* models).
output_format	string	No	e.g. png, jpeg, webp (gpt-image-* models).
response_format	string	No	url or b64_json. gpt-image-* models always return base64 and reject this field, so it is only forwarded when set.
user	string	No	Opaque end-user identifier, forwarded upstream.

Response

{
  "created": 1725480000,
  "data": [
    { "b64_json": "iVBORw0KG...", "revised_prompt": "A watercolor-style illustration of a fox..." }
  ],
  "request_id": "req_..."
}

Each data[] entry carries whichever of b64_json / url the upstream returned, plus revised_prompt when the model rewrote the prompt.

Billing and quota

Image models bill per image, not per token — the model's pricing entry in the Model Hub carries a per-image rate. The pre-flight quota check counts the request itself (rate limit) and settles the budget from usage.images (or data.length when the upstream didn't report a count) after the call completes.

Errors

Status	Description
400	Missing model or prompt, or n is not a positive number
401	Invalid API token
404	Model key not found, or not an image-category model
429	Rate limit or budget exceeded
500	Upstream or internal error

Example

curl -X POST https://gateway.example.com/api/client/v1/images/generations \
  -H "Authorization: Bearer cpeer_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor fox reading a book under a streetlamp",
    "response_format": "b64_json"
  }'

Where to go next

• Model Hub — deploy an image-category model and try it from the built-in Playground.
• Chat Completions — the text counterpart of this endpoint.