POST /v1/images/generations

Generate images from a prompt (unit-billed, per image returned)

Images route (route_type: images; OpenAI images shape, synchronous). Strict accepted set — model, prompt (required, non-empty), n (integer 1-10, default 1), size (WIDTHxHEIGHT with positive integer dimensions — the provider APPLIES it), and response_format with the value url ONLY (b64_json is a named 400 day-one: the provider's API rejects it, and a value we cannot serve is refused at our door, never coerced); everything else — seed, quality, style, background, output_format, output_compression, moderation, stream, partial_images, user — is unknown_param naming the offender. Metering: unit_type='images' — the count IS the response's data[] length (n-billed-as-returned: a partial return bills what returned; a failed generation bills zero with its failure row). usage on every answer is OUR {images, cost} at 6dp (the provider's token-shaped usage block is all-zero noise and never crosses). The response's hosted image URLs pass through byte-identical (no proxy, no transform) and are EPHEMERAL — fetch promptly and store client-side. Idempotency-Key carries replay semantics on this route (contract §8 route-scope — the embeddings/rerank JSON class).

curl -X POST https://api.ironstratum.com/v1/images/generations \
  -H "Authorization: Bearer $IRONSTRATUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model>","prompt":"<prompt>"}'