Сводная аналитика использования

GEThttps://api.souz.ai/v1/usage/summary

Расход за период + ряд по дням (у каждого дня — разрез по моделям by_model) + топ моделей по расходу. Только завершённые запросы и их списания, по дню завершения (UTC); суммы — в микроединицах валюты из поля currency. С bucket=hour ряд — по часам завершения (UTC) за последние days × 24 часа, включая текущий час, в поле hourly; итоги и топ моделей — за те же часы. Не пагинировано — для детальной таблицы см. GET /v1/usage.

Авторизация

ManagementKey

Ключ управления из кабинета souz.ai (выдают владелец и администратор аккаунта — себе или участнику). Даёт ровно то, что его держатель видит и может в кабинете: баланс, историю операций и запросов, расходы, обычные ключи, настройки аккаунта — с той же ролью, лимитами и цифрами. Модели не запускает. Обычный API-ключ здесь не подходит: 403 forbidden с detail[].reason: requires_management_key.

ClientSession

Сессия кабинета souz.ai в браузере — те же ручки, что у ключа управления.

Параметры запроса

daysinteger

Период в днях назад, по умолчанию 30, максимум 365; с bucket=hour — по умолчанию 1, максимум 2

bucketstring

Шаг ряда — day (по умолчанию) или hour. Ряд по часам — только за окно до 48 часов (days не больше 2), иначе 400

Значения: day, hour

Ответы

200OK

application/json

Схема UsageSummaryResponse

by_modelarray[ModelUsageEntry]обязательно

currencystringобязательно

Пример: "RUB"

dailyarray[DailyUsageEntry]обязательно

Ряд по UTC-дням; дней без запросов в нём нет. С bucket=hour — пустой, ряд в hourly.

hourlyarray[HourlyUsageEntry]

Ряд по UTC-часам — только с bucket=hour; часов без запросов в нём нет, по часу вверх.

period_daysintegerобязательно

Пример: 30

total_requestsintegerобязательно

Пример: 42

total_spend_microintegerобязательно

Пример: 1250000

total_succeededintegerобязательно

Пример: 40

400Запрос отклонён; `error.detail[]` называет поля и допустимые значения.

application/json

Error

401Нет ключа или ключ недействителен.

application/json

Error

403Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли

Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. detail[].reason говорит, что именно: requires_api_key, requires_management_key, cabinet_only (только в кабинете), insufficient_role (в allowed — роли, которым можно), not_key_author (секрет ключа открывает только тот, кто его создал).

application/json

Error

429Слишком часто — повторите через `Retry-After` секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены (их ограничивают баланс и лимиты трат); здесь 429 — на поток запросов с ключом, который сервер не знает, с одного адреса, и на потоки сверх 1000 одновременных на аккаунт (события задачи, чат с `stream: true`). Пределы — раздел «Лимиты» руководства.

application/json

Error

Бесплатно, со своим ключом

Запрос

curl -X GET 'https://api.souz.ai/v1/usage/summary' \
  -H "Authorization: Bearer $SOUZ_MANAGEMENT_KEY"

import os
import requests

response = requests.get(
    "https://api.souz.ai/v1/usage/summary",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_MANAGEMENT_KEY']}"},
)
print(response.json())

const response = await fetch("https://api.souz.ai/v1/usage/summary", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.SOUZ_MANAGEMENT_KEY}` },
});
console.log(await response.json());

Ответ

{
  "error": {
    "code": "capability_mismatch",
    "detail": [
      {
        "allowed": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "path": "aspect_ratio",
        "reason": "unsupported_value"
      }
    ],
    "message": "the model does not support this value",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}