Pular para o conteúdo
Cheapest Imagen
Guias

Requisições síncronas e assíncronas

Duas formas de chamar a API de imagens: espere a imagem em uma requisição, ou envie async true, receba um id de tarefa na hora e consulte tarefas ou use um webhook.

Há duas formas de gerar uma imagem. Elas aceitam os mesmos parâmetros, custam o mesmo e têm os mesmos limites; escolha a cada requisição.

Síncrona (padrão)Assíncrona
ComoEnvie a requisição e espereAdicione async: true e receba um id de tarefa na hora
A resposta chegaNa própria resposta, depois de 20 segundos a alguns minutosDepois: você consulta, ou chamamos o seu webhook
Conexão abertaAté a imagem ficar prontaMenos de um segundo
Duração máxima7 minutos10 minutos
DevolveDados da imagem (b64_json) ou um link (url)Um link (url)
Funciona comOs SDKs da OpenAI e qualquer ferramenta feita para a API de Imagens da OpenAIQualquer cliente HTTP
Bom paraScripts, back-ends, uma imagem por vezPáginas web, muitas imagens de uma vez, modelos lentos, funções serverless com limite curto de tempo

As três chamadas

ChamadaO que faz
POST /v1/images/generations or /v1/images/edits with async: trueInicia uma tarefa. Responde 202 com o id da tarefa
GET /v1/images/tasks?ids=a,b,cO estado de até 100 tarefas em uma requisição
GET /v1/images/tasks/{id}O estado de uma tarefa

1. Inicie uma tarefa

Adicione async: true ao corpo de POST /v1/images/generations, ou como campo de formulário em POST /v1/images/edits.

curl https://api.cheapestimagen.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true}'

A resposta é 202 Accepted, em bem menos de um segundo:

{
  "id": "req_33ac10d3e9a8e6f120f4c0d3",
  "object": "image.task",
  "status": "in_progress",
  "created": 1795062073,
  "finished": null,
  "model": "gpt-image-2.6"
}

Guarde o id. Três coisas para saber:

  • Só links. As imagens de uma tarefa são devolvidas como links, então deixe response_format de fora ou defina como url. b64_json é recusado com 400.
  • Requisições inválidas falham aqui, não depois. Um parâmetro errado (400), créditos insuficientes (402) ou requisições demais (429) são respondidos na hora, como numa requisição síncrona. Nenhuma tarefa é criada.
  • Sem campo no corpo? O cabeçalho Prefer: respond-async faz o mesmo que async: true.

2. Leia as tarefas

Várias tarefas em uma requisição

Quando você espera mais de uma tarefa, peça todas de uma vez. Uma página que iniciou 10 tarefas envia uma consulta, não 10.

curl "https://api.cheapestimagen.com/v1/images/tasks?ids=req_33ac10d3e9a8e6f120f4c0d3,req_26e50328772b7d62f59d355a" \
  -H "Authorization: Bearer YOUR_KEY"
{
  "object": "list",
  "data": [
    {
      "id": "req_33ac10d3e9a8e6f120f4c0d3",
      "object": "image.task",
      "status": "succeeded",
      "created": 1795062073,
      "finished": 1795062098,
      "model": "gpt-image-2.6",
      "result": {
        "created": 1795062098,
        "data": [{ "url": "https://img.cheapestimagen.com/g/req_33ac10d3e9a8e6f120f4c0d3/0.png" }]
      }
    },
    {
      "id": "req_26e50328772b7d62f59d355a",
      "object": "image.task",
      "status": "in_progress",
      "created": 1795062074,
      "finished": null,
      "model": "gpt-image-2.6"
    }
  ],
  "not_found": []
}
  • ids aceita até 100 ids de tarefa, separados por vírgula.
  • data traz as tarefas na ordem em que você as pediu.
  • Um id que não é uma tarefa da sua conta, ou cujas imagens não são mais guardadas, aparece em not_found. Isso não faz a requisição falhar.

Uma tarefa

curl https://api.cheapestimagen.com/v1/images/tasks/req_33ac10d3e9a8e6f120f4c0d3 \
  -H "Authorization: Bearer YOUR_KEY"

A resposta é só o objeto da tarefa. Um id desconhecido responde 404.

O que uma tarefa informa

statusSignificadoCampo extra
in_progressA imagem está sendo geradanenhum
succeededConcluídaresult: exatamente o que a chamada síncrona teria devolvido, { created, data: [{ url }] }
failedNão deu certoerror: exatamente o erro que a chamada síncrona teria devolvido

Uma tarefa que falhou fica assim:

{
  "id": "req_33ac10d3e9a8e6f120f4c0d3",
  "object": "image.task",
  "status": "failed",
  "created": 1795062073,
  "finished": 1795062110,
  "model": "gpt-image-2.6",
  "error": { "message": "The image provider failed. You were not charged.", "type": "api_error", "param": null, "code": "upstream_error" }
}

