Generazione di immagini

POST /v1/images/generations

Genera immagini da un prompt testuale. Compatibile con OpenAI — stesso endpoint e stessa chiamata SDK (client.images.generate) dell'API immagini di OpenAI, instradata sui modelli immagine di OpenAI, Google, Alibaba e ByteDance dietro un'unica chiave API.

Corpo della richiesta

Modelli disponibili

La disponibilità dei modelli dipende dal tuo deployment. Recupera l'elenco aggiornato e filtrato per conformità tramite GET /v1/images/models. Un insieme rappresentativo:

Non sai quale modello scegliere? Scegli in base a ciò che ti serve

Price: token · $in→$out /1M = fatturato in base all'uso (OpenAI / Google); $/image = tariffa fissa per immagine generata. Response: i modelli b64 · url ✓ possono anche restituire un URL pre-firmato ospitato dal fornitore (response_format: "url", valido ~24 h). La velocità di download dipende dal fornitore: gli URL di Alibaba passano per una CDN accelerata a livello globale (veloce ovunque, inclusa la Cina continentale); gli URL seedream di ByteDance sono serviti da object storage a Singapore (veloce per i client esteri, lento dalla Cina continentale). I modelli b64 only rifiutano response_format: "url" con 400 url_not_supported. Edit (i2i) = ogni modello supporta image-to-image (invia il campo image); il valore è il numero massimo di immagini di riferimento.

Image-to-image (modifica)

Aggiungi un campo image alla stessa richiesta per modificare o usare come riferimento un'immagine di input. Supportato su gpt-image, gemini-*-image, qwen-image / wan2.7 e seedream (ogni modello limita quante immagini di input accetta). Invia l'immagine come base64 o data URI; passa un array per più riferimenti.

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

Formato della risposta

Imposta response_format: b64_json restituisce i byte dell'immagine in base64 (predefinito); url restituisce un URL scaricabile dove l'upstream lo supporta. La risposta corrisponde all'API immagini di OpenAI: { created, data: [{ b64_json | url }] }.

url è supportato solo dove l'upstream stesso restituisce un URL CDN — attualmente le famiglie Alibaba e ByteDance (qwen-image*, wan*, seedream*); l'immagine si scarica dalla CDN del vendor tramite un URL pre-firmato valido ~24 ore. I modelli OpenAI e Google (gpt-image*, gemini*) sono solo b64: richiedere url lì restituisce 400 url_not_supported — rifiutata prima della generazione, senza alcun addebito. Verifica per modello tramite il campo supports_url di GET /v1/images/models, oppure nella tabella dei modelli qui sopra.

Esempio completo — modalità url

Genera con response_format: "url", leggi data[0].url dalla risposta, poi scarica l'immagine dalla CDN del vendor — un giro completo che puoi incollare in un terminale:

# 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..."

L'URL è pre-firmato — chiunque lo abbia può scaricare, senza header di autenticazione — e scade in ~24 ore: scaricalo subito e ri-ospita il file se ti serve a lungo termine. Tempo tipico end-to-end: ~15–30 s di generazione + download dalla CDN sotto il secondo.

Latenza, risposte grandi e timeout

Il tempo di generazione varia per modello: qwen-image-2.0 risponde tipicamente in ~5–10 s, mentre wan2.7-image e i modelli di classe seedream richiedono ~15–30 s (di più a dimensioni 2K+). Il gateway consente fino a 180 s per richiesta e oltre restituisce 504 generation_timeout — questa API di per sé non restituisce mai 408.

Il response_format=b64_json predefinito incorpora l'immagine completa nel corpo della risposta (2–3 MB di base64 per i modelli grandi). Su collegamenti client lenti o a lunga distanza, scaricare quel corpo può richiedere minuti e far scattare il timeout del tuo client HTTP o del gateway intermedio — che sul tuo lato appare tipicamente come 408 o errore di timeout.

Fatturazione

Fatturato solo in caso di successo (HTTP 200). La maggior parte dei modelli è addebitata per immagine (numero × prezzo unitario); i modelli OpenAI gpt-image-* che restituiscono l'utilizzo in token sono addebitati per token. Ogni addebito è registrato con request_id, modello e costo per la tracciabilità.

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

Esempio — Python (SDK OpenAI)

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)

Esempio — Node (SDK OpenAI)

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

Idempotenza

Passa un header X-Idempotency-Key per rendere sicuri i retry: una richiesta ripetuta con la stessa chiave restituisce 409 invece di generare (e fatturare) una seconda volta. La generazione di immagini è lenta e soggetta a retry, quindi questo evita addebiti doppi.