Synchrone und asynchrone Anfragen
Zwei Wege, die Bild-API aufzurufen: in einer Anfrage auf das Bild warten, oder async true senden, sofort eine Task-ID erhalten und Tasks per Abfrage oder Webhook lesen.
Es gibt zwei Wege, ein Bild zu erstellen. Sie nehmen dieselben Parameter, kosten gleich viel und teilen dieselben Limits; wählen Sie pro Anfrage.
| Synchron (Standard) | Asynchron | |
|---|---|---|
| Vorgehen | Anfrage senden und warten | async: true hinzufügen, sofort eine Task-ID erhalten |
| Die Antwort kommt | In derselben Antwort, nach 20 Sekunden bis einigen Minuten | Später: Sie fragen ab, oder wir rufen Ihren Webhook auf |
| Verbindung offen gehalten | Bis das Bild fertig ist | Unter einer Sekunde |
| Längste Laufzeit | 7 Minuten | 10 Minuten |
| Liefert | Bilddaten (b64_json) oder einen Link (url) | Einen Link (url) |
| Funktioniert mit | Den OpenAI-SDKs und jedem Tool für die OpenAI Images API | Jedem HTTP-Client |
| Gut für | Skripte, Back-Ends, ein Bild nach dem anderen | Webseiten, viele Bilder auf einmal, langsame Modelle, Serverless-Funktionen mit kurzen Zeitlimits |
Die drei Aufrufe
| Aufruf | Was er bewirkt |
|---|---|
POST /v1/images/generations oder /v1/images/edits mit async: true | Startet einen Task. Antwortet mit 202 und der Task-ID |
GET /v1/images/tasks?ids=a,b,c | Der Zustand von bis zu 100 Tasks in einer Anfrage |
GET /v1/images/tasks/{id} | Der Zustand eines Tasks |
1. Einen Task starten
Fügen Sie async: true dem Body von POST /v1/images/generations hinzu oder als Formularfeld bei 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}'Die Antwort ist 202 Accepted, in deutlich unter einer Sekunde:
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "in_progress",
"created": 1795062073,
"finished": null,
"model": "gpt-image-2.6"
}Behalten Sie die id. Drei Dinge sollten Sie wissen:
- Nur Links. Die Bilder eines Tasks werden als Links zurückgegeben, lassen Sie
response_formatalso weg oder setzen Sie es aufurl.b64_jsonwird mit400abgelehnt. - Fehlerhafte Anfragen scheitern hier, nicht später. Ein falscher Parameter (
400), zu wenige Credits (402) oder zu viele Anfragen (429) werden sofort beantwortet, wie bei einer synchronen Anfrage. Es wird kein Task erstellt. - Kein Feld im Body? Der Header
Prefer: respond-asyncbewirkt dasselbe wieasync: true.
2. Die Tasks lesen
Mehrere Tasks in einer Anfrage
Wenn Sie auf mehr als einen Task warten, fragen Sie alle auf einmal ab. Eine Seite, die 10 Tasks gestartet hat, sendet eine Abfrage, nicht 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": []
}idsnimmt bis zu 100 Task-IDs, durch Kommas getrennt.dataenthält die Tasks in der Reihenfolge, in der Sie sie angefragt haben.- Eine ID, die kein Task Ihres Kontos ist oder deren Bilder nicht mehr gespeichert werden, steht in
not_found. Sie lässt die Anfrage nicht fehlschlagen.
Ein Task
curl https://api.cheapestimagen.com/v1/images/tasks/req_33ac10d3e9a8e6f120f4c0d3 \
-H "Authorization: Bearer YOUR_KEY"Die Antwort ist das Task-Objekt allein. Eine unbekannte ID antwortet mit 404.
Was ein Task aussagt
status | Bedeutung | Zusätzliches Feld |
|---|---|---|
in_progress | Das Bild wird erstellt | keines |
succeeded | Fertig | result: genau das, was der synchrone Aufruf zurückgegeben hätte, { created, data: [{ url }] } |
failed | Es hat nicht geklappt | error: genau der Fehler, den der synchrone Aufruf zurückgegeben hätte |
Ein fehlgeschlagener Task sieht so aus:
{
"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" }
}Ein fehlgeschlagener Task wird nicht berechnet. Die einzige Ausnahme ist dieselbe wie bei synchronen Anfragen: eine Ablehnung auf den Stable-Kanälen von Nano Banana.
Wie oft abfragen
Alle 2 bis 5 Sekunden genügt. Das Lesen von Tasks ist kostenlos und keine Bildanfrage: Es zählt nicht zu den laufenden Anfragen. Ein Task lässt sich 72 Stunden lang lesen, solange seine Bilder gespeichert sind.
Beispiel: eine Webseite, die 10 Bilder startet
Eine Anfrage pro Bild zum Starten, dann alle 3 Sekunden eine Anfrage für alle.
const API = "https://api.cheapestimagen.com/v1";
const headers = { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" };
// 10 Tasks starten.
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())
));
// Alle mit einer Anfrage abfragen, bis keiner mehr läuft.
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);
}Legen Sie Ihren API-Schlüssel nicht in eine öffentliche Webseite. Rufen Sie die API von Ihrem eigenen Server aus auf und lassen Sie die Seite mit diesem sprechen.
Beispiel: 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"])Mit dem OpenAI-SDK übergeben Sie das Feld über extra_body={"async": True} und lesen die Tasks mit einer einfachen HTTP-Anfrage.
Webhook statt Abfragen
Fügen Sie webhook_url hinzu, und wir senden den fertigen Task per POST dorthin:
{ "model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true, "webhook_url": "https://example.com/hooks/images" }- Die Adresse muss
https://auf einem öffentlichen Hostnamen sein. - Der Body ist das Task-Objekt, dasselbe JSON wie bei
GET /v1/images/tasks/{id}. - Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen
2xx. Andernfalls versuchen wir es noch zweimal, nach 3 und 15 Sekunden, und hören dann auf. - Damit der Aufruf signiert wird, senden Sie mit der Anfrage ein eigenes Geheimnis als
webhook_secret(16 bis 128 Zeichen). Ohne es ist der Aufruf nicht signiert: Behandeln Sie ihn als Hinweis, entnehmen Sie ihm dieidund lesen Sie den Task mit Ihrem Schlüssel, bevor Sie dem Inhalt vertrauen. - Der Task bleibt lesbar, ob der Webhook ankam oder nicht, ein verpasster Aufruf geht also nicht verloren.
Die Signatur prüfen
Mit webhook_secret trägt der Aufruf den Header x-webhook-signature: t=1763560000,v1=5f2b…. t ist der Zeitpunkt des Aufrufs in Unix-Sekunden, und v1 ist der HMAC-SHA256, hexadezimal, des Textes <t>.<body>, gebildet mit Ihrem Geheimnis. Berechnen Sie denselben Wert aus dem rohen Request-Body und vergleichen Sie; lehnen Sie Aufrufe ab, deren t mehr als einige Minuten alt ist.
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;
}Verwenden Sie den Body genau so, wie er ankam, vor jedem JSON-Parsing. Das Geheimnis wird für diese eine Anfrage verwendet und nicht bei Ihrem Konto gespeichert.
Limits
Eine asynchrone Anfrage zählt wie eine synchrone: 300 Anfragen pro Minute und 50 laufende pro Konto. Eine Anfrage, die gesendet wird, während 50 laufen, wird mit 429 abgelehnt; warten Sie, bis eine fertig ist. Das Lesen von Tasks wird nicht gezählt.
Idempotency-Key funktioniert genauso: Solange eine Anfrage mit diesem Schlüssel läuft oder nachdem sie erfolgreich war, antwortet eine Wiederholung mit 409.
Seitenverhältnisse und Größen
Die Bildgrößen, die Sie im Feld size der Cheapest Imagen API übergeben können: bis zu 19 Seitenverhältnisse in 1K, 2K und 4K sowie eigene Größen.
Rate Limits und Massenerstellung
Die Limits der Cheapest Imagen API (300 pro Minute, 50 gleichzeitig), was ein 429 bedeutet und wie Sie Tausende Bilder mit Wiederholungen ohne Doppelabrechnung erstellen.