Voice PaaS Admin API
版本:2026-11-17.2。逐接口与完整字段参考 · 下载完整 OpenAPI 3.1。预定义模型直接调用 Realtime;需要持久化业务配置时,沿用自定义模型发布流程。
本页是 LatenTX Voice 管理接口的接入指南,逐字段契约见完整参考。所有接口都使用同一个 API Key,并且只访问当前租户的数据。管理 API 不需要先创建 Agent;推荐使用 LatenTX 模型或已发布的自定义模型。根据目录中所选型号的语言和音色配置自己的模型。
https://api.latenth.com/voice/v1认证:
Authorization: Bearer YOUR_API_KEY成功:
{"success":true,"data":...}失败:先检查非 2xx HTTP 状态,错误体可能是 JSON、纯文本或空响应。联系支持时请提供请求 ID。
可在通话记录查看会话,再使用下方通话记录接口查询详情、事件和录音。
目录
目录与音色
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /catalog |
返回当前租户可用模型、型号支持的语言、公共音色和基础价格。 |
| GET | /voices |
返回公共音色目录。 |
curl https://api.latenth.com/voice/v1/catalog \
-H "Authorization: Bearer $LATENTX_API_KEY"
# data 节选,具体能力与价格以当前目录为准
{
"models": ["latentx-realtime-2.5-max", "latentx-realtime-2.5-plus", "latentx-realtime-2.5-mini"],
"agent_models": ["latentx-realtime-2.5-max", "latentx-realtime-2.5-plus", "latentx-realtime-2.5-mini"],
"voice_models": [{"id":"latentx-realtime-2.5-mini","voices":[{"id":"female-default"}],"default_voice":"female-default"}],
"voices": [{"id":"female-default","name":"定制女声","gender":"female"}],
"default_voice": "female-default"
}
用 voice_models[].id 填写草稿的
config.base_model;语言、音色从同一型号选择。
自定义模型
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /custom-models |
列出租户全部草稿和已发布版本。 |
| GET | /custom-models/{id} |
读取一个模型的草稿、revision 和版本。 |
| PUT | /custom-models/{id} |
创建或更新草稿。需要最新 revision,冲突返回 409。 |
| DELETE | /custom-models/{id} |
删除没有发布版本的草稿。 |
| POST | /custom-models/{id}/validate |
校验型号、资源、MCP 连通性和工具兼容性。 |
| POST | /custom-models/{id}/publish |
生成不可变的 custom-...-vN 模型 ID。 |
| DELETE | /custom-models/{id}/versions/{version} |
停用版本;新会话拒绝,活动会话继续。已发布版本不可删除。 |
PUT /voice/v1/custom-models/support
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"revision": 0,
"config": {
"name": "售后客服",
"base_model": "latentx-realtime-2.5-mini",
"voice": "female-default",
"instructions": "回答售后问题,必要时调用工具。",
"temperature": 0.2,
"max_tokens": 2048,
"silence_duration_ms": 300,
"skills": [],
"knowledge_refs": [],
"mcp_refs": [],
"tools": []
}
}
POST /voice/v1/custom-models/support/validate
{"revision": 1}
POST /voice/v1/custom-models/support/publish
{"revision": 1}
tools 只能保存 Function 定义;MCP 使用
mcp_refs。保存草稿不产生推理费用。发布响应中的
versions[].model 是唯一可调用
ID,必须使用实际返回值。更新、校验和发布均使用最近一次读取或保存所得的
revision。详见自定义模型文档。
Skill 资源
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /skills |
列出当前租户的 Skill 版本。 |
| GET | /skills/{id}/versions/{version} |
读取 Skill 内容和资源。 |
| PUT | /skills/{id}/versions/{version} |
创建不可变版本;修改内容请使用新版本号,覆盖冲突返回 409。 |
PUT /voice/v1/skills/support/versions/v1
{"markdown":"---\nname: support\ndescription: 售后规则\n---\n先询问订单号。"}
Skill 是版本化 Markdown/文本资源。可在 Realtime 的
session.latentx.skills
中内联或引用,也可在自定义模型发布时引用;发布后内容冻结。Skill
不执行任意代码。
知识资源
与流程 Skill 独立展示、独立挂载。知识正文仍是版本化 Markdown 与文本资源,不要求固定 QA 格式。无需预先构建向量索引。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /knowledge | 列出当前租户知识版本 |
| GET | /knowledge/{id}/versions/{version} | 完整正文、resources 和 sha256 |
| PUT | /knowledge/{id}/versions/{version} | 创建不可变知识版本 |
PUT /voice/v1/knowledge/support-faq/versions/v1
{"markdown":"---\nname: support-faq\ndescription: 售后知识\n---\n## 退货\n问:多久可以退货?\n答:以订单约定为准。","resources":{"references/shipping.md":"## 配送\n配送日期以订单页面为准。"}}
自定义模型使用
config.knowledge_refs:[{id,version}],会话使用
session.latentx.knowledge_refs。系统自动提供知识搜索,仅检索已挂载知识。不要再通过外部 MCP
挂载同名搜索工具。
MCP 资源
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /mcp |
列出当前租户已注册 MCP。 |
| POST | /mcp |
创建 MCP 资源。 |
| GET | /mcp/{id} |
读取 MCP 元数据。 |
| PUT | /mcp/{id} |
更新名称、URL、白名单或启用状态。 |
| DELETE | /mcp/{id} |
删除资源;若返回引用冲突,请先核对仍在使用的业务配置。 |
POST /voice/v1/mcp
{
"mcp_id": "orders",
"name": "订单工具",
"url": "https://example.com/mcp",
"headers": {"Authorization":"Bearer YOUR_MCP_TOKEN"},
"tools": ["lookup_order"],
"enabled": true
}
请求中的鉴权头只写入服务端,响应不会回显。MCP URL 必须是公网
HTTPS;私网、元数据地址、凭据
URL、重定向和未列入白名单的工具会被拒绝。自定义模型通过
mcp_refs 引用资源并在发布时冻结配置。
网页临时凭证
在 Voice Playground 中登录即可开始付费多轮调试。签发前校验余额并预占少量额度;服务端持续计量,挂断后核对并释放未消费预占。关闭页面不会取消已发生的费用。每份凭证仅允许一通电话,通话期限以返回凭证及计费会话的 deadline 为准。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /webrtc/credentials |
为网页 SDK 签发单通话短期 SIP/WebRTC 凭证。返回 session_id 和服务端分配的 caller;真实推理按模型的四类 token 费率从钱包扣费。 |
POST /voice/v1/webrtc/credentials
{
"model": "latentx-realtime-2.5-mini",
"from": "web-client",
"instructions": "你是客服。",
"greeting": "您好,请问有什么可以帮您?",
"voice": "female-default",
"silence_duration_ms": 300,
"allow_mcp_tools": false
}
# 返回 data
{"ws":"wss://…","uri":"sip:web-client@…","target":"sip:w…@…","auth_user":"…","password":"…","expires_at":"…"}
该接口必须由业务后端调用。长期 Key 不得进入浏览器;浏览器使用
/sdk/latentx-voice.js 和业务后端自己的 credential
endpoint。详见网页与电话文档。
电话呼入
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /phone-numbers |
列出本租户的平台分配号码。 |
| GET | /phone-numbers/{phone_id} |
读取号码配置。 |
| PUT | /phone-numbers/{phone_id} |
把一个号码绑定到一个 LatenTX 或已发布自定义模型。 |
| DELETE | /phone-numbers/{phone_id} |
解绑号码,进行中的通话不受影响。 |
PUT /voice/v1/phone-numbers/{phone_id}
{
"model": "latentx-realtime-2.5-mini",
"instructions": "你是客服,请简短回答。",
"greeting": "您好,有什么可以帮您?",
"voice": "female-default",
"silence_duration_ms": 300,
"enabled": true,
"allow_mcp_tools": false
}
号码不能跨租户转移。instructions
省略表示继承模型提示词,传空字符串表示明确清空;silence_duration_ms
为 0 表示继承。电话/网页不支持客户端 Function 工具;MCP
自动执行必须显式设置 allow_mcp_tools=true。
电话外呼
通过公共模型或已发布自定义模型发起一通电话,不改变该号码的呼入配置。只允许使用本账号已分配且开通外呼能力的号码。
POST /voice/v1/calls
{"model":"latentx-realtime-2.5-mini","phone_id":"从号码列表获取的ID","to":"13800000000","request_id":"callback-001","greeting":"您好,我是您的业务助手。","ring_timeout":40}
使用 GET /voice/v1/calls/{call_id} 或
GET /voice/v1/calls?request_id=callback-001 查询。POST /voice/v1/calls/{call_id}/cancel
在拨号时取消、接通后挂机。取消是异步的,应查询直到 ended。网络超时或
503 时使用原 request_id 查询或重试,不能换新 ID
盲目重拨;相同参数返回原记录,不同参数返回
409,已经结束的通话也不会重拨。状态为
preparing、dialing、answered、ended。
拨号前预留额度,并保留 API Key 的模型、分组及额度限制;未接通不产生语音模型推理用量,预留按实际执行状态释放。模型用量费不含运营商线路费。详情、转写、事件和录音仍用相同 call_id 查询 conversations 接口。可选 context 最多8000字节、greeting 最多2000字节,ring_timeout 为5–120秒,默认40秒。外部 MCP 须显式 allow_mcp_tools=true;不支持客户执行的 Function。完整字段见 Admin 管理 API。
通话记录
| 方法 | 路径 | 查询 |
|---|---|---|
| GET | /conversations |
limit(1–500)、call_type(realtime /
phone_inbound / phone_outbound / webrtc / playground /
unknown)、origin(realtime / web /
external,兼容筛选)、from/to(RFC3339)、cursor(上一页末项的游标)
|
| GET | /conversations/{call_id} |
读取单通通话、转写和录音临时地址。 |
| GET | /conversations/{call_id}/events |
会话事件;limit 为 1–200,原样传递返回的 next_cursor。即使 items 为空,有游标仍须继续翻页。 |
| GET | /conversations/{call_id}/recordings |
录音轨道、采集状态与临时签名地址;链接过期后重新查询。 |
五种调用方式共用以上租户接口。列表与详情的 call_type 分别为 realtime(Realtime API)、phone_inbound(电话呼入)、phone_outbound(电话外呼)、webrtc(WebRTC)和 playground(Playground);历史来源无法确认时为 unknown。使用 call_type 筛选时先筛选再分页。原 origin 筛选继续兼容:realtime 为 Realtime,web 包括 WebRTC 和 Playground,external 包括电话呼入和外呼。列表下一页使用末项 cursor,直到返回空数组。电话和网页优先读取详情 recording;Realtime 即使没有整通录音,也应查询 recordings 获取轨道。分别检查整通录音和各轨道状态;历史记录可能没有录音。录音 URL 是短期签名地址,请在有效期内使用,不要公开分享。
Admin 日志与用量
| 方法 | 路径 | 查询 |
|---|---|---|
| GET | /logs |
limit(1–500)。返回
request_id、key_id、method、path、status、latency_ms、at。
|
| GET | /usage |
limit(1–500)。返回 Realtime response usage。 |
管理日志不记录请求体、Key、MCP 鉴权头、完整提示词或录音。Realtime usage 的四类字段为文本输入、文本输出、音频输入、音频输出;价格和映射见Realtime 计费。
用量接口的 data 为数组,每项包含 session_id、response_id、model、status、time、usage。这是响应用量审计,不是钱包账单。独立转写用量从该会话的 events → items[].data.usage 核对。
写入请求统一使用
Content-Type: application/json,请求体上限 512
KiB。部分网关错误响应可能为空;先判断 HTTP 状态,再尝试解析
JSON。列表不提供统一
total;通话和事件按上述游标分页;logs、usage
默认 limit=100,通话默认 limit=50。
MCP 的 PUT 为完整替换,需保留所需 headers、tools 与 enabled;省略 headers 不代表保留旧凭据。GET 不回显 headers,当前也不返回 enabled;请由业务后端安全保存所需配置。
错误与安全
| 状态 | 含义 |
|---|---|
| 400 | 参数、模型、资源版本或工具配置无效。 |
| 401 | Key 缺失、过期或无效。 |
| 404 | 资源不属于当前租户、模型已停用或号码不存在。 |
| 409 | revision 冲突、资源仍被兼容接口引用、Skill 版本内容冲突,或已发布版本不可删除。 |
| 413 | 请求体超过平台限制。 |
| 429 | 触发账户、Key 或服务容量限制。 |
| 5xx | 服务暂时不可用;安全重试 GET,写操作请使用最新 revision 后重试。 |
租户归属由认证上下文确定,请勿传入 tenant
参数;不支持的查询参数会被拒绝。写操作通过 Admin API 日志追踪;请保存
X-Request-ID 便于排障。
公开元数据与价格
目录不提供租户实现标识。已有模型 ID 和资源操作 ID 保持有效,请将它们视为不透明标识,不根据 ID 字符串推导账号或运行结构。三种接入方式均使用预定义或已发布自定义模型 ID。可复用业务配置通过自定义模型的草稿、校验和发布流程管理。
公开价格接口 GET /api/pricing 返回用于展示的基础销售单价,不返回执行表达式或供应商、分组关联配置。price_currency 为 USD;token 单价单位为每百万 token,billingUnit=request 时 fixedPrice 单位为每请求。账号价格调整可能适用;price_tiers 为空表示无法提供展示单价,不代表免费。
{"success":true,"data":[{"model_name":"example-model","public_pricing":true,"price_currency":"USD","price_basis":"base","price_tiers":[{"label":"standard","conditions":[],"inputPrice":2,"outputPrice":8}]}]}
多个价格档位按顺序匹配 conditions;最后的空条件档位为兜底。接口错误保留 HTTP 状态、错误码及请求 ID,通用网关错误类型为 api_error。