# Nirvani AI

> Nirvani AI is a free AI business advisor for owners of small and mid-sized businesses, built by Nirvani Company (Scottsdale, Arizona). Owners ask about marketing, sales, cash flow, pricing, hiring, operations, customer experience, accounting and legal basics, and AI automation, and get a direct recommendation with the reasoning, the tradeoffs and a next step. It is free at https://ask.nirvani.ai with no sign-up. Nirvani AI is also one API for leading AI models (base URL https://api.nirvani.ai/v1) in the standard chat-completions format, with streaming, per-key rate limits, monthly token quotas and live usage metering.

Key facts:
- For owners: ask in plain words at https://ask.nirvani.ai or https://ask.nirvani.ai/chat/. Conversation history stays in the browser tab; Nirvani's servers log usage counts and timing, not message text. For tax, legal, lending and licensing decisions it gives general guidance and recommends confirming with a CPA, attorney or licensed advisor.
- Nirvani's AI agents: the AI Receptionist, AI Live Voice Agent, AI Live Chat Agent, AI Instagram Agent, AI Facebook Agent, AI Sales Rep, AI Follow-Up Specialist, AI Reviews Manager, AI Multilingual Concierge, AI Executive Assistant, AI Operations Manager and custom AI agents answer calls and messages, follow up on leads, book appointments and request reviews around the clock. Owners can request a free AI Business Diagnostic at https://ask.nirvani.ai/#diagnostic. See https://nirvani.ai.
- For developers, authentication: `Authorization: Bearer nvk_test_...` or `nvk_live_...`. Keys are shown once by email and stored only as SHA-256 hashes.
- Models: `nirvani-flash` (fast default), `nirvani-flash-lite` (lowest cost), `nirvani-pro` (deepest reasoning and writing), `nirvani-open` (open weights). Live list: `GET https://api.nirvani.ai/v1/models` (no key needed).
- Test keys: 20 requests per minute and 100,000 tokens per month. Live keys: 120 requests per minute and 5,000,000 tokens per month, set up per business.
- Existing chat-completions SDKs work after setting the base URL to https://api.nirvani.ai/v1.

# 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](https://ask.nirvani.ai/get-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](https://ask.nirvani.ai/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.