接入说明
各服务的调用格式与示例代码:
- 语音对话(
/v1/realtime):语音进、语音出 - 纯识别(
/v1/asr):语音进、文字出
本页是两种服务共用的约定:API key、鉴权、拒绝与错误码、费用,以及用 API key 查询余额和账单。
API key
- key 由我们签发,形如
sk_live_<12 位十六进制>_<密文>。明文只在签发时给一次,请自行妥善保存,不要写进代码仓库、聊天记录或日志;日志里只记前缀(sk_live_加 12 位十六进制)。 - 一把 key 只开通一种服务:语音对话的 key 只能连
/v1/realtime,纯识别的 key 只能连/v1/asr,连错入口握手被拒。两种服务都要时,我们签两把。 - key 归属于一个账户:并发上限、余额和账单都按账户计算,同一账户下的多把 key 共用。
鉴权与连接
| 项 | 规定 |
|---|---|
| 语音对话入口 | wss://api.jftxyun.com:31080/v1/realtime |
| 纯识别入口 | wss://api.jftxyun.com:31080/v1/asr |
| 鉴权 | WebSocket 握手请求头 Authorization: Bearer <key>。不接受用其他请求头、URL 参数或事件字段传 key |
| 粒度 | 一通电话(一次识别会话)一条 WebSocket 连接 |
| 首帧 | 握手之后第一条消息必须是带 session_id 的 session.start;所有消息都是 JSON 文本帧,音频用 Base64 |
拒绝与错误码
握手被拒返回 HTTP 403:key 格式不对、不存在、已吊销或过期、账户停用、IP 不在白名单、key 用在了另一种服务的入口。具体原因不返回,请联系我们核对 key;403 不要重试。
握手成功、发出 session.start 之后准入失败,会收到一条 error(fatal: true),随后连接关闭。error.session_id 是你方 session.start 里的 session_id。
| code | 关闭码 | 可重试 | 含义 |
|---|---|---|---|
INVALID_EVENT | 1008 | 否 | 超时没收到首帧,或首帧不是带 session_id 的 session.start |
CONCURRENCY_LIMIT | 4429 | 是 | 超出账户的并发上限 |
INSUFFICIENT_BALANCE | 4402 | 否 | 余额不够开始这一通 |
CUSTOMER_INACTIVE | 4403 | 是 | 账户被暂停 |
NO_CAPACITY | 1013 | 是 | 暂时没有空闲的服务容量 |
SERVICE_UNAVAILABLE | 1013 | 是 | 服务暂时不可用 |
会话进行中:余额耗尽时先收到 error{code:"INSUFFICIENT_BALANCE", fatal:false},随后照常收到 session.result;被我们在管理端挂断时收到 error{code:"CALL_TERMINATED"},随后照常收到 session.result。
费用
session.result 带 billing: {currency, cost_micros},是这一通的费用;金额单位 micros,1 元 = 1,000,000 micros。计费规则与价格以用量后台公示的为准。
查询余额、用量与账单
用任一把 key 发 HTTPS GET,请求头同样是 Authorization: Bearer <key>,查到的是这把 key 所属账户的数据。key 不可用时回 HTTP 403。金额单位 micros,时间为北京时间(+08:00),月份按北京时间切。
curl -s -H "Authorization: Bearer $KEY" https://api.jftxyun.com:31080/v1/account
| 接口 | 返回 |
|---|---|
GET /v1/account | 余额 balance_micros、信用额度 credit_limit_micros、可用额度 available_micros(扣除进行中通话的预留)、并发上限 max_concurrency、在线通话数 live_calls、当前价格 plan |
GET /v1/usage?period=YYYY-MM | 该月(默认本月)的通话数 calls、消费 charged_micros、按服务分的 by_service、计费量 billed_quantity、被拒次数 refusals |
GET /v1/sessions?limit=&before=&session_id= | 通话列表,按开始时间倒序:call_id、session_id、service、status、end_reason、started_at、ended_at、charged_micros、key_name、计价明细 lines。limit 默认 100、最大 1000;翻页把上一页最后一条的 started_at 作为 before |
GET /v1/ledger?limit=&before_id= | 资金流水,按 id 倒序:kind(topup 充值 / charge 扣费 / refund 退款 / adjust 调整)、amount_micros(扣费为负)、balance_after_micros、call_id、created_at。翻页把上一页最后一条的 id 作为 before_id |
同样的数据也可以登录用量后台查看。