Кредити
Як працює резервування, витрачання та повернення кредитів API для генерації контенту.
API Qamera AI використовує кредитну систему для обліку генерації контенту. Розуміння того, як кредити проходять через API, допоможе вам керувати витратами та обробляти граничні випадки.
Безкоштовні та платні ендпоінти
| Метод | Кредити | Приклади |
|---|---|---|
| GET | Безкоштовно | Перегляд продуктів, отримання статусу замовлення, завантаження результатів. |
| POST | Витрачає кредити | Створення замовлень на пакшоти, запуск фотосесій, генерація відео. |
Операції читання ніколи не витрачають кредити. Лише POST-запити, що запускають генерацію контенту, списують кошти з балансу вашого акаунта.
Процес резервування кредитів
Коли ви надсилаєте POST-запит на генерацію контенту, кредити проходять три етапи:
1. Резервування
Перед початком будь-якої обробки API резервує необхідну кількість кредитів з балансу вашого акаунта. Це гарантує, що ваш акаунт може покрити вартість запитаної генерації.
Якщо баланс недостатній, запит негайно відхиляється з відповіддю 402 Payment Required:
{
"error": "Insufficient credits. Required: 5, available: 2."
}
2. Обробка
Завдання генерації виконується. Ваші кредити залишаються в зарезервованому стані протягом цього часу — вони списані з доступного балансу, але ще не витрачені остаточно.
3. Розрахунок
Після завершення обробки:
- У разі успіху — Зарезервовані кредити витрачаються остаточно.
- У разі невдачі — Зарезервовані кредити автоматично повертаються на баланс вашого акаунта.
Вам не потрібно вживати жодних дій для повернення коштів. Система обробляє це автоматично.
Відстеження витрат кредитів
POST-відповіді, що запускають генерацію, містять поля, пов'язані з кредитами:
{
"orderId": "order_abc123",
"reservationId": "res_xyz789",
"creditsReserved": 5,
"status": "processing"
}
| Поле | Опис |
|---|---|
orderId | Унікальний ідентифікатор замовлення на генерацію контенту. |
reservationId | Ідентифікатор резервування кредитів, прив'язаного до цього замовлення. |
creditsReserved | Кількість кредитів, зарезервованих для цього запиту. |
Використовуйте orderId для опитування ендпоінта статусу замовлення та підтвердження того, чи були кредити витрачені або повернені.
Перевірка балансу
Перед надсиланням запитів на генерацію переконайтесь, що на вашому акаунті достатньо кредитів. Ви можете перевірити поточний баланс кредитів у розділі Credits вашого командного робочого простору або врахувати очікувану вартість у логіці вашої інтеграції.
Ціноутворення
Кількість кредитів, що витрачаються за запит, залежить від типу контенту та конфігурації ціноутворення вашого акаунта. Різні типи генерації (пакшоти, фотосесії, відео) мають різну вартість у кредитах. Зверніться до деталей вашого тарифного плану для конкретного ціноутворення.
Найкращі практики
- Перевіряйте перед генерацією — Якщо ваш робочий процес передбачає пакетну генерацію, переконайтесь, що баланс кредитів може покрити весь пакет перед початком.
- Обробляйте 402 коректно — Побудуйте вашу інтеграцію так, щоб вона виявляла відповіді про недостатність кредитів і сповіщала вашу команду до того, як це заблокує робочий процес.
- Моніторте резервування — Використовуйте
orderIdтаreservationIdдля відстеження поточних генерацій та звірки витрат кредитів. - Довіряйте автоматичним поверненням — Невдалі завдання повертають кредити без будь-якого втручання. Немає потреби створювати логіку ручного повернення.