电话与网页接入
最新完整字段见 网页凭证请求、电话配置及 网页语音 OpenAPI。ASR/TTS语言可在对应配置中设置,必须是所选型号支持的值。内置知识搜索无需外部MCP;外部MCP仍需 allow_mcp_tools=true,网页和电话不支持客户执行的Function。
对外只有 LatenTX 模型和自定义模型。自定义模型选择完整的基础语音型号,配置业务提示词、语言、音色和资源,发布后获得 model ID。电话与网页是模型的接入方式,不需要另外创建 Agent。
网页应用从网页接入获取 SDK 与后端签发凭证的示例;电话场景分别使用电话呼入绑定接听模型,或在电话外呼选择主叫、模型和被叫号码。所有记录统一在通话记录查看。
电话呼入:一个号码绑定一个模型
沿用 Realtime API Key,后端调用
https://api.latenth.com/voice/v1,请求头为
Authorization: Bearer YOUR_API_KEY。号码由平台分配,只能配置本租户的号码和模型。
从号码列表取得
phone_id
后配置、停用或解绑该号码。同一线路的多个号码可以使用不同模型,操作互不影响。line_id
仅表示所属线路;旧线路标识仅兼容原展示号码,不用于选择其他号码。
GET /phone-numbers
GET /phone-numbers/{phone_id}
PUT /phone-numbers/{phone_id}
{
"model": "latentx-realtime-2.5-mini",
"instructions": "你是公司的客服,请简洁回答。",
"greeting": "您好,有什么可以帮您?",
"voice": "female-default",
"silence_duration_ms": 300,
"idle_timeout_ms": 10000,
"enabled": true,
"allow_mcp_tools": false
}
DELETE /phone-numbers/{phone_id}
model 也可以是已发布的 custom-…-vN。省略 instructions
使用模型默认提示词,传空字符串则覆盖为空;省略 voice
或传空值使用模型音色;省略 silence_duration_ms 或传 0 使用模型
VAD(200–2000ms,仅用于断句)。idle_timeout_ms
独立控制通话无回应提醒/挂断,默认10000ms、范围3000–60000ms。保存使用完整配置替换,未传的开场白为空、enabled
默认为 true、MCP 授权默认为 false,不是
PATCH。自定义模型按发布版本冻结,不自动跟随草稿修改。
停用版本阻止新的电话和网页通话,活动通话继续。解绑停止该号码的新通话。旧接入记录保持兼容,重新选择模型并保存后使用新模式。
网页临时凭证与 SDK
POST /webrtc/credentials
{
"model": "latentx-realtime-2.5-mini",
"from": "web-client",
"greeting": "您好"
}
支持与号码相同的通话配置。from 为 1–32 位字母、数字、下划线、加号或减号。返回 ws、uri、target、auth_user、password、expires_at,均用于本次租户的短期浏览器接入;长期 API Key 只存放于业务后端。
import { VoiceWebSession } from '/sdk/latentx-voice.js'
const session = new VoiceWebSession({
model: 'latentx-realtime-2.5-mini',
credentialEndpoint: '/your-backend/voice-credential',
callConfig: { greeting: '您好' },
audioElement: document.querySelector('audio'),
onStatus: console.log
})
await session.start()
// session.mute(true); session.stop()
业务后端需校验登录态和允许调用的模型,再转发 model、from、通话配置,返回临时凭证。SDK 使用 SIP 信令和 WebRTC 音频,需要 HTTPS、麦克风权限和可达的媒体网络;不是 OpenAI 原生 WebRTC 接口。
SDK 参数与状态
audioElement 必填,传入实际的
HTMLAudioElement。页面应提供 audio 元素,从用户点击事件调用
start() 并捕获异常。SDK
可以下载到自己的站点;跨站集成时,请使用实际部署的 SDK 文件地址。
-
credentialEndpoint:自己的后端地址。SDK POST model、from 和 callConfig;后端返回平台的 success/data 包装或单独的 data 对象。 -
getCredential:替代 credentialEndpoint 的异步函数,必须直接返回已解包的凭证对象。 -
iceServers:可选 RTCIceServer 数组,根据网络环境设置 STUN/TURN。 -
onStatus:connecting、ringing、active、ended;playback-blocked 表示需要用户允许音频播放。onError接收 Error。 -
start()发起通话,mute(true|false)开关麦克风,stop()结束通话并释放媒体资源。
排查顺序:凭证接口状态、expires_at、WSS 可达性、麦克风授权、ICE/媒体网络、音频自动播放。
可观测性与录音输入
inputStream 可传入已有 MediaStream,SDK
不再申请麦克风,也不负责停止调用方的音轨。适合录音回放、设备选择和自动化验收。省略则由
SDK 采集并管理麦克风。
onPeerConnection(pc) 提供原生连接;await session.getStats()
返回浏览器 RTCStatsReport,可观察
packetsReceived、packetsLost、jitter、RTT。上传统计前应过滤候选地址等网络信息。
onEnded({originator,cause}) 每通仅通知一次;originator 为
local、remote 或 system,cause 是
SIP/本地关闭原因。服务端业务挂断原因仍应查询通话记录的 hangup_reason。
自动回放应等开场白或上一轮回复结束后再发送下一条;固定时间发送可能主动打断回复。先验收完整转写与回复,再评估低延迟。
机器可读的网页接入接口:OpenAPI JSON;范围仅覆盖临时凭证及通话记录,不是全平台协议声明。
电话外呼
外呼只需选择一个已开通外呼能力的主叫号码、语音模型及被叫号码。每通可单独设置开场白和 context;调用前请核对号码、授权和账户余额。
图中为未分配主叫号码时的表单。开通号码后才可拨测;平台不提供任务编排或批量调度。
通过公共模型或已发布自定义模型发起一通电话,不改变该号码的呼入配置。只允许使用本账号已分配且开通外呼能力的号码。
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。
会话记录
新会话默认记录事件。电话、网页和 Realtime 统一通过
GET /voice/v1/conversations/{id}/events 查询;查看
capture_state 判断记录是否完整,原样传递 next_cursor
分页。电话和网页保留原生事件语义。整通录音优先查看会话详情
recording;账号开通分段录音时,/recordings
还可返回轨道。整通文件可用与分段状态 partial
可以同时成立;按每条轨道的 state 和临时链接判断。录音与事件采集独立。
工具和计费边界
Skill/MCP 来自自定义模型发布快照。电话和网页无法向客户端回传 Function 工具执行请求,因此含 Function 的模型会拒绝接入,请改用 Realtime WebSocket。MCP 自动执行需显式设置 allow_mcp_tools=true,仅允许模型的工具白名单。
Realtime WebSocket 沿用四类 token 计费。Console Playground 网页通话按所选模型的四类 token 费率从钱包扣费。所有账号的电话通话默认计费,来电接入前检查账号、号码、模型与余额,通话按模型四类实际用量从钱包扣费,结束后结算并释放剩余预留额度。使用日志来源为 phone / Voice Phone;重复用量上报不重复扣款,模型用量费用不包含运营商线路费。