Nirvani AI API

Base URL https://api.nirvani.ai/v1. Send your key as Authorization: Bearer nvk_... and POST chat requests to /chat/completions. The format is the standard chat-completions format, so existing code works after you change the base URL.

Quickstart

Three steps, about two minutes.

Get a free test key. It arrives by email and is shown nowhere else.
Save it as an environment variable: export NIRVANI_API_KEY=nvk_test_...
Make a call:

curl https://api.nirvani.ai/v1/chat/completions \
  -H "Authorization: Bearer $NIRVANI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nirvani-flash","messages":[{"role":"user","content":"Hello"}]}'

Authentication

Every request to /chat/completions and /usage needs a key in the Authorization header. Keys start with nvk_test_ (free tier) or nvk_live_ (production). A missing, unknown or turned-off key returns HTTP 401.

Keep keys on your server. Never ship a key inside browser or mobile app code.

Models

Pass the model ID in the model field. GET /v1/models returns the live list without a key.

Model ID	Best for	Context	Max output
`nirvani-flash`	Fast, capable default for chat, support and agents	1,000,000	8,192
`nirvani-flash-lite`	Lowest cost for classification, routing and summaries	1,000,000	8,192
`nirvani-pro`	Deepest reasoning and writing quality	200,000	8,192
`nirvani-open`	Open-weights workloads	128,000	4,096

Chat completions

POST /v1/chat/completions generates the next assistant message.

Request body

Field	Type	Notes
`model`	string	Required. A model ID from the table above.
`messages`	array	Required. Up to 200 items, each with `role` (`system`, `user` or `assistant`) and text `content`. Include at least one user message.
`stream`	boolean	Default `false`. When `true`, tokens arrive as server-sent events.
`max_tokens`	integer	Cap on output tokens. Values above the model maximum are lowered to it.
`temperature`	number	0 to 2. Lower is more focused.
`top_p`	number	Greater than 0, up to 1.
`stop`	string or array	Up to 4 stop sequences.
`stream_options.include_usage`	boolean	With streaming, sends a final chunk carrying token usage.

Response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1793404800,
  "model": "nirvani-flash",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help?" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 7, "total_tokens": 16 }
}

finish_reason is stop when the model finished, length when it hit max_tokens, or content_filter when the request was blocked for safety.

Streaming

Set "stream": true. The response is text/event-stream: one data: line per chunk, ending with data: [DONE]. Each chunk carries new text in choices[0].delta.content.

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"nirvani-flash","choices":[{"index":0,"delta":{"content":"Hel"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"nirvani-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

If the model fails after streaming starts, you receive one chunk with an error object, then [DONE].

Usage

GET /v1/usage returns live numbers for the calling key: requests, tokens, average latency and error rate today, hourly counts for the last 24 hours, a breakdown by model, recent requests, and tokens used against your monthly quota. The console shows the same data.

curl https://api.nirvani.ai/v1/usage -H "Authorization: Bearer $NIRVANI_API_KEY"

Limits and quotas

Key	Requests per minute	Tokens per month
Test (`nvk_test_`)	20	100,000
Live (`nvk_live_`)	120	5,000,000

Rate limits are applied per key at each edge location, so short bursts can briefly exceed them. Monthly quotas reset at 00:00 UTC on the first of each month. For higher limits, reply to your key email.

Errors

Errors return JSON: {"error": {"message": "...", "type": "...", "code": "..."}}. The message always says what happened and what to do.

Status	Type	Meaning
400	`invalid_request_error`	The body is malformed or a parameter is out of range.
401	`invalid_request_error`	The key is missing, unknown or turned off.
404	`invalid_request_error`	The model or endpoint does not exist.
413	`invalid_request_error`	The request body is larger than 512 KB.
429	`rate_limit_error`	Too many requests per minute on this key. Retry after a short wait.
429	`quota_exceeded`	The key used its monthly tokens. Upgrade to a live key.
502	`upstream_error`	The model hit a snag. Retry with backoff.
503	`capacity` or `model_unavailable`	The model is busy or not available. Retry or switch tiers.
504	`timeout`	The model took too long. Retry or lower `max_tokens`.

Using an existing SDK

Any client that speaks the chat-completions format works. Set two values:

Base URL: https://api.nirvani.ai/v1
API key: your nvk_ key

Then use a Nirvani model ID such as nirvani-flash. No other code changes are needed for text chat and streaming.

Key security

Your key is shown once, in the email that delivers it. Nirvani stores only a SHA-256 hash.
Each key has its own rate limit, quota and usage history, so one leaked key cannot affect another.
Lost a key or think it leaked? Reply to your key email and it will be turned off and replaced.