开发者文档

{
  "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：从 https://sox.sourceforge.net/ 下载安装，并将安装目录加入 PATH

node -v          # 需 >= 18
rec --version    # 可选；未安装 SoX 会提示找不到命令，仅影响实时录音

git clone https://github.com/chivox-developer/cvx_local_mcp.git
# 或：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
# 或：npm install -g .

{
  "mcpServers": {
    "chivox-speech-eval": {
      "type": "streamable-http",
      "url": "https://mcp.cloud.chivox.com",
      "headers": {
        "Authorization": "Bearer sk-你的完整密钥"
      }
    }
  }
}

{
  "mcpServers": {
    "chivox-speech-eval": {
      "command": "node",
      "args": ["/path/to/cvx_local_mcp/dist/index.js"],
      "env": {
        "MCP_REMOTE_URL": "https://mcp.cloud.chivox.com",
        "MCP_API_KEY": "sk-你的完整密钥"
      }
    }
  }
}

claude mcp add --transport http chivox-speech-eval https://mcp.cloud.chivox.com \
  --header "Authorization: Bearer sk-你的完整密钥"

# 源码构建后
claude mcp add chivox-speech-eval -- env MCP_REMOTE_URL=https://mcp.cloud.chivox.com MCP_API_KEY=sk-你的完整密钥 node /path/to/cvx_local_mcp/dist/index.js

{
  "mcpServers": {
    "chivox-speech-eval": {
      "type": "streamable-http",
      "url": "https://mcp.cloud.chivox.com",
      "headers": {
        "Authorization": "Bearer sk-你的完整密钥"
      }
    }
  }
}

{
  "mcpServers": {
    "chivox-speech-eval": {
      "type": "streamable-http",
      "url": "https://mcp.cloud.chivox.com",
      "headers": {
        "Authorization": "Bearer sk-你的完整密钥"
      }
    }
  }
}

你是一位专业的英语口语教练。当用户上传音频并请求评测时：
1. 使用 evaluate_english_word / evaluate_english_sentence 等工具进行评测
2. 根据评测结果（overall、accuracy、fluency 等分数）给出专业分析
3. 针对得分较低的维度提供具体改进建议
4. 鼓励用户持续练习

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "evaluate_english_sentence",
    "arguments": {
      "audioId": "{{audioId}}",
      "sentence": "{{ref_text}}"
    }
  },
  "id": 1
}

{
  "mcpServers": {
    "chivox-speech-eval": {
      "type": "streamable-http",
      "url": "https://mcp.cloud.chivox.com",
      "headers": {
        "Authorization": "Bearer sk-你的完整密钥"
      }
    }
  }
}

# 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")  # 豆包 / DeepSeek / OpenAI 同构

async def main(audio_id: str, ref: str):
    async with streamablehttp_client(
        MCP_URL,
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) 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"帮我评测 audioId={audio_id}，参考文本：{ref}"}],
                tools=openai_tools,
            )

            for call in resp.choices[0].message.tool_calls or []:
                result = await sess.call_tool(call.function.name,
                                              arguments=eval(call.function.arguments))
                print(call.function.name, "→", result.content[0].text[:200])

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

// npm i @modelcontextprotocol/sdk openai
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import OpenAI from "openai";

const mcp = new Client({ name: "chivox-biz", version: "1.0.0" });
await mcp.connect(new StreamableHTTPClientTransport(
  new URL("https://mcp.cloud.chivox.com"),
  { requestInit: { headers: { "Authorization": `Bearer ${process.env.CHIVOX_API_KEY}` } } }
));

const { tools } = await mcp.listTools();
const openai = new OpenAI({ apiKey: process.env.DEEPSEEK_KEY, baseURL: "https://api.deepseek.com/v1" });

const resp = await openai.chat.completions.create({
  model: "deepseek-chat",
  messages: [{ role: "user", content: "评测 audioId=abc123, 参考 I think therefore I am" }],
  tools: tools.map(t => ({ type: "function", function: {
    name: t.name, description: t.description, parameters: t.inputSchema
  }})),
});

for (const call of resp.choices[0].message.tool_calls ?? []) {
  const r = await mcp.callTool({ name: call.function.name,
                                 arguments: JSON.parse(call.function.arguments) });
  console.log(call.function.name, r.content);
}

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);

# 适用：豆包（火山方舟）/ DeepSeek / Qwen / Moonshot / GLM 等 OpenAI 兼容 API
# 核心思路：MCP 列工具 → 转 OpenAI tools → LLM 决策 → MCP 执行 → 回填

