Как самому проверить, что списания по API считаются честно

Когда деньги списываются автоматически по мере использования API, естественно хочется свериться самому, а не верить цифре в личном кабинете на слово. Это можно сделать без поддержки и без экспорта отчётов — вся нужная информация приходит прямо в ответах API.

Ниже — конкретные шаги, которые можно повторить за один вечер с обычным curl, без написания отдельного скрипта для сверки.

Стоимость каждого запроса — в заголовках ответа

Каждый обычный (не потоковый) ответ несёт два заголовка, которые не нужно выпрашивать отдельно:

• X-Zukko-Cost-Micros — стоимость именно этого запроса в микродолларах (1,000,000 микродолларов = $1).
• X-Fetch-Balance-Cents — остаток баланса на счёте сразу после списания за этот запрос. Несмотря на название, значение тоже в микродолларах (1,000,000 = $1); точный баланс в центах — GET /v1/balance, поле balance_cents.

У потоковых ответов (stream: true) этих заголовков нет — их расход сверяйте по /v1/usage и /v1/balance.

Чтобы их увидеть, добавьте -i к curl — так вы получите заголовки вместе с телом:

curl -i https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":100,"messages":[{"role":"user","content":"тест"}]}'

В выводе среди заголовков будет что-то вроде:

Это значит: запрос стоил $0.000342, а после списания на счету осталось $0.19 (187 654 микродоллара). Проверить арифметику легко: сделайте два запроса подряд, зафиксируйте X-Fetch-Balance-Cents до и после — разница (она уже в микродолларах) должна совпасть с X-Zukko-Cost-Micros второго запроса с точностью до округления.

Сверка с публичным прайсом моделей

Цены и лимиты каждой модели можно посмотреть без ключа вообще:

curl https://api.zukko.pro/v1/models/info

Дальше остаётся школьная арифметика: посчитать число входных и выходных токенов запроса (например, через POST /v1/messages/count_tokens для входных — это бесплатно) и сравнить полученную по прайсу сумму с тем, что реально показал X-Zukko-Cost-Micros. Если это разные модели с разной ценой за токен, стоит сверять именно по той модели, что указана в поле model вашего запроса — цена у каждой своя.

Полная история — с курсорной пагинацией

Для сверки за период есть GET /v1/usage — история списаний по всему аккаунту (все ключи вместе) с курсорной пагинацией. Каждая запись содержит created_at, model, input_tokens, output_tokens, total_tokens и cost_cents (дробные центы). Так можно выгрузить весь список операций постранично и просуммировать самостоятельно, не полагаясь на агрегированную цифру из интерфейса:

curl "https://api.zukko.pro/v1/usage?limit=100" \
  -H "Authorization: Bearer fetch_ваш_ключ"

Ответ содержит курсор для следующей страницы (next_cursor) — проходите постранично, пока курсор не закончится, и складывайте cost_cents построчно. Учтите, что пополнения и попадания в кэш в /v1/usage не попадают. Если общая цифра разойдётся с показанным балансом — это первое, что стоит прислать в поддержку с конкретными номерами операций, а не с общим «баланс не сходится».

Текущий баланс и общая сумма списанных токенов доступны отдельным вызовом:

curl https://api.zukko.pro/v1/balance \
  -H "Authorization: Bearer fetch_ваш_ключ"

Неудачные запросы не должны ничего стоить

Один из самых частых поводов для сомнений в честности биллинга — списание за запрос, который вроде бы «не сработал». Тут важно различать, где именно случился сбой.

Если баланс пуст, сервер отвечает 402 ещё до похода к модели:

{"error": {"message": "Недостаточно средств на балансе", "code": "insufficient_balance"}}

Проверка баланса происходит до обращения к провайдеру — значит, такой ответ в принципе не может нести списание, потому что до модели дело не дошло. Если вы видите X-Zukko-Cost-Micros при 402 — это баг, о котором стоит написать в поддержку, а не норма.

Иначе обстоит дело с обрывом ответа на середине — это почти всегда таймаут клиента или сети, а не лимит по токенам. Обрыв соединения со стороны клиента не останавливает списание: шлюз дочитывает ответ провайдера до конца и списывает всю генерацию, даже ту часть, которую клиент уже не получил. Здесь стоит смотреть на max_tokens и таймауты HTTP-клиента, а не считать это несправедливым списанием.

Повторные запросы не должны считаться дважды

Два механизма гейтвея напрямую защищают от лишних списаний, и оба можно проверить руками.

Idempotency-Key. Если вы отправляете один и тот же запрос повторно с одинаковым заголовком Idempotency-Key (свой на каждый логический запрос, одинаковый при его повторах) в течение 24 часов, ответ будет идентичным, а повторного списания не произойдёт. Проверяется просто: отправьте запрос дважды с одним и тем же ключом идемпотентности и сверьте X-Fetch-Balance-Cents — во второй раз баланс не должен измениться.

Кэш ответов. С заголовком X-Zukko-Cache: true (temperature: 0 тоже включает кэш, но только у моделей, которые его принимают, — модели Claude могут отклонить temperature, отличный от 1) одинаковые запросы одного и того же пользователя кэшируются (для чата — до 7 суток). Повторный идентичный запрос возвращается мгновенно и бесплатно, а в ответе появляется заголовок X-Zukko-Cache: hit; такие попадания не пишутся в /v1/usage. Срабатывает кэш только при полном совпадении тела запроса. Проверить легко: отправьте один и тот же запрос дважды с этими условиями и посмотрите, появился ли X-Zukko-Cache: hit на втором вызове и не изменился ли баланс.

Если цифры всё равно не сходятся

Если после всех проверок сумма по X-Zukko-Cost-Micros за период не совпадает с изменением баланса в /v1/balance (с учётом потоковых запросов, у которых заголовков нет, и пополнений), соберите конкретные тайм-штампы и заголовки спорных запросов и напишите в поддержку в Telegram: @zukkopro↗. Конкретные номера запросов и цифры разбираются быстрее, чем общая жалоба на то, что «что-то не так со счётом».

Стоит взять за привычку проводить такую сверку не после того, как счёт «показался странным», а регулярно — раз в неделю прогонять пару контрольных запросов, сохранять заголовки и сверять их с /v1/usage за тот же период. Это занимает пару минут, а разбираться постфактум с разошедшимися цифрами за месяц — куда дольше.