Chat

The one endpoint behind everything: pick a model (or say auto), send messages, get the answer and the price.

POST /api/v1/chat

{
  "model": "gpt-5",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain quantum computing in one paragraph."}
  ]
}

Response

{
  "model": "gpt-5",
  "choices": [{
    "message": {"role": "assistant", "content": "Quantum computing harnesses..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 24, "completion_tokens": 87, "total_tokens": 111},
  "cost": {"this_request": "$0.0010"},
  "balance": "$4.820",
  "metadata": {"latency_ms": 1243}
}

Parameters

Parameter	Type	Default	Description
`model`	string	`ninja-1`	A model ID, an `auto` variant, an ensemble, or a fallback chain like `"a>b>c"`.
`messages`	array	required	1–50 messages of `{role, content}` — roles are `system`, `user`, `assistant`. `content` is a string, or an array of `text` / `image_url` parts for vision input.
`temperature`	number	`0.7`	0 = deterministic, 2 = creative.
`max_tokens`	integer	`2048`	Max response length (1–16,384).
`max_completion_tokens`	integer	—	OpenAI alias for `max_tokens`. Takes precedence if both are set.
`top_p`	number	—	Nucleus sampling (0–1).
`stop`	string or array	—	Up to 4 stop sequences.
`frequency_penalty`	number	—	-2 to 2. Penalizes tokens by how often they’ve already appeared.
`presence_penalty`	number	—	-2 to 2. Penalizes tokens that have appeared at all.
`seed`	integer	—	Best-effort deterministic sampling seed.
`n`	integer	`1`	Only `n=1` is supported.
`user`	string	—	Opaque end-user identifier for your own tracking (max 256 chars).
`response_format`	object	—	`{"type": "text" \| "json_object"}`.
`stream_options`	object	—	`{"include_usage": boolean}`. Only relevant when `stream: true`.
`stream`	boolean	`false`	Token-by-token SSE — Streaming.
`session_id`	string	—	Server-side conversation memory — Sessions.
`cache`	boolean	`true`	Identical requests return instantly at no cost — see Caching below for the full list of conditions that disable it.
`include_quality`	boolean	`false`	Include a `quality` confidence score in the response — Quality Scoring.
`include_routing`	boolean	`false`	Include a `routing` object describing how `auto` resolved.
`budget_cents`	number	—	Auto-select the best model at or under this cost (0.1–100 cents). Overrides `model` entirely — Budget Routing.
`min_quality`	number	—	Minimum quality threshold (0–1). If the response scores below it, auto-retry with a better model — Fallback Chains.
`fallback_on_error`	boolean	`true`	With a fallback chain, continue to the next model on error.
`fallback_strategy`	string	`sequential`	`sequential`, `parallel-race` (first quality response wins), or `parallel-best` (highest quality after all complete) — Fallback Chains.
`tools`	array	—	OpenAI-style function definitions, up to 32 — see Function calling.
`tool_choice`	string or object	—	`"auto"`, `"none"`, `"required"`, or `{"type": "function", "function": {"name": "..."}}`.
`route_mode`	string	`smart`	`smart` or `fast` — controls how much analysis `auto` does before picking a model.

Multi-turn

Two ways to carry a conversation:

Sessions (recommended)
Manual history

Send only the new message — NinjaChat stores and injects history server-side for 7 days.

{
  "model": "gpt-5",
  "messages": [{"role": "user", "content": "What did I just ask you?"}],
  "session_id": "user-alice-1"
}

Sessions →

Pass the full conversation every request:

{
  "model": "gpt-5",
  "messages": [
    {"role": "user", "content": "What is photosynthesis?"},
    {"role": "assistant", "content": "Photosynthesis converts sunlight..."},
    {"role": "user", "content": "How does it compare to solar panels?"}
  ]
}

Vision input

Any vision-capable model accepts images by sending content as an array of parts instead of a plain string — mix text and image_url parts in one message:

{
  "model": "gpt-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg", "detail": "auto"}}
      ]
    }
  ]
}

image_url.url accepts a public HTTPS URL or a base64 data URL. detail is optional (auto, low, or high). Sending images to a model that isn’t vision-capable returns a model_not_vision_capable error listing which models support it.

Function calling

Pass OpenAI-style tools and NinjaChat routes the model’s tool calls back to you the same way OpenAI does — the model doesn’t execute anything itself, it just tells you what to call:

{
  "model": "gpt-5",
  "messages": [{"role": "user", "content": "What's the weather in Austin?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

Only tool-capable models accept tools — passing them to a model that doesn’t support tool calling returns a model_not_tool_capable error.

Caching

cache: true (the default) returns identical requests instantly at no cost. Caching is automatically disabled — the request always runs live — when any of these are true:

session_id is set (history changes every turn)
stream: true
model is a fallback chain ("a>b>c")
model is an ensemble variant (ensemble, ensemble-quality)
Any message contains image content
tools is set
temperature is above 0.3

The model field is a superpower

Everything else about the request stays the same — only model changes:

`model` value	Behavior
`"gpt-5"`	That exact model
`"auto"`	Best model for this prompt — Smart Routing
`"auto-fast"` / `"auto-cheap"` / `"auto-quality"`	Routing biased to latency / cost / quality
`"claude-opus-4.6>gpt-5>gemini-3.1-pro"`	Try in order until one succeeds — Fallback Chains
`"ensemble"`	3 models answer, a 4th synthesizes — Ensemble

Try any of these live in the Playground — every run shows the exact request that made it.

Get Started

Superpowers

Media & Search

Reference

Chat

Parameters

Multi-turn

Vision input

Function calling

Caching

The model field is a superpower

​Parameters

​Multi-turn

​Vision input

​Function calling

​Caching

​The model field is a superpower

Parameters

Multi-turn

Vision input

Function calling

Caching

The model field is a superpower