Eine KI-Bild-API in die Pipeline einer Agentur einbinden: Schlüssel, Buchführung und Archiv

Die API-Referenz zeigt dir, wie du ein Bild erzeugst. Eine Agentur hat ein anderes Problem: Tausende Bilder, ein Dutzend Kunden, drei Leute, die Knöpfe drücken, und eine Person in der Buchhaltung, die am Monatsende fragt, wer was verbraucht hat. Nichts davon ist schwer, aber jeder Teil lässt sich in der ersten Woche leicht falsch machen. Hier sind sechs Regeln, jede abgeleitet aus dem, was die API tatsächlich tut, nicht aus dem, was wir uns wünschen würden. Wenn du noch keine erste Anfrage gestellt hast, fang mit der API-Einführung an.

Regel 1: ein Schlüssel pro Kunde, eine Geldbörse dahinter

Schlüssel werden in der API Console angelegt, jeder mit einem Namen, und der vollständige Schlüssel wird genau einmal angezeigt. Benenne sie nach deinen Kunden. Ein Schlüssel, der geleakt ist, oder ein Vertrag, der endet, wird einzeln widerrufen, und die anderen funktionieren weiter. Was Schlüssel nicht tun: das Geld aufteilen. Jeder Schlüssel des Kontos verbraucht dasselbe Coin-Guthaben. Wenn sich zwei Kunden nie ein Guthaben teilen dürfen, sind das zwei Konten, und Coins lassen sich nachträglich nicht zwischen Konten verschieben.

Regel 2: deine Buchführung, verknüpft über deine Job-ID

Der Listen-Endpunkt liefert das ganze Konto, Studio-Bilder eingeschlossen, nicht die Arbeit eines einzelnen Schlüssels. Führe also deine eigene Buchführung: Kunde, Job, Generierungs-ID, berechnete Coins. Am saubersten verknüpfst du das über den Header Idempotency-Key. Bau ihn aus deiner eigenen Job-ID, dann liefert eine nach einem Verbindungsabbruch wiederholte Anfrage die bereits vorhandene Generierung zurück, statt ein zweites Mal zu berechnen. Gib ihm ein Präfix, das nur deine Agentur nutzt, ein Zufallsstring reicht, denn der Schlüssel wird im gesamten Dienst geprüft, nicht nur in deinem Konto.

POST /v1/api/images
Authorization: Bearer fk_live_key_for_client_a
Idempotency-Key: 7f1c2b90-client-a-deck-0042

{
  "prompt": "a linen shirt on a wooden hanger, soft window light",
  "quality": "standard",
  "aspectRatio": "4:5"
}

Die Antwort ist ein 202 mit der ID der Generierung und coinsCharged; schreib beides in die Buchführung, bevor du irgendetwas anderes tust.

Regel 3: pollen statt warten

Eine Generierung landet in einer Warteschlange und läuft im Hintergrund. Frag ihren Status in gemächlichem Abstand ab (solange sie wartet, enthält die Antwort eine Schätzung in etaMs) und starte mehrere Jobs gleichzeitig statt nacheinander: Die API erlaubt pro Konto mehr parallele Jobs als das Studio, weil das ihr normaler Betrieb ist.

GET /v1/api/images/{id}          -> "queued", "generating", then "succeeded",
                                    or "failed" / "refunded" with refunded: true
GET /v1/api/images/{id}/content  -> the bytes, until the retention window ends
                                    (after that: 410 BYTES_EXPIRED)

Regel 4: Fehler sind Daten

Eine fehlgeschlagene Generierung erstattet ihre Coins automatisch und meldet das in refunded. Ihr failureCode stammt aus einer kurzen, festen Liste: TIMEOUT und VENDOR_ERROR sind einen späteren Wiederholungsversuch wert, MODERATION_REJECTED heißt, dass der Prompt umgeschrieben statt wiederholt werden muss, und UNKNOWN deckt den Rest ab. Halte den Code in deiner Buchführung fest; ein Kunde, dessen Briefing immer wieder an der Moderation scheitert, braucht ein Gespräch, keine Wiederholungsschleife. Die Ökonomie der Wiederholungen steht in dem Artikel über Preise und Fehler.

Regel 5: archivieren, sobald es geklappt hat

Die API ist keine Asset-Bibliothek. Fertige Dateien werden gelöscht, wenn die Aufbewahrungsfrist auf der Produktseite endet, und danach antwortet die Inhaltsanfrage mit 410 BYTES_EXPIRED. Lade jedes erfolgreiche Bild sofort in deinen eigenen Speicher, abgelegt unter Kunde und Job aus deiner Buchführung, und wenn ein Kunde nicht möchte, dass wir seine Bilder überhaupt aufbewahren, lösch sie nach dem Archivieren über die API.

Regel 6: Limits per Code prüfen und vor der Auslieferung einen Menschen draufschauen lassen

Jeder Schlüssel hat eine Anfragerate, und das Konto hat ein tägliches Bildkontingent. Beides liefert ein einziger Aufruf, sodass ein Batch-Job vor dem Start prüfen kann, statt auf halbem Weg zu scheitern:

GET /v1/api/me
-> { "keyName": "client-a", "coins": ..., "rateLimitPerMin": ..., "dailyImagesRemaining": ... }

Die Zahlen selbst stehen auf der Produktseite. Und bevor irgendetwas bei einem Kunden ankommt, schaut jemand drauf. Ein Modell kann einer Hand sechs Finger verpassen oder ein falsches Wort auf ein Schild setzen, und eine automatisierte Pipeline liefert das genauso schnell aus wie ein gutes Bild.

Was die API für eine Agentur nicht übernimmt

Sie hat keine Unterkonten, keine Guthaben pro Kunde und keinen Nutzungsbericht pro Schlüssel: Diese Buchhaltung liegt bei dir. Es gibt kein Service Level Agreement und keine garantierte Lieferzeit, also versprich einem Kunden keine Minuten, die du nicht gemessen hast. Ein generiertes Bild wird dadurch nicht im urheberrechtlichen Sinn deins, wie wem KI-Bilder gehören erklärt, auch wenn die kommerzielle Nutzung erlaubt ist und wir keinen Anteil nehmen. Und das Gesicht einer echten Person braucht weiterhin die Erlaubnis dieser Person, egal auf welchem Weg die Anfrage kommt.

Wie du die Coins für all das budgetierst, steht in was ein Team wirklich ausgibt, und das Studio für die von Hand gemachten Bilder ist Fellowi Images.