Чому 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-консоль, щоб створити ключ.