Pro API: лимиты, коды ошибок и правила хорошего тона

Ограничения

Каждый ключ имеет три ограничения: одновременные рендеры (по умолчанию 2), запросы в минуту (по умолчанию 60) и, если ты его задал, дневной лимит кредитов.

При превышении лимита сервер возвращает 429 с заголовком Retry-After в секундах. Отклонённый вызов не стоит ничего. Сутки для подсчёта лимитов отсчитываются по UTC.

Наша собственная карта разделяется с пользователями приложения. Когда она занята, твои рендеры уходят на арендованные GPU по той же цене и через тот же API, с небольшой дополнительной задержкой при старте в несколько десятков секунд.

Коды ошибок

Код	error	Что это значит и что делать
400	champ prompt requis	Добавь промпт.
400	contenu_interdit	Фильтр контента отклонил промпт.
400	image_requise, inpaint_images_requises	Режим требует image_b64, а для inpaint ещё и mask_b64.
401	cle_requise, cle_invalide	Заголовок отсутствует или ключ не распознан.
402	credits_insuffisants	Недостаточно баланса для этого рендера (сумма указана в cost). Пополни баланс на сайте.
403	cle_desactivee, cle_revoquee, cle_expiree	Ключ отключён, отозван или истёк: создай новый в приложении.
403	licence_revoquee, licence_non_pro	Лицензия отозвана или аккаунт не является Pro.
403	portee_manquante	У ключа нет запрошенного разрешения, его название указано в portee.
403	lora_inconnu	Персонаж не принадлежит этому аккаунту.
404	media_indisponible	Файл недоступен: отправь запрос повторно.
413	image_trop_lourde	Исходное изображение или маска превышают 12 МБ после декодирования.
429	trop_de_rendus_simultanes, cadence_minute, plafond_jour	Достигнут один из лимитов, смотри Retry-After.
429	plafond_credits_jour	Достигнут дневной лимит кредитов ключа (plafond, depense, cout).
502	soumission_echouee, statut_echoue	Инцидент на стороне рендеринга: повтори запрос через несколько секунд.
503	licence_inverifiable	Аккаунт сейчас недоступен для проверки: повтори через минуту.

Названия ошибок — это точные строки, которые возвращает API. Сопоставляй по ним, а не по полю message, которое может быть изменено.

Правила хорошего тона

• Опрашивай статус каждые 3 секунды, не чаще. Очередь общая, и частые запросы никому не помогут.
• Скачивай файл сразу, как статус стал completed. Файл не архивируется.
• Пиши промпты на английском, а для видео описывай движение, а не статичную картину.
• Один ключ на одно использование, и дневной лимит кредитов на каждом ключе, который живёт на сервере. Утечка ключа с лимитом обойдётся в один день, а не в весь баланс.
• Воспринимай 429 как норму, а не как сбой: жди Retry-After и продолжай.

Промпты логируются на нашей стороне, как и в приложении, в целях безопасности.