Geração de imagens

POST /v1/images/generations

Gere imagens a partir de um prompt de texto. Compatível com OpenAI — o mesmo endpoint e a mesma chamada de SDK (client.images.generate) da API de imagens da OpenAI, roteado entre os modelos de imagem da OpenAI, Google, Alibaba e ByteDance por trás de uma única chave de API.

Corpo da requisição

Modelos disponíveis

A disponibilidade dos modelos depende da sua implantação. Obtenha a lista ao vivo e ciente de conformidade via GET /v1/images/models. Um conjunto representativo:

Não sabe qual modelo escolher? Escolha conforme sua necessidade

Price: token · $in→$out /1M = cobrado por uso (OpenAI / Google); $/image = valor fixo por imagem gerada. Response: modelos b64 · url ✓ também podem retornar uma URL pré-assinada hospedada pelo fornecedor (response_format: "url", válida por ~24 h). A velocidade de download depende do fornecedor: as URLs da Alibaba usam um CDN acelerado globalmente (rápido em toda parte, incluindo a China continental); as URLs seedream da ByteDance são servidas a partir de armazenamento de objetos em Singapura (rápido para clientes no exterior, lento a partir da China continental). Modelos b64 only rejeitam response_format: "url" com 400 url_not_supported. Edit (i2i) = todo modelo suporta imagem para imagem (envie o campo image); o valor é o número máximo de imagens de referência.

Imagem para imagem (edição)

Adicione um campo image à mesma requisição para editar ou referenciar uma imagem de entrada. Suportado em gpt-image, gemini-*-image, qwen-image / wan2.7 e seedream (cada modelo limita quantas imagens de entrada aceita). Envie a imagem como base64 ou um data URI; passe um array para múltiplas referências.

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 da resposta

Defina response_format: b64_json retorna os bytes da imagem em base64 (padrão); url retorna uma URL acessível quando o provedor upstream suporta. A resposta corresponde à API de imagens da 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.

Cobrança

Cobrado apenas em caso de sucesso (HTTP 200). A maioria dos modelos é cobrada por imagem (quantidade × preço unitário); os modelos OpenAI gpt-image-* que retornam uso de tokens são cobrados por token. Cada cobrança é registrada com request_id, model e cost para rastreabilidade.

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

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

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

Idempotência

Passe um X-Idempotency-Key cabeçalho para tornar as novas tentativas seguras: uma requisição repetida com a mesma chave retorna 409 em vez de gerar (e cobrar) uma segunda vez. A geração de imagens é lenta e propensa a novas tentativas, então isso evita cobranças duplicadas.