vaaya / docs / reference

LLMs

One OpenAI-compatible endpoint for 300+ models, including Kimi, GPT, Gemini, Claude, DeepSeek, Llama and Qwen, billed per token from your Vaaya balance. No per-vendor keys, no subscriptions: the same Vaaya API key that runs every other service is your LLM key.

The router

Base URL

https://vaaya.ai/api/llm/v1

Endpoint

POST /chat/completions (OpenAI-compatible)

Price

per token, metered from your balance

Models

300+: any OpenRouter slug, or a Vaaya tier alias

The router speaks the OpenAI chat-completions wire format, so any OpenAI SDK works unchanged: set base_url and pass your key as the api_key. Streaming (stream: true) is supported. max_tokens defaults to 4096 and caps at 16384.

curl -X POST https://vaaya.ai/api/llm/v1/chat/completions \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vaaya/mid",
    "messages": [{"role": "user", "content": "Summarize the tradeoffs of edge vs regional compute."}]
  }'

Or with the OpenAI SDK:

from openai import OpenAI

client = OpenAI(
    base_url="https://vaaya.ai/api/llm/v1",
    api_key=os.environ["VAAYA_API_KEY"],  # your Vaaya API key
)

resp = client.chat.completions.create(
    model="anthropic/claude-opus-5",
    messages=[{"role": "user", "content": "Review this migration plan for failure modes: ..."}],
    stream=True,
)

When to use which

Routing rules that hold up: default to vaaya/mid for general work. Drop to vaaya/cheap for anything mechanical (summarization, extraction, reformatting), where the cheap tier is effectively free. Reserve vaaya/best for hard reasoning and for cross-checking answers that matter; a rival frontier model is the cheapest form of review you can buy.

Tiers and model slugs

model accepts either an exact OpenRouter slug or one of three Vaaya tier aliases: vaaya/cheap, vaaya/mid, vaaya/best. A tier is an ordered fallback list of current models, so a single-vendor outage never fails your call. The lists track the market, so you inherit upgrades without code changes.

GET /api/llm/v1/pricing (free, no auth) returns the current tier composition and per-model prompt/completion pricing in USD per million tokens. Not sure of a slug? Ask the router itself: one vaaya/cheap call with “what is the OpenRouter slug for Kimi K3?” costs a fraction of a cent.

Direct vendor endpoints

The router above stays the default for LLM calls. Reach for a direct vendor endpoint when you need the vendor’s native request shape (tool use, response_format, vision fields) or a model the router does not carry. Each one is an ordinary catalog action: POST /api/run/{service}/{action} with the vendor’s standard params and your Vaaya key. No vendor key, no vendor account.

Pricing is dynamic. Each call settles over MPP at the vendor’s actual charge for the model and tokens used, capped at $1 per call.

curl -X POST https://vaaya.ai/api/run/anthropic/messages \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Name three failure modes of retry storms."}]
  }'

openai/image-generate (about 5¢) also exists for callers who want OpenAI images specifically. For image work in general, the fal actions on Media generation are the better default.

Powering a voice agent

A self-hosted voice agent (Dograh, Pipecat, LiveKit Agents) usually names its three legs separately: speech-to-text, a model, and text-to-speech. Point the model leg at the router and it runs on your Vaaya balance with no OpenAI account. In most stacks that is three fields in a config file, not an integration.

# Any stack that speaks OpenAI chat-completions
llm:
  provider: openai
  base_url: https://vaaya.ai/api/llm/v1
  api_key: ${VAAYA_API_KEY}
  model: google/gemini-2.5-flash-lite

For live conversation the number that matters is time to first token, because the pipeline starts speaking as tokens arrive. Total completion time is irrelevant if the first word is late. Measured from a us-east host in August 2026:

• Never pick a reasoning model for a spoken turn. It spends its token budget thinking before emitting anything, so a small max_tokens returns an empty string: 128 reasoning tokens with max_tokens: 60 produces no content at all.
• Latency is dominated by the model you chose and by your distance from us-east, not by the router. Measure from where your pipeline actually runs, not from your laptop. A laptop on another continent can add 400ms that production never pays.
• Different agents can run different models on the same key, so a latency-sensitive assistant and a batch summarizer need one account between them.

Gotchas

• Calls are stateless one-shots: there is no server-side conversation. Carry the full message history in messages on every call, exactly as with any OpenAI-compatible API.
• A $10/day per-account inference cap applies. Hitting it returns 429 with a Retry-After header. See Errors & billing.
• Token billing is metered from your credit balance like every other call and itemized on your transactions. There is no separate LLM account.
• Not for images, audio, or video. Generation models live behind their own endpoint with per-call pricing. See Media generation.