TypeScript and Python SDKs

The official SDKs cover NinjaChat’s core API v1 primitives: Responses, Chat Completions, models, images, video, search, usage, balance, health, request traces, and webhooks.

These endpoints — POST /batch, POST /compare, POST /estimate, GET /pricing, /sessions, and /pipelines — are not wrapped by either SDK. Call them as raw REST with the same Authorization: Bearer header. See Batch, Compare, Cost estimation, Pricing, Conversation state, Pipelines, and Presets.

NinjaChat API keys are server-side credentials. Load NINJACHAT_API_KEY from your deployment platform or secret manager; never include an nj_sk_... key in browser or mobile code.

Choose an integration

TypeScript SDK

Best for Node.js, Next.js, workers, and TypeScript services. Typed resources, streams, retries, and webhook verification are included.

Python SDK

Best for FastAPI, Flask, Django, notebooks, and background workers.

OpenAI client

Keep an existing OpenAI integration and change the base URL, API key, and model ID.

Raw REST

Use the HTTP contract directly when adding a dependency is not desirable.

Install

npm install @ninjachat/sdk

pip install ninjachat

The TypeScript package requires Node.js 18 or newer. The Python package requires Python 3.9 or newer.

Create a client

import { NinjaChat } from "@ninjachat/sdk";

const client = new NinjaChat({
  apiKey: process.env.NINJACHAT_API_KEY!,
});

import os
from ninjachat import NinjaChat

client = NinjaChat(api_key=os.environ["NINJACHAT_API_KEY"])

You do not need to configure a base URL. Both clients default to https://www.ninjachat.ai/api/v1.

Next.js route handler

app/api/generate/route.ts

import { NinjaChat } from "@ninjachat/sdk";

const client = new NinjaChat({ apiKey: process.env.NINJACHAT_API_KEY! });

export async function POST(request: Request) {
  const { input } = await request.json();
  const response = await client.responses.create({ model: "ninja/auto", input });
  return Response.json({ text: response.output_text, requestId: response.request_id });
}

FastAPI route

app.py

import os
from fastapi import FastAPI
from pydantic import BaseModel
from ninjachat import NinjaChat

app = FastAPI()
client = NinjaChat(api_key=os.environ["NINJACHAT_API_KEY"])

class GenerateBody(BaseModel):
    input: str

@app.post("/generate")
def generate(body: GenerateBody):
    response = client.responses.create(model="ninja/auto", input=body.input)
    return {"text": response["output_text"], "request_id": response["request_id"]}

Generate a response

Use Responses for new stateless text, vision, tool, and structured-output integrations:

const response = await client.responses.create({
  model: "ninja/auto",
  input: "Give me three names for a developer tool.",
  max_output_tokens: 100,
  routing: {
    strategy: "balanced",
    data_policy: "no_training",
  },
});

console.log(response.output_text);
console.log(response.cost_usd, response.request_id);

response = client.responses.create(
    model="ninja/auto",
    input="Give me three names for a developer tool.",
    max_output_tokens=100,
    routing={"strategy": "balanced", "data_policy": "no_training"},
)

print(response["output_text"])
print(response["cost_usd"], response["request_id"])

Use Chat Completions

Use Chat Completions when your application already works with role-based messages:

const completion = await client.chat.completions.create({
  model: "gpt-5.6-luna",
  messages: [{ role: "user", content: "Explain edge caching in one paragraph." }],
  max_completion_tokens: 200,
});

console.log(completion.choices[0].message.content);

completion = client.chat.completions.create(
    model="gpt-5.6-luna",
    messages=[{"role": "user", "content": "Explain edge caching in one paragraph."}],
    max_completion_tokens=200,
)

print(completion["choices"][0]["message"]["content"])

Already using OpenAI’s client? You can keep it and change the base URL and key.

Stream output

const events = await client.responses.create({
  model: "ninja/auto",
  input: "Write a short launch announcement.",
  stream: true,
});

for await (const event of events) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta ?? "");
  }
}

events = client.responses.create(
    model="ninja/auto",
    input="Write a short launch announcement.",
    stream=True,
)

for event in events:
    if event.get("type") == "response.output_text.delta":
        print(event.get("delta", ""), end="")

See Streaming for event behavior and complete examples.

Images and video

