{"service":"本地语音双引擎管理平台（Agent 自助注册 + 语音合成）","version":"1.0.0","spec":"OpenAPI 3.1，另见 /api/openapi.json","openapi_url":"https://desktop-gd6ps84.tail9020ed.ts.net/api/openapi.json","base_url":"https://desktop-gd6ps84.tail9020ed.ts.net","quick_start":[{"step":1,"action":"POST https://desktop-gd6ps84.tail9020ed.ts.net/api/register","body":{"name":"你的Agent名","agent_type":"播报","purpose":"每日新闻"},"result":"返回 agent_id 与 api_key（Key 仅展示一次，务必保存）"},{"step":2,"action":"调用业务接口时携带请求头 X-API-Key: <你的api_key>"},{"step":3,"action":"POST https://desktop-gd6ps84.tail9020ed.ts.net/api/tts，选择 engine: cosyvoice3（通用）或 indextts2（情感）即可合成语音"}],"authentication":{"type":"header","header":"X-API-Key","how":"注册后获得独立 Key（形如 ttsk-xxx）。业务接口必须携带；GET /health、POST /api/register、GET /api/docs、GET /api/openapi.json 除外。","register":{"method":"POST","path":"/api/register","body_fields":["name(必填)","agent_type","org","contact","purpose","apply_note"]},"errors":{"401":"Key 缺失或无效","403":"Agent 已被禁用","429":"超过每分钟调用上限"},"rate_limit":"8 次/分钟/Agent（滑动窗口 60s）"},"endpoints":[{"method":"GET","path":"/health","auth":false,"desc":"网关与双引擎健康状态","response":{"status":"ok","service":"mgmt","engines":{"cosyvoice3":"ok|down","indextts2":"ok|down"},"agents":0,"api_docs":"/api/docs"}},{"method":"POST","path":"/api/register","auth":false,"desc":"注册新 Agent，返回 Agent ID 与独立 API Key（Key 仅此一次返回）","request_body":{"name":"示例Agent","agent_type":"播报","org":"某团队","contact":"可选","purpose":"新闻播报","apply_note":"约200次/天"},"response":{"ok":true,"agent_id":"agent-xxxx","api_key":"ttsk-xxxx","engines":["cosyvoice3","indextts2"],"default_engine":"cosyvoice3","gateway_tts":"POST https://desktop-gd6ps84.tail9020ed.ts.net/api/tts","api_docs":"https://desktop-gd6ps84.tail9020ed.ts.net/api/docs"}},{"method":"GET","path":"/api/docs","auth":false,"desc":"本机器可读接口文档"},{"method":"GET","path":"/api/openapi.json","auth":false,"desc":"OpenAPI 3.1 规范，供 Agent 工具自动解析"},{"method":"GET","path":"/api/voices","auth":true,"query":{"engine":"cosyvoice3|indextts2（默认 cosyvoice3）"},"desc":"获取指定引擎音色列表（103 个）","response":{"engine":"cosyvoice3","voices":["v_0001","...","v_0103"],"count":103}},{"method":"GET","path":"/api/me","auth":true,"desc":"当前 Agent 信息与用量（含累计调用数、最近调用时间）"},{"method":"POST","path":"/api/tts","auth":true,"desc":"语音合成：按 engine 路由到 8000/8001，自动统计 + 限流","request_body":{"voice_id":"v_0001","text":"你好","format":"wav","engine":"cosyvoice3","instruct":"(cosyvoice3 可选)","emo_text":"(indextts2 可选)","emo_alpha":0.8},"format":["wav","pcm16","mp3"],"response":"audio 二进制（Content-Type: audio/wav 等）","response_headers":["X-Duration-Sec","X-RTF","X-Sample-Rate","X-Voice","X-Format","X-Engine","X-Agent-ID","X-Gateway-RTF"],"note":"CosyVoice3(cosyvoice3) 支持 instruct 语气指令与文本情绪标签；IndexTTS-2(indextts2) 支持 emo_text/emo_alpha 独立情绪控制。"}],"engines":[{"id":"cosyvoice3","port":8000,"name":"CosyVoice3","desc":"通用/多语种零样本克隆，文本内嵌情绪标签","sample_rate":24000,"params":{"instruct":{"optional":true,"desc":"语气/风格指令，如：用温柔的语气说"},"text_emotion_tags":{"optional":true,"desc":"文本中可直接写情绪描述/表情"}},"rtf":"短句约 4（纯 CPU）"},{"id":"indextts2","port":8001,"name":"IndexTTS-2","desc":"情感克隆，独立情绪控制","sample_rate":22050,"params":{"emo_text":{"optional":true,"desc":"独立情绪描述，如：开心"},"emo_alpha":{"optional":true,"default":0.8,"desc":"情绪强度 0~1"}},"rtf":"约 10（纯 CPU）"}],"tts_request_schema":{"voice_id":{"type":"string","required":true,"example":"v_0001","desc":"音色 ID，见 /api/voices"},"text":{"type":"string","required":true,"desc":"待合成文本"},"format":{"type":"string","enum":["wav","pcm16","mp3"],"default":"wav"},"engine":{"type":"string","enum":["cosyvoice3","indextts2"],"default":"cosyvoice3"},"instruct":{"type":"string","optional":true,"engine":"cosyvoice3"},"emo_text":{"type":"string","optional":true,"engine":"indextts2"},"emo_alpha":{"type":"number","optional":true,"default":0.8,"engine":"indextts2"}},"tts_response_headers":{"X-Duration-Sec":"合成音频时长（秒）","X-RTF":"实时率（耗时/时长）","X-Sample-Rate":"采样率（Hz）","X-Voice":"音色 ID","X-Format":"音频格式","X-Engine":"实际引擎","X-Chars":"合成字符数","X-Agent-ID":"调用方 Agent ID","X-Gateway-RTF":"网关层 RTF"},"error_codes":[{"code":400,"meaning":"参数错误（缺 text/voice_id、format 不支持、engine 不存在）"},{"code":401,"meaning":"API Key 缺失或无效"},{"code":403,"meaning":"Agent 已被禁用"},{"code":404,"meaning":"音色不存在"},{"code":429,"meaning":"超过每分钟调用上限（默认 8 次）"},{"code":502,"meaning":"引擎转发失败"},{"code":503,"meaning":"引擎未就绪（down）"}],"examples":["# 1) 注册（公开，无需 Key）\ncurl -X POST https://desktop-gd6ps84.tail9020ed.ts.net/api/register -H 'Content-Type: application/json' -d '{\"name\":\"天气播报\",\"agent_type\":\"播报\",\"purpose\":\"每日天气\"}'","# 2) CosyVoice3 合成（通用）\ncurl -X POST https://desktop-gd6ps84.tail9020ed.ts.net/api/tts -H 'X-API-Key: <你的Key>' -H 'Content-Type: application/json' -d '{\"voice_id\":\"v_0001\",\"text\":\"你好，欢迎使用语音合成\",\"format\":\"wav\",\"engine\":\"cosyvoice3\"}' -o out.wav","# 3) IndexTTS-2 合成（情感）\ncurl -X POST https://desktop-gd6ps84.tail9020ed.ts.net/api/tts -H 'X-API-Key: <你的Key>' -H 'Content-Type: application/json' -d '{\"voice_id\":\"v_0001\",\"text\":\"今天真开心\",\"format\":\"wav\",\"engine\":\"indextts2\",\"emo_text\":\"开心\",\"emo_alpha\":0.8}' -o out.wav","# 4) 获取音色列表\ncurl -X GET 'https://desktop-gd6ps84.tail9020ed.ts.net/api/voices?engine=cosyvoice3' -H 'X-API-Key: <你的Key>'","# 5) 自查用量\ncurl -X GET 'https://desktop-gd6ps84.tail9020ed.ts.net/api/me' -H 'X-API-Key: <你的Key>'"]}