Developer documentation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-client", "version": "1.0.0" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "en_word_eval",
    "arguments": {
      "ref_text": "hello",
      "audio_base64": "<base64 encoded audio>",
      "accent": 2,
      "rank": 100
    }
  }
}

# macOS
brew install sox

# Ubuntu / Debian
sudo apt-get install sox

# Windows: download from https://sox.sourceforge.net/ and add the install folder to PATH

node -v          # need >= 18
rec --version    # optional; missing SoX only affects live mic capture

git clone https://github.com/chivox-developer/cvx_local_mcp.git
# or: git clone https://git.chivox.com/CLOUD_DEV/cvx_local_mcp.git
cd cvx_local_mcp
npm install
npm run build

git clone https://github.com/chivox-developer/cvx_local_mcp.git
cd cvx_local_mcp
bash scripts/build.sh

cd cvx_local_mcp
npm link
# or: npm install -g .

{
  "name": "chivox-speech-eval",
  "type": "streamable-http",
  "url": "https://mcp.cloud.chivox.com"
}

{
  "mcpServers": {
    "chivox": {
      "command": "node",
      "args": ["/path/to/cvx_local_mcp/dist/index.js"],
      "env": {
        "MCP_REMOTE_URL": "https://mcp.cloud.chivox.com",
        "MCP_API_KEY": "your-api-key"
      }
    }
  }
}

claude mcp add chivox -- env MCP_REMOTE_URL=https://mcp.cloud.chivox.com MCP_API_KEY=your_chivox_api_key node /path/to/cvx_local_mcp/dist/index.js

{
  "mcpServers": {
    "chivox-speech-eval": {
      "type": "streamable-http",
      "url": "https://mcp.cloud.chivox.com"
    }
  }
}

# pip install mcp openai
import asyncio, os
from openai import OpenAI
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

MCP_URL = "https://mcp.cloud.chivox.com"
llm = OpenAI(api_key=os.getenv("DOUBAO_KEY"),
             base_url="https://ark.cn-beijing.volces.com/api/v3")

async def main(audio_id: str, ref: str):
    async with streamablehttp_client(MCP_URL) as (reader, writer, _):
        async with ClientSession(reader, writer) as sess:
            await sess.initialize()
            tools = await sess.list_tools()
            openai_tools = [{
                "type": "function",
                "function": {"name": t.name, "description": t.description,
                             "parameters": t.inputSchema},
            } for t in tools.tools]

            resp = llm.chat.completions.create(
                model="doubao-1-5-pro-32k",
                messages=[{"role": "user",
                           "content": f"Score audioId={audio_id}, reference: {ref}"}],
                tools=openai_tools,
            )
            # handle tool_calls → sess.call_tool → second LLM pass

asyncio.run(main("abc123", "I think therefore I am"))

import requests

with open('audio.mp3', 'rb') as f:
    r = requests.post(
        'https://your-audio-host.com/upload',
        data=f,
        headers={'Content-Type': 'audio/mp3'}
    )

result = r.json()
print(f"audioId: {result['audioId']}")
print(f"size: {result['size']} bytes")
print(f"expires: {result['expiresIn']}")

const fs = require('fs');
const audioData = fs.readFileSync('audio.mp3');
const res = await fetch('https://your-audio-host.com/upload', {
  method: 'POST',
  headers: { 'Content-Type': 'audio/mp3' },
  body: audioData,
});
const result = await res.json();
console.log('audioId:', result.audioId);

# Doubao / DeepSeek / Qwen / Moonshot / GLM — OpenAI-compatible
import json
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession
# doubao = OpenAI(base_url="https://ark.cn-beijing.volces.com/api/v3", api_key=os.getenv("ARK_API_KEY"))

async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
    async with ClientSession(r, w) as mcp:
        await mcp.initialize()
        tools = (await mcp.list_tools()).tools
        oa_tools = [{"type": "function", "function": {
            "name": t.name,
            "description": t.description,
            "parameters": t.inputSchema,
        }} for t in tools]
        messages = [{"role": "user", "content": "Score audioId=abc123"}]
        resp = doubao.chat.completions.create(
            model="doubao-1-5-pro-32k", messages=messages, tools=oa_tools,
        )
        msg = resp.choices[0].message
        if msg.tool_calls:
            messages.append(msg)
            for c in msg.tool_calls:
                result = await mcp.call_tool(
                    c.function.name, arguments=json.loads(c.function.arguments))
                messages.append({"role": "tool", "tool_call_id": c.id,
                                 "content": result.content[0].text})
            final = doubao.chat.completions.create(
                model="doubao-1-5-pro-32k", messages=messages)
            print(final.choices[0].message.content)

