Een AI-beeld-API in een bureaupipeline: sleutels, administratie en archieven

De API-referentie vertelt je hoe je één afbeelding maakt. Een bureau heeft een ander probleem: duizenden afbeeldingen, een tiental klanten, drie mensen die op knoppen drukken en één iemand van financiën die aan het eind van de maand vraagt wie wat heeft gebruikt. Niets daarvan is moeilijk, maar elk onderdeel is in de eerste week makkelijk fout te doen. Dit zijn zes regels, elk ontleend aan hoe de API zich echt gedraagt en niet aan hoe we zouden willen dat hij zich gedroeg. Heb je nog geen eerste verzoek gedaan, begin dan met de API-introductie.

Regel 1: één sleutel per klant, één portemonnee erachter

Sleutels maak je aan in de API Console, elk met een naam, en de volledige sleutel wordt precies één keer getoond. Noem ze naar klanten. Een gelekte sleutel, of een contract dat afloopt, trek je los in en de andere blijven werken. Wat sleutels niet doen is het geld opsplitsen: elke sleutel op het account besteedt hetzelfde coinsaldo. Mogen twee klanten nooit een saldo delen, dan zijn dat twee accounts, en coins kunnen achteraf niet tussen accounts worden verplaatst.

Regel 2: jouw administratie, gekoppeld aan jouw job-id

Het lijst-endpoint geeft het hele account terug, studiobeelden inbegrepen, niet het werk van één sleutel. Houd dus je eigen administratie bij: klant, job, generatie-id, afgerekende coins. De netste manier om die aan elkaar te knopen is de header Idempotency-Key. Bouw hem op uit je eigen job-id, en een herhaald verzoek na een verbroken verbinding geeft de generatie terug die al bestaat in plaats van een tweede af te rekenen. Geef hem een prefix die uniek is voor jouw bureau, een willekeurige string is genoeg, want de sleutel wordt over de hele dienst gecontroleerd, niet alleen binnen jouw account.

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

Het antwoord is een 202 met de id van de generatie en coinsCharged; schrijf beide in je administratie voordat je iets anders doet.

Regel 3: pollen, niet wachten

Een generatie komt in een wachtrij en draait op de achtergrond. Poll de status met een rustig interval (zolang hij in de wachtrij staat, bevat het antwoord een schatting in etaMs), en start meerdere jobs tegelijk in plaats van na elkaar: de API staat per account meer parallelle jobs toe dan de studio, omdat dat zijn normale vorm is.

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: behandel mislukkingen als data

Een mislukte generatie krijgt haar coins automatisch terug en meldt dat in refunded. Haar failureCode komt uit een korte, vaste lijst: TIMEOUT en VENDOR_ERROR zijn later één nieuwe poging waard, MODERATION_REJECTED betekent dat de prompt herschreven moet worden in plaats van herhaald, en UNKNOWN dekt de rest. Leg de code vast in je administratie; een klant wiens briefing steeds op moderatie strandt, vraagt om een gesprek, niet om een retry-lus. De economie van nieuwe pogingen staat in de post over prijzen en mislukkingen.

Regel 5: archiveer zodra het gelukt is

De API is geen assetbibliotheek. Klare bestanden worden verwijderd wanneer de bewaartermijn op de productpagina afloopt, en daarna antwoordt het content-verzoek met 410 BYTES_EXPIRED. Download elk gelukt beeld meteen naar je eigen opslag, onder de klant en job uit je administratie, en als een klant helemaal niet wil dat wij zijn beelden bewaren, verwijder ze dan via de API zodra ze gearchiveerd zijn.

Regel 6: controleer de limieten vanuit code, en zet een mens vóór de oplevering

Elke sleutel heeft een verzoeklimiet, en het account heeft een dagelijkse beeldtoelage. Beide komen terug uit één aanroep, dus een batchjob kan vooraf controleren in plaats van halverwege te falen:

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

De getallen zelf staan op de productpagina. En voordat iets bij een klant terechtkomt, kijkt er iemand naar. Een model kan zes vingers aan een hand zetten of een verkeerd woord op een bord, en een geautomatiseerde pipeline levert dat net zo snel op als een goed beeld.

Wat de API niet voor een bureau doet

Er zijn geen subaccounts, geen saldi per klant en geen gebruiksrapport per sleutel: die boekhouding is aan jou. Er is geen service level agreement en geen gegarandeerde levertijd, dus beloof een klant geen minuten die je niet zelf hebt gemeten. Een gegenereerd beeld wordt niet van jou in auteursrechtelijke zin, zoals van wie zijn AI-beelden uitlegt, ook al is commercieel gebruik toegestaan en nemen wij geen aandeel. En het gezicht van een echt persoon vraagt nog altijd om toestemming van die persoon, hoe het verzoek ook binnenkomt.

Het budgetteren van de coins achter dit alles staat in wat een team echt uitgeeft, en de studio voor de handgemaakte beelden is Fellowi Images.