Budget Routing

Pass budget_cents and NinjaChat picks the highest-quality model at or under that price — it overrides model entirely.

POST /api/v1/chat

{
  "budget_cents": 0.5,
  "messages": [{"role": "user", "content": "Translate to Spanish: Hello world"}],
  "include_routing": true
}

Response

{
  "model": "gemini-3-flash",
  "routing": {
    "budget_routing": {
      "requested_budget_cents": 0.5,
      "resolved": "gemini-3-flash",
      "reason": "Best model within 0.5¢ budget: Gemini 3 Flash (free tier, 0.3¢/req)"
    }
  },
  "cost": {"this_request": "$0.003"}
}

Parameters

Parameter	Description
`budget_cents`	Max cost in cents for this request. Takes priority over `model` — even over `auto`.
`include_routing`	Show the decision in the response.

Within the cheapest qualifying tier, several free-tier models can tie on cost (0.3¢/req) and on number of capabilities. When that happens, the router breaks the tie deterministically by taking the first equally-ranked model in its internal catalog order — not necessarily the “best” one by any qualitative measure. gemini-3-flash, gemini-2.5-flash, deepseek-v3, and qwq-32b are all 4-capability free-tier models, for example; gemini-3-flash wins ties against the others purely because it’s listed first.

Where it shines

Per-request cost control without maintaining a model list. A tiered product can literally map plan → budget:

BUDGETS = {"free": 0.3, "pro": 1.5, "enterprise": 3.0}  # cents per request

def chat_for(plan: str, message: str):
    return requests.post("https://www.ninjachat.ai/api/v1/chat",
        headers=HEADERS,
        json={
            "budget_cents": BUDGETS[plan],
            "messages": [{"role": "user", "content": message}],
        }).json()

As new models launch, every tier silently upgrades to the best model its budget buys.

Get Started

Chat

Superpowers

Media & Search

Reference

Parameters

Where it shines

​Parameters

​Where it shines

Parameters

Where it shines