Chariot API
OpenAI-compatible HTTP endpoints for Chariot Tri and Chariot Audio, and a WebSocket for the Chariot Voice speech-to-speech agent.
Base URL: https://…. Every request and response on this service is recorded for evaluation.
Authentication
Send your key as a bearer token: Authorization: Bearer sk-…. This is what the OpenAI SDKs do with api_key. WebSocket clients that cannot set headers (browsers) can pass ?api_key=sk-… instead.
Each key has scopes (llm, audio, voice) and its own rate and concurrency limits. Ask the Chariot team for a key.
export CHARIOT_API_KEY=sk-...
export CHARIOT_BASE={{BASE}}Models
| Model | What it is | Endpoint |
|---|---|---|
chariot-tri | Text LLM: chat, reasoning (thinking mode), tool calls | POST /v1/chat/completions |
chariot-audio | Audio understanding: speech, sounds, music, emotion | POST /v1/chat/completions |
chariot-voice | Real-time speech-to-speech agent | WS /v1/voice |
chariot-voice-tri | The same voice agent, replying with Chariot Tri | WS /v1/voice?model=chariot-voice-tri |
curl $CHARIOT_BASE/v1/models -H "Authorization: Bearer $CHARIOT_API_KEY"
Chariot Tri (text)
The OpenAI Chat Completions format with "model": "chariot-tri". Supported fields:
messages(rolessystem,user,assistant,tool)stream,stream_options.include_usagetools(JSON Schema functions); the reply carriestool_callsandfinish_reason: "tool_calls"- Sampling:
max_tokens/max_completion_tokens,temperature,top_p,top_k,repetition_penalty,seed,stop - Thinking:
chat_template_kwargs: {"enable_thinking": true}(off by default); the reasoning comes back inreasoning_content nmust be 1. Other OpenAI fields are ignored.
curl $CHARIOT_BASE/v1/chat/completions \
-H "Authorization: Bearer $CHARIOT_API_KEY" -H "Content-Type: application/json" \
-d '{"model": "chariot-tri",
"messages": [{"role": "user", "content": "Namaste! What can you do?"}],
"max_tokens": 256}'from openai import OpenAI
import os
client = OpenAI(base_url="{{BASE}}/v1", api_key=os.environ["CHARIOT_API_KEY"])
r = client.chat.completions.create(
model="chariot-tri",
messages=[{"role": "user", "content": "भारत की राजधानी क्या है?"}],
max_tokens=256,
)
print(r.choices[0].message.content)
print(r.usage)Streaming
With "stream": true the reply is sent as server-sent events in the OpenAI chunk format, ending with data: [DONE]. Lines starting with : are keep-alive comments.
curl -N $CHARIOT_BASE/v1/chat/completions \
-H "Authorization: Bearer $CHARIOT_API_KEY" -H "Content-Type: application/json" \
-d '{"model": "chariot-tri", "stream": true, "stream_options": {"include_usage": true},
"messages": [{"role": "user", "content": "Write a haiku about Bengaluru traffic."}]}'stream = client.chat.completions.create(
model="chariot-tri",
messages=[{"role": "user", "content": "Tell me about the Konark Sun Temple."}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)Thinking
r = client.chat.completions.create(
model="chariot-tri",
messages=[{"role": "user", "content": "If 3 pens cost 45 rupees, what do 7 pens cost?"}],
max_tokens=2048,
extra_body={"chat_template_kwargs": {"enable_thinking": True}},
)
msg = r.choices[0].message
print(getattr(msg, "reasoning_content", None)) # the reasoning
print(msg.content) # the answerWhen streaming, reasoning arrives in delta.reasoning_content before the answer's delta.content.
Tools
import json
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Current weather for a city",
"parameters": {"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]},
},
}]
messages = [{"role": "user", "content": "What's the weather in Pune right now?"}]
r = client.chat.completions.create(model="chariot-tri", messages=messages, tools=tools)
msg = r.choices[0].message
if msg.tool_calls:
messages.append(msg.model_dump(exclude_none=True))
for call in msg.tool_calls:
args = json.loads(call.function.arguments) # {"city": "Pune"}
result = {"city": args["city"], "temp_c": 27, "sky": "clear"}
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
r = client.chat.completions.create(model="chariot-tri", messages=messages, tools=tools)
print(r.choices[0].message.content)Long generations (thinking on, large max_tokens) can take minutes; set your client timeout to at least 600 s, or use stream: true to see tokens as they arrive.
Chariot Audio
The same endpoint with "model": "chariot-audio". Put the audio and the question in the user message's content parts:
{"type": "input_audio", "input_audio": {"data": <base64>, "format": "wav"}}. Formats: wav, flac, mp3, ogg/opus, webm, m4a.{"type": "audio_url", "audio_url": {"url": "data:audio/wav;base64,…"}}. Onlydata:URLs are accepted. Remote URLs and file paths are rejected with 400.{"type": "text", "text": "…"}
Up to 600 s per clip. Decoding is greedy (sampling fields are ignored), max_tokens is at most 512, and thinking works through chat_template_kwargs. stream: true is accepted, but the answer arrives in one piece.
import base64
b64 = base64.b64encode(open("clip.wav", "rb").read()).decode()
r = client.chat.completions.create(
model="chariot-audio",
max_tokens=512,
messages=[{"role": "user", "content": [
{"type": "input_audio", "input_audio": {"data": b64, "format": "wav"}},
{"type": "text", "text": "Transcribe the speech, then describe the speaker's emotion."},
]}],
)
print(r.choices[0].message.content)# curl + jq (the audio is read from a file, so large clips are fine)
jq -n --rawfile b64 <(base64 -w0 clip.wav) '{model: "chariot-audio", max_tokens: 512,
messages: [{role: "user", content: [
{type: "input_audio", input_audio: {data: $b64, format: "wav"}},
{type: "text", text: "What sounds can you hear?"}]}]}' |
curl $CHARIOT_BASE/v1/chat/completions \
-H "Authorization: Bearer $CHARIOT_API_KEY" -H "Content-Type: application/json" -d @-Chariot Voice (WebSocket)
A full-duplex call: you stream microphone audio up, and the agent streams its spoken replies down with live events. You can talk over it at any time. ASR, turn-taking and barge-in all run on the server.
Two models share this endpoint and its session limit: chariot-voice (the default) and chariot-voice-tri, the same agent replying with Chariot Tri. Choose with ?model=chariot-voice-tri in the URL or "model": "chariot-voice-tri" in the start message. A model that is not available yet is refused with an error event (code model_unavailable) and close code 1013.
- Connect to wss://…
/v1/voice?api_key=…, or send theAuthorization: Bearerheader. - First message (text):
{"type": "start", "settings": {…}}- Settings:
voice(a voice id fromGET /v1/voice/voices),speed(0.75 to 1.5),language(auto,enorhi),backchannels(bool),fillers(bool). Other settings are ignored. tools(JSON Schema function declarations, plain or OpenAI-wrapped) andinstructions(extra system text) are honoured only for evaluation keys.
- Settings:
- Wait for
{"type": "ready"}, then send binary frames: 16 kHz mono PCM16 little-endian, 20 ms (640 bytes) recommended. Max 64 KB per frame and at most 3x real time; keep sending, including silence, for the whole call.
Server to client
Binary frames: a 12-byte little-endian header <BBHII (kind = 1 for audio, flags with bit 0 = last frame of the reply, reserved, reply id rid, seq), followed by 44.1 kHz mono PCM16. Audio is sent ahead of real time, so buffer it and play it at real time. Drop the frames of a rid after a clear for it.
| Event | Meaning |
|---|---|
ready | The call is set up (settings echoes the accepted ones) |
vad | {speech: true|false, ms} user speech started / stopped |
asr.partial, asr.final | Live and final transcript of the user's turn (text) |
response.start | A reply rid starts (user_text = the turn it answers) |
response.text | The reply's text so far (text; final: true when complete) |
response.done | All audio of the reply was sent (text, audio_ms, timings) |
response.cancel, response.interrupted, response.retracted | A reply was dropped, cut off by the user (heard = what was heard), or taken back because the user was not done |
clear | Stop playing rid (graceful: finish to the next pause) |
duck, unduck | Turn the reply down (gain) while a possible interruption is judged, then back up |
voice | The voice changed (voice, speed, by) |
tool.call | {id, name, args}: run the tool and answer with tool.result (evaluation keys) |
reset, pong | The history was cleared; the reply to ping |
busy, error, session.end | No session free (then the socket closes with 1013); an error (error, code); the call ended (reason: idle_timeout, max_duration, …) |
Client to server
| Message | Use |
|---|---|
{"type": "playback", "rid", "played_ms", "buffered_ms", "done"} | Report playout progress (every ~150 ms, and done: true when a reply has finished playing, or after a clear). The agent uses it to know what the user heard. |
{"type": "interrupt"} | Stop the current reply |
{"type": "reset"} | Forget the conversation so far |
{"type": "voice", "voice", "speed"} | Switch the voice |
{"type": "settings", "backchannels", "fillers"} | Change those settings mid-call |
{"type": "tool.result", "id", "result"} | The result of a tool.call |
{"type": "text", "text"} | A typed user turn (evaluation keys only) |
{"type": "ping", "t"} | Keep-alive; answered with pong |
Example client (Python)
# pip install websockets (a 16 kHz mono 16-bit WAV in, the replies' audio out)
import asyncio, json, os, struct, wave
import websockets
HDR = struct.Struct("<BBHII") # kind, flags (bit 0 = last), reserved, reply id, seq
URL = "{{WSBASE}}/v1/voice?api_key=" + os.environ["CHARIOT_API_KEY"]
async def main(path="question_16k.wav"):
async with websockets.connect(URL, max_size=2**24) as ws:
await ws.send(json.dumps({"type": "start", "settings": {"voice": "Sarah", "language": "auto"}}))
async def speak(): # real-time 20 ms frames, then silence
with wave.open(path) as w:
while chunk := w.readframes(320):
await ws.send(chunk)
await asyncio.sleep(0.02)
while True:
await ws.send(b"\0" * 640)
await asyncio.sleep(0.02)
replies, sender = {}, None
async for msg in ws:
if isinstance(msg, bytes):
kind, flags, _, rid, seq = HDR.unpack_from(msg)
replies.setdefault(rid, bytearray()).extend(msg[HDR.size:])
if flags & 1: # last frame: pretend it was played
await ws.send(json.dumps({"type": "playback", "rid": rid,
"played_ms": len(replies[rid]) / 88.2, "done": True}))
continue
ev = json.loads(msg)
print(ev["type"], ev.get("text", ""))
if ev["type"] == "ready" and sender is None:
sender = asyncio.create_task(speak())
if ev["type"] == "response.done":
break
sender and sender.cancel()
for rid, pcm in replies.items():
with wave.open(f"reply_{rid}.wav", "wb") as w:
w.setnchannels(1); w.setsampwidth(2); w.setframerate(44100); w.writeframes(bytes(pcm))
asyncio.run(main())Limits
| Limit | Value |
|---|---|
| Request body | 60 MB |
| Chariot Tri request time | up to 600 s |
| Chariot Audio request time | up to 300 s; 600 s of audio per clip |
| Voice calls | at most 20 minutes; closed after 2 minutes without activity |
| Rate and concurrency | per key (requests per minute, parallel requests per model, voice sessions) and per service. When busy, requests wait briefly in a queue, then get 429 with Retry-After. |
The OpenAI SDKs retry 429 and 5xx responses automatically (max_retries). For benchmarks, keep your concurrency within your key's limit.
Errors
Errors use the OpenAI format: {"error": {"message": "…", "type": "…", "code": "…"}}.
| Status | When |
|---|---|
400 | Invalid request (bad messages, unsupported audio, a non-data audio URL, a context that is too long) |
401 | Missing, invalid, expired or revoked API key |
403 | The key does not include this model |
404 | Unknown model or path |
413 | The body is over 60 MB |
429 | Over the key's rate or concurrency, or the service is at capacity (see Retry-After) |
503 / 504 | The model is temporarily unavailable, or took too long |