Koppla ett AI-bild-API till byråns pipeline: nycklar, register och arkiv

API-referensen visar hur du gör en bild. En byrå har ett annat problem: tusentals bilder, ett dussin kunder, tre personer som trycker på knappar och en person på ekonomi som i slutet av månaden frågar vem som använde vad. Inget av det är svårt, men varje del är lätt att göra fel första veckan. Här är sex regler, var och en hämtad från hur API:et faktiskt beter sig snarare än hur vi önskar att det gjorde. Om du inte har gjort din första begäran än, börja med API-introduktionen.

Regel 1: en nyckel per kund, en plånbok bakom dem

Nycklar skapas i API Console, var och en med ett namn, och hela nyckeln visas exakt en gång. Döp dem efter kunder. En nyckel som läcker, eller ett avtal som tar slut, återkallas för sig och de andra fortsätter fungera. Det nycklar inte gör är att dela upp pengarna: varje nyckel på kontot spenderar samma myntsaldo. Om två kunder aldrig får dela saldo blir det två konton, och mynt kan inte flyttas mellan konton i efterhand.

Regel 2: ditt register, kopplat till ditt jobb-id

List-endpointen returnerar hela kontot, studiobilder inräknade, inte en enskild nyckels arbete. Så för ett eget register: kund, jobb, genererings-id, debiterade mynt. Det renaste sättet att knyta ihop dem är headern Idempotency-Key. Bygg den på ditt eget jobb-id, så returnerar ett omförsök efter en tappad anslutning den generering som redan finns i stället för att debitera en till. Ge den ett prefix som är unikt för din byrå, en slumpmässig sträng räcker, eftersom nyckeln kontrolleras i hela tjänsten och inte bara på ditt 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"
}

Svaret är en 202 med genereringens id och coinsCharged; skriv in båda i registret innan du gör något annat.

Regel 3: polla, vänta inte

En generering köas och körs i bakgrunden. Polla dess status med ett lugnt intervall (svaret innehåller en uppskattning i etaMs medan den står i kö), och skicka iväg flera jobb samtidigt i stället för ett i taget: API:et tillåter fler parallella jobb per konto än studion, eftersom det är så det normalt används.

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: behandla fel som data

En misslyckad generering återbetalar sina mynt automatiskt och säger det i refunded. Dess failureCode är en av en kort, fast lista: TIMEOUT och VENDOR_ERROR är värda ett nytt försök senare, MODERATION_REJECTED betyder att prompten behöver skrivas om snarare än upprepas, och UNKNOWN täcker resten. Spara koden i registret; en kund vars brief hela tiden ger moderationsfel behöver ett samtal, inte en omförsöksloop. Ekonomin bakom omförsök finns i inlägget om priser och fel.

Regel 5: arkivera i samma stund som det lyckas

API:et är inget tillgångsbibliotek. Färdiga filer raderas när lagringsperioden på produktsidan tar slut, och därefter svarar innehållsbegäran 410 BYTES_EXPIRED. Ladda ner varje lyckad bild till din egen lagring direkt, under kunden och jobbet från ditt register, och om en kund inte vill att vi sparar deras bilder alls, radera dem via API:et när de är arkiverade.

Regel 6: kontrollera gränserna i koden, och sätt en människa före leverans

Varje nyckel har en begärandegräns, och kontot har en daglig bildkvot. Båda rapporteras av ett enda anrop, så ett batchjobb kan kontrollera innan det startar i stället för att fallera halvvägs:

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

Själva siffrorna finns på produktsidan. Och innan något når en kund tittar någon på det. En modell kan sätta sex fingrar på en hand eller ett felaktigt ord på en skylt, och en automatiserad pipeline levererar det lika snabbt som en bra bild.

Vad API:et inte gör åt en byrå

Det finns inga underkonton, inga saldon per kund och ingen användningsrapport per nyckel: den bokföringen är din. Det finns inget servicenivåavtal och ingen garanterad leveranstid, så lova inte en kund minuter du inte har mätt. En genererad bild blir inte din i upphovsrättslig mening, som vem äger AI-bilder förklarar, även om kommersiell användning är tillåten och vi inte tar någon andel. Och en verklig persons ansikte kräver fortfarande den personens tillstånd, hur begäran än kommer in.

Hur du budgeterar mynten bakom allt detta tas upp i vad ett team faktiskt spenderar, och studion för de handgjorda bilderna är Fellowi Images.