from fastapi import FastAPI
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession
from contextlib import asynccontextmanager

mcp_session: ClientSession | None = None

@asynccontextmanager
async def lifespan(app):
    global mcp_session
    async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
        async with ClientSession(r, w) as s:
            await s.initialize()
            mcp_session = s
            yield
    mcp_session = None

app = FastAPI(lifespan=lifespan)

@app.post("/api/evaluate")
async def evaluate(audio_id: str, ref_text: str):
    r = await mcp_session.call_tool(
        "evaluate_english_sentence",
        {"audioId": audio_id, "sentence": ref_text},
    )
    return {"result": r.content[0].text}

import os, json, asyncio
from openai import OpenAI
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/v1",
)

async def run(audio_id: str, ref_text: str):
    async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()
            tools = (await mcp.list_tools()).tools
            oa_tools = [{"type": "function", "function": {
                "name": t.name,
                "description": t.description,
                "parameters": t.inputSchema,
            }} for t in tools]
            messages = [{"role": "user", "content":
                f"Score this clip audioId={audio_id}, reference: {ref_text}"}]
            resp = client.chat.completions.create(
                model="deepseek-chat", messages=messages, tools=oa_tools)
            msg = resp.choices[0].message
            if msg.tool_calls:
                messages.append(msg)
                for call in msg.tool_calls:
                    result = await mcp.call_tool(
                        call.function.name,
                        arguments=json.loads(call.function.arguments),
                    )
                    messages.append({
                        "role": "tool",
                        "tool_call_id": call.id,
                        "content": result.content[0].text,
                    })
                final = client.chat.completions.create(
                    model="deepseek-chat", messages=messages)
                return final.choices[0].message.content

asyncio.run(run("audio_abc123", "Hello, nice to meet you."))

import os, json, asyncio
from openai import OpenAI
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

