curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'group_by=model'
import requests
response = requests.get(
"https://api.apimart.ai/v1/usage",
headers={"Authorization": "Bearer <token>"},
params={
"start": "2026-09-01T00:00:00+08:00",
"end": "2026-09-08T00:00:00+08:00",
"group_by": "model",
},
timeout=30,
)
payload = response.json()
if not response.ok or not payload.get("success"):
message = payload.get("error", {}).get("message", "Не удалось получить данные использования")
raise RuntimeError(f"HTTP {response.status_code}: {message}")
print(payload["data"]["total"])
print(payload["data"]["items"])
const url = new URL("https://api.apimart.ai/v1/usage");
url.search = new URLSearchParams({
start: "2026-09-01T00:00:00+08:00",
end: "2026-09-08T00:00:00+08:00",
group_by: "model",
}).toString();
const response = await fetch(url, {
headers: { Authorization: "Bearer <token>" },
});
const payload = await response.json();
if (!response.ok || !payload.success) {
throw new Error(
`HTTP ${response.status}: ${payload.error?.message ?? "Не удалось получить данные использования"}`,
);
}
console.log(payload.data.total);
console.log(payload.data.items);
{
"success": true,
"data": {
"scope": "key",
"start": 1788192000,
"end": 1788796800,
"tz": "Asia/Shanghai",
"group_by": "model",
"total": {
"amount_usd": 12.3456,
"credits": 123.456,
"requests": 1834,
"prompt_tokens": 902311,
"completion_tokens": 215044
},
"items": [
{
"model": "gpt-5.6-luna",
"amount_usd": 9.1271,
"credits": 91.271,
"requests": 1520,
"prompt_tokens": 880120,
"completion_tokens": 201300
},
{
"model": "sora-2",
"amount_usd": 3.2185,
"credits": 32.185,
"requests": 314,
"prompt_tokens": 22191,
"completion_tokens": 13744
}
]
}
}
{
"success": false,
"error": {
"code": "range_too_large",
"message": "Time range must not exceed 31 days.",
"type": "usage_query_error"
}
}
Управление аккаунтом
Запрос расходов и использования
- Расходы и статистика вызовов за заданный период
- Фильтрация по моделям, группировка по моделям и календарным дням
- Статистика текущего API Key или всего аккаунта
- Сумма в USD, кредиты, число вызовов и токены
GET
/
v1
/
usage
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'group_by=model'
import requests
response = requests.get(
"https://api.apimart.ai/v1/usage",
headers={"Authorization": "Bearer <token>"},
params={
"start": "2026-09-01T00:00:00+08:00",
"end": "2026-09-08T00:00:00+08:00",
"group_by": "model",
},
timeout=30,
)
payload = response.json()
if not response.ok or not payload.get("success"):
message = payload.get("error", {}).get("message", "Не удалось получить данные использования")
raise RuntimeError(f"HTTP {response.status_code}: {message}")
print(payload["data"]["total"])
print(payload["data"]["items"])
const url = new URL("https://api.apimart.ai/v1/usage");
url.search = new URLSearchParams({
start: "2026-09-01T00:00:00+08:00",
end: "2026-09-08T00:00:00+08:00",
group_by: "model",
}).toString();
const response = await fetch(url, {
headers: { Authorization: "Bearer <token>" },
});
const payload = await response.json();
if (!response.ok || !payload.success) {
throw new Error(
`HTTP ${response.status}: ${payload.error?.message ?? "Не удалось получить данные использования"}`,
);
}
console.log(payload.data.total);
console.log(payload.data.items);
{
"success": true,
"data": {
"scope": "key",
"start": 1788192000,
"end": 1788796800,
"tz": "Asia/Shanghai",
"group_by": "model",
"total": {
"amount_usd": 12.3456,
"credits": 123.456,
"requests": 1834,
"prompt_tokens": 902311,
"completion_tokens": 215044
},
"items": [
{
"model": "gpt-5.6-luna",
"amount_usd": 9.1271,
"credits": 91.271,
"requests": 1520,
"prompt_tokens": 880120,
"completion_tokens": 201300
},
{
"model": "sora-2",
"amount_usd": 3.2185,
"credits": 32.185,
"requests": 314,
"prompt_tokens": 22191,
"completion_tokens": 13744
}
]
}
}
{
"success": false,
"error": {
"code": "range_too_large",
"message": "Time range must not exceed 31 days.",
"type": "usage_query_error"
}
}
Запрашивайте расходы за заданный период с помощью API Key. Доступны фильтрация по моделям и группировка по моделям, календарным дням или обоим признакам. Результат агрегируется сразу: создавать задачу и опрашивать её статус не нужно.
Оба эндпоинта имеют одинаковые функции и поддерживают CORS. Храните API Key безопасно и не раскрывайте его в публичном коде фронтенда.
При этой группировке каждый элемент
Для оставшегося лимита используйте запрос баланса токена или запрос баланса пользователя.
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'group_by=model'
import requests
response = requests.get(
"https://api.apimart.ai/v1/usage",
headers={"Authorization": "Bearer <token>"},
params={
"start": "2026-09-01T00:00:00+08:00",
"end": "2026-09-08T00:00:00+08:00",
"group_by": "model",
},
timeout=30,
)
payload = response.json()
if not response.ok or not payload.get("success"):
message = payload.get("error", {}).get("message", "Не удалось получить данные использования")
raise RuntimeError(f"HTTP {response.status_code}: {message}")
print(payload["data"]["total"])
print(payload["data"]["items"])
const url = new URL("https://api.apimart.ai/v1/usage");
url.search = new URLSearchParams({
start: "2026-09-01T00:00:00+08:00",
end: "2026-09-08T00:00:00+08:00",
group_by: "model",
}).toString();
const response = await fetch(url, {
headers: { Authorization: "Bearer <token>" },
});
const payload = await response.json();
if (!response.ok || !payload.success) {
throw new Error(
`HTTP ${response.status}: ${payload.error?.message ?? "Не удалось получить данные использования"}`,
);
}
console.log(payload.data.total);
console.log(payload.data.items);
{
"success": true,
"data": {
"scope": "key",
"start": 1788192000,
"end": 1788796800,
"tz": "Asia/Shanghai",
"group_by": "model",
"total": {
"amount_usd": 12.3456,
"credits": 123.456,
"requests": 1834,
"prompt_tokens": 902311,
"completion_tokens": 215044
},
"items": [
{
"model": "gpt-5.6-luna",
"amount_usd": 9.1271,
"credits": 91.271,
"requests": 1520,
"prompt_tokens": 880120,
"completion_tokens": 201300
},
{
"model": "sora-2",
"amount_usd": 3.2185,
"credits": 32.185,
"requests": 314,
"prompt_tokens": 22191,
"completion_tokens": 13744
}
]
}
}
{
"success": false,
"error": {
"code": "range_too_large",
"message": "Time range must not exceed 31 days.",
"type": "usage_query_error"
}
}
Аутентификация
string
обязательно
Используйте тот же API Key, что и для вызова моделей, с аутентификацией Bearer Token. Получить ключ можно на странице управления API Key.
Authorization: Bearer YOUR_API_KEY
Запрос доступен при нулевом балансе. Баланс не проверяется, но проверяются статус и срок действия API Key, список разрешённых IP и статус аккаунта.
Эндпоинты
GET /v1/usage
GET /usage
Параметры запроса
Все параметры передаются в строке запроса URL.integer | string
Время начала включается в период. Принимается Unix timestamp в секундах или строка RFC3339 с часовым поясом, например
2026-09-01T00:00:00+08:00.По умолчанию — за 24 часа до end. Timestamp задаётся в секундах, не в миллисекундах.integer | string
Время окончания не включается. Формат тот же, что у
start; по умолчанию — текущее время.Должно быть позже start; end - start не может превышать 31 день.string
Название модели. Если не указано, учитываются все модели. Несколько моделей разделяются запятыми; максимум
50.Точное совпадение без учёта регистра. Подстановочные знаки не поддерживаются.Пример: gpt-5.6-luna,sora-2string
по умолчанию:"none"
Группировка:
none: только итог,items— пустой массивmodel: по моделямdate: по календарным днямmodel,date: по моделям и календарным дням
string
по умолчанию:"Asia/Shanghai"
Часовой пояс IANA. По умолчанию
Asia/Shanghai.Влияет только на границы календарных дней, когда group_by содержит date, и не меняет моменты начала и окончания. Времена RFC3339 интерпретируются с указанным в них часовым поясом.string
по умолчанию:"key"
Область статистики:
key: только текущий API Key (по умолчанию)account: все API Key аккаунта, которому принадлежит текущий ключ
Период —
[start, end): начало включается, окончание исключается. Одинаковое значение end предыдущего запроса и start следующего исключает двойной учёт границы.При ручном составлении URL кодируйте + в RFC3339 как %2B. cURL --data-urlencode, Python params и JavaScript URLSearchParams в примерах делают это автоматически.Примеры запросов
Расходы текущего API Key за последние 24 часа
Без параметров строки запроса используются период, область и группировка по умолчанию.curl 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>'
Ежедневные расходы всего аккаунта по выбранным моделям
Запрос расходов с 11 по 18 сентября 2026 года по пекинскому времени, не включая 18 сентября.curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--data-urlencode 'start=1789056000' \
--data-urlencode 'end=1789660800' \
--data-urlencode 'model=gpt-5.6-luna' \
--data-urlencode 'group_by=date' \
--data-urlencode 'scope=account' \
--data-urlencode 'tz=Asia/Shanghai'
Группировка по моделям и календарным дням
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'model=gpt-5.6-luna,sora-2' \
--data-urlencode 'group_by=model,date' \
--data-urlencode 'tz=Asia/Shanghai'
items содержит и model, и date.
Поля ответа
boolean
Успешность запроса:
true при успехе, false при ошибке запроса использования.object
При успехе возвращает область запроса, итог и сгруппированные данные.
Показать Свойства data
Показать Свойства data
string
Область статистики:
key или account.integer
Фактическое время начала: Unix timestamp в секундах, включительно.
integer
Фактическое время окончания: Unix timestamp в секундах, исключительно.
string
Часовой пояс для группировки по календарным дням.
string
Группировка:
none, model, date или model,date.object
Итог за период запроса. Статистические поля приведены ниже.
object[]
Сгруппированные данные по убыванию
amount_usd. При group_by=none — пустой массив. Каждый элемент содержит статистические поля из таблицы ниже.- Если
group_byсодержитmodel, элемент содержитmodel - Если
group_byсодержитdate, элемент содержитdateв форматеYYYY-MM-DD; границы дней определяютсяtz
data.total и data.items[] используют следующие общие статистические поля:
| Поле | Тип | Описание |
|---|---|---|
amount_usd | number | Сумма в USD, округлённая до 6 знаков после запятой |
credits | number | Кредиты сервиса: amount_usd × 10, в тех же единицах, что на сайте |
requests | integer | Число успешно оплаченных вызовов |
prompt_tokens | integer | Входные токены; обычно 0 для изображений и видео с оплатой за вызов или секунду |
completion_tokens | integer | Выходные токены; обычно 0 для изображений и видео с оплатой за вызов или секунду |
object
При ошибке запроса использования содержит
code, message и type; type равен usage_query_error. Ошибки аутентификации 401 / 403 возвращает слой аутентификации.Лимиты и кеш
- Не более
60запросов в минуту на API Key; также действуют глобальные лимиты API - Результаты с одинаковыми параметрами кешируются на
60секунд; заголовокX-Usage-Cache—hitилиmiss - Расходы обычно доступны в течение 1 секунды, но данные за последнюю минуту могут быть неполными; возможна задержка кеша
- Рекомендуется интервал не менее 1 минуты; не используйте эндпоинт как уведомление о списаниях в реальном времени
Правила учёта
- Используются записи успешно оплаченных вызовов, как в панели данных на сайте
- Неуспешные вызовы и возвраты после сбоя задачи исключены; вычитать их вручную не нужно. При частичном успехе пакета изображений оплачиваются фактически выданные изображения
- Расходы относятся ко времени проведения платежа. Асинхронные задачи изображений и видео учитываются при завершении, не при отправке; при переходе через полночь — в день завершения
- API Key, созданный заново после удаления, является новым ключом. Его запрос
scope=keyне включает историю старого ключа - Ручные корректировки баланса не являются расходами вызовов и исключаются
- Доступны данные после 27 апреля 2026 года
Обработка ошибок
| Статус HTTP | error.code | Описание |
|---|---|---|
| 400 | invalid_start / invalid_end | Неверный формат времени начала или окончания |
| 400 | invalid_range | end не позже start |
| 400 | range_too_large | Период превышает 31 день; разбейте его на несколько запросов |
| 400 | invalid_tz | Неизвестный часовой пояс IANA |
| 400 | invalid_group_by | Неверная группировка |
| 400 | invalid_scope | Неверная область статистики |
| 400 | too_many_models | Более 50 моделей |
| 401 / 403 | — | Недействительный или просроченный API Key, IP не разрешён либо аккаунт отключён |
| 429 | — | Более 60 запросов в минуту на ключ либо глобальный лимит API |
| 503 | usage_unavailable | Данные временно недоступны; повторите позже |
Ответ
503 usage_unavailable не содержит сумм. Это означает недоступность запроса, а не нулевые расходы. Не заменяйте ошибку нулевой суммой и не перезаписывайте предыдущий успешный результат.Отличия от других эндпоинтов
| Эндпоинт | Возможности |
|---|---|
GET /v1/dashboard/billing/usage | Только накопленные расходы; без фильтров по моделям или времени |
POST /v1/logs/export | Асинхронный экспорт деталей вызовов (CSV / XLSX); агрегация на вашей стороне |
GET /v1/usage | Запрос по времени и моделям с прямым возвратом итога и сгруппированных расходов |