canonical: https://jentic.com/apis/ninjachat.ai/ninjachat

# NinjaChat API

The NinjaChat API serves chat completions, stateless responses, and Anthropic-compatible messages across a list of live models, with routing options and a models array for fallback. Alongside text it generates images and video jobs, speech, embeddings, document reranking, and web search, and it can compare several chat models side by side, run batches, and chain up to five dependent chat, image, and video steps as one async pipeline. Account tooling covers usage, balance, request traces, saved presets, webhooks for video completion and spend alerts, and a separate management surface for API keys, projects, budgets, and audit logs. Chat and responses bill actual token usage, while images and videos use per-unit pricing.

## For AI agents

Call many chat models through one OpenAI-style or Anthropic-style endpoint, generate images, video, speech, and embeddings, rerank documents, search the web, and manage keys, projects, budgets, and webhooks.

## Scope

Does not fine-tune or host custom models, store files for retrieval, or provide a vector database. Use for calling hosted chat, image, video, speech, embedding, rerank, and search models through one NinjaChat account only.

## Capabilities

- Create chat completions with messages, tools, response_format, and a models list for fallback routing
- Send Anthropic-compatible requests to /messages with model, max_tokens, and messages
- Generate images from a prompt and start video jobs with duration, aspect_ratio, and reference media
- Create embeddings, rerank documents against a query with top_n, and generate speech from text with a chosen voice
- Search the web with query, max_results, search_depth, and include_answer
- Compare several chat models on one prompt and chain up to five chat, image, and video steps in one pipeline
- Create, rotate, and revoke API keys and set project monthlyBudgetCents through the management endpoints

## Use cases

### Multi-model agent backend through Jentic

An agent that needs a language model for sub-tasks searches Jentic for 'create a chat completion', gets the NinjaChat chat completions schema, and posts messages with a models list so the gateway can fall back if the first model is unavailable. It can read the request trace by ID afterwards to see which model answered and what it cost.

Example prompt: Search Jentic for 'create a chat completion', call POST `/chat/completions` with messages=[{role:'user',content:'Summarise this ticket'}] and a models list of two model IDs from GET /models, then call GET `/requests/{id}` for the returned request

### Retrieval with embeddings and reranking

Search and question-answering features need both recall and precision. POST /embeddings turns documents into vectors with an optional dimensions setting, and POST /rerank orders candidate documents against a query with top_n and return_documents, so an app can retrieve broadly and then keep only the most relevant passages.

Example prompt: Call POST /rerank with model, query='refund policy for annual plans', documents set to the ten retrieved passages, and top_n=3

### Image and video generation

Marketing and content tools can produce visuals from the same account. POST `/images/generations` takes a prompt with size, n, or aspect_ratio, and POST /videos starts an async video job with duration, aspect_ratio, and optional image_url or reference media; GET `/videos/{id}` reports progress, and a webhook can announce completion.

Example prompt: Call POST /videos with prompt='slow pan across a mountain lake at dawn', duration=5, aspect_ratio='16:9', then poll GET `/videos/{id}` until the job completes

### Spend control with keys and projects

Teams of one or a few developers still need budgets. The management endpoints, which need a separate management key, create projects with monthlyBudgetCents, issue keys with readOnly, expiresInDays, or their own budget, rotate or revoke keys, and read the audit log, so a runaway script cannot spend past its limit.

Example prompt: Call POST `/management/projects` with name='support-bot' and monthlyBudgetCents=2000, then POST `/management/keys` with name='support-bot-prod', the projectId, and expiresInDays=90

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/chat/completions` | Create a chat completion |
| POST | `/messages` | Create an Anthropic-compatible message |
| POST | `/embeddings` | Create embeddings |
| POST | `/images/generations` | Generate images |
| POST | `/videos` | Create a video job |
| GET | `/models` | List live models |
| POST | `/management/keys` | Create an API key |

## Key resources

- **Inference** — Chat completions, responses, Anthropic-compatible messages, presets, batch, and compare
- **Media and retrieval** — Images, video jobs, speech, embeddings, rerank, and web search
- **Models and pricing** — Live models, pricing, network availability, cost estimates, and model battle rankings
- **Account** — Usage, balance, request traces, sessions, pipelines, and webhooks
- **Management** — API keys, projects, budgets, webhooks, and the audit log under a management key

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 43 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 77 / 100
  - Developer Experience & Jentic Compatibility: 68 / 100
  - AI-Readiness & Agent Experience: 20 / 100
  - Agent Usability: 92 / 100
  - Security: 57 / 100
  - AI Discoverability: 59 / 100
- **View full report:** https://jentic.com/apis/ninjachat.ai/ninjachat/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring NinjaChat by hand means tracking which of three credentials each path needs: the inference key as a bearer, the x-api-key header for /messages, and a management key for /management/*. Through Jentic you install once, import NinjaChat from the API Directory, store each key once, and your agent calls it.
- **Permission scoping:** NinjaChat already splits inference keys from management keys, and the key and project ids sit in the URL path (`/management/keys/{id}`), so a rule can bound your agent to the operations you pick and to one key or project. You choose the operations it may call, so ones like key revocation or project archiving are not included unless you add them.
- **Credential handling:** Your NinjaChat keys are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a chat completion' or 'rerank documents', and Jentic returns the matching NinjaChat operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenRouter API** — Unified chat completions across many model providers
- **OpenAI API** — Direct access to OpenAI models for chat, images, audio, and embeddings
- **Anthropic Messages API** — First-party Messages API for Claude models
- **ElevenLabs API** — Voice generation and cloning beyond basic text to speech

## FAQ

### What authentication does the NinjaChat API use?

Per its OpenAPI spec, the NinjaChat API uses three credentials. Inference and account endpoints take a NinjaChat API key from the developer console as a bearer token. The /messages endpoint also accepts that key in the `x-api-key` header for Anthropic compatibility. The /management/* endpoints need a separate management key (format nj_mk_...) as a bearer token, and inference keys cannot call them. Public endpoints such as /models, /pricing, /health, and /estimate are open. Through Jentic, each key is stored encrypted by your own Jentic One instance and injected at call time.

### Can I use Anthropic-style requests with the NinjaChat API?

Yes. POST /messages is an Anthropic Messages compatibility endpoint that takes model, max_tokens, and messages, with optional system, tools, and stream. OpenAI-style clients use POST `/chat/completions` instead.

### What are the rate limits for the NinjaChat API?

The OpenAPI spec does not specify rate limits. Spend is metered instead: chat and responses bill actual token usage, images and videos use per-unit pricing, and project and key budgets cap spend. Check https://www.ninjachat.ai/developers for current limits.

### How do I generate an image with the NinjaChat API through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, add NinjaChat from the Jentic API Directory, and store your NinjaChat API key. Your agent searches for 'generate an image', calls POST `/images/generations` with a prompt and size, and can call POST /estimate first to preview the cost. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the NinjaChat API?

Yes. Store only the inference key, and write a rule that allows POST `/chat/completions`, POST /embeddings, and GET /models. The agent can then call models and read the model list, but it cannot start video jobs, register webhooks, or reach any /management/* operation, since it holds no management key.

### Is there a NinjaChat MCP server?

You don't need an MCP server to give your agent the NinjaChat API. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls it, discovering operations on demand rather than loading all of them into its context.

### Can I see how much a NinjaChat request will cost before sending it?

Yes. POST /estimate is a public pre-flight estimate that does not deduct credits, and GET /pricing returns the live price sheet. After a call, GET `/requests/{id}` returns the request trace.