Aller au contenu
Cheapest Imagen
Guides

Requêtes synchrones et asynchrones

Deux façons d’appeler l’API d’images : attendre l’image dans une requête, ou envoyer async true, obtenir un identifiant de tâche et le lire par interrogation ou webhook.

Il y a deux façons de créer une image. Elles prennent les mêmes paramètres, coûtent le même prix et partagent les mêmes limites ; choisissez à chaque requête.

Synchrone (par défaut)Asynchrone
PrincipeEnvoyer la requête et attendreAjouter async: true, obtenir tout de suite un identifiant de tâche
La réponse arriveDans la même réponse, après 20 secondes à quelques minutesPlus tard : vous interrogez, ou nous appelons votre webhook
Connexion maintenue ouverteJusqu’à ce que l’image soit prêteMoins d’une seconde
Durée maximale7 minutes10 minutes
RenvoieLes données de l’image (b64_json) ou un lien (url)Un lien (url)
Fonctionne avecLes SDK OpenAI et tout outil conçu pour l’API OpenAI ImagesTout client HTTP
Convient pourScripts, back-ends, une image à la foisPages web, nombreuses images à la fois, modèles lents, fonctions serverless à durée limitée

Les trois appels

AppelRôle
POST /v1/images/generations or /v1/images/edits with async: trueDémarre une tâche. Répond 202 avec l’identifiant de la tâche
GET /v1/images/tasks?ids=a,b,cL’état de 100 tâches au plus en une requête
GET /v1/images/tasks/{id}L’état d’une tâche

1. Démarrer une tâche

Ajoutez async: true au corps de POST /v1/images/generations, ou comme champ de formulaire sur 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}'

La réponse est 202 Accepted, en bien moins d’une seconde :

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

Conservez l’id. Trois choses à savoir :

  • Liens uniquement. Les images d’une tâche sont renvoyées sous forme de liens, donc omettez response_format ou mettez-le à url. b64_json est refusé avec une erreur 400.
  • Les requêtes invalides échouent ici, pas plus tard. Un mauvais paramètre (400), des crédits insuffisants (402) ou trop de requêtes (429) reçoivent une réponse immédiate, comme avec une requête synchrone. Aucune tâche n’est créée.
  • Pas de champ dans le corps ? L’en-tête Prefer: respond-async fait la même chose que async: true.

2. Lire les tâches

Plusieurs tâches en une requête

Quand vous attendez plus d’une tâche, demandez-les toutes en une fois. Une page qui a démarré 10 tâches envoie une seule requête d’interrogation, pas 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 accepte jusqu’à 100 identifiants de tâche, séparés par des virgules.
  • data contient les tâches dans l’ordre où vous les avez demandées.
  • Un identifiant qui n’est pas une tâche de votre compte, ou dont les images ne sont plus conservées, figure dans not_found. Cela ne fait pas échouer la requête.

Une seule tâche

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

La réponse est l’objet de la tâche seul. Un identifiant inconnu répond 404.

Ce que dit une tâche

statusSignificationChamp supplémentaire
in_progressL’image est en cours de créationaucun
succeededTerminéresult : exactement ce que l’appel synchrone aurait renvoyé, { created, data: [{ url }] }
failedCela n’a pas fonctionnéerror : exactement l’erreur que l’appel synchrone aurait renvoyée

Une tâche échouée ressemble à ceci :

{
  "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" }
}

Une tâche échouée n’est pas facturée. La seule exception est la même que pour les requêtes synchrones : un refus sur les canaux stables Nano Banana.

À quelle fréquence interroger

Toutes les 2 à 5 secondes suffisent. Lire des tâches est gratuit et ne compte pas comme une requête d’image : cela n’entre pas dans les requêtes en cours. Une tâche peut être lue pendant 72 heures, tant que ses images sont conservées.

Exemple : une page web qui lance 10 images

Une requête par image pour les lancer, puis une requête toutes les 3 secondes pour l’ensemble.

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

// Démarrer 10 tâches.
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())
));

// Les interroger toutes avec une seule requête jusqu’à ce qu’aucune ne soit en cours.
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);
}

Ne mettez pas votre clé API dans une page web publique. Appelez l’API depuis votre propre serveur et laissez la page s’adresser à celui-ci.

Exemple : 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"])

Avec le SDK OpenAI, passez le champ via extra_body={"async": True} et lisez les tâches avec une simple requête HTTP.

Webhook au lieu de l’interrogation

Ajoutez webhook_url et nous envoyons la tâche terminée par POST à cette adresse :

{ "model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true, "webhook_url": "https://example.com/hooks/images" }
  • L’adresse doit être en https:// sur un nom d’hôte public.
  • Le corps est l’objet de la tâche, le même JSON que GET /v1/images/tasks/{id}.
  • Répondez par un code 2xx quelconque dans les 10 secondes. Sinon, nous réessayons deux fois, après 3 et 15 secondes, puis nous arrêtons.
  • Pour que l’appel soit signé, envoyez avec la requête un secret de votre choix dans webhook_secret (16 à 128 caractères). Sans lui, l’appel n’est pas signé : considérez-le comme une simple notification, prenez-en l’id et lisez la tâche avec votre clé avant de faire confiance au contenu.
  • La tâche reste lisible que le webhook soit arrivé ou non, donc un appel manqué ne fait rien perdre.

Vérifier la signature

Avec webhook_secret, l’appel porte l’en-tête x-webhook-signature: t=1763560000,v1=5f2b…. t est l’heure de l’appel en secondes Unix, et v1 est le HMAC-SHA256, en hexadécimal, du texte <t>.<body> calculé avec votre secret. Calculez la même valeur à partir du corps brut de la requête et comparez ; refusez les appels dont le t date de plus de quelques minutes.

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;
}

Utilisez le corps exactement tel qu’il est arrivé, avant tout traitement JSON. Le secret sert pour cette seule requête et n’est pas conservé avec votre compte.

Limites

Une requête asynchrone compte comme une requête synchrone : 300 requêtes par minute et 50 en cours par compte. Une requête envoyée alors que 50 sont en cours est refusée avec 429 ; attendez qu’une se termine. La lecture des tâches n’est pas comptée.

Idempotency-Key fonctionne de la même façon : tant qu’une requête avec cette clé est en cours, ou après son succès, une répétition répond 409.

Sur cette page