Génération d'images

POST /v1/images/generations

Générez des images à partir d'un prompt textuel. Compatible OpenAI — le même endpoint et le même appel SDK (client.images.generate) que l'API d'images d'OpenAI, routé entre les modèles d'images d'OpenAI, Google, Alibaba et ByteDance derrière une seule clé API.

Corps de la requête

Modèles disponibles

La disponibilité des modèles dépend de votre déploiement. Récupérez la liste à jour et conforme via GET /v1/images/models. Un ensemble représentatif :

Vous ne savez pas quel modèle choisir ? Choisissez selon vos besoins

Price : token · $in→$out /1M = facturé à l'usage (OpenAI / Google) ; $/image = tarif fixe par image générée. Response : les modèles b64 · url ✓ peuvent aussi renvoyer une URL pré-signée hébergée par le fournisseur (response_format: "url", valable ~24 h). La vitesse de téléchargement dépend du fournisseur : les URL d'Alibaba passent par un CDN accéléré mondialement (rapide partout, y compris en Chine continentale) ; les URL seedream de ByteDance sont servies depuis un stockage objet à Singapour (rapide pour les clients étrangers, lent depuis la Chine continentale). Les modèles b64 only rejettent response_format: "url" avec 400 url_not_supported. Edit (i2i) = chaque modèle prend en charge l'image-to-image (envoyez le champ image) ; la valeur correspond au nombre maximal d'images de référence.

Image-vers-image (édition)

Ajoutez un champ image à la même requête pour éditer une image d'entrée ou s'y référer. Pris en charge sur gpt-image, gemini-*-image, qwen-image / wan2.7 et seedream (chaque modèle limite le nombre d'images d'entrée acceptées). Envoyez l'image en base64 ou en data URI ; passez un tableau pour plusieurs références.

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

Format de réponse

Définissez response_format: b64_json renvoie les octets de l'image en base64 (par défaut) ; url renvoie une URL récupérable lorsque l'amont le prend en charge. La réponse correspond à l'API d'images d'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.

Facturation

Facturé uniquement en cas de succès (HTTP 200). La plupart des modèles sont facturés par image (nombre × prix unitaire) ; les modèles OpenAI gpt-image-* qui renvoient l'utilisation de tokens sont facturés par token. Chaque facturation est enregistrée avec request_id, model et cost pour la traçabilité.

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

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

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

Idempotence

Passez un en-tête X-Idempotency-Key pour sécuriser les nouvelles tentatives : une requête répétée avec la même clé renvoie 409 au lieu de générer (et facturer) une seconde fois. La génération d'images est lente et sujette aux retentatives, ce qui évite ainsi les doubles facturations.