LATENTX / DOCUMENTATION

Voice PaaS Admin API

版本:2026-11-17.2。逐接口与完整字段参考 · 下载完整 OpenAPI 3.1。预定义模型直接调用 Realtime;需要持久化业务配置时,沿用自定义模型发布流程。

本页是 LatenTX Voice 管理接口的接入指南,逐字段契约见完整参考。所有接口都使用同一个 API Key,并且只访问当前租户的数据。管理 API 不需要先创建 Agent;推荐使用 LatenTX 模型或已发布的自定义模型。根据目录中所选型号的语言和音色配置自己的模型。

Base URL:https://api.latenth.com/voice/v1
认证:Authorization: Bearer YOUR_API_KEY
成功:{"success":true,"data":...}
失败:先检查非 2xx HTTP 状态,错误体可能是 JSON、纯文本或空响应。联系支持时请提供请求 ID。

可在通话记录查看会话,再使用下方通话记录接口查询详情、事件和录音。

通话记录列表:调用方式筛选和详情入口;时间、主被叫标识及通话 ID 均已遮盖。
通话记录界面 · 时间、主被叫标识及通话 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。