Bildgenerierung

POST /v1/images/generations

Generiere Bilder aus einem Text-Prompt. OpenAI-kompatibel — derselbe Endpoint und SDK-Aufruf (client.images.generate) wie bei der Bild-API von OpenAI, geroutet über Bildmodelle von OpenAI, Google, Alibaba und ByteDance hinter einem einzigen API-Key.

Anfragetext

Verfügbare Modelle

Die Modellverfügbarkeit hängt von deinem Deployment ab. Rufe die aktuelle, compliance-bewusste Liste ab über GET /v1/images/models. Eine repräsentative Auswahl:

Unsicher, welches Modell? Wählen Sie nach Ihrem Bedarf

Price: token · $in→$out /1M = nach Nutzung abgerechnet (OpenAI / Google); $/image = Pauschale pro generiertem Bild. Response: b64 · url ✓-Modelle können auch eine vorsignierte, vom Anbieter gehostete URL zurückgeben (response_format: "url", gültig ~24 h). Die Download-Geschwindigkeit hängt vom Anbieter ab: Alibaba-URLs nutzen ein global beschleunigtes CDN (überall schnell, auch in Festlandchina); ByteDance-seedream-URLs werden aus Objektspeicher in Singapur ausgeliefert (schnell für Kunden im Ausland, langsam aus Festlandchina). b64 only-Modelle lehnen response_format: "url" mit 400 url_not_supported ab. Edit (i2i) = jedes Modell unterstützt Image-to-Image (das Feld image senden); der Wert ist die maximale Anzahl an Referenzbildern.

Image-to-image (Bearbeitung)

Füge derselben Anfrage ein image-Feld hinzu, um ein Eingabebild zu bearbeiten oder zu referenzieren. Unterstützt bei gpt-image, gemini-*-image, qwen-image / wan2.7 und seedream (jedes Modell begrenzt, wie viele Eingabebilder es akzeptiert). Sende das Bild als base64 oder data URI; übergib ein Array für mehrere Referenzen.

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)"'"
  }'

Antwortformat

Setze response_format: b64_json gibt base64-Bildbytes zurück (Standard); url gibt eine abrufbare URL zurück, sofern der Upstream dies unterstützt. Die Antwort entspricht der images-API von OpenAI: { 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.

Abrechnung

Wird nur bei Erfolg (HTTP 200) abgerechnet. Die meisten Modelle werden pro Bild abgerechnet (Anzahl × Stückpreis); OpenAI-gpt-image-*-Modelle, die die Token-Nutzung zurückgeben, werden pro Token abgerechnet. Jede Abrechnung wird mit request_id, model und cost zur Nachverfolgbarkeit erfasst.

Beispiel — 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"
  }'

Beispiel — 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)

Beispiel — 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"));

Idempotenz

Übergib einen X-Idempotency-Key Header, um Wiederholungen sicher zu machen: Eine erneute Anfrage mit demselben Key gibt 409 zurück, anstatt ein zweites Mal zu generieren (und abzurechnen). Die Bildgenerierung ist langsam und wiederholungsanfällig, daher verhindert dies doppelte Abrechnungen.