Почему API изображений оценивается в монетах (и сам возвращает деньги при сбое)

Когда мы строили публичный API поверх Fellowi Images, пришлось принять несколько решений, которые не выглядят как отдельные фичи в документации - они проявляются как отсутствие проблем. Вот логика за ними: почему это монеты, а не подписка, что происходит при сбое генерации и почему пара цифр в документации (лимиты запросов, дни хранения) значат меньше, чем кажется на первый взгляд.

Монеты, а не подписка

У генерации изображения есть реальная, переменная стоимость на каждый вызов. Фиксированная месячная подписка либо переплачивает за того, кто генерирует пять изображений в месяц, либо недоплачивает за того, кто генерирует пятьсот - здесь нет числа мест или квоты запросов, которые аккуратно на это ложатся. Монеты позволяют стоимости напрямую следовать за использованием: вы платите ровно за то, что реально сгенерировали, не больше. Монеты не сгорают, и отменять нечего, а значит не нужно следить за платёжным циклом - покупайте пакет, когда он нужен, а до тех пор он просто лежит в кошельке.

Неудачная генерация возвращает деньги сама

Если генерация превышает время ожидания или отклоняется до того, как получилось изображение, потраченные на неё монеты возвращаются автоматически и сразу же. Это не обращение в поддержку - это свойство самой системы: с вас никогда не спишут деньги за изображение, которое вы не получили. Мы считаем это гарантией надёжности, а не любезностью.

Любой сбой сводится ровно к одному из четырёх кодов, намеренно немногочисленных:

• TIMEOUT - генерация заняла слишком много времени и была прервана.
• MODERATION_REJECTED - запрос нарушил политику по контенту.
• VENDOR_ERROR - что-то пошло не так на стороне генерации.
• UNKNOWN - настоящий универсальный код для всего, что не подошло под первые три.

Небольшой фиксированный набор кодов - осознанный выбор: под него реально можно написать switch-конструкцию, а не подгонять сопоставление под произвольные строки ошибок, которые могут поменяться под вами в любой момент.

Изображения истекают через 30 дней

Байты сгенерированного изображения хранятся 30 дней. После этого запись о самой генерации в истории остаётся - ваш эндпоинт со списком по-прежнему покажет, что генерация была, когда и сколько стоила, - но при запросе самого файла вернётся HTTP 410 Gone. Это простой, не скрытый компромисс из-за стоимости хранения: если хотите сохранить изображение дольше 30 дней, скачайте и храните его сами. Мы не удаляем запись о генерации молча, только байты.

Лимиты запросов - не настоящий потолок

Лимит запросов в минуту на ваш API-ключ (по умолчанию 20 запросов в минуту на генерацию, 120 - на чтение) существует, чтобы сдерживать злоупотребления, а не быть тем, что реально ограничивает число изображений, которые вы можете сделать. Настоящий потолок - это баланс Fellowi Coins: если монеты есть, вы можете их тратить, вплоть до этой скорости. Если хочется более жёсткого бюджета, чем позволяет баланс, у ключа можно также задать необязательный дневной лимит монет - для собственного контроля расходов, а не нашего.

Ключи, которые нельзя вернуть

API-ключ показывается ровно один раз, в момент создания. После этого на нашей стороне хранится только хэш и короткий фрагмент для отображения - та же позиция, что и с любым другим секретом в продукте. Если ключ потерян, создайте новый; процедуры восстановления нет, потому что на нашей стороне попросту нечем его восстановить.

Один кошелёк, одна цена

API и веб-приложение тратят из одного и того же баланса Fellowi Coins, по одной и той же цене за уровень качества - 40 монет за стандартное качество, 60 - за высокое. Отдельного «тарифа для API» нет. Это осознанное решение: стоимость предсказуема независимо от того, через какую дверь вы генерируете.

За реальными форматами запросов/ответов и рабочими примерами кода загляните в наш быстрый старт по API, либо сразу переходите в API-консоль, чтобы создать ключ.