Как встроить 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.