Image Generation

POST /v1/images/generations

Generate images from a text prompt. OpenAI-compatible — the same endpoint and SDK call (client.images.generate) as OpenAI's image API, routed across OpenAI, Google, Alibaba, and ByteDance image models behind one API key.

Request Body

Available models

Model availability depends on your deployment. Fetch the live, compliance-aware list via GET /v1/images/models. A representative set:

Not sure which model? Pick by what you need

Price: token · $in→$out /1M = billed on usage (OpenAI / Google); $/image = flat per generated image. Response: b64 · url ✓ models can also return a pre-signed vendor-hosted URL (response_format: "url", valid ~24 h). Download speed depends on the vendor: Alibaba URLs ride a globally-accelerated CDN (fast everywhere, incl. mainland China); ByteDance seedream URLs are served from Singapore object storage (fast for overseas clients, slow from mainland China). b64 only models reject response_format: "url" with 400 url_not_supported. Edit (i2i) = every model supports image-to-image (send the image field); the value is the max reference images.

Image-to-image (edit)

Add an image field to the same request to edit or reference an input image. Supported on gpt-image, gemini-*-image, qwen-image / wan2.7, and seedream (each model caps how many input images it accepts). Send the image as base64 or a data URI; pass an array for multiple references.

curl https://synthorai.io/v1/images/generations \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "add a small red party hat on the main subject",
    "image": "'"$(base64 -i input.png)"'"
  }'

Response format

Set response_format: b64_json returns base64 image bytes (default); url returns a fetchable URL where the upstream supports it. The response matches OpenAI's images API: { created, data: [{ b64_json | url }] }.

url is supported only where the upstream itself hands back a CDN URL — currently the Alibaba and ByteDance families (qwen-image*, wan*, seedream*); the image downloads from the vendor's CDN via a pre-signed URL valid ~24 hours. OpenAI and Google models (gpt-image*, gemini*) are b64-only: requesting url there returns 400 url_not_supported — rejected before generation, nothing is billed. Check per model via the supports_url field of GET /v1/images/models, or the model table above.

Complete example — url mode

Generate with response_format: "url", read data[0].url from the response, then download the image from the vendor's CDN — a full round-trip you can paste into a terminal:

# 1) Generate — ask for a URL instead of inline base64
curl https://synthorai.io/v1/images/generations \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image",
    "prompt": "a serene mountain lake at sunrise",
    "response_format": "url"
  }'

# → 200 in ~15–30 s. Tiny JSON body — no image bytes inline:
{
  "created": 1783064343,
  "data": [
    {
      "url": "https://dashscope-463f.oss-accelerate.aliyuncs.com/1d/8a/20260703/xxxx.png?Expires=1783151704&OSSAccessKeyId=LTAI...&Signature=bvTa..."
    }
  ]
}

# 2) Download from the vendor CDN — the URL is pre-signed, no auth header needed
curl -o out.png "https://dashscope-463f.oss-accelerate.aliyuncs.com/1d/8a/20260703/xxxx.png?Expires=1783151704&OSSAccessKeyId=LTAI...&Signature=bvTa..."

The URL is pre-signed — anyone with it can download, no auth header needed — and expires in ~24 hours: fetch promptly and re-host the file if you need it long-term. Typical end-to-end: ~15–30 s generation + sub-second CDN download.

Latency, large responses & timeouts

Generation time varies by model: qwen-image-2.0 typically returns in ~5–10 s, while wan2.7-image and seedream-class models take ~15–30 s (longer at 2K+ sizes). The gateway allows up to 180 s per request and returns 504 generation_timeout beyond that — this API itself never returns 408.

The default response_format=b64_json embeds the full image in the response body (2–3 MB of base64 for large models). On slow or long-haul client links, downloading that body can add minutes and trip your HTTP client's or relay gateway's own timeout — typically surfaced on your side as 408 or a timeout error.

Billing

Billed only on success (HTTP 200). Most models are charged per image (count × unit price); OpenAI gpt-image-* models that return token usage are charged per token. Every charge is recorded with request_id, model, and cost for traceability.

Example — curl

curl https://synthorai.io/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "a serene mountain lake at sunrise, photorealistic",
    "n": 1,
    "size": "1024x1024"
  }'

Example — Python (OpenAI SDK)

from openai import OpenAI
import base64

client = OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

resp = client.images.generate(
    model="qwen-image-2.0",
    prompt="a serene mountain lake at sunrise, photorealistic",
    n=1,
    size="1024x1024",
)
# Default response_format is b64_json
img = base64.b64decode(resp.data[0].b64_json)
with open("out.png", "wb") as f:
    f.write(img)

Example — Node (OpenAI SDK)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  baseURL: "https://synthorai.io/v1",
  apiKey: process.env.SYNTHORAI_API_KEY,
});

const resp = await client.images.generate({
  model: "seedream-4-0-250828",
  prompt: "a serene mountain lake at sunrise, photorealistic",
  n: 1,
});
fs.writeFileSync("out.png", Buffer.from(resp.data[0].b64_json, "base64"));

Idempotency

Pass an X-Idempotency-Key header to make retries safe: a repeat request with the same key returns 409 instead of generating (and billing) a second time. Image generation is slow and retry-prone, so this prevents double charges.