Usage

Every response tells you what it cost you in tokens. One endpoint tells you what is left on your key.

Figures on this page are illustrative: they show how a bill is worked out, not what any model costs today. Current prices are on Pricing.

What a response reports

Every reply carries a usage block.

"usage": {
  "input_tokens": 12,
  "cache_creation_input_tokens": 1204,
  "cache_read_input_tokens": 0,
  "cache_creation": {"ephemeral_5m_input_tokens": 1204, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 33
}

Field	Meaning
`input_tokens`	Prompt tokens that were not cached
`cache_creation_input_tokens`	Written to the cache. Charged at 1.25×
`cache_read_input_tokens`	Served from the cache. Charged at 0.10×
`output_tokens`	Everything generated, reasoning included

When streaming

Usage arrives in two pieces, and the first one is incomplete.

Event	Carries
`message_start`	Final input counts. `output_tokens` is a placeholder `1`
`message_delta`	The real `output_tokens`

Read the output count from message_delta. A client that reads usage only from message_start records one output token for every streamed call.

Telling a cache hit from a cache write

Send a stable prefix with a cache breakpoint on it:

"messages": [{"role": "user", "content": [
  {"type": "text", "text": "<your long stable prefix>",
   "cache_control": {"type": "ephemeral"}},
  {"type": "text", "text": "<the part that changes>"}
]}]

Then read the numbers back:

cache_creation_input_tokens > 0 — a write. You paid 1.25× to fill the cache.
cache_read_input_tokens > 0 — a hit. You paid 0.10×.

Where each model runs

claude-opus-5 is served from different capacity than the other six models, and is metered differently as a result.

It counts input tokens more generously. For English prose we measure about 1.67× the token count you would expect, plus a fixed overhead of roughly 530 tokens on every request. For Chinese and for code we have measured a higher per-unit count but have not yet pinned down the ratio, so treat it as at least 1.67× and measure your own traffic.

Checking your balance

Your balance, held credit and every charge — text and video, per key — are in Preview details. Amounts are USD with six decimal places; no exchange rate applies. Negative or insufficient available credit blocks new paid calls, while reads and funding remain available.

GET /v1/usage has been retired and now answers 404. To see which models your key can call, use GET /v1/models.

curl https://api.nightferry.io/v1/models \
  -H "x-api-key: $NIGHTFERRY_KEY"

A model on that list can still return a no-capacity error, and the price page lists only the models we have most recently seen working.

What we do not offer

/v1/messages/count_tokens exists in the Anthropic API but is not served here. We do not serve it, and the count we could return would ignore your tools and system blocks — on a real agent payload that is wrong by more than thirty times. A wrong number that looks right is worse than no number, so it returns 404.

To size a prompt before sending it, send it and read usage back. Failed requests are not billed — see Errors.