Generación de imágenes

POST /v1/images/generations

Genera imágenes a partir de un prompt de texto. Compatible con OpenAI — el mismo endpoint y la misma llamada del SDK (client.images.generate) que la API de imágenes de OpenAI, enrutado entre los modelos de imágenes de OpenAI, Google, Alibaba y ByteDance con una sola API key.

Cuerpo de la solicitud

Modelos disponibles

La disponibilidad de modelos depende de tu despliegue. Obtén la lista en vivo y consciente del cumplimiento mediante GET /v1/images/models. Un conjunto representativo:

¿No sabes qué modelo elegir? Elige según lo que necesites

Price: token · $in→$out /1M = facturado por uso (OpenAI / Google); $/image = tarifa fija por imagen generada. Response: los modelos b64 · url ✓ también pueden devolver una URL prefirmada alojada por el proveedor (response_format: "url", válida ~24 h). La velocidad de descarga depende del proveedor: las URL de Alibaba usan una CDN acelerada globalmente (rápida en todas partes, incluida China continental); las URL seedream de ByteDance se sirven desde almacenamiento de objetos en Singapur (rápida para clientes en el extranjero, lenta desde China continental). Los modelos b64 only rechazan response_format: "url" con 400 url_not_supported. Edit (i2i) = cada modelo admite imagen a imagen (envía el campo image); el valor es el número máximo de imágenes de referencia.

Imagen a imagen (edición)

Añade un campo image a la misma solicitud para editar o tomar como referencia una imagen de entrada. Compatible con gpt-image, gemini-*-image, qwen-image / wan2.7 y seedream (cada modelo limita cuántas imágenes de entrada acepta). Envía la imagen como base64 o como data URI; pasa un array para varias referencias.

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 de respuesta

Establece response_format: b64_json devuelve los bytes de la imagen en base64 (predeterminado); url devuelve una URL descargable donde el proveedor upstream lo admita. La respuesta coincide con la API de imágenes de 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.

Facturación

Se factura solo en caso de éxito (HTTP 200). La mayoría de los modelos se cobran por imagen (cantidad × precio unitario); los modelos gpt-image-* de OpenAI que devuelven uso de tokens se cobran por token. Cada cargo se registra con request_id, modelo y coste para su trazabilidad.

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

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

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

Idempotencia

Pasa un X-Idempotency-Key para que los reintentos sean seguros: una solicitud repetida con la misma clave devuelve 409 en lugar de generar (y facturar) por segunda vez. La generación de imágenes es lenta y propensa a reintentos, por lo que esto evita cargos duplicados.