Статистика

Статистику вы забираете сами — мы не отправляем исходящих запросов к вашей системе. Данные доступны за любой период и обновляются по мере активности пользователей.

Справочник событий

GET /api/v1/partner/stats/user-events

Возвращает список событий, по которым доступна статистика. Ключи из поля type — это же ключи объекта stats в ответах статистики.

[
  { "type": "generation.text",  "description": "Генераций текста" },
  { "type": "generation.image", "description": "Генераций изображений" },
  { "type": "generation.video", "description": "Генераций видео" },
  { "type": "generation.audio", "description": "Генераций аудио" },
  { "type": "tokens.spent",     "description": "Потрачено токенов" }
]

string

Ключ события. Используется как ключ в объекте stats.

string

Название события на русском языке — можно показывать в интерфейсе как есть.

Список пополняется. Стройте интерфейс по ответу этого эндпоинта, а не по фиксированному перечню ключей — тогда новые метрики появятся у вас без доработок.

Статистика пользователей

GET /api/v1/partner/stats/users

Постраничный список пользователей с их активностью. Это единственное место, где выдаётся public_id — сохраните его, чтобы потом запрашивать статистику по конкретному пользователю.

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

integer

Позиция, с которой продолжить обход. Для первой страницы не передаётся, дальше — значение next_cursor из предыдущего ответа.

integer

default:"20"

Размер страницы, от 1 до 100.

integer

Начало периода, unix-время. Не передан — считаем с начала истории.

integer

Конец периода, unix-время. Не передан — считаем по настоящий момент.

Ответ

{
  "items": [
    {
      "public_id": "9f1c2a6e-4b70-4f1a-9d2c-8b5e0a7d3f42",
      "external_user_id": "u_12345",
      "stats": {
        "generation.text": 128,
        "generation.image": 34,
        "generation.video": 6,
        "generation.audio": 2,
        "tokens.spent": 184300
      }
    }
  ],
  "next_cursor": 4820
}

array

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

Show поля

string

Идентификатор пользователя в Ai-Seven. Нужен для запроса статистики по одному пользователю.

string | null

Ваш идентификатор пользователя — тот, что вы передавали в sub токена входа. null, если пользователь пришёл не через вашу платформу.

object

Суммы по каждому событию из справочника за период. События без активности присутствуют со значением 0.

integer | null

Курсор следующей страницы. null — данные закончились.

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

GET /api/v1/partner/stats/users/{public_id}

string

required

Идентификатор пользователя из списка выше.

integer

Начало периода, unix-время.

integer

Конец периода, unix-время.

Ответ

{
  "public_id": "9f1c2a6e-4b70-4f1a-9d2c-8b5e0a7d3f42",
  "external_user_id": "u_12345",
  "stats": {
    "generation.text": 12,
    "generation.image": 3,
    "generation.video": 0,
    "generation.audio": 0,
    "tokens.spent": 20450
  }
}

string

Идентификатор пользователя в Ai-Seven.

string | null

Ваш идентификатор пользователя.

object

Суммы по каждому событию из справочника за период. События без активности присутствуют со значением 0.

Ответ приходит и для пользователя без активности — со значениями 0. Этим запрос по public_id отличается от списка, куда такой пользователь не попадёт вовсе.

Пример

Обход всех страниц за последние сутки:

import time
import requests

BASE = "https://aisevenai.ru/api/v1/partner"
headers = {"Authorization": f"Bearer {api_token}"}
params = {"date_from": int(time.time()) - 86400, "limit": 100}

while True:
    response = requests.get(f"{BASE}/stats/users", headers=headers, params=params)
    response.raise_for_status()
    page = response.json()

    for user in page["items"]:
        print(user["external_user_id"], user["stats"])

    if not page["next_cursor"]:
        break
    params["cursor"] = page["next_cursor"]

const BASE = "https://aisevenai.ru/api/v1/partner";
const params = new URLSearchParams({
  date_from: String(Math.floor(Date.now() / 1000) - 86400),
  limit: "100",
});

for (;;) {
  const response = await fetch(`${BASE}/stats/users?${params}`, {
    headers: { Authorization: `Bearer ${apiToken}` },
  });
  const page = await response.json();

  for (const user of page.items) {
    console.log(user.external_user_id, user.stats);
  }

  if (!page.next_cursor) break;
  params.set("cursor", String(page.next_cursor));
}

curl -G https://aisevenai.ru/api/v1/partner/stats/users \
  -H "Authorization: Bearer $API_TOKEN" \
  -d date_from=$(( $(date +%s) - 86400 )) \
  -d limit=100

Поведение

Что попадает в статистику

Учитывается вся активность пользователя в Ai-Seven, а не только то, что он делал после перехода из вашего кабинета.Генерации считаются штуками и раскладываются по категориям: text, image, video, audio. Составные инструменты попадают в категорию своего результата — например, слайды карусели считаются изображениями, а озвучка — аудио.tokens.spent — сумма списанных токенов за период, включая операции, которые не являются генерацией.

Кто попадает в список

В список попадают пользователи, у которых была активность за указанный период. Пользователь без единого события за период не вернётся вовсе — это не то же самое, что нули в stats.Сам объект stats в обоих эндпоинтах устроен одинаково: в нём всегда присутствуют все события из справочника, отсутствующие — нулями.

Чужие пользователи в ответе

Список включает всех пользователей платформы, а не только пришедших через вашу интеграцию. У пользователей, пришедших не от вас, поле external_user_id равно null.Если вам нужны только свои — отбирайте по непустому external_user_id на своей стороне.

Границы периода

date_from и date_to — unix-время в секундах, обе границы включительно. Можно указать только одну: без date_from считаем с начала истории, без date_to — по текущий момент.События записываются в момент завершения операции. Генерация, начатая до date_to и завершившаяся после, попадёт в следующий период.

Ошибки

Помимо ошибок авторизации:

Код	Сообщение	Причина
`404`	Пользователь не найден	Указан несуществующий `public_id`
`422`	—	`public_id` не является UUID, `limit` вне диапазона 1–100, отрицательные даты или неизвестный параметр запроса

Для регулярной выгрузки берите период с запасом и опирайтесь на date_from/date_to, а не на «всё время»: так объём ответа остаётся предсказуемым, а повторный запрос за тот же период даёт тот же результат.

Начало работы

Авторизация

Партнёрский API

Справочник событий

Статистика пользователей

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

Ответ

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

Ответ

Пример

Поведение

Ошибки

​Справочник событий

​Статистика пользователей

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

​Ответ

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

​Ответ

​Пример

​Поведение

​Ошибки

Справочник событий

Статистика пользователей

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

Ответ

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

Ответ

Пример

Поведение

Ошибки