client = OpenAI(
    api_key=os.environ["ZHIPU_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/",
)

async def run(audio_id: str, ref_text: str):
    async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()
            tools = (await mcp.list_tools()).tools
            oa_tools = [{"type": "function", "function": {
                "name": t.name,
                "description": t.description,
                "parameters": t.inputSchema,
            }} for t in tools]
            messages = [{"role": "user", "content":
                f"Score audioId={audio_id}, reference: {ref_text}"}]
            resp = client.chat.completions.create(
                model="glm-4-flash",   # free dev tier; production: glm-5 / glm-4.7
                messages=messages, tools=oa_tools)
            msg = resp.choices[0].message
            if msg.tool_calls:
                messages.append(msg)
                for call in msg.tool_calls:
                    result = await mcp.call_tool(
                        call.function.name,
                        arguments=json.loads(call.function.arguments),
                    )
                    messages.append({
                        "role": "tool",
                        "tool_call_id": call.id,
                        "content": result.content[0].text,
                    })
                final = client.chat.completions.create(
                    model="glm-4-flash", messages=messages)
                return final.choices[0].message.content

asyncio.run(run("audio_abc123", "How are you today?"))

import os, json, asyncio
from openai import OpenAI
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

async def run(audio_id: str, ref_text: str):
    async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()
            tools = (await mcp.list_tools()).tools
            oa_tools = [{"type": "function", "function": {
                "name": t.name,
                "description": t.description,
                "parameters": t.inputSchema,
            }} for t in tools]
            messages = [{"role": "user", "content":
                f"Score English audioId={audio_id}, reference: {ref_text}"}]
            resp = client.chat.completions.create(
                model="kimi-k2.5",   # flagship; or kimi-k2-turbo-preview / moonshot-v1-128k
                messages=messages, tools=oa_tools)
            msg = resp.choices[0].message
            if msg.tool_calls:
                messages.append(msg)
                for call in msg.tool_calls:
                    result = await mcp.call_tool(
                        call.function.name,
                        arguments=json.loads(call.function.arguments),
                    )
                    messages.append({
                        "role": "tool",
                        "tool_call_id": call.id,
                        "content": result.content[0].text,
                    })
                final = client.chat.completions.create(
                    model="kimi-k2.5", messages=messages)
                return final.choices[0].message.content

asyncio.run(run("audio_abc123", "Nice to meet you."))

# Volcano Ark console → API key management
ARK_API_KEY=ak-xxxxxxxxxxxxxxxxxxxxxxxx
CHIVOX_APP_KEY=your_chivox_app_key
CHIVOX_SECRET_KEY=your_chivox_secret_key

import os, json, asyncio
from openai import OpenAI
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

# Volcano Ark OpenAI-compatible endpoint
client = OpenAI(
    api_key=os.environ["ARK_API_KEY"],
    base_url="https://ark.cn-beijing.volces.com/api/v3",
)

MODEL = "doubao-seed-2-0-pro-260215"   # or lite / mini

async def evaluate_with_doubao(audio_id: str, ref_text: str):
    async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()

            # 1. Inject all 16 Chivox tool schemas dynamically
            tools = (await mcp.list_tools()).tools
            ark_tools = [{
                "type": "function",
                "function": {
                    "name": t.name,
                    "description": t.description,
                    "parameters": t.inputSchema,
                },
            } for t in tools]

            messages = [
                {"role": "system",
                 "content": "You are a professional English speaking coach who actively calls Chivox evaluation tools to read real scores."},
                {"role": "user",
                 "content": f"Evaluate this recording. audio_id={audio_id}, refText: {ref_text}. "
                            f"Run sentence-level scoring first; if any word is weak, follow up with word-level."},
            ]

            # 2. Round 1 — let Doubao pick tools
            resp = client.chat.completions.create(
                model=MODEL,
                messages=messages,
                tools=ark_tools,
                tool_choice="auto",
                # extra_body={"thinking": {"type": "disabled"}},  # toggle off for low latency
            )

            msg = resp.choices[0].message
            messages.append(msg)

            # 3. Tool-call loop — Doubao may emit multiple tool_calls per turn
            for call in (msg.tool_calls or []):
                result = await mcp.call_tool(
                    call.function.name,
                    arguments=json.loads(call.function.arguments),
                )
                messages.append({
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result.content[0].text,
                })

            # 4. Round 2 — Doubao reads the real evaluation JSON and produces coaching prose
            final = client.chat.completions.create(
                model=MODEL,
                messages=messages,
            )
            return final.choices[0].message.content

print(asyncio.run(evaluate_with_doubao(
    audio_id="audio_abc123",
    ref_text="The quick brown fox jumps over the lazy dog.",
)))

# Disable thinking — faster, ideal for live feedback
client.chat.completions.create(
    model="doubao-seed-2-0-lite-260215",
    messages=messages,
    tools=ark_tools,
    extra_body={"thinking": {"type": "disabled"}},
)

# Enable thinking — default; ideal for Pro + multi-step agents
client.chat.completions.create(
    model="doubao-seed-2-0-pro-260215",
    messages=messages,
    tools=ark_tools,
    extra_body={"thinking": {"type": "enabled"}},
)

import os, json, asyncio
from openai import OpenAI
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

async def run(audio_id: str, ref_text: str):
    async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()
            tools = (await mcp.list_tools()).tools
            oa_tools = [{"type": "function", "function": {
                "name": t.name,
                "description": t.description,
                "parameters": t.inputSchema,
            }} for t in tools]
            messages = [{"role": "user", "content":
                f"Score audioId={audio_id}, reference: {ref_text}"}]
            resp = client.chat.completions.create(
                model="qwen3.6-plus",   # flagship; or qwen3.6-flash / qwen-long
                messages=messages, tools=oa_tools)
            msg = resp.choices[0].message
            if msg.tool_calls:
                messages.append(msg)
                for call in msg.tool_calls:
                    result = await mcp.call_tool(
                        call.function.name,
                        arguments=json.loads(call.function.arguments),
                    )
                    messages.append({
                        "role": "tool",
                        "tool_call_id": call.id,
                        "content": result.content[0].text,
                    })
                final = client.chat.completions.create(
                    model="qwen3.6-plus", messages=messages)
                return final.choices[0].message.content

asyncio.run(run("audio_abc123", "The weather is nice today."))

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
CHIVOX_APP_KEY=your_chivox_app_key
CHIVOX_SECRET_KEY=your_chivox_secret_key

import os, json, asyncio
from openai import OpenAI
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def evaluate_with_gpt(audio_id: str, ref_text: str):
    async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()
            tools = (await mcp.list_tools()).tools
            oa_tools = [{"type": "function", "function": {
                "name": t.name,
                "description": t.description,
                "parameters": t.inputSchema,
            }} for t in tools]

            messages = [
                {"role": "system",
                 "content": "You are an English speaking coach. Always call the Chivox eval tool first to get real scores."},
                {"role": "user",
                 "content": f"Score this take. audioId={audio_id}, reference: {ref_text}"},
            ]

            resp = client.chat.completions.create(
                model="gpt-5.1",
                messages=messages,
                tools=oa_tools,
                tool_choice="auto",
                reasoning_effort="medium",   # GPT-5.1 only: none / low / medium / high
            )

            msg = resp.choices[0].message
            messages.append(msg)
            for call in (msg.tool_calls or []):
                result = await mcp.call_tool(
                    call.function.name,
                    arguments=json.loads(call.function.arguments),
                )
                messages.append({
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result.content[0].text,
                })

            final = client.chat.completions.create(
                model="gpt-5.1", messages=messages)
            return final.choices[0].message.content

print(asyncio.run(evaluate_with_gpt(
    "audio_abc123", "The quick brown fox jumps over the lazy dog.")))

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx
CHIVOX_APP_KEY=your_chivox_app_key
CHIVOX_SECRET_KEY=your_chivox_secret_key

# pip install anthropic mcp
import os, json, asyncio
from anthropic import Anthropic
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

async def evaluate_with_claude(audio_id: str, ref_text: str):
    async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()

            # Convert MCP tools to Anthropic shape (uses input_schema, not parameters)
            tools = (await mcp.list_tools()).tools
            anth_tools = [{
                "name": t.name,
                "description": t.description,
                "input_schema": t.inputSchema,
            } for t in tools]

            messages = [{"role": "user",
                         "content": f"Score this take: audioId={audio_id}, reference: {ref_text}"}]

            # Tool loop — Claude may emit multiple tool_use blocks across turns
            while True:
                resp = client.messages.create(
                    model="claude-opus-4-7",   # or claude-sonnet-4-6 / claude-haiku-4-5
                    max_tokens=2048,
                    tools=anth_tools,
                    messages=messages,
                    system="You are an English speaking coach. Always call the Chivox eval tool first.",
                )

                # Append the full assistant turn (including tool_use blocks)
                messages.append({"role": "assistant", "content": resp.content})

                if resp.stop_reason != "tool_use":
                    return "".join(b.text for b in resp.content if b.type == "text")

                # Extract every tool_use block, run it, return tool_result
                tool_results = []
                for block in resp.content:
                    if block.type == "tool_use":
                        result = await mcp.call_tool(block.name, arguments=block.input)
                        tool_results.append({
                            "type": "tool_result",
                            "tool_use_id": block.id,
                            "content": result.content[0].text,
                        })
                messages.append({"role": "user", "content": tool_results})

print(asyncio.run(evaluate_with_claude(
    "audio_abc123", "The quick brown fox jumps over the lazy dog.")))

GEMINI_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxx
CHIVOX_APP_KEY=your_chivox_app_key
CHIVOX_SECRET_KEY=your_chivox_secret_key

import os, json, asyncio
from openai import OpenAI
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

# Gemini OpenAI-compatible endpoint — full OpenAI SDK reuse
client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

async def evaluate_with_gemini(audio_id: str, ref_text: str):
    async with streamablehttp_client("https://mcp.cloud.chivox.com") as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()
            tools = (await mcp.list_tools()).tools
            oa_tools = [{"type": "function", "function": {
                "name": t.name,
                "description": t.description,
                "parameters": t.inputSchema,
            }} for t in tools]

            messages = [{"role": "user",
                         "content": f"Score audioId={audio_id}, reference: {ref_text}"}]

            resp = client.chat.completions.create(
                model="gemini-3-flash-preview",   # or gemini-3.1-pro-preview
                messages=messages,
                tools=oa_tools,
                tool_choice="auto",
            )
            msg = resp.choices[0].message
            messages.append(msg)
            for call in (msg.tool_calls or []):
                result = await mcp.call_tool(
                    call.function.name,
                    arguments=json.loads(call.function.arguments),
                )
                messages.append({
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result.content[0].text,
                })

            final = client.chat.completions.create(
                model="gemini-3-flash-preview", messages=messages)
            return final.choices[0].message.content

print(asyncio.run(evaluate_with_gemini(
    "audio_abc123", "The quick brown fox jumps over the lazy dog.")))

# pip install google-genai
from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# Convert MCP tools to Gemini function_declarations
fn_decls = [{
    "name": t.name,
    "description": t.description,
    "parameters": t.inputSchema,
} for t in tools]

resp = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=f"Score audioId={audio_id}, reference: {ref_text}",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=fn_decls)],
        # Gemini 3+: thinking_level replaces the older thinking_budget
        # thinking_level="high",
    ),
)

