Base URL
https://api.vani.ai/v1Include /v1 once. Select the API format documented in your client's guide.
New: DeepSeek V4.1 Flash Derisked. In chat and on the API.
See modelsWhat's newReport a bugVani documentation
Connect your preferred client, build with the API, or get more from chat. Start with configuration examples and a clear view of what each integration supports.
Connect with three values: a base URL, your API key, and an enabled model identifier. Vani exposes bounded Chat Completions, stateless Responses and Anthropic Messages adapters at the endpoint below.
https://api.vani.ai/v1Include /v1 once. Select the API format documented in your client's guide.
Create a key in Developer settings (Plus and higher plans) or on the API platform (prepaid) after verifying your account. Keep it in your client's secret field or environment.
openai/gpt-6-solA starting example. GET /models returns the models available to your account.
Important
For pay-as-you-go access, open the API platform to manage prepaid keys, check your balance, and see API usage by model and key for today, 7, 30 or 90 days. Eligible API models cost 30% below their verified official rates; private models priced directly by Vani are labelled “Vani price”. Rates include source references and context tiers; unavailable rates are never treated as free.
export VANI_BASE_URL="https://api.vani.ai/v1"
export VANI_MODEL="openai/gpt-6-sol"
# Set VANI_API_KEY in your shell secret store or environment.
# Use the API origin shown here, ending in /v1 once.
# The website /chat and /api/chat routes are not this API base.
# Start by fetching /models; that check does not invoke inference.curl --fail-with-body "$VANI_BASE_URL/models" \
-H "Authorization: Bearer $VANI_API_KEY"
# Use an exact data[].id from this account-scoped response.Use an exact data[].id from the authenticated model list as VANI_MODEL. The examples start with openai/gpt-6-sol; change it when needed. Model access is account-specific; disabled inference can still prevent a request.
curl --fail-with-body "$VANI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"openai/gpt-6-sol","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":256,"stream":false}'Note
A curated set of 15 popular clients and coding tools. Each guide separates supported API settings from features that need an adapter or extra validation.
15 of 15 guides · Popular coding and chat clients.
Configure a named custom provider using Hermes' documented Chat Completions transport.
Use the Codex CLI with Vani’s stateless Responses adapter, including local function and namespaced custom tools.
Add Vani as a custom provider with the OpenAI-compatible Chat Completions package.
Connect Claude Code to Vani’s Anthropic Messages adapter for text, streaming and client-executed tools.
Cursor's current official BYOK guide documents provider keys, but does not verify this custom Vani endpoint or GPT-6 Sol.
Use Cline's OpenAI Compatible provider and the exact Vani model identifier.
Configure a Chat-only OpenAI-compatible model and explicitly disable automatic Responses routing.
Point Aider's OpenAI-compatible transport at Vani and preserve the exact Vani model ID.
A fast code editor with its own agent and configurable OpenAI-compatible model providers.
Connect the OpenClaw agent runtime to Vani through a custom Chat Completions provider.
Use an admin-managed OpenAI-compatible connection with the Vani model allowlist.
Add Vani as a custom OpenAI-compatible endpoint using a minimal request baseline.
Configure the OpenAI-compatible provider and an exact custom Vani model id.
Use a custom OpenAI endpoint for ordinary chat; preserve the Vani model prefix.
Choose the Generic OpenAI LLM provider for text chat while keeping document indexing separate.
Note
Media library is an archive of generated results, while creation stays in chat.
Choose Search in the composer when you need current information. The submitted message becomes the search query; typing alone does not start a search.
Start a saved evidence job from Research history or confirm a research action proposed in chat. Follow its progress, cancel it if needed, and return to saved sources. The composer's Research mode can also add evidence to a message; it does not by itself promise a separate saved job.
Source links and citations help you check the evidence. Search results and web pages are untrusted reference material, and generated summaries can be incomplete or wrong. Open the cited source before relying on a claim.
Note
Create a Project for related conversations and reusable instructions. Changes apply to future sends; they do not rewrite saved messages or a request already being processed.
Resolve active work before branching. A missing or expired original attachment can block a draft. After an uncertain send, refresh saved results instead of repeatedly generating the same draft.
Your subscription allowance is shared across available models and conversations. The app applies both billing-period and weekly limits, along with request-rate and concurrency limits. A higher plan changes configured capacity; it does not guarantee a fixed number of messages, tokens or images.
Your usage dashboard offers Today, 7 days and 30 days as UTC calendar windows including today. Request counts use their start date; token and allowance records use settlement time, so activity spanning midnight can appear on different days.
| Feature | Supported behavior |
|---|---|
| Endpoints | API-key access at https://api.vani.ai/v1: GET /models; POST /chat/completions, /responses, /messages and /messages/count_tokens; media at /images/generations, /images/edits and /videos (prepaid keys); documents, slides and designs at /artifacts (plan-billed keys). Every route requires a Vani API key; browser session cookies do not authenticate API calls. The API reference (/docs/api) covers each in detail. |
| Account and keys | Verify your email address, then create a key under API keys on the API platform (prepaid balance) or in Developer settings in Vani Chat (plan allowance; Plus and higher plans). Keep keys in a secret store or environment variables, never in browser code. Keys can be renamed, and a prepaid key can have a monthly spend limit; a request the rest of the limit cannot cover gets 402 api_key_spend_limit_reached. |
| Model ids | Use an id from GET /models, such as anthropic/claude-sonnet-5.5. A vendor's own id (claude-sonnet-5-5, a dated id, Bedrock's or Vertex's form) is served as the Vani model it names when it names exactly one model your key can use; the answer then carries x-vani-model-routed-from. GET /models also gives each model's created time, context length, largest output (top_provider.max_completion_tokens) and, for prepaid keys, pricing in USD per token. For prepaid keys it lists the image and video models too: their context and output limits are null, their pricing is per image, second or video, and their ids go to the media endpoints, not the chat endpoints. |
| Chat Completions | Text strings or content parts; user, assistant, system and tool messages. developer is normalized to system. User messages can also carry image_url parts (for models that can see) and file parts with a PDF in file_data (see Images and PDFs). Use max_completion_tokens or max_tokens, never both. Up to 512 function schemas and matching tool results are accepted. |
| Common client controls | stop accepts one string or up to four nonempty sequences totalling at most 1,024 UTF-8 bytes; the answer ends before the first one (finish_reason stop) on every model. Some models do not always keep to stop or to the output limit and write on past them: the text after a stop sequence is not returned, and a prepaid key is never charged more than the prompt and the output limit can cost (set an output limit when you rely on stop). parallel_tool_calls: false limits a reply to one tool call; true is the default. frequency_penalty and presence_penalty accept finite values from -2 to 2. Model support still varies. n may be omitted or 1; store must be false or null. user is bounded metadata, ignored for authentication and not forwarded. |
| Stateless Responses | Text, image and PDF input (input_image for models that can see, input_file) and instructions, full explicit message history, function/custom tool calls and results, namespaced tools, MCP tools, structured output (text.format), streaming and non-streaming output. Use max_output_tokens and store:false (or no store). Resend complete input for each call: there is no previous_response_id, stored conversation, background mode or response retrieval, no hosted file search or image generation, and no file_id references. The web_search tool runs on Vani (see Web search tools). Custom grammar hints are advisory, not a guarantee of grammar-constrained generation. |
| Anthropic Messages | Text/system blocks, image blocks (for models that can see) and document blocks (the model reads their text), tool_use/tool_result, tool definitions and tool_choice, max_tokens, stop_sequences, streaming and non-streaming output, and MCP servers (mcp_servers with the anthropic-beta header mcp-client-2025-11-20; mcp-client-2026-09-15 and the older mcp-client-2025-04-04 are accepted too). The web_search and web_fetch server tools run on Vani (see Web search tools); other server tools are refused. thinking sets the reasoning effort unless output_config.effort does: disabled asks for the lowest effort (most models still think a little), enabled with budget_tokens for the effort of that budget; thinking blocks are not returned, usage.output_tokens_details.thinking_tokens says how much output was reasoning. stop_sequences end the answer before the first sequence that completes, and the answer reports stop_reason stop_sequence with that sequence in stop_sequence (in message_delta on a stream); tool calls after it are dropped. Claude models stop at a sequence themselves without saying why, so their answer ends before it but reports end_turn with stop_sequence null. Ephemeral cache_control hints on system and user text blocks are passed to the model provider where it takes them (response header x-vani-cache-hints: forwarded); hints elsewhere are accepted and ignored. A hint never guarantees a cache hit. top_k is accepted and ignored. |
| Web search tools | The providers' own web tools work with every chat model, the Derisked models included: web_search_20250305 and web_fetch_20250910 (and their later dated versions, such as web_search_20260209 from the Vercel AI SDK) on /messages (server_tool_use and web_search_tool_result / web_fetch_tool_result blocks, citations, usage.server_tool_use), web_search on /responses (web_search_call items, url_citation annotations) and web_search_options on /chat/completions (message.annotations). Vani runs each search and page read. A search costs USD 0.005 (USD 5 per 1,000) on top of tokens and a failed one nothing; page reads cost tokens only. Up to 8 uses of each tool per request; web_fetch reads only URLs you send or that earlier results brought, never one the model wrote. For apps that never send a web tool, add :online to the model id (zhipu/glm-5.3-derisked:online): the same model, with web search and page reading on every request. Apps that send plugins: [{"id":"web"}] get the same search (search only; max_results, include_domains, exclude_domains, search_prompt). The API reference (/docs/api/web-tools) has the fields, limits and answers. |
| Images and PDFs | Send images to models that can see (GET /models lists image in a model's architecture.input_modalities) and PDFs to any model: image_url and file parts on /chat/completions, input_image and input_file on /responses, image and document blocks on /messages, inline (base64 or a data URL) or as a public https URL. Images: PNG, JPEG, WebP or GIF, up to 20 MB each and 100 per request, sent to the model with their metadata removed and at most 2,048 pixels on the long side (larger ones are scaled down). PDFs: up to 10 MB each and 20 per request, read as text (a scan without text is refused; up to 20 MB of new PDFs per request). Files by URL: public https only, up to 16 per request and 64 MB in all. There is no Files API: file_id is refused. An image for a model that cannot see is refused with 400 model_does_not_support_images before anything is held. Images are billed as input tokens as the provider counts them; a prepaid hold counts 1,600 tokens per image, more for a large one. A request can get 503 media_busy when many files are being read at once: retry shortly. The API reference (/docs/api/images-and-pdfs) has the fields and limits. |
| Token count estimate | POST /messages/count_tokens returns a local token estimate and x-vani-token-count: local-estimate (it fetches no URL and reads no new PDF: an image counts as its hold does, a file by URL 1,600 tokens, a new PDF an estimate from its size). It does not invoke a model or replace provider-reported usage used for billing. |
| Streaming and errors | Read complete SSE frames and terminal events. HTTP 200 can be followed by an error. Reported usage depends on the provider; local estimates are labelled. Disconnecting requests cancellation, but completed output can still be settled. Use stream: true for long answers: a non-streaming answer that takes longer than about 100 seconds can be cut by the network edge (HTTP 524, no JSON body), and such a call is not charged. |
| Fast models | Where a model offers priority processing, GET /models lists a separate fast model, for example openai/gpt-6-astra-fast, with its own published rate. While one is listed, sending service_tier "priority" (or "fast") with the standard model is the same request at the same rate. auto and default are always accepted; other service tiers are refused. |
| Billing and persistence | Each completion is billed by its key: keys created in Vani Chat use the subscription allowance and limits; API platform keys use the prepaid balance at the published API rates. API calls are independent runs; retries do not promise Idempotency-Key replay protection. store:false does not erase operational, usage or security records. |
| Prompt caching | Prompt caching is automatic where the model's provider caches: repeating a long prompt prefix (system prompt, tools, earlier turns) within a few minutes makes the repeat cheaper. Cached input is billed at the cached-input price only when the provider reports a cache hit, and hits are not guaranteed. usage.prompt_tokens_details.cached_tokens (Responses: usage.input_tokens_details.cached_tokens; Messages: usage.cache_read_input_tokens) shows the prompt tokens billed at the cached-input price. Models marked “No cache discount” in the API price list have no cheaper cached-input price: cached input costs the input price there. |
| Structured output | Chat Completions response_format of type json_object or json_schema, and Responses text.format, are supported: the model is instructed to answer with a single JSON value that matches your schema (up to 32 KiB). Not every provider enforces a schema strictly, so validate the result in your client; the OpenAI SDK's parse helpers work. |
| Limits and headers | Each model has its own output limit (top_provider.max_completion_tokens in GET /models); a larger max_tokens is lowered to it and the answer carries x-vani-max-output-clamped. Every API-key answer carries x-ratelimit-limit/remaining/reset for requests and, for prepaid keys, tokens; a 429 adds Retry-After. Usage reports cached and reasoning tokens (reasoning is estimated where a provider does not count it). |
| Media and research | Image generation and edits and video jobs have their own endpoints (/images/generations, /images/edits, /videos; prepaid keys; see the media API reference). Chat's own media and research workflows are separate from client function tools: the chat adapters never run your functions, your client does. |
| Unsupported capabilities | No audio input on the chat adapters and no Files API (send images and PDFs inline or by URL); no embeddings; no hosted file search, code execution or computer tools (web search and web fetch run on Vani); no stateful Responses; no encrypted reasoning continuation or reasoning summaries; and one completion per request (n must be 1). An optional encrypted-content projection can be omitted by the Responses adapter; no encrypted state is fabricated. |
Important
The API reference covers model ids, limits, headers and usage, MCP tools on the API, the media API, the artifacts API and the Responses API's scope.
Chat Completions accepts function definitions, but your API client executes them. Vani does not automatically run arbitrary client functions. Validate the model’s proposed arguments, apply your own permissions, execute the function, then send the assistant tool call and a matching tool result in the next request.
{
"model": "openai/gpt-6-sol",
"messages": [
{
"role": "user",
"content": "What is the weather in Paris?"
}
],
"max_completion_tokens": 256,
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
],
"additionalProperties": false
}
}
}
],
"tool_choice": "auto"
}Every assistant tool call must have a matching result before another message. Built-in web research and media actions in the Vani chat UI are a separate workflow with saved action state. In Tool settings, Vani can create requested images and videos right away or ask first. Web tool proposals always require confirmation.
Use https://api.vani.ai/v1 as the base URL and exactly one /v1 prefix. Choose the endpoint matching the client protocol: chat/completions, responses or messages. Other paths are not exposed by the fixed gateway; an unknown path under /v1 answers a JSON 404 that names it.
Verify your email address before creating API keys or uploading files: open the link in the verification email, or request a new one from your account settings.
Keys created in Vani Chat use the plan's allowance and need the Plus plan or higher, to create and to use. Upgrade (existing keys work again), or create a prepaid key on the API platform.
This key reached its monthly spend limit. Raise or remove the limit under API keys, or use another key; the limit resets at the start of the next UTC month.
Choose the documented protocol for your client and use text/tool messages. Turn image input on only for models that can see (GET /models), and disable audio input, provider-only fields and stateful features. A custom base URL alone does not establish full compatibility.
Check key expiry or revocation. Create or manage keys in Developer settings.
No key was sent, or not as Authorization: Bearer <key>. x-api-key is read on /v1/messages only.
API keys cannot create, list, rename or revoke keys. Manage keys signed in: API keys in the console for prepaid keys, or Settings → Developer in Vani Chat for plan keys.
Check content parts (text, images for models that can see, PDFs), output limits, stop-sequence bounds, complete tool-call/result pairing and the adapter-specific field list. Validation failures are rejected before a billable run.
The model cannot see images. Choose a model whose GET /models entry lists image input, or remove the image. Nothing was held or billed.
Check the account model list and plan eligibility. A catalogue entry does not prove that inference is configured.
Wait for Retry-After when supplied, and pace requests with the x-ratelimit-remaining-* and x-ratelimit-reset-* headers. Avoid bursts; read and write requests have separate budgets and account limits still apply across clients.
Check both weekly and billing-period progress and reset times. 402 usage_limit_exceeded means the billing period; 429 weekly_limit_reached means the weekly window. Active work may reserve allowance before settlement.
A non-streaming answer took longer than about 100 seconds and the network edge closed the connection before it arrived. Nothing reached you, so it is not charged. Send it again with stream: true; streams stay open while the model works.
The model's provider failed (the code may also be upstream_timeout or upstream_unavailable). A request that delivered nothing is not charged; send it again after a short wait.
Check the status page and save the request reference. An HTTP 200 stream can still contain an error; inspect the stream and usage before retrying.
Before you retry
Idempotency-Key. A timeout can occur after work starts. Inspect saved usage and the request reference before issuing a new completion.Closing the compatibility stream requests cancellation; already produced output can still be settled. Read error frames even after HTTP 200. The status page separates recent model outcomes from low-sample or unknown observations. It shows Vani's recorded attempts, not official global provider uptime, and does not invent recovery estimates.
Saved chats, projects, uploaded files, research evidence and in-app updates use this deployment’s database and storage. Selected model providers and web sources may still receive the request data needed for inference or search. Self-hosted application storage does not mean inference runs on this server.
Temporary chat is not added to saved conversation history, but operational run, usage and security records can still exist. Files attached in a temporary chat are deleted when you leave it, or within a few hours at most (other uploads are kept for 30 days). This is not a zero-retention promise.
Use Help → Report a bug in the chat sidebar or the Settings header, or Report a bug beside a failed message. The report contains the text you enter, an optional page path and an optional request reference. Conversations and files are not attached automatically.
A request reference helps staff correlate operational metadata; it is not proof of request ownership. Keep secrets and sensitive content out of bug reports. Manage keys in Developer settings and review the privacy policy.