Skip to content
API Reference

Text to Image

Generating high-quality images from natural language descriptions is easy with SIRAYA Model Router. Our unified API allows you to access various state-of-the-art image generation models using a single interface.

POST https://llm.siraya.ai/v1/images/generations
Authorization string Required
Your API Key (e.g., Bearer <API_KEY>).

Body

model string Required
The ID of the model to use (e.g. gpt-image-2, gemini-3.1-flash-image, z-image-spicy). Z-Image sizes its output with width / height — see Z-Image.
prompt string Required
A text description of the desired image.
n integer Default: 1
The number of images to generate (1-10). Gemini Image models (gemini-*-image) accept only 1; a larger value returns a 400.
size string
The dimensions of the generated image (e.g. 1024x1024, 1792x1024, 1024x1792).
quality string
The quality of the generated image. GPT Image models take low, medium, high, auto (the 2.5 models also take xhigh and max); standard and hd are accepted as aliases for medium and high. See the model pages for other families.
response_format string
The format in which the generated image is returned. Possible values: b64_json, url. Support depends on the model: GPT Image and Gemini Image models always return b64_json and ignore url; Seedream defaults to b64_json and returns a signed URL for url.
user string
A unique identifier representing your end-user.
background string
The background type for the generated image. Possible values: transparent, opaque, auto.
output_format string
GPT Image models only. The encoding of the returned image: png or jpeg.
output_compression integer
GPT Image models only. The compression level for the output image (0-100). Only valid with output_format: jpeg.
moderation string
The content moderation level. Possible values: low, auto.
image string | array
A reference image for image-to-image generation, or an array of them to combine several references. Pass a public URL, or a base64 data URL in the form data:image/png;base64,<BASE64> for a local file. Supported by Seedream and Gemini Image models.
sequential_image_generation string
Controls batch image generation mode. Possible values: auto, disabled. Supported by Seedream models.
async boolean Default: false
When false, the request waits for generation to finish and returns the completed image. When true, it returns immediately with an image id while generation runs in the background. There's no status/poll endpoint for images — pass callbackUrl to receive the result. See Asynchronous generation.
callbackUrl string
Required when async is true and must be an http(s) URL; otherwise the request is rejected with a 400 (see Asynchronous generation). A URL the router will POST to once generation completes (or fails). This is the only way to retrieve the result of an async image job.
extra_body object
Additional model-specific parameters passed directly to the provider. Unknown top-level fields are also automatically captured into this object. 
curl https://llm.siraya.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "A cat is playing piano in a cozy room"
  }'

import requests

url = "https://llm.siraya.ai/v1/images/generations"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API_KEY>"
}
data = {
    "model": "gemini-3.1-flash-image",
    "prompt": "A cat is playing piano in a cozy room",
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Example Response

{
    "created": 1774716098,
    "data": [
        {
            "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zUAAAAg3..."
        }
    ]
}

Asynchronous generation

Image generation is normally fast, but some models can take a while. By default the request is synchronous — it waits for generation to finish and returns the completed image. For slower models, set async: true to return immediately with an image id and receive the result later via a callback.

No poll or download endpoint

Unlike video generation, async image generation has no status/poll endpoint and no separate download endpoint. callbackUrl is therefore required whenever async is true. A request without a valid http(s) callbackUrl is rejected with HTTP 400 before any generation starts:

{
  "created": 1774716098,
  "data": {},
  "error": { "message": "callbackUrl must be an http(s) URL when async is true" }
}

Submit an async job

curl https://llm.siraya.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "A cat is playing piano in a cozy room",
    "async": true,
    "callbackUrl": "https://your-app.com/webhooks/siraya-image"
  }'

The job is accepted immediately. status is processing and no image is returned yet. id identifies the job and is echoed in the callback:

{
  "created": 1774716098,
  "id": "6f1c0b9e8a2d4c7e",
  "status": "processing"
}

Callback

When the job finishes, the router sends a POST to callbackUrl. The body is the synchronous response — the finished image as base64 under data[], not a URL — plus the job id and a status of completed:

{
  "id": "6f1c0b9e8a2d4c7e",
  "created": 1774716103,
  "status": "completed",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zUAAAAg3..." }
  ],
  "error": {}
}

If generation failed, status is failed, data is empty and error.message carries the reason:

{
  "id": "6f1c0b9e8a2d4c7e",
  "created": 1774716103,
  "status": "failed",
  "data": {},
  "error": { "message": "..." }
}

Your endpoint should respond 2xx within 10 seconds. A failed delivery is retried up to 3 more times (4 attempts in total).

For a list of all available image models, visit the Models Directory.