Developer API reference

The TokenCalculator Developer API exposes the same normalized model catalog and measurement mechanics as the web application. Use the HTTP API for non-sensitive remote integrations and the npm SDK when prompts, code, or extracted files must remain inside your environment.

Quickstart

No API key is required for the initial public v1 service.

curl https://tokencalculator.dev/api/v1/count \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": { "text": "Explain retrieval-augmented generation." },
    "output_tokens": 500
  }'

Request schema

A measurement accepts multiple content classes. TokenCalculator counts each part separately and returns an optional per-part breakdown.

• model — a model ID from GET /models.
• input.text — one raw prompt or text string.
• input.messages[] — role, optional name, and content. Raw content is measured; provider-added message framing is not inferred.
• input.files[] — a filename, optional media type, and already-extracted text or source code. Binary files are not accepted.
• input.images[] — pixel width, height, and low/high detail for provider-published vision formulas.
• output_tokens and cached_input_tokens — workload assumptions used by cost and context calculations.
• options.include — any of usage, breakdown, cost, context, method, and pricing.
• metadata — arbitrary caller data echoed unchanged for correlation.

Endpoints

Response contract

A full response can include:

• usage: input, text, image, cached input, expected output, and total tokens.
• breakdown: token result, accuracy classification, and algorithm for every input part.
• cost: USD input, cache-read, output, and total projections.
• context: selected model window, maximum output, used and remaining capacity, ratio, and overflow state.
• method: exact/projected status, calculation algorithms, and explicit limitations.
• pricing: applied tier, unit rates, verification date, and primary source URL.

Every successful response includes X-Request-Id and X-API-Version headers. Supply your own X-Request-Id (up to 96 characters) when you need correlation across systems.

Privacy, retention, and service limits

The public HTTP API is not browser-local. It receives payload content at the TokenCalculator.dev Cloudflare Worker. The application does not intentionally write request bodies to a database, object store, queue, or analytics dataset. Cloudflare may process infrastructure and security metadata under its platform controls.

Do not submit credentials, regulated data, confidential prompts, or proprietary source repositories. Use the local SDK or browser tool for that material.

• 60 requests per minute, per route, connecting IP, and Cloudflare edge location.
• 256 KiB maximum JSON request body.
• 200 KiB combined UTF-8 text, message, and extracted-file content.
• 25 measurements per batch and 10 models per comparison.
• No uptime SLA for the free public service.

Errors

Errors use application/problem+json and the RFC 9457 fields type, title, status, detail, and instance. Expect 400 for invalid JSON or fields, 413 for body size, 415 for media type, 422 for range constraints, and 429 for rate limiting.

Local npm SDK

Install the public package when request content must not cross the TokenCalculator.dev API boundary:

npm install @jay0073/tokencalculator-core

import { measureModel, compareModels } from '@jay0073/tokencalculator-core';

const result = await measureModel({
  text: privatePrompt,
  files: [
    { text: extractedContract },
    { text: extractedSourceCode },
    { image: { width: 1920, height: 1080, detail: 'high' } },
  ],
  outputTokens: 500,
}, 'gpt-5.6-terra');

The SDK accepts raw text plus multiple already-extracted text files and image dimensions. Browser-side PDF and DOCX extraction remains part of the web application; pass extracted content to the SDK when building a private ingestion pipeline.