Чек-лист перед запуском

Демо хватает одного запроса. Продукт должен пережить таймауты, дублирующиеся вебхуки, истёкшие ссылки и утёкший ключ. Пройдитесь по этому списку перед запуском.

Ключи

• Ключ лежит в хранилище секретов сервера и никогда не попадает в браузер или сборку приложения.
• У каждой среды и каждого сервиса свой ключ, чтобы отзывать их по отдельности.
• Боевые ключи ограничены нужными моделями и имеют дневной лимит расходов.
• Вы знаете, как сменить ключ без простоя (Аутентификация).

Создание задач

• Каждый createTask отправляет Idempotency-Key, выведенный из вашего ID задания, — созданный один раз и повторно используемый при каждом повторе.
• Повторяются только 429, 500, 503 и 50301, с растущей паузой и учётом Retry-After (Ошибки).
• 400, 40004 и другие ошибки «исправьте запрос» показываются или пишутся в лог, но не повторяются.
• Если вы показываете цены, вы сначала запрашиваете расчёт, передаёте quoteId и expectedCredits и обрабатываете 40901.
• О низком балансе (40201) узнаёт человек — через алерт, письмо или баннер — раньше, чем пользователи.

Получение результатов

• У задач есть callBackUrl; ваш эндпоинт проверяет подпись и отклоняет устаревшие отметки времени.
• Обработчик вебхука быстро отвечает 2xx, а работу делает в фоне.
• Дубликаты доставок отсекаются по request_id.
• Периодическая проверка дочитывает задачи, чей вебхук так и не пришёл.
• Код считает любое состояние, кроме succeeded, failed, expired и canceled, состоянием «ещё выполняется».

Файлы

• Готовые файлы копируются в ваше хранилище (или в библиотеку ассетов), а не подключаются по подписанной ссылке, которая истекает примерно через 20 минут.
• Вы храните taskId, а не подписанные ссылки.
• Код скачивания не отправляет API-ключ на подписанную ссылку.
• Референсные файлы — это публичные HTTPS-ссылки на сам файл, загрузки или ассеты, а не страницы «поделиться».

Расходы

• Вы знаете единицу цены каждой модели (за изображение, за секунду, за запрос) и настройки, которые её повышают.
• Превью и тесты идут в самом дешёвом разрешении и с минимальной длительностью.
• Лимит расходов остановит зациклившийся код раньше, чем он опустошит баланс.
• Вы проверяете credits и settled, а не считаете, что списан именно расчётный резерв.

Мониторинг

• При каждом сбое вы логируете request_id, taskId, code и errorCode.
• Вы следите за долей задач failed по каждой модели; резкий рост обычно означает, что поменялся промпт, входные данные или модель.
• Вы отслеживаете время от createTask до вебхука по моделям и настраиваете алерты на выбросы.
• Кто-то в команде знает, где в API-консоли логи и страница статистики.

Контент

PopNow — сервис для широкой аудитории. У моделей свои правила контента, и отклонённые ими запросы падают с content_rejected. Если промпты пишут ваши пользователи, объясните в своём интерфейсе, почему запрос отклонён, вместо того чтобы показывать сырую ошибку, и дайте возможность его изменить.