async with streamablehttp_client(
    "https://mcp.cloud.chivox.com",
    headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
) as (r, w, _):
    async with ClientSession(r, w) as mcp:
        await mcp.initialize()
        tools = (await mcp.list_tools()).tools

        # ① 用 MCP 拉到的 schema 自动转 OpenAI 格式
        oa_tools = [{"type": "function", "function": {
            "name": t.name,
            "description": t.description,
            "parameters": t.inputSchema,
        }} for t in tools]

        # ② 喂给豆包
        messages = [{"role": "user", "content": "评测一下 audioId=abc123"}]
        resp = doubao.chat.completions.create(
            model="doubao-1-5-pro-32k", messages=messages, tools=oa_tools,
        )

        # ③ LLM 回 tool_calls → 折返跑到 MCP 执行
        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",
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) 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):
    # 直接选一个最合适的工具执行（不经 LLM，延迟最低）
    r = await mcp_session.call_tool("evaluate_english_sentence",
                                    {"audioId": audio_id, "sentence": ref_text})
    return {"result": r.content[0].text}

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx
CHIVOX_API_KEY=your_chivox_api_key

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

# DeepSeek 客户端（OpenAI 兼容）
client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/v1",
)

async def evaluate_with_deepseek(audio_id: str, ref_text: str):
    async with streamablehttp_client(
        "https://mcp.cloud.chivox.com",
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()

            # ① 拉取驰声 MCP 工具列表
            tools = (await mcp.list_tools()).tools
            oa_tools = [{"type": "function", "function": {
                "name": t.name,
                "description": t.description,
                "parameters": t.inputSchema,
            }} for t in tools]

            # ② 调用 DeepSeek，让它选择合适的评测工具
            messages = [{"role": "user", "content":
                f"请评测这段英文录音，audioId={audio_id}，参考文本：{ref_text}"}]

            resp = client.chat.completions.create(
                model="deepseek-chat",   # 或 deepseek-reasoner
                messages=messages,
                tools=oa_tools,
            )

            # ③ 执行 tool_calls
            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,
                    })

                # ④ 让 DeepSeek 根据评测结果生成自然语言诊断
                final = client.chat.completions.create(
                    model="deepseek-chat",
                    messages=messages,
                )
                return final.choices[0].message.content

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

ZHIPU_API_KEY=xxxxxxxx.xxxxxxxxxxxxxxxx
CHIVOX_API_KEY=your_chivox_api_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["ZHIPU_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/",
)

async def evaluate_with_glm(audio_id: str, ref_text: str):
    async with streamablehttp_client(
        "https://mcp.cloud.chivox.com",
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) 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"请评测这段录音，audioId={audio_id}，参考文本：{ref_text}"}]

            resp = client.chat.completions.create(
                model="glm-4-flash",   # 免费快速版；生产推荐 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(evaluate_with_glm("audio_abc123", "How are you today?"))

from zhipuai import ZhipuAI

client = ZhipuAI(api_key=os.environ["ZHIPU_API_KEY"])

# 其余逻辑与方式一相同，仅替换 client 实例
resp = client.chat.completions.create(
    model="glm-5",   # 旗舰；也可用 glm-4.7 / glm-4-flash
    messages=messages,
    tools=oa_tools,
)

MOONSHOT_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
CHIVOX_API_KEY=your_chivox_api_key

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

# 中国大陆用 api.moonshot.cn；海外/国际版用 api.moonshot.ai
client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.cn/v1",
)

async def evaluate_with_kimi(audio_id: str, ref_text: str):
    async with streamablehttp_client(
        "https://mcp.cloud.chivox.com",
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) 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"请评测这段英文录音，audioId={audio_id}，参考文本：{ref_text}"}]

            resp = client.chat.completions.create(
                model="kimi-k2.5",   # 旗舰；也可选 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(evaluate_with_kimi("audio_abc123", "Nice to meet you."))

# 火山方舟控制台 → API Key 管理
ARK_API_KEY=ak-xxxxxxxxxxxxxxxxxxxxxxxx
CHIVOX_API_KEY=your_chivox_api_key

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

# 火山方舟 OpenAI 兼容端点
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"   # 也可换成 lite / mini

async def evaluate_with_doubao(audio_id: str, ref_text: str):
    async with streamablehttp_client(
        "https://mcp.cloud.chivox.com",
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()

            # ① 把驰声 16 个评测工具的 schema 动态注入豆包
            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": "你是一位专业的英语口语教练，会主动调用驰声评测工具获取真实分数。"},
                {"role": "user",
                 "content": f"请评测这段录音，audio_id={audio_id}，参考文本：{ref_text}。"
                            f"先做句子级评测，弱项再追加单词级定位。"},
            ]

            # ② 第一轮 —— 让豆包根据 prompt 自主选工具
            resp = client.chat.completions.create(
                model=MODEL,
                messages=messages,
                tools=ark_tools,
                tool_choice="auto",
                # extra_body={"thinking": {"type": "disabled"}},  # 需要时可关思考
            )

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

            # ③ 折返跑：豆包可能一次发起多个 tool_calls，全部回填
            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,
                })

            # ④ 第二轮 —— 让豆包基于真实评测 JSON 输出诊断 / 练习建议
            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.",
)))

# 关闭思考（更快、适合实时反馈）
client.chat.completions.create(
    model="doubao-seed-2-0-lite-260215",
    messages=messages,
    tools=ark_tools,
    extra_body={"thinking": {"type": "disabled"}},
)

