Обзор API
API запроса логов возвращает подробную запись каждого API-вызова, выполненного в рамках вашей учётной записи, включая использованную модель, фактически списанную сумму, задержку, был ли вызов выполнен с потоковой передачей, и код ошибки, если вызов завершается ошибкой. Он дополняет API запроса баланса: запрос баланса показывает, сколько кредита осталось, а запрос логов — куда он ушёл. Три типичных сценария использования:Автоматическая сверка
Самостоятельная диагностика
Обращения в поддержку
request_id в поддержку, чтобы они могли точно определить вызовКак получить ваш System Token
Log Query API выполняет аутентификацию с помощью System Token, который не является тем же самым, что и API key (см. Важные примечания в конце этой страницы).Открыть консоль
api.apiyi.com/account/profile, чтобы открыть страницу вашего профиляНайдите System Token
Сгенерируйте AccessToken

Информация об API
Сведения о запросе
Заголовки запроса
Параметры запроса
pageSize — самая эффективная оптимизация для этого эндпоинта. При 10 записях
на страницу аккаунту, выполняющему 500,000 вызовов в день, потребуется 50,000 запросов; при
5000 на страницу — 100. Это на два порядка меньше запросов, и смещение пагинации
уменьшается вместе с ним — см. Примечания по производительности ниже.Страница на 5000 записей имеет размер примерно 700 KB в gzip и обрабатывается примерно за 2,5 секунды. Если пропускная способность или
память ограничены, 1000 — удобный компромисс.Примечания по производительности
Стоимость одного запроса не фиксирована. Она зависит от трёх факторов. Следуйте этим правилам, и API будет работать быстро; проигнорируйте их, и вы упрётесь в серверный лимит запроса в 60 секунд и получите ошибку.- Всегда передавайте
start_timestampиend_timestamp. Не указывать окно — самый дорогостоящий способ вызвать этот API. - Увеличьте
pageSize. Это самый простой пункт: переход от 10 к 1000–5000 записей на страницу сокращает число запросов на два порядка, а вместе с ним падает и смещение. - Сужайте окно вместо того, чтобы углублять смещение. Платите вы не за «какая это страница», а за «сколько записей было пропущено, чтобы до неё дойти», и этот показатель растёт сверхлинейно. Вместо того чтобы проходить всё большое окно постранично, разбейте его на 24 часовых окна, чтобы каждое окно снова начиналось со смещения 0.
- Один раз выгрузите историю, сохраните её, а затем синхронизируйте только приращения. Старые данные обходятся намного дороже при запросе, чем недавние, поэтому повторное чтение одной и той же истории — это чистая трата ресурсов.
pageSize=1000, объём вызовов для этого периода
высокий — разбейте окно пополам и запросите каждую половину отдельно. Это намного быстрее, чем
уходить глубже по страницам. Константа MAX_PAGES в примере на Python ниже делает именно это.60 секунд — это жёсткий лимит, и его превышение возвращает ошибку
Сервер ограничивает любой отдельный запрос 60 секундами. После этого вы не получаете медленный ответ — вы получаете ошибку, а уже затраченное время не даёт вам никаких данных. С высокой вероятностью его вызовут эти три сценария. Избегайте их сразу, а не повторяйте запрос и надеетесь на удачу:pageSize, чтобы было меньше постраничной навигации —
в любом случае дайте серверу меньше данных на обработку за один вызов.
Типы журналов
Детали ответа
Пример успешного ответа
Ключевые поля ответа
other содержит строку JSON, а не вложенный объект, поэтому требуется повторный разбор
(json.loads() в Python, JSON.parse() в JavaScript). Оно содержит billing_type,
request_path (фактически вызванный эндпоинт), group_ratio, model_ratio и usage.Записи о расчётах для асинхронных задач генерации видео также содержат final_quota (итоговую сумму задачи),
original_quota (авансовое списание при отправке), adjustment_quota (разницу для этой записи) и actual_tokens; см. раздел FAQ ниже.Конвертация квоты
Правило конвертации
quota ÷ 500,000
Примеры:
quota: 7500→ $0.015 USDquota: 22500→ $0.045 USDquota: 18→ $0.000036 USD
Сообщения об ошибках
HTTP 401 - Сбой аутентификации
sk-, был
по ошибке использован как system token.
Решение: Перегенерируйте system token в консоли и убедитесь, что Authorization содержит
необработанное значение без префикса Bearer.
Примеры кода
Пример cURL (одна страница, быстрая проверка)
Пример на Python: ежедневная инкрементальная синхронизация (готово для использования как задание cron)
Это рекомендуемый стандартный способ использования: запускайте его раз в день, получайте только то, что появилось с момента последней синхронизации, и записывайте это в локальную базу данных SQLite. Повторный запуск безопасен (записи дедуплицируются поrequest_id), а выполнение, прерванное на середине, возобновляется с места остановки.
Пример на Node.js (одно временное окно)
Та же идея: разбивайте по часам, последовательно обрабатывайте страницы и уменьшайте окно, если пагинация становится слишком глубокой.--compressed.Распространённые сценарии
Ежедневная сверка (рекомендуемый подход)
Настройте запуск приведённого выше Python-скрипта раз в день и сохраняйте журналы в локальную базу данных. Любую нужную вам детализацию — общие расходы, по модели, по token — затем можно получить с помощью SQL-запроса к вашей собственной базе данных. Есть три причины, почему это правильный вариант: локальные запросы выполняются быстро; вы не зависите от окна хранения журналов; и вы избегаете замедления API из-за повторного чтения старой истории. Чтобы синхронизировать записи только одной модели, добавьте параметрmodel_name в запрос.
Поиск неудачных вызовов
Когда данные находятся локально, выполняйте запрос непосредственно к своей таблице:quota равный 0 и
не тарифицируются. error_code в журнале позволяет вам отделить «вызов завершился с ошибкой» от
«вызов завершился успешно, но мне не понравился результат».Предоставление request ID для поддержки
Найдите проблемный вызов в журналах и передайте поддержкеrequest_id. Это идентифицирует
точный запрос end to end, что гораздо эффективнее, чем описывать «вызов к какой-то модели
завершился с ошибкой примерно в определённое время».
Часто задаваемые вопросы
Мой запрос выполняется медленно или полностью завершается по тайм-ауту — что делать?
Мой запрос выполняется медленно или полностью завершается по тайм-ауту — что делать?
- Передаёте ли вы
start_timestampиend_timestamp? Пропуск временного окна — самый затратный способ вызвать этот API: сервер выполняет поиск по всей вашей истории. - Окно слишком старое или слишком широкое? Запрос данных месячной давности обходится значительно дороже, чем запрос данных за вчера. Сохраняйте диапазон менее одного дня, а при больших объёмах разбивайте его по часам.
- Достигло ли
pнескольких тысяч? Стоимость пагинации растёт сверхлинейно. Решение — сузить временное окно так, чтобы для каждого окна требовалось лишь несколько десятков страниц, а не углублять пагинацию в рамках одного большого окна.
Почему я получаю только 10 записей?
Почему я получаю только 10 записей?
page_size в snake_case.Правильное написание — camelCase pageSize. Это единственный параметр camelCase в этом
эндпоинте: все остальные (model_name, token_name, start_timestamp, …) используют snake_case,
поэтому здесь легко ошибиться. Ошибка не возникает: сервер считает параметр
отсутствующим и использует 10 записей на страницу по умолчанию.p=0, p=1, …), пока ответ не вернёт пустой массив: примеры на Python и
Node.js выше уже включают эту логику.Можно ли найти один конкретный вызов по ID запроса?
Можно ли найти один конкретный вызов по ID запроса?
request_id, и будет возвращена только эта запись:Некоторые поля в ответе пусты — что-то не так?
Некоторые поля в ответе пусты — что-то не так?
quota, model_name, error_code и request_id
всегда полностью заполнены.Почему token_group отличается от названия группы, отображаемого в консоли?
Почему token_group отличается от названия группы, отображаемого в консоли?
default, а консоль показывает «По умолчанию».Полное сопоставление доступно в публичном эндпоинте https://api.apiyi.com/api/pricing
в поле usable_group, которое сопоставляет идентификатор с меткой. Если вы хотите, чтобы ваши отчёты
совпадали с консолью, примените это сопоставление самостоятельно.Количество tokens и квота, похоже, не совпадают — что является достоверным?
Количество tokens и квота, похоже, не совпадают — что является достоверным?
quota. Это сумма, фактически списанная за вызов, и единственное поле,
подходящее для сверки. Для моделей с ценой за вызов, таких как генерация изображений и генерация видео,
количество tokens в ответе может быть значением-заполнителем, не участвующим в тарификации —
такие модели передают by_count в other.billing_type.Насколько далеко в прошлое можно выполнять запросы?
Насколько далеко в прошлое можно выполнять запросы?
curl возвращает искажённый текст или jq выдаёт ошибку
curl возвращает искажённый текст или jq выдаёт ошибку
Content-Encoding: gzip), а curl
не распаковывает его.Решение: добавьте флаг --compressed:Задача генерации видео создала две записи журнала. Как сопоставить их с task_id и узнать стоимость видео?
Задача генерации видео создала две записи журнала. Как сопоставить их с task_id и узнать стоимость видео?
completion_tokens равно 0, присутствует request_id) и расчёт
(completion_tokens — фактическое использование, request_id пусто, quota — только разница).
Ни одна из записей не содержит task_id, поэтому этот API не может сопоставить записи с задачами.Чтобы узнать фактическую стоимость видео, запросите API задач по task_id; его quota — это сумма двух записей:page_size, при этом p начинается с 1, в отличие от этого API.
Неудачная задача всё равно показывает предварительное списание в quota, но её фактическая стоимость равна 0 (журналы содержат отрицательную запись возврата type=11).
Подробное руководство: Как узнать фактическую стоимость видео Seedance по task_id.Расходует ли запрос журналов квоту?
Расходует ли запрос журналов квоту?
Важные примечания
- Синхронизируйте один раз в день — чаще не нужно; каждый запуск загружает только новое
- Используйте
pageSizeв размере 1000–5000, а не значение по умолчанию 10 — это важнее всего остального вместе взятого - Вызывайте последовательно, примерно с интервалом в одну секунду между страницами, никогда не параллельно
- Установите тайм-аут клиента на 60 секунд (ограничение запроса на стороне сервера тоже составляет 60 секунд)
- Ограничивайте каждый временной интервал одним днем или меньше; для аккаунтов с большим объемом данных разбивайте по часам
- При тайм-ауте уменьшите окно перед повторной попыткой — идентичная повторная попытка не будет быстрее
Связанная документация
- API запроса баланса — проверьте оставшийся кредит учетной записи
- API управления token — создавайте и управляйте API-ключами программно
- Как просмотреть мои записи вызовов — ручной просмотр в консоли
- Понимание логов и тарификации — как читать поля тарификации