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 | |
|---|---|---|
| Como | Envie a requisição e espere | Adicione async: true e receba um id de tarefa na hora |
| A resposta chega | Na própria resposta, depois de 20 segundos a alguns minutos | Depois: você consulta, ou chamamos o seu webhook |
| Conexão aberta | Até a imagem ficar pronta | Menos de um segundo |
| Duração máxima | 7 minutos | 10 minutos |
| Devolve | Dados da imagem (b64_json) ou um link (url) | Um link (url) |
| Funciona com | Os SDKs da OpenAI e qualquer ferramenta feita para a API de Imagens da OpenAI | Qualquer cliente HTTP |
| Bom para | Scripts, back-ends, uma imagem por vez | Páginas web, muitas imagens de uma vez, modelos lentos, funções serverless com limite curto de tempo |
As três chamadas
| Chamada | O que faz |
|---|---|
POST /v1/images/generations or /v1/images/edits with async: true | Inicia uma tarefa. Responde 202 com o id da tarefa |
GET /v1/images/tasks?ids=a,b,c | O 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_formatde fora ou defina comourl.b64_jsoné recusado com400. - 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-asyncfaz o mesmo queasync: 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": []
}idsaceita até 100 ids de tarefa, separados por vírgula.datatraz 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
status | Significado | Campo extra |
|---|---|---|
in_progress | A imagem está sendo gerada | nenhum |
succeeded | Concluída | result: exatamente o que a chamada síncrona teria devolvido, { created, data: [{ url }] } |
failed | Não deu certo | error: 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
2xxem 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 oiddela 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"])) < 300import { 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.
Proporções e tamanhos
Os tamanhos de imagem que você pode passar no campo size da API do Cheapest Imagen: até 19 proporções em 1K, 2K e 4K, e tamanhos personalizados.
Limites de uso e geração em lote
Os limites da API do Cheapest Imagen (300 por minuto, 50 ao mesmo tempo), o que significa um 429 e como gerar milhares de imagens com novas tentativas sem cobrança dupla.