API do obrazów AI w pipeline agencji: klucze, rejestry i archiwa

Dokumentacja API mówi, jak zrobić jeden obraz. Agencja ma inny problem: tysiące obrazów, kilkunastu klientów, trzy osoby klikające przyciski i jedna osoba z finansów, która pod koniec miesiąca pyta, kto ile zużył. Nic z tego nie jest trudne, ale w pierwszym tygodniu łatwo pomylić się przy każdym elemencie. Oto sześć zasad, każda wzięta z tego, jak API naprawdę działa, a nie z tego, jak byśmy chcieli, żeby działało. Jeśli nie wysłałeś jeszcze pierwszego żądania, zacznij od wprowadzenia do API.

Zasada 1: jeden klucz na klienta, jeden portfel za nimi

Klucze tworzysz w API Console, każdy z nazwą, a pełny klucz widać dokładnie raz. Nazywaj je od klientów. Klucz, który wyciekł, albo taki, którego umowa się skończyła, unieważniasz osobno, a pozostałe działają dalej. Klucze nie dzielą jednak pieniędzy: każdy klucz na koncie korzysta z tego samego salda monet. Jeśli dwaj klienci nigdy nie mogą dzielić salda, potrzebujesz dwóch kont, a monet nie da się potem przenosić między kontami.

Zasada 2: twój rejestr, powiązany twoim identyfikatorem zadania

Endpoint listy zwraca całe konto, łącznie z obrazami ze studia, a nie pracę jednego klucza. Prowadź więc własny rejestr: klient, zadanie, identyfikator generacji, pobrane monety. Najczystszy sposób, żeby to powiązać, to nagłówek Idempotency-Key. Zbuduj go z własnego identyfikatora zadania, a ponowione żądanie po zerwanym połączeniu zwróci już istniejącą generację zamiast obciążyć drugą. Dodaj prefiks unikalny dla twojej agencji, wystarczy losowy ciąg znaków, bo klucz jest sprawdzany w całej usłudze, nie tylko na twoim koncie.

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

Odpowiedź to 202 z identyfikatorem generacji i coinsCharged; zapisz oba w rejestrze, zanim zrobisz cokolwiek innego.

Zasada 3: odpytuj, nie czekaj

Generacja trafia do kolejki i działa w tle. Odpytuj jej status w spokojnym odstępie (dopóki czeka w kolejce, odpowiedź zawiera szacunek w etaMs) i uruchamiaj kilka zadań naraz zamiast jedno po drugim: API pozwala na więcej równoległych zadań na konto niż studio, bo to jest jego normalny tryb pracy.

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)

Zasada 4: traktuj błąd jak dane

Nieudana generacja automatycznie zwraca monety i informuje o tym w polu refunded. Jej failureCode pochodzi z krótkiej, stałej listy: TIMEOUT i VENDOR_ERROR są warte jednej ponownej próby później, MODERATION_REJECTED oznacza, że prompt trzeba przepisać, a nie powtarzać, a UNKNOWN obejmuje resztę. Zapisuj kod w rejestrze; klient, którego brief wciąż kończy się odrzuceniem przez moderację, to temat do rozmowy, a nie pętla ponowień. Ekonomię ponowień opisuje wpis o cenach i błędach.

Zasada 5: archiwizuj w chwili sukcesu

API nie jest biblioteką zasobów. Gotowe pliki są usuwane, gdy kończy się okres przechowywania podany na stronie produktu, a potem żądanie treści odpowiada 410 BYTES_EXPIRED. Pobieraj każdy udany obraz do własnego magazynu od razu, pod klientem i zadaniem z rejestru, a jeśli klient nie chce, żebyśmy w ogóle przechowywali jego obrazy, usuń je przez API po zarchiwizowaniu.

Zasada 6: sprawdzaj limity w kodzie i postaw człowieka przed dostawą

Każdy klucz ma limit częstotliwości żądań, a konto dzienny limit obrazów. Oba zwraca jedno wywołanie, więc zadanie wsadowe może sprawdzić je przed startem, zamiast wyłożyć się w połowie:

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

Same liczby są na stronie produktu. A zanim cokolwiek trafi do klienta, ktoś musi na to spojrzeć. Model potrafi dorysować szósty palec albo wstawić złe słowo na szyld, a zautomatyzowany pipeline dostarczy to równie szybko jak dobry obraz.

Czego API nie zrobi za agencję

Nie ma subkont, sald dla poszczególnych klientów ani raportu użycia dla każdego klucza: ta księgowość należy do ciebie. Nie ma umowy SLA ani gwarantowanego czasu dostawy, więc nie obiecuj klientowi minut, których nie zmierzyłeś. Wygenerowany obraz nie staje się twój w sensie prawa autorskiego, co wyjaśnia wpis do kogo należą obrazy AI, mimo że użycie komercyjne jest dozwolone i nie bierzemy żadnego udziału. A twarz prawdziwej osoby nadal wymaga zgody tej osoby, niezależnie od tego, jak przychodzi żądanie.

Budżetowanie monet stojących za tym wszystkim opisuje ile zespół naprawdę wydaje, a studio do obrazów robionych ręcznie to Fellowi Images.