# 开启思考（默认，适合 Pro 模型 + 多步 Agent）
client.chat.completions.create(
    model="doubao-seed-2-0-pro-260215",
    messages=messages,
    tools=ark_tools,
    extra_body={"thinking": {"type": "enabled"}},
)

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
CHIVOX_API_KEY=your_chivox_api_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",
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) 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": "你是英语口语教练，必须调用驰声评测工具拿真实分数后再回答。"},
                {"role": "user",
                 "content": f"请评测：audioId={audio_id}，参考文本：{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 新参数：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_API_KEY=your_chivox_api_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",
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()

            # 把驰声 MCP 工具转成 Anthropic 风格（用 input_schema 而非 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"请评测这段录音 audioId={audio_id}，参考文本：{ref_text}"}]

            # 工具循环：Claude 可能多轮 tool_use，需逐轮回填
            while True:
                resp = client.messages.create(
                    model="claude-opus-4-7",   # 或 claude-sonnet-4-6 / claude-haiku-4-5
                    max_tokens=2048,
                    tools=anth_tools,
                    messages=messages,
                    system="你是专业英语口语教练，必须调用驰声评测工具获取真实分数。",
                )

                # 把整段助手回复（含 tool_use 块）追加进 messages
                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")

                # 提取所有 tool_use 块、并行执行、把 tool_result 回填给 Claude
                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_API_KEY=your_chivox_api_key

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

# Gemini OpenAI 兼容端点 —— 完全复用 OpenAI SDK
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",
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) 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"请评测：audioId={audio_id}，参考文本：{ref_text}"}]

            resp = client.chat.completions.create(
                model="gemini-3-flash-preview",   # 或 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 mcp
import os, asyncio
from google import genai
from google.genai import types
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

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

async def evaluate_with_gemini_native(audio_id: str, ref_text: str):
    async with streamablehttp_client(
        "https://mcp.cloud.chivox.com",
        headers={"Authorization": f"Bearer {os.getenv('CHIVOX_API_KEY')}"},
    ) as (r, w, _):
        async with ClientSession(r, w) as mcp:
            await mcp.initialize()
            tools = (await mcp.list_tools()).tools

            # 把 MCP 工具转成 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"评测 audioId={audio_id}，参考文本：{ref_text}",
                config=types.GenerateContentConfig(
                    tools=[types.Tool(function_declarations=fn_decls)],
                    # Gemini 3 起：thinking_level 替代旧的 thinking_budget
                    # thinking_level="high",
                ),
            )

            # tool_call 在 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}")

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

Authorization: Bearer <your_api_key>

GET /v1/functions
Authorization: Bearer <api_key>

{
  "object": "list",
  "data": [
    {
      "type": "function",
      "function": {
        "name": "en_word_eval",
        "description": "英文单词发音评测，返回总分和每个音标得分。",
        "parameters": {
          "type": "object",
          "properties": {
            "ref_text":     { "type": "string", "description": "参考文本" },
            "audio_base64": { "type": "string", "description": "Base64 编码音频（与 audio_url 二选一）" },
            "audio_url":    { "type": "string", "description": "音频 HTTP(S) URL（与 audio_base64 二选一）" },
            "accent":       { "type": "number", "description": "1=英式 / 2=美式 / 3=不区分（默认）" },
            "rank":         { "type": "number", "description": "评分制：4 或 100（默认）" }
          },
          "required": ["ref_text"]
        }
      }
    }
    /* … 其它函数依此类推 … */
  ]
}

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": { /* 音素 / 韵律 / 流利度等结构与 MCP 模式完全一致 */ }
  }
}

{
  "name": "en_word_eval",
  "error": { "message": "错误描述" }
}

// ① 创建会话
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: 'pcm',
      sample_rate: 16000,
    },
  }),
});
const { result } = await resp.json();

// ② WebSocket 推送音频
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('部分结果', msg.data); break;
    case 'result':       console.log('最终结果', msg.data); ws.close(); break;
    case 'backpressure': console.warn('降速 ~', 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); // 直接发二进制
}

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

// ① 创建会话，拿到 ws_url
val createResp = OkHttpClient().newCall(
    Request.Builder()
        .url("https://fc.cloud.chivox.com/v1/call")
        .addHeader("Authorization", "Bearer ${apiKey}")
        .addHeader("Content-Type", "application/json")
        .post("""{"name":"start_stream_eval","arguments":{"core_type":"en.sent.score","ref_text":"Hello world","audio_type":"pcm"}}""".toRequestBody())
        .build()
).execute()
val wsUrl = JSONObject(createResp.body!!.string()).getJSONObject("result").getString("ws_url")

// ② 连接 WebSocket
val client = OkHttpClient()
val req    = Request.Builder()
    .url(wsUrl)
    .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"))
        }
    }
})

// 录音回调中发送 PCM 字节
fun onAudioData(pcm: ByteArray) {
    ws.send(ByteString.of(*pcm))
}

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

// ws_url 取自 start_stream_eval 响应，追加 resume 参数即可重连
GET {ws_url}?resume={resume_token}

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 },
        { "phoneme": "l", "score": 88 },
        { "phoneme": "oʊ", "score": 80 }
      ]
    }
  ]
}