API reference
Anthropic-compatible API
POST /messages takes Anthropic's Messages format, so the Anthropic SDKs and Anthropic-format clients such as Claude Code work by setting the base URL to https://api.vani.ai (the SDKs add /v1/messages) and using a Vani key. Any model GET /models lists can be called this way, not only Claude.
- SDK base URL
- https://api.vani.ai (without /v1)
- Endpoints
- POST https://api.vani.ai/v1/messages · /messages/count_tokens
- Authentication
- x-api-key or Authorization: Bearer
- Version header
- anthropic-version: 2023-06-01 (optional; another value is refused)
On this pageQuickstart
Quickstart
Create a Vani key, then give the Anthropic SDK Vani's origin as its base URL. max_tokens is required, as on Anthropic's API.
Python (Anthropic SDK)
import os
from anthropic import Anthropic
client = Anthropic(base_url="https://api.vani.ai", api_key=os.environ["VANI_API_KEY"])
message = client.messages.create(
model="anthropic/claude-sonnet-5.5", # any id from GET /models
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
print(message.content)TypeScript (Anthropic SDK)
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ baseURL: "https://api.vani.ai", apiKey: process.env.VANI_API_KEY });
const message = await client.messages.create({
model: "openai/gpt-6-sol", // any id from GET /models
max_tokens: 1024,
messages: [{ role: "user", content: "Hello" }],
});
console.log(message.content);curl
curl "https://api.vani.ai/v1/messages" \
-H "x-api-key: $VANI_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model":"anthropic/claude-sonnet-5.5","max_tokens":256,"messages":[{"role":"user","content":"Hello"}]}'Supported
- Text and system blocks,
tool_useandtool_result, tool definitions andtool_choice,max_tokens,stop_sequences, and streaming and non-streaming answers. stop_sequencesend the answer before the first sequence that completes, streamed or not, and the answer reportsstop_reason: "stop_sequence"with that sequence instop_sequence(on a stream, inmessage_delta); tool calls after it are dropped. Claude models stop at a sequence themselves without saying why: their answer also ends before it, but reportsstop_reason: "end_turn"andstop_sequence: null.- MCP servers:
mcp_serverswith theanthropic-betaheadermcp-client-2025-11-20(mcp-client-2026-09-15andmcp-client-2025-04-04are accepted too). - The web search and web fetch server tools (
web_search_20250305,web_fetch_20250910): Vani runs them and answers with Anthropic'sserver_tool_use,web_search_tool_resultandweb_fetch_tool_resultblocks. USD 0.005 per search on top of tokens; page reads cost tokens only. thinkingsets the reasoning effort unlessoutput_config.effortdoes. Thinking blocks are not returned;usage.output_tokens_details.thinking_tokenssays how much of the output was reasoning.- Claude Code's
safeguards(a request for Anthropic's server-side auto mode classifier) and a message's ownoutput_configare accepted and not used: Vani runs no such classifier, so Claude Code's auto mode decides with its local classifier, and the request'soutput_config.effortis the effort that applies. cache_controlhints on system and user text blocks are passed to the model's provider where it takes them (x-vani-cache-hints: forwarded); a cache hit is never guaranteed, andusage.cache_read_input_tokensshows what was billed as cached.POST /messages/count_tokensreturns a local estimate (x-vani-token-count: local-estimate); billing uses the provider's usage. The estimate can be well below the provider's count, most of all with tools: providers add their own tool instructions (often a few hundred tokens) and count text differently.- A stream's
message_startcarries this estimate of the prompt;message_deltaat the end has the provider's figures.
Claude Code
Claude Code talks to the Messages endpoint. Set ANTHROPIC_BASE_URL to Vani's origin without /v1 and ANTHROPIC_API_KEY to your Vani key (never an Anthropic key), choose any model id, and keep your normal permission settings. Claude Code's WebSearch tool works as it does on Anthropic's API, with every model: Vani runs each search (USD 0.005 per search). These are the settings tested in the Claude Code guide:
Claude Code environment
export ANTHROPIC_BASE_URL='https://api.vani.ai'
export ANTHROPIC_API_KEY='vani_YOUR_VANI_API_KEY'
export ANTHROPIC_MODEL='openai/gpt-6-sol'
export CLAUDE_CODE_DISABLE_THINKING=1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1
export ENABLE_TOOL_SEARCH=falseWhat differs from Anthropic's API
- Model ids name their maker, for example
anthropic/claude-sonnet-5.5oropenai/gpt-6-sol. Anthropic's own ids, such asclaude-sonnet-5-5, are accepted when they name exactly one model your key can use. imageblocks (base64 or url) work with models that can see, anddocumentblocks (a PDF as base64 or url, plain text, or content) with every model, in user messages and tool results: the model reads a document's text, and citations are not returned. An image for a model that cannot see is refused with 400 before a model runs, so nothing is billed. See Images and PDFs on the API.- Of Anthropic's server tools, web search and web fetch run on Vani (see Web search and web fetch tools); the others, such as code execution, are refused with 400.
anthropic-betavalues are accepted; a header alone changes nothing. A beta feature Vani does not support is refused with 400 when the request uses it (its blocks, tools or fields). The MCP betas are listed above.- Refusals use Anthropic's error shape plus Vani's
code(for exampleinvalid_token,api_insufficient_balance,model_not_available), as the OpenAI-format endpoints carry it;model_not_availablemay adddetails.suggestion. A provider failure is a 500api_error. top_kis accepted and ignored.
Note
Model ids, limits, headers and usageImages and PDFs on the APIAPI prices per model
More reference: OpenAI-compatible API · Model ids, limits, headers and usage · Images and PDFs on the API · MCP tools on the API · Web search and web fetch tools · Media API: images and videos · Artifacts API · Responses API: scope and limits · Model changes: webhooks, feeds and the changes API · API overview · Docs and quickstart