Zum Inhalt springen
Cheapest Imagen
Anleitungen

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
VorgehenAnfrage senden und wartenasync: true hinzufügen, sofort eine Task-ID erhalten
Die Antwort kommtIn derselben Antwort, nach 20 Sekunden bis einigen MinutenSpäter: Sie fragen ab, oder wir rufen Ihren Webhook auf
Verbindung offen gehaltenBis das Bild fertig istUnter einer Sekunde
Längste Laufzeit7 Minuten10 Minuten
LiefertBilddaten (b64_json) oder einen Link (url)Einen Link (url)
Funktioniert mitDen OpenAI-SDKs und jedem Tool für die OpenAI Images APIJedem HTTP-Client
Gut fürSkripte, Back-Ends, ein Bild nach dem anderenWebseiten, viele Bilder auf einmal, langsame Modelle, Serverless-Funktionen mit kurzen Zeitlimits

Die drei Aufrufe

AufrufWas er bewirkt
POST /v1/images/generations oder /v1/images/edits mit async: trueStartet einen Task. Antwortet mit 202 und der Task-ID
GET /v1/images/tasks?ids=a,b,cDer 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_format also weg oder setzen Sie es auf url. b64_json wird mit 400 abgelehnt.
  • 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-async bewirkt dasselbe wie async: 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": []
}
  • ids nimmt bis zu 100 Task-IDs, durch Kommas getrennt.
  • data enthä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

statusBedeutungZusätzliches Feld
in_progressDas Bild wird erstelltkeines
succeededFertigresult: genau das, was der synchrone Aufruf zurückgegeben hätte, { created, data: [{ url }] }
failedEs hat nicht geklappterror: 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 die id und 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"])) < 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;
}

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.

Auf dieser Seite