TypeScript and Python SDKs

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

Typed clients for Node.js, Next.js and workers.

Python SDK

For Python services, notebooks and background workers.

Vercel AI SDK

Official provider for the AI SDK — generateText, streamText, tools, and structured outputs, with the routing trace on providerMetadata.

OpenAI client

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

Raw REST

Call the API without an SDK.

Install

npm install @ninjachat/sdk

pip install ninjachat

The TypeScript package requires Node.js 18 or newer. The Python package requires Python 3.10 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.

Vercel AI SDK

If your app is built on the AI SDK, use the official provider rather than a generic OpenAI-compatible shim — you keep NinjaChat’s routing policy and its routing trace.

npm install @ninjachat/ai-sdk-provider

import { generateText } from "ai";
import { ninjachat } from "@ninjachat/ai-sdk-provider";

const { text, providerMetadata } = await generateText({
  model: ninjachat("ninja/auto"),
  prompt: "Write a haiku about clean APIs.",
  providerOptions: {
    ninjachat: { routing: { strategy: "cost", allow_fallbacks: true } },
  },
});

// What actually ran, what it cost, and how to trace it.
const { resolvedModel, provider, costUsd, requestId } = providerMetadata!.ninjachat;

streamText, tool calling, structured outputs, and image inputs all work. Reads NINJACHAT_API_KEY from the environment, or call createNinjaChat({ apiKey }). For an ordered fallback chain, ninjachat.chain(["claude-opus-5", "gpt-5.6-sol"]) sends the models array. Media generation, search, batch, compare, and pipelines live in @ninjachat/sdk — the AI SDK provider covers text.

Package links

TypeScript on npm

@ninjachat/sdk

Python on PyPI

ninjachat

AI SDK provider on npm

@ninjachat/ai-sdk-provider

Source code

Browse the SDKs and release history

API quickstart

Make your first request

More capabilities

Speech: client.audio.speech.create returns audio bytes (Python) or a binary Response (TypeScript).
Embeddings: client.embeddings.create returns vectors.
Reranking: client.rerank.create returns ranked documents.
Anthropic Messages: client.messages.create supports messages and streaming.
Account management: use a management credential for keys, projects and account operations.

Get Started

Chat

Orchestration

Production

Media & search

Reference

Choose an integration

TypeScript SDK

Python SDK

Vercel AI 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

Vercel AI SDK

Package links

TypeScript on npm

Python on PyPI

AI SDK provider on npm

Source code

API quickstart

More capabilities

​Choose an integration

TypeScript SDK

Python SDK

Vercel AI 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

​Vercel AI SDK

​Package links

TypeScript on npm

Python on PyPI

AI SDK provider on npm

Source code

API quickstart

​More capabilities

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

Vercel AI SDK

Package links

More capabilities