Chat Completions

Send messages to any model and get a response.

Request

POST https://ninjachat.ai/api/v1/chat
Authorization: Bearer nj_sk_YOUR_API_KEY
Content-Type: application/json

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

Response

{
  "id": "chatcmpl-1749584400000",
  "object": "chat.completion",
  "model": "gpt-5",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Quantum computing harnesses quantum mechanical phenomena..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 87,
    "total_tokens": 111
  },
  "cost": {"this_request": "$0.006"},
  "balance": "$4.820",
  "metadata": {"latency_ms": 1243}
}

Parameters

Parameter	Type	Required	Default	Description
model	string	No	ninja-1	Model ID, smart routing variant (auto, auto-fast, etc.), ensemble variant, or fallback chain (a>b>c).
messages	array	Yes	—	1–50 messages. Each has role (system, user, or assistant) and content.
temperature	number	No	0.7	0 = deterministic, 2 = creative.
max_tokens	integer	No	2048	Max response length (1–16,384).
stream	boolean	No	false	Stream tokens via SSE. See Streaming.
session_id	string	No	—	Attach to a persistent session. History is auto-injected.
cache	boolean	No	true	Cache responses. Identical requests return instantly at no cost. Disabled when using session_id or stream.

Multi-turn conversations

Without sessions, pass the full conversation history manually:

messages = [
    {"role": "system", "content": "You are a helpful tutor."},
    {"role": "user", "content": "What is photosynthesis?"},
    {"role": "assistant", "content": "Photosynthesis converts sunlight into energy..."},
    {"role": "user", "content": "How does it compare to solar panels?"},
]
r = requests.post("https://ninjachat.ai/api/v1/chat",
    headers={"Authorization": f"Bearer {os.environ['NINJACHAT_API_KEY']}"},
    json={"model": "gpt-5", "messages": messages}
)

Or use sessions to have NinjaChat manage history for you.

More features

The chat endpoint supports several additional capabilities — each documented on its own page:

• Smart Routing — auto-select the best model per request
• Fallback Chains — try models in sequence
• Ensemble — consensus-driven answers from multiple models
• Budget Routing — best model within a cost ceiling
• Quality Scoring — confidence scores with auto-retry
• Streaming — token-by-token SSE output
• Sessions — persistent conversation memory