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 | |
|---|---|---|
| Principe | Envoyer la requête et attendre | Ajouter async: true, obtenir tout de suite un identifiant de tâche |
| La réponse arrive | Dans la même réponse, après 20 secondes à quelques minutes | Plus tard : vous interrogez, ou nous appelons votre webhook |
| Connexion maintenue ouverte | Jusqu’à ce que l’image soit prête | Moins d’une seconde |
| Durée maximale | 7 minutes | 10 minutes |
| Renvoie | Les données de l’image (b64_json) ou un lien (url) | Un lien (url) |
| Fonctionne avec | Les SDK OpenAI et tout outil conçu pour l’API OpenAI Images | Tout client HTTP |
| Convient pour | Scripts, back-ends, une image à la fois | Pages web, nombreuses images à la fois, modèles lents, fonctions serverless à durée limitée |
Les trois appels
| Appel | Rôle |
|---|---|
POST /v1/images/generations or /v1/images/edits with async: true | Démarre une tâche. Répond 202 avec l’identifiant de la tâche |
GET /v1/images/tasks?ids=a,b,c | L’é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_formatou mettez-le àurl.b64_jsonest refusé avec une erreur400. - 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-asyncfait la même chose queasync: 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": []
}idsaccepte jusqu’à 100 identifiants de tâche, séparés par des virgules.datacontient 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
status | Signification | Champ supplémentaire |
|---|---|---|
in_progress | L’image est en cours de création | aucun |
succeeded | Terminé | result : exactement ce que l’appel synchrone aurait renvoyé, { created, data: [{ url }] } |
failed | Cela 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
2xxquelconque 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’idet 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"])) < 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;
}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.
Formats et tailles
Les tailles d’image que vous pouvez passer dans le champ size de l’API Cheapest Imagen : jusqu’à 19 formats en 1K, 2K et 4K, et des tailles personnalisées.
Limites de débit et génération en masse
Les limites de l’API Cheapest Imagen (300 par minute, 50 à la fois), ce que signifie une erreur 429, et comment générer des milliers d’images sans double facturation.