Cost estimation

POST /api/v1/estimate estimates a chat request’s cost. It is free and requires no API key. Use estimate.create in either SDK.

cURL

curl https://www.ninjachat.ai/api/v1/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "Summarize the attached incident report in five bullets."}],
    "max_tokens": 1024,
    "count": 1000,
    "models": ["gemini-3.7-flash", "claude-sonnet-5"]
  }'

Parameters

Parameter	Type	Default	Description
`model`	string	required	A chat model ID from `GET /models`.
`messages`	array	—	Up to 10 `system`, `user`, or `assistant` messages (content ≤ 8,000 chars each) used for the prompt-token estimate. Omit it to price a 5,000-token reference input.
`max_tokens`	integer	—	Output bound for the maximum estimate (1–16,384). Also caps the typical completion.
`count`	integer	`1`	Multiply the estimate by this many requests (1–10,000).
`models`	array	—	Up to 10 additional model IDs to price the same payload against.

Response

{
  "model": "gpt-5.4",
  "model_name": "GPT-5.4",
  "provider": "openai",
  "tier": "premium",
  "pricing_version": "2026-09-01.provider-rails.1",
  "billing": "metered",
  "rates": { "input_per_mtok": 2.5, "output_per_mtok": 15, "cached_input_per_mtok": 0.25 },
  "estimated_tokens": { "prompt": 24, "completion": 64 },
  "estimated_cents": 0.1,
  "estimated_cost": "$0.0010",
  "estimated_max_cents": 1.54,
  "estimated_max": "$0.0154",
  "for_count": 1000,
  "total_estimated_cents": 100,
  "total_estimated": "$1.00",
  "cheaper_alternatives": [
    { "id": "gemini-3-flash", "name": "Gemini 3 Flash", "estimated_cents": 0.02, "savings_percent": 80, "capabilities": ["..."] }
  ],
  "monthly_estimate": { "at_100": "$0.10", "at_1000": "$1.00", "at_10000": "$10.00", "at_100000": "$100.00" },
  "model_comparison": [
    { "model": "gemini-3.7-flash", "estimated_cents": 0.05, "total_estimated_cents": 50 },
    { "model": "claude-sonnet-5", "estimated_cents": 0.07, "total_estimated_cents": 70 }
  ],
  "note": "Billing is per token ($/MTok input + output). Requests preauthorize estimated_max and settle to actual usage; estimates here use the same engine and estimator that bill real traffic."
}

Two numbers matter:

estimated_cents / estimated_cost — a realistic mid-point. The completion side uses a heuristic of 40% of the prompt tokens (at least 64), capped at max_tokens or 2,048.
estimated_max_cents / estimated_max — the pre-authorization hold a real request with these messages and max_tokens would reserve. The hold is a reserve, not a ceiling: the request settles to actual usage and the unused portion is returned. Use it to size routing.max_cost_usd — a cap below the hold is rejected with 400 max_cost_exceeded. See Spend controls.

cheaper_alternatives lists up to three catalog models that would cost less at this exact payload, sorted by savings. model_comparison appears only when you pass models. The numbers in the sample are illustrative; the endpoint returns live values.

Limits

30 requests per minute per client IP (429 rate_limit_exceeded with retry_after and a Retry-After header).
Unknown model IDs return 400 validation_error with the closest matching ID in the message.

Live price sheet

GET /api/v1/pricing for every model’s metered rates.

Cap a request

routing.max_cost_usd turns an estimate into a hard ceiling.

Get Started

Chat

Orchestration

Production

Media & search

Reference

Parameters

Response

Limits

Live price sheet

Cap a request

​Parameters

​Response

​Limits

Live price sheet

Cap a request

Parameters

Response

Limits