API reference

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

GET/v1/models
ModelWhat it isEndpoint
chariot-triText LLM: chat, reasoning (thinking mode), tool callsPOST /v1/chat/completions
chariot-audioAudio understanding: speech, sounds, music, emotionPOST /v1/chat/completions
chariot-voiceReal-time speech-to-speech agentWS /v1/voice
chariot-voice-triThe same voice agent, replying with Chariot TriWS /v1/voice?model=chariot-voice-tri
curl $CHARIOT_BASE/v1/models -H "Authorization: Bearer $CHARIOT_API_KEY"

Chariot Tri (text)

POST/v1/chat/completions

The OpenAI Chat Completions format with "model": "chariot-tri". Supported fields:

  • messages (roles system, user, assistant, tool)
  • stream, stream_options.include_usage
  • tools (JSON Schema functions); the reply carries tool_calls and finish_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 in reasoning_content
  • n must 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 answer

When 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

POST/v1/chat/completions

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,…"}}. Only data: 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)

WS/v1/voice?api_key=sk-…

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.

  1. Connect to wss://…/v1/voice?api_key=…, or send the Authorization: Bearer header.
  2. First message (text): {"type": "start", "settings": {…}}
    • Settings: voice (a voice id from GET /v1/voice/voices), speed (0.75 to 1.5), language (auto, en or hi), backchannels (bool), fillers (bool). Other settings are ignored.
    • tools (JSON Schema function declarations, plain or OpenAI-wrapped) and instructions (extra system text) are honoured only for evaluation keys.
  3. 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.

EventMeaning
readyThe call is set up (settings echoes the accepted ones)
vad{speech: true|false, ms} user speech started / stopped
asr.partial, asr.finalLive and final transcript of the user's turn (text)
response.startA reply rid starts (user_text = the turn it answers)
response.textThe reply's text so far (text; final: true when complete)
response.doneAll audio of the reply was sent (text, audio_ms, timings)
response.cancel, response.interrupted, response.retractedA reply was dropped, cut off by the user (heard = what was heard), or taken back because the user was not done
clearStop playing rid (graceful: finish to the next pause)
duck, unduckTurn the reply down (gain) while a possible interruption is judged, then back up
voiceThe voice changed (voice, speed, by)
tool.call{id, name, args}: run the tool and answer with tool.result (evaluation keys)
reset, pongThe history was cleared; the reply to ping
busy, error, session.endNo session free (then the socket closes with 1013); an error (error, code); the call ended (reason: idle_timeout, max_duration, …)

Client to server

MessageUse
{"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

LimitValue
Request body60 MB
Chariot Tri request timeup to 600 s
Chariot Audio request timeup to 300 s; 600 s of audio per clip
Voice callsat most 20 minutes; closed after 2 minutes without activity
Rate and concurrencyper 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": "…"}}.

StatusWhen
400Invalid request (bad messages, unsupported audio, a non-data audio URL, a context that is too long)
401Missing, invalid, expired or revoked API key
403The key does not include this model
404Unknown model or path
413The body is over 60 MB
429Over the key's rate or concurrency, or the service is at capacity (see Retry-After)
503 / 504The model is temporarily unavailable, or took too long