# Tool call lives in response.candidates[0].content.parts[0].function_call
fc = resp.candidates[0].content.parts[0].function_call
print(f"call: {fc.name}({dict(fc.args)})  id={fc.id}")

Authorization: Bearer <your_api_key>

GET /v1/functions
Authorization: Bearer <api_key>

{
  "object": "list",
  "data": [
    {
      "type": "function",
      "function": {
        "name": "en_word_eval",
        "description": "English word pronunciation eval; returns overall score and per-phoneme scores.",
        "parameters": {
          "type": "object",
          "properties": {
            "ref_text":     { "type": "string", "description": "Reference text" },
            "audio_base64": { "type": "string", "description": "Base64-encoded audio (either this or audio_url)" },
            "audio_url":    { "type": "string", "description": "HTTP(S) URL of audio (either this or audio_base64)" },
            "accent":       { "type": "number", "description": "1 = British / 2 = American / 3 = any (default)" },
            "rank":         { "type": "number", "description": "Scoring scale: 4 or 100 (default)" }
          },
          "required": ["ref_text"]
        }
      }
    }
    /* … more functions … */
  ]
}

curl -X POST https://fc.cloud.chivox.com/v1/call \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "en_word_eval",
    "arguments": {
      "ref_text": "hello",
      "audio_url": "https://example.com/hello.mp3",
      "accent": 2,
      "rank": 100
    }
  }'

