Images

POST /v1/images/generations and POST /v1/images/edits accept the OpenAI Images API request and forward it to the provider that serves the requested model. Tokamak changes one field, model, to the provider's own model id, and relays the provider's response unchanged.

Use your Tokamak inference key. Image models are listed in Models with a per-image price; openai/gpt-image-2 is the current one.

Generate

curl -sS https://api.tokamak.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKAMAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A lighthouse on a basalt cliff at blue hour, long exposure, thin fog rolling in from the sea, 35mm film grain",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

The response is the provider's:

{
  "created": 1791024000,
  "data": [{ "b64_json": "iVBORw0KGgo…" }],
  "usage": {
    "input_tokens": 31,
    "output_tokens": 4160,
    "total_tokens": 4191,
    "input_tokens_details": { "text_tokens": 31, "image_tokens": 0 }
  }
}

gpt-image models return b64_json and do not accept response_format; leave it out. size, quality, background, output_format and the other OpenAI fields are sent as you wrote them.

The settled generation id is returned in the X-Tokamak-Execution-Id response header and can be looked up on GET /v1/generation.

Edit

Edits use OpenAI's multipart/form-data form: one or more image[] files, an optional PNG mask applied to the first image, the prompt and the model.

curl -sS https://api.tokamak.sh/v1/images/edits \
  -H "Authorization: Bearer $TOKAMAK_API_KEY" \
  -F "model=openai/gpt-image-2" \
  -F "image[][email protected]" \
  -F "prompt=Replace the sky with a clear night sky and the Milky Way; keep the lighthouse and cliff unchanged" \
  -F "quality=high"

The mask is guidance, not strict inpainting: the model regenerates the whole image and keeps the unmasked area close to the original. Describe the whole resulting image in the prompt. input_fidelity is not accepted by gpt-image-2.

Limits and errors

• n may be 1–10 per request. Above that the request is refused with 422 for billed organizations.
• Billing is per image (per_image in the model's price). Token counts in usage are reported for analytics and are not what is charged.
• Tokamak's own errors (missing model, unknown model, an unreadable n) use the OpenAI error shape, {"error":{"message","type","code"}}. Provider errors are returned as the provider sent them.
• There is no /v1/images/variations.

See Images and files for sending images as input to text models.