LLM API guide
Stream chat completions
Use the standard Wave URL and your dashboard API key to stream Gemma responses from your application.
Configure access
Base URL: https://api.dotwave.ai/v1. Model: gemma4-bf16. Manage and revoke keys in API keys. Keep keys on your application server. Gemma access must be enabled for your project.
Project access hours use the timezone shown in your dashboard and follow daylight-saving changes. Your usage history remains readable outside generation hours.
Conversation affinity
Send X-Session-Affinity with the same opaque conversation ID on every turn, including tool-result continuations. Create a different ID for each new call. A LiveKit room SID or a random UUID works; avoid names, phone numbers, email addresses or other personal data. Accepted values contain 1–256 ASCII letters, digits, periods, underscores, colons or hyphens.
The assignment belongs to your project and model, so rotating your API key keeps it. API restarts and added capacity preserve active assignments. If the assigned service becomes unavailable, Wave returns an error and does not switch the conversation automatically. After 24 hours without a routing attempt, a new assignment is allowed. Without the header, requests are routed independently.
Affinity helps reuse matching prompt prefixes. It does not guarantee cache hits or retain your conversation: send the relevant message history and tools with every request.
Python
Install openai and set DOTWAVE_API_KEY. Automatic SDK retries are disabled in this example so your application controls retry and fallback decisions.
import os
from openai import OpenAI
from uuid import uuid4
conversation_id = str(uuid4()) # Keep this value for the whole conversation.
client = OpenAI(
base_url="https://api.dotwave.ai/v1",
api_key=os.environ["DOTWAVE_API_KEY"],
max_retries=0,
timeout=30.0,
)
stream = client.chat.completions.create(
model="gemma4-bf16",
messages=[{"role": "user", "content": "Say hello in French."}],
stream=True,
max_tokens=80,
reasoning_effort="none",
stream_options={"include_usage": True},
extra_headers={"X-Session-Affinity": conversation_id},
)
try:
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="", flush=True)
if chunk.usage:
print("\nUsage:", chunk.usage.model_dump())
finally:
stream.close()TypeScript
Install openai. Run this example on your server.
import OpenAI from 'openai';
import {randomUUID} from 'node:crypto';
const conversationId = randomUUID(); // Keep it for every turn of this call.
const client = new OpenAI({
baseURL: 'https://api.dotwave.ai/v1',
apiKey: process.env.DOTWAVE_API_KEY,
maxRetries: 0,
timeout: 30_000,
});
const controller = new AbortController();
const stream = await client.chat.completions.create({
model: 'gemma4-bf16',
messages: [{role: 'user', content: 'Say hello in French.'}],
stream: true,
max_tokens: 80,
reasoning_effort: 'none',
stream_options: {include_usage: true},
}, {signal: controller.signal, headers: {'X-Session-Affinity': conversationId}});
for await (const chunk of stream) {
if (chunk.choices.length) process.stdout.write(chunk.choices[0].delta.content ?? '');
if (chunk.usage) console.log('\nUsage:', chunk.usage);
}
// Call controller.abort() when the caller cancels the turn.LiveKit Agents
Install livekit-agents[openai]==1.8.7 for this example. In your existing Python agent, use the OpenAI plugin with Wave's base URL and dashboard API key. This connects the LLM directly to Wave; your existing speech recognition, speech synthesis and turn detection can stay as configured.
import os
from livekit.agents import AgentSession, APIConnectOptions
from livekit.agents.voice.agent_session import SessionConnectOptions
from livekit.plugins import openai
def create_wave_llm(conversation_id: str) -> openai.LLM:
# Create one LLM instance per conversation; do not share it between rooms.
return openai.LLM(
model="gemma4-bf16",
base_url="https://api.dotwave.ai/v1",
api_key=os.environ["DOTWAVE_API_KEY"],
reasoning_effort="none",
max_completion_tokens=80,
max_retries=0,
extra_headers={"X-Session-Affinity": conversation_id},
)
def create_wave_session(conversation_id: str, *, stt, tts, vad):
return AgentSession(
llm=create_wave_llm(conversation_id),
stt=stt,
tts=tts,
vad=vad,
conn_options=SessionConnectOptions(
llm_conn_options=APIConnectOptions(max_retry=0, timeout=30.0),
),
)In your entrypoint, connect to the room first, then call create_wave_session(ctx.room.sid, stt=your_stt, tts=your_tts, vad=your_vad) and start it with your existing agent and room. Keep the room SID for all turns and tool continuations, including reconnects to that same conversation. Construct a separate LLM for each conversation so headers cannot leak between callers. A new room/conversation uses a new ID.
The plugin sends streaming chat requests, tools and native usage. Both the OpenAI client retry and LiveKit's LLM retry are disabled here. Wave returns errors to your agent; configure any fallback in your own agent. Handle the session's error event and interrupted streams. A 30-second client timeout is a request timeout, not a latency guarantee.
Function tools
Send a tools array with function names and JSON schemas, and tool_choice: "auto" (or a named function). Accumulate each streamed call's argument fragments by index. Parse its JSON only after the call completes.
{
"tools": [{"type": "function", "function": {
"name": "lookup_order", "description": "Look up an order by ID",
"parameters": {"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]}
}}],
"tool_choice": "auto"
}Your application executes the function. For the next request, append the assistant's tool_calls message, then a role: "tool" message with the matching tool_call_id and the result. Wave does not execute tools.
Once output or a tool call has started, do not automatically replay the request. A replay could produce duplicate actions.
Usage and cache
Request stream_options: {"include_usage": true}. The final usage event reports prompt_tokens, completion_tokens and, when available, prompt_tokens_details.cached_tokens. Usage events may have an empty choices list.
Read your project's numeric history from GET /v1/usage/llm or LLM usage. The default period is 24 hours; since accepts Unix seconds, limited to the last 31 days. Results include totals and up to 100 recent requests.
Cache reuse depends on shared prompt prefixes and can change. It is not guaranteed to be 100%. Unknown token counts remain unknown after cancellations or interrupted responses. Prompts, generated text and function arguments are not stored in this usage history.
Errors and interrupted streams
| HTTP | Meaning | Action |
|---|---|---|
| 400 | Invalid request | Check the model, messages, streaming option and parameters. |
| 401 | Invalid or revoked key | Check the key in the dashboard. |
| 403 | Model access disabled or outside service hours | Check project access and the configured timezone. |
| 429 | Service busy | Apply your application's retry or fallback policy. |
| 502 / 503 / 504 | Generation failed, unavailable or timed out | Handle the failure in your application. |
Before the first output, failures return a non-200 response. After HTTP 200 and streaming output have begun, the HTTP status cannot change: an interrupted stream is a failure. At the raw SSE level, require the terminating [DONE] event. With an SDK, also handle stream exceptions and missing completion/finish events.
Wave makes one generation attempt and does not perform provider fallback. Your application decides how to retry or use another API. Include X-Wave-Request-Id from the response when contacting support.
Client references
Python client · TypeScript client · Gemma parameters · Wave API reference