Image Generations

> Minimum-discount routing: Prefix the path with a min{N} segment (e.g. /min30/v1/images/generations) to require marketplace seller offers to meet a minimum estimated buyer discount before routing. Buyer-owned providers are not covered. See Minimum-Discount Routing.

OpenAI-compatible image generation via the marketplace. One synchronous request returns the image(s); the marketplace routes to the cheapest healthy seller for the model and settles USDC to that seller.

Request

POST /v1/images/generations

Auth: API key (Authorization: Bearer inf_*), or pay-per-request via x402 (PAYMENT-SIGNATURE) or MPP (Authorization: Payment *). With no auth, the endpoint returns 402 advertising both x402 and MPP. See Buyer endpoints. Request Body:

Field	Type	Required	Description
`model`	string	✅	Model ID, e.g. `venice-z-image-turbo`, `seedream-4.5`, `venice-flux-2-pro`, `gpt-5.4-image-2`. Query `/v1/models` for the live catalog
`prompt`	string	✅	Text prompt
`n`	integer	Number of images (1–10, default 1). Token-metered models served over the chat wire return a single image
`size`	string	e.g. `1024x1024`. Drives per-megapixel billing and the per-token output estimate
`quality`	string	e.g. `low`, `medium`, `high`. Drives the per-token output estimate where the provider doesn't report usage
`response_format`	string	`b64_json` or `url` (passed through to the provider)

Response: 200 OK

{
  "created": 1713200000,
  "data": [
    { "b64_json": "iVBORw0KGgo..." }
  ]
}

Headers include X-Request-Id. With response_format=url, items are { "url": "https://..." }.

Pricing — canonical price × discount

Each image model has a canonical reference price (OpenRouter-first, then Venice, then the SI registry). A seller's offer is a discount off that canonical, and the marketplace routes to the deepest discount. You always pay the canonical × the winning offer's discount — never an arbitrary per-seller price.

Canonical follows the model's native metering unit:

Unit	Models (examples)	Canonical	Buyer charge
per-token	Nano Banana, GPT-image, Gemini image	`$/1M` input + output	`usage_tokens × canonical/1M × discount`
per-image	Z-Image, SDXL, Seedream, Lustify, …	`$/image`	`canonical/image × n × discount`
per-megapixel	FLUX.2 Pro/Max/Flex, Grok Imagine	`$/MP`	`canonical/MP × (w×h/1e6 × n) × discount`

Per-token models bill on actual usage the provider reports; when a provider returns none (e.g. Venice serving a token-canonical model), usage is derived from size/quality so the buyer sees true per-1M pricing and the seller isn't underpaid.
Per-image and per-megapixel are deterministic from the request (n, size) — no provider usage needed.
See the live canonical and effective discounts at /api/markets/:model and /v1/prices: token-image models show $/1M input/output, diffusion models $/image, FLUX/Grok $/MP.

All costs are USDC microdollars (1 USD = 1,000,000 microdollars). One settle() transaction pulls USDC from the buyer to the seller per completed request.

Errors

Status	Meaning
`400`	Invalid request (bad JSON, validation, unknown model)
`402`	Insufficient USDC balance/allowance (API key), or payment required (no auth — dual x402/MPP challenge)
`404`	No available sellers for the model
`5xx`	Provider error (sanitized; the marketplace retries the next healthy seller before failing)