const image = await client.images.generate({
  model: "nano-banana-2",
  prompt: "A paper crane on a drafting table, soft morning light",
});
console.log(image.data[0].url);

const job = await client.videos.generate({
  model: "veo-3.1-fast",
  prompt: "Ocean waves at dusk, slow aerial push-in",
});
const video = await client.videos.waitFor(job.id);
console.log(video.video_url);

image = client.images.generate(
    model="nano-banana-2",
    prompt="A paper crane on a drafting table, soft morning light",
)
print(image["data"][0]["url"])

job = client.videos.generate(
    model="veo-3.1-fast",
    prompt="Ocean waves at dusk, slow aerial push-in",
)
video = client.videos.wait_for(job["id"])
print(video["video_url"])

Video polling stops automatically when the job completes or fails. Failed generation jobs are refunded by the API.

Models, usage, and traces

const models = await client.models.list();
const usage = await client.usage("7d");
const balance = await client.balance();
const health = await client.health();
const trace = await client.requests.get(response.request_id);

models = client.models.list()
usage = client.usage("7d")
balance = client.balance()
health = client.health()
trace = client.requests.get(response["request_id"])

See Observability for the fields to log, health checks, alerting, and signed webhook verification.

Search and webhooks

Run AI-assisted search through the same client:

const results = await client.search.query({
  query: "What changed in the latest ECMAScript specification?",
  max_results: 5,
});

console.log(results.answer, results.sources);

results = client.search.query(
    query="What changed in the latest ECMAScript specification?",
    max_results=5,
)

print(results["answer"], results["sources"])

For long-running video and pipeline jobs and spend alerts, register a signed webhook instead of polling — in Developers → Webhooks or via the SDK. The events are video.completed, video.failed, pipeline.completed, pipeline.failed, budget.alert, and balance.low; omit events to subscribe to all six. Store the returned signing secret immediately; it is shown once.

const endpoint = await client.webhooks.create({
  url: "https://example.com/webhooks/ninjachat",
  events: ["video.completed", "video.failed", "budget.alert"],
});

console.log(endpoint.secret);

endpoint = client.webhooks.create(
    url="https://example.com/webhooks/ninjachat",
    events=["video.completed", "video.failed", "budget.alert"],
)

print(endpoint["secret"])

Handle errors

Every failed request raises a typed NinjaChatError with an HTTP status, machine-readable code, and request ID when the server produced one.

import { NinjaChatError } from "@ninjachat/sdk";

try {
  await client.models.retrieve("missing-model");
} catch (error) {
  if (error instanceof NinjaChatError) {
    console.error(error.status, error.code, error.requestId);
  }
}

from ninjachat import NinjaChatError

try:
    client.models.retrieve("missing-model")
except NinjaChatError as error:
    print(error.status, error.code, error.request_id)

The clients retry 429, 500, 502, 503, and 504 responses (up to maxRetries, default 2), honor Retry-After, and attach an Idempotency-Key to billed requests before retrying so a retry can only replay, never double-bill. A 409 request_in_flight is retried only when the request carried an idempotency key; 408 is never retried. Pass maxRetries: 0 (max_retries=0) to disable retries. See Error handling and Rate limits. Before customer traffic, complete the go-live checklist.

Package links

TypeScript on npm

@ninjachat/sdk

Python on PyPI

ninjachat

Source code

Browse both SDKs and release history

API quickstart

Make your first request

Get Started

Chat

Routing & scale

Orchestration

Production

Media & search

Reference

Choose an integration

TypeScript SDK

Python SDK

OpenAI client

Raw REST

Install

Create a client

Generate a response

Use Chat Completions

Stream output

Images and video

Models, usage, and traces

Search and webhooks

Handle errors

Package links

TypeScript on npm

Python on PyPI

Source code

API quickstart

​Choose an integration

TypeScript SDK

Python SDK

OpenAI client

Raw REST

​Install

​Create a client

​Generate a response

​Use Chat Completions

​Stream output

​Images and video

​Models, usage, and traces

​Search and webhooks

​Handle errors

​Package links

TypeScript on npm

Python on PyPI

Source code

API quickstart

Choose an integration

Install

Create a client

Generate a response

Use Chat Completions

Stream output

Images and video

Models, usage, and traces

Search and webhooks

Handle errors

Package links