Як вбудувати API генерації зображень у процеси агенції: ключі, облік і архів

Довідник з API пояснює, як зробити одну картинку. В агенції задача інша: тисячі картинок, десяток клієнтів, троє людей, які натискають кнопки, і один фінансист, який наприкінці місяця питає, хто скільки витратив. Нічого складного тут немає, але помилитися в будь-якій частині легко вже за перший тиждень. Нижче шість правил, і кожне взяте з того, як API поводиться насправді, а не з того, як нам хотілося б. Якщо ви ще не надіслали жодного запиту, почніть із вступу до API.

Правило 1: один ключ на клієнта, один гаманець за ними

Ключі створюються в API Console, кожен має назву, а повний ключ показується рівно один раз. Називайте їх за клієнтами. Ключ, що витік, або ключ клієнта, з яким закінчився договір, відкликається окремо, а решта працює далі. Чого ключі не роблять, так це не розділяють гроші: усі ключі акаунта витрачають один і той самий баланс монет. Якщо двом клієнтам у жодному разі не можна ділити баланс, потрібні два акаунти, а перенести монети між акаунтами потім не можна.

Правило 2: ваш облік, прив’язаний до вашого id завдання

Ендпоінт списку повертає весь акаунт, разом із картинками зі студії, а не роботу одного ключа. Тому ведіть власний облік: клієнт, завдання, id генерації, списані монети. Найзручніше пов’язати їх заголовком Idempotency-Key. Складайте його з власного id завдання, і повторний запит після обриву з’єднання поверне вже наявну генерацію, а не спише оплату вдруге. Додайте до нього префікс, унікальний для вашої агенції, вистачить випадкового рядка, бо ключ перевіряється в межах усього сервісу, а не лише вашого акаунта.

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

У відповідь приходить 202 з id генерації та coinsCharged; запишіть обидва значення в облік раніше, ніж зробите щось інше.

Правило 3: опитуйте, а не чекайте

Генерація стає в чергу й виконується у фоні. Опитуйте її статус із розумним інтервалом (поки вона в черзі, відповідь містить оцінку в etaMs) і запускайте кілька завдань одразу, а не одне за одним: API дозволяє на акаунт більше паралельних завдань, ніж студія, бо для нього це звичайний режим роботи.

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)

Правило 4: помилка - це дані

Невдала генерація автоматично повертає монети й повідомляє про це в полі refunded. Її failureCode береться з короткого фіксованого списку: TIMEOUT і VENDOR_ERROR варто один раз повторити пізніше, MODERATION_REJECTED означає, що промпт треба переписати, а не повторювати, а UNKNOWN охоплює все інше. Записуйте код в облік; клієнт, чий бриф раз у раз упирається в модерацію, потребує розмови, а не циклу повторів. Економіку повторів розібрано в статті про ціни та збої.

Правило 5: архівуйте одразу після успіху

API не медіатека. Готові файли видаляються, коли закінчується строк зберігання, зазначений на сторінці продукту, і після цього запит вмісту відповідає 410 BYTES_EXPIRED. Завантажуйте кожне успішне зображення у своє сховище одразу, під клієнтом і завданням із вашого обліку, а якщо клієнт не хоче, щоб його картинки взагалі зберігалися в нас, видаліть їх через API після архівування.

Правило 6: перевіряйте ліміти з коду й ставте людину перед здачею

Кожен ключ має ліміт запитів, а акаунт має денний ліміт зображень. Обидва повертаються одним викликом, тож пакетне завдання може перевірити їх до старту, а не впасти на півдорозі:

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

Самі цифри вказано на сторінці продукту. І перш ніж щось потрапить до клієнта, на це має подивитися людина. Модель може намалювати шість пальців на руці чи не те слово на вивісці, а автоматичний конвеєр доставить це так само швидко, як і гарну картинку.

Чого API не зробить для агенції

У ньому немає субакаунтів, балансів за клієнтами та звіту про витрати за ключами: ця бухгалтерія на вас. Немає угоди про рівень сервісу й гарантованого часу виконання, тож не обіцяйте клієнту хвилин, які ви не виміряли. Згенерована картинка не стає вашою в сенсі авторського права, як пояснює стаття кому належать ШІ-зображення, хоча комерційне використання дозволене і ми не беремо жодної частки. І для обличчя реальної людини, як і раніше, потрібен її дозвіл, хоч би яким шляхом прийшов запит.

Як планувати бюджет монет на все це, розповідає стаття скільки насправді витрачає команда, а студія для картинок, які робляться вручну, це Fellowi Images.