Uma tarefa que falhou não é cobrada. A única exceção é a mesma das requisições síncronas: uma recusa nos canais estáveis do Nano Banana.

Com que frequência consultar

De 2 em 2 a 5 em 5 segundos basta. Ler tarefas é grátis e não é uma requisição de imagem: não conta entre as requisições em andamento. Uma tarefa pode ser lida por 72 horas, enquanto as imagens forem guardadas.

Exemplo: uma página web que inicia 10 imagens

Uma requisição por imagem para iniciá-las, depois uma requisição a cada 3 segundos para todas.

const API = "https://api.cheapestimagen.com/v1";
const headers = { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" };

// Inicia 10 tarefas.
const prompts = Array.from({ length: 10 }, (_, i) => `a red fox in the snow, variation ${i + 1}`);
const started = await Promise.all(prompts.map((prompt) =>
  fetch(`${API}/images/generations`, {
    method: "POST", headers,
    body: JSON.stringify({ model: "gpt-image-2.6", prompt, async: true }),
  }).then((r) => r.json())
));

// Consulta todas com uma requisição até nenhuma estar em andamento.
let waiting = started.map((t) => t.id);
const done = {};
while (waiting.length) {
  await new Promise((r) => setTimeout(r, 3000));
  const { data } = await fetch(`${API}/images/tasks?ids=${waiting.join(",")}`, { headers }).then((r) => r.json());
  for (const task of data) if (task.status !== "in_progress") done[task.id] = task;
  waiting = waiting.filter((id) => !done[id]);
}

for (const task of Object.values(done)) {
  console.log(task.status === "succeeded" ? task.result.data[0].url : task.error.message);
}

Não coloque a sua chave de API em uma página web pública. Chame a API a partir do seu próprio servidor e deixe a página falar com ele.

Exemplo: Python

import time, requests

API = "https://api.cheapestimagen.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}

ids = [
    requests.post(f"{API}/images/generations", headers=HEADERS, json={
        "model": "gpt-image-2.6", "prompt": f"a red fox in the snow, variation {i}", "async": True,
    }).json()["id"]
    for i in range(10)
]

done = {}
while len(done) < len(ids):
    time.sleep(3)
    waiting = [i for i in ids if i not in done]
    tasks = requests.get(f"{API}/images/tasks", headers=HEADERS, params={"ids": ",".join(waiting)}).json()["data"]
    done.update({t["id"]: t for t in tasks if t["status"] != "in_progress"})

for t in done.values():
    print(t["result"]["data"][0]["url"] if t["status"] == "succeeded" else t["error"]["message"])

Com o SDK da OpenAI, passe o campo por extra_body={"async": True} e leia as tarefas com uma requisição HTTP comum.

Webhook em vez de consulta

Adicione webhook_url e enviamos um POST com a tarefa concluída para esse endereço:

{ "model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true, "webhook_url": "https://example.com/hooks/images" }
  • O endereço deve ser https://, em um nome de host público.
  • O corpo é o objeto da tarefa, o mesmo JSON de GET /v1/images/tasks/{id}.
  • Responda com qualquer 2xx em até 10 segundos. Caso contrário, tentamos mais duas vezes, após 3 e 15 segundos, e depois paramos.
  • Para que a chamada seja assinada, envie um segredo seu como webhook_secret (de 16 a 128 caracteres) junto com a requisição. Sem ele, a chamada não é assinada: trate-a como um aviso, pegue o id dela e leia a tarefa com a sua chave antes de confiar no conteúdo.
  • A tarefa continua legível, tenha o webhook chegado ou não, então uma chamada perdida não faz você perder nada.

Verifique a assinatura

Com webhook_secret, a chamada leva o cabeçalho x-webhook-signature: t=1763560000,v1=5f2b…. t é o horário da chamada em segundos Unix, e v1 é o HMAC-SHA256, em hexadecimal, do texto <t>.<body> feito com o seu segredo. Calcule o mesmo valor a partir do corpo bruto da requisição e compare; recuse chamadas cujo t tenha mais do que alguns minutos.

import hashlib, hmac, time

def is_ours(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300
import { createHmac, timingSafeEqual } from 'node:crypto';

function isOurs(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}

Use o corpo exatamente como chegou, antes de qualquer interpretação do JSON. O segredo é usado só para essa requisição e não fica guardado na sua conta.

Limites

Uma requisição assíncrona conta como uma síncrona: 300 requisições por minuto e 50 em andamento por conta. Uma requisição enviada enquanto 50 estão rodando é recusada com 429; espere uma terminar. A leitura de tarefas não conta.

Idempotency-Key funciona do mesmo jeito: enquanto uma requisição com essa chave está em andamento, ou depois de ter dado certo, uma repetição responde 409.

Nesta página