Skip navigation
Contents

API

Image generation

POST /v1/images/generations — generate images from a text prompt. Same request as the OpenAI Images API; shares the wallet, API keys and rate limits with chat.

Generate an image#

Only models of type Image in the pricing table can be used. Calling a chat model here is rejected with model_type_mismatch. Most models answer with b64_json; some answer with a url.

Generate and save an image
curl https://<host>/v1/images/generations \
  -H "Authorization: Bearer sk-runtide-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs/FLUX-1-schnell",
    "prompt": "A watercolor of a lotus pond at sunrise",
    "size": "1024x1024",
    "n": 1
  }'
Response
{
  "created": 1731340800,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUg…" }
  ]
}

Parameters#

  • model
    Rule
    Required. An image model.
  • prompt
    Rule
    Required. Non-empty text, at most 32,000 characters.
  • n
    Rule
    Optional integer from 1 to 10 (default 1).
  • size
    Rule
    Optional, written <code>WIDTHxHEIGHT</code> in pixels, e.g. <code>1024x1024</code> (default). Each side must be 64–4096. Named sizes such as <code>auto</code> are not accepted.
  • response_format
    Rule
    b64_json or url. Not every model supports both.
  • quality, style, user
    Rule
    Optional; passed to the model when it supports them.

Billing#

  • Billed per image, scaled by size: n × width × height relative to a 1024×1024 image (1 image = 1,000 billing units of one thousandth). The price in the pricing table is USD per 1024×1024 image.
  • Example: at $0.0005 per image, one 1024×1024 image costs $0.0005; two 512×512 images cost $0.00025.
  • You are billed for the images actually delivered. Provider errors are not billed.
  • The amount for the requested images is held before the call; not enough balance → 402 insufficient_balance and nothing is sent upstream. General details: Billing.

Common errors#

400 model_type_mismatch
HTTP/1.1 400 Bad Request

{"error": {"message": "The model `gpt-4o-mini` is a chat model; use /v1/chat/completions instead.",
           "type": "invalid_request_error", "code": "model_type_mismatch"}}
  • 400 model_type_mismatch
    Cause
    The model is not an image model (or an image model was called on another endpoint). The message names the correct endpoint.
  • 400 invalid_request
    Cause
    prompt empty, n outside 1–10, size not <code>WxH</code> or outside 64–4096, invalid response_format.
  • 404 model_not_found
    Cause
    Unknown model name, or the model is disabled.
  • 402 insufficient_balance
    Cause
    Not enough balance for the hold — top up or request fewer / smaller images.

All error codes: Error codes.