Napojení API pro AI obrázky do pipeline agentury: klíče, evidence a archivy

Referenční dokumentace API ti řekne, jak udělat jeden obrázek. Agentura má jiný problém: tisíce obrázků, tucet klientů, tři lidi, kteří mačkají tlačítka, a jednoho člověka z financí, který se na konci měsíce ptá, kdo co spotřeboval. Nic z toho není těžké, ale v prvním týdnu se dá snadno pokazit každá část. Tady je šest pravidel, každé odvozené z toho, jak se API skutečně chová, ne z toho, jak bychom si přáli, aby se chovalo. Pokud jsi ještě neposlal první požadavek, začni úvodem do API.

Pravidlo 1: jeden klíč na klienta, jedna peněženka za nimi

Klíče se vytvářejí v API Console, každý s názvem, a celý klíč se zobrazí přesně jednou. Pojmenuj je podle klientů. Klíč, který unikne, nebo smlouva, která skončí, se zruší samostatně a ostatní fungují dál. Co klíče nedělají, je rozdělení peněz: každý klíč na účtu čerpá ze stejného zůstatku mincí. Pokud dva klienti nikdy nesmějí sdílet zůstatek, jsou to dva účty, a mince se mezi účty později přesouvat nedají.

Pravidlo 2: tvoje evidence, propojená tvým ID úlohy

Endpoint seznamu vrací celý účet včetně obrázků ze studia, ne práci jednoho klíče. Veď si proto vlastní evidenci: klient, úloha, ID generování, naúčtované mince. Nejčistší způsob, jak je propojit, je hlavička Idempotency-Key. Sestav ji z vlastního ID úlohy a opakovaný požadavek po přerušeném spojení vrátí generování, které už existuje, místo aby naúčtoval druhé. Dej jí prefix jedinečný pro tvoji agenturu, stačí náhodný řetězec, protože klíč se kontroluje v celé službě, nejen v rámci tvého účtu.

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

Odpovědí je 202 s ID generování a coinsCharged; zapiš obojí do evidence dřív, než uděláš cokoli dalšího.

Pravidlo 3: dotazuj se, nečekej

Generování se zařadí do fronty a běží na pozadí. Dotazuj se na jeho stav s klidným intervalem (dokud čeká ve frontě, nese odpověď odhad v etaMs) a spouštěj několik úloh najednou místo jedné po druhé: API povoluje na účet víc paralelních úloh než studio, protože tak se běžně používá.

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)

Pravidlo 4: ber selhání jako data

Neúspěšné generování automaticky vrátí mince a oznámí to v refunded. Jeho failureCode pochází z krátkého pevného seznamu: TIMEOUT a VENDOR_ERROR stojí za jeden pozdější pokus, MODERATION_REJECTED znamená, že prompt je potřeba přepsat, ne opakovat, a UNKNOWN pokrývá zbytek. Zapisuj kód do evidence; klient, jehož zadání pořád končí zamítnutím moderací, potřebuje rozhovor, ne smyčku opakování. Ekonomiku opakování popisuje článek o cenách a selháních.

Pravidlo 5: archivuj hned, jak se to podaří

API není knihovna podkladů. Hotové soubory se smažou, když skončí doba uchování uvedená na stránce produktu, a potom požadavek na obsah odpoví 410 BYTES_EXPIRED. Každý úspěšný obrázek si hned stáhni do vlastního úložiště, pod klienta a úlohu z evidence, a pokud klient nechce, abychom jeho obrázky vůbec drželi, smaž je po archivaci přes API.

Pravidlo 6: kontroluj limity z kódu a před předáním postav člověka

Každý klíč má limit počtu požadavků a účet má denní příděl obrázků. Obojí vrací jedno volání, takže dávková úloha si to může ověřit před startem, místo aby selhala v půlce:

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

Samotná čísla jsou na stránce produktu. A než se cokoli dostane ke klientovi, někdo se na to podívá. Model umí dát ruce šest prstů nebo napsat na ceduli špatné slovo, a automatizovaná pipeline to doručí stejně rychle jako dobrý obrázek.

Co API za agenturu neudělá

Nemá podúčty, zůstatky po klientech ani přehled využití po klíčích: tohle účetnictví je na tobě. Není tu žádná smlouva o úrovni služeb ani garantovaná doba dodání, takže neslibuj klientovi minuty, které sis nezměřil. Vygenerovaný obrázek se nestává tvým ve smyslu autorského práva, jak vysvětluje článek komu patří AI obrázky, i když je komerční použití povolené a nebereme si žádný podíl. A tvář skutečného člověka pořád vyžaduje jeho svolení, ať požadavek přijde jakkoli.

Rozpočtování mincí za tím vším popisuje kolik tým skutečně utratí, a studio pro ručně dělané obrázky je Fellowi Images.