Image generation API

Overview

The API turns a text prompt into one image and returns it synchronously as Base64 JSON.

It follows the platform payment flow: anonymous x402 needs no account, a platform API key uses quota granted to your Koinelix account.

Payment flow, authentication and shared errors are described in the platform documentation. →

Quickstart

Start with a plain request to see the quote. Then let an x402 client pay and save the image.

# 1. Ask for a quote. No payment, no account.
curl -i -X POST https://api.koinelix.com/v1/images/generations \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"A watercolor lighthouse at sunrise","size":"1024x1024","output_format":"png"}'

# HTTP/2 402
# PAYMENT-REQUIRED: <base64 x402 v2 quote: price, network, asset, payee>
#
# 2. An x402 client signs that quote with your wallet and repeats the same request
#    with a PAYMENT-SIGNATURE header. See the TypeScript and Python tabs.

• No account or API key is needed for x402 calls.
• To complete a paid call you need a wallet that holds USDC on Base. Keep its private key in an environment variable, never in code.
• Generation is synchronous. Keep the connection open until the response arrives.

Endpoint

All requests go to a single endpoint. GET and HEAD return the same 402 quote as an unsigned POST, which catalogs use as a probe.

POST https://api.koinelix.com/v1/images/generations

Request body

Send a JSON object. Unknown fields are rejected.

Example request

{
  "prompt": "A watercolor lighthouse at sunrise",
  "size": "1024x1024",
  "output_format": "png"
}

Response

A successful call returns 200 with a JSON body. The image bytes are returned as sent by the provider, without conversion.

Behavior and limits

• One image per call (n = 1), no streaming.
• Requests are synchronous and usually take tens of seconds. Keep the connection open until the response arrives.
• Each payment buys exactly one generation attempt. Payment settles before generation starts and is not refunded if generation fails.
• The size you request is forwarded to the image provider. The returned image can have different dimensions, so check the image you receive.
• The image is not saved. If it was generated but never reached you, resending the same request and PAYMENT-SIGNATURE returns image_result_unavailable and starts no new generation.
• Rate limits apply per IP address and per payer. The prompt is limited to 6000 UTF-8 bytes.

Errors

These codes are specific to image generation. Shared payment and request errors are listed in the platform documentation.