Generate an image from a text prompt

POST /v1/images/generations

Operation ID: createImageGeneration. The canonical machine-readable schema is OpenAPI.

Request body

Choose an available image-generation model from GET /v1/models. The first release accepts one 1024×1024 image. Use response_format: "url" for the default hosted result or "b64_json" when inline bytes are also required.

{
  "model": "gemini-3.1-flash-lite-image",
  "prompt": "A small observatory beneath a clear night sky, editorial illustration",
  "n": 1,
  "image_size": "1K",
  "aspect_ratio": "1:1",
  "response_format": "url"
}

Payment lifecycle

The first request returns Hypertext Transfer Protocol (HTTP) status 402 without calling the model provider. Check the Base network, United States Dollar Coin (USDC) contract, payment recipient, expiry time, payment scheme, and maximum amount. Sign locally with an official x402 client, then retry the identical effective request with the same idempotency key.

After success, read the PAYMENT-RESPONSE, X-Request-ID, X-Receipt-ID, and X-Catalog-Version headers together with the receipt link. The response is released only after the result, payment, and receipt are safely stored.

Read the response

Read the generated image from data[0].url. The capability-protected hosted URL is available for exactly seven days; data[0].url_retention_days is 7 and data[0].url_expires_at gives the precise expiration time. Download the image before then. When response_format is b64_json, the same item also contains inline bytes, but the hosted URL still expires at the disclosed time.

Responses

• 200: Durably settled response with X-Receipt-ID and PAYMENT-RESPONSE headers
• 400: Invalid or unsupported request
• 402: Payment required. The PAYMENT-REQUIRED header is authoritative and contains the official x402 challenge.
• 409: Idempotency key reused with a different effective request
• 503: Provider, payment, or safety dependency unavailable