{
  "name": "en_word_eval",
  "result": {
    "overall": 85.5,
    "details": { /* phonemes / prosody / fluency — identical schema to MCP mode */ }
  }
}

{
  "name": "en_word_eval",
  "error": { "message": "human-readable description" }
}

// 1. Create session
const resp = await fetch('https://fc.cloud.chivox.com/v1/call', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'start_stream_eval',
    arguments: {
      core_type: 'en.sent.score',
      ref_text: 'Hello world',
      audio_type: 'wav',
      sample_rate: 16000,
    },
  }),
});
const { result } = await resp.json();

// 2. WebSocket: push audio
const ws = new WebSocket(result.ws_url);
ws.onmessage = (ev) => {
  const msg = JSON.parse(ev.data);
  switch (msg.type) {
    case 'ready':        startRecording(); break;
    case 'intermediate': console.log('partial', msg.data); break;
    case 'result':       console.log('final', msg.data); ws.close(); break;
    case 'backpressure': console.warn('slow down ~', msg.suggested_interval_ms, 'ms'); break;
    case 'error':        console.error(msg.code, msg.message); break;
  }
};

function onAudioChunk(pcm) {
  if (ws.readyState === WebSocket.OPEN) ws.send(pcm); // raw binary
}

function stopRecording() {
  ws.send(JSON.stringify({ type: 'stop' }));
}

val wsUrl  = "ws://your-host:8080/ws/eval/$sessionId"
val client = OkHttpClient()
val req    = Request.Builder()
    .url(wsUrl)
    .addHeader("Authorization", "Bearer ${apiKey}")
    .build()

val ws = client.newWebSocket(req, object : WebSocketListener() {
    override fun onMessage(ws: WebSocket, text: String) {
        val msg = JSONObject(text)
        when (msg.getString("type")) {
            "ready"        -> startRecording()
            "intermediate" -> updateUI(msg.getJSONObject("data"))
            "result"       -> handleFinalResult(msg.getJSONObject("data"))
            "error"        -> handleError(msg.getString("code"), msg.getString("message"))
        }
    }
})

// Forward PCM bytes from your recorder
fun onAudioData(pcm: ByteArray) {
    ws.send(ByteString.of(*pcm))
}

fun stop() {
    ws.send("""{"type":"stop"}""")
}

GET ws://your-host:8080/ws/eval/{session_id}?resume={resume_token}
Authorization: Bearer <your_api_key>

curl -X POST https://fc.cloud.chivox.com/v1/call \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_stream_result",
    "arguments": {
      "session_id": "stream-1713340800-a1b2c3",
      "auto_stop": true,
      "timeout": 30
    }
  }'

{
  "overall": 85,
  "accuracy": 82,
  "pron": 88,
  "fluency": { "overall": 78, "speed": 65, "pause": 2 },
  "integrity": 95,
  "details": [
    {
      "char": "hello",
      "score": 85,
      "phone": [
        { "phoneme": "h", "score": 90 },
        { "phoneme": "ɛ", "score": 82 }
      ]
    }
  ]
}