Перейти к содержимому

Справочник API

Аккаунт и баланс

GET /v1/account — доступный баланс аккаунта в кредитах, число запросов и списанные кредиты этого ключа за последние 30 дней.

Получите доступный баланс аккаунта в кредитах и статистику использования ключа.

Песочница

Для проб — тестовый ключ

В форму ниже вставляйте ключ clipia_test_…: он не списывает кредиты и не вызывает модели, а ответ приходит в том же формате. Форма запоминает ключ в этом браузере, поэтому боевой clipia_live_… — серверный секрет — в неё не вводите. Подробнее — «Тестовый режим».

GET
/v1/account

Авторизация

headerАвторизацияBearer <токен>

API-ключ в заголовке Authorization со схемой Bearer — основной способ. Сгенерированные клиенты добавляют префикс Bearer сами, а в плейграунде поле уже содержит его: допишите ключ после него. Плейграунд запоминает ключ в этом браузере, поэтому для проб берите тестовый:

Authorization: Bearer <CLIPIA_API_KEY>

Тот же ключ принимается и со схемой Key (Authorization: Key <ключ>, слово Key — в любом регистре), и в отдельном заголовке X-Api-Key (схема apiKeyHeader) — выбирайте удобную форму, сервер различает их сам. Ключ создаётся в консоли разработчика (clipia.ai/developer, вкладка «API-ключи») и показывается один раз. Формат: clipia_live_… (боевой), clipia_test_… (песочница).

Sandbox / тестовый режим. Ключ с префиксом clipia_test_… работает в песочнице: submit не списывает кредиты и не запускает реальную генерацию — он мгновенно возвращает status: COMPLETED с детерминированным mock-результатом (фиксированный sample-ассет на media.clipia.ai). Поле cost показывает расчётную стоимость, но она не списывается. Вебхуки приходят тем же подписанным механизмом (HMAC-SHA256). Режим предназначен для отладки интеграции до подключения боевого ключа.

Тело ответа

Сведения об аккаунте.

application/json
  1. response
account_id?string

Идентификатор аккаунта.

balance*
usage_30d*

Использование за последние 30 дней.

curl -X GET "https://example.com/v1/account"
{  "account_id": "8f3a1c7e-2b4d-4e6f-9a01-23456789abcd",  "balance": {    "credits": 1840  },  "usage_30d": {    "requests": 512,    "credits_spent": 6120  }}

GET /v1/account возвращает баланс аккаунта, к которому привязан ключ, и сводку по этому ключу за последние 30 дней. Хватит любого действующего ключа — отдельное право не нужно.

GET/v1/account

Запрос

curl https://api.clipia.ai/v1/account \
  -H "Authorization: Bearer $CLIPIA_KEY"

Ответ 200

{
  "account_id": "8f3a1c7e-2b4d-4e6f-9a01-23456789abcd",
  "balance": { "credits": 1840 },
  "usage_30d": { "requests": 512, "credits_spent": 6120 }
}

Свойство

Тип

Кредиты

Генерации и LLM-чат списывают кредиты с баланса аккаунта, к которому привязан ключ. Пополнить баланс можно в личном кабинете на clipia.ai. Если кредитов не хватает, отправка вернёт 402 insufficient_credits, а если у аккаунта нет активной подписки — 402 subscription_required; подробнее в разделе «Ошибки». Баланс в этом ответе такой запрет не показывает.

Оценка стоимости

POST /v1/models/{model}/estimate — узнать стоимость генерации в кредитах до запуска; задача не создаётся, кредиты не резервируются и не списываются.

Идемпотентность

Заголовок Idempotency-Key делает повтор отправки генерации безопасным — тот же запрос вернёт тот же request_id без второй задачи и второго списания.