REST 接口｜玲声开放平台文档

接口地址 https://aicall.lingshengai.com。每个请求带请求头 Authorization: Bearer <令牌>，请求体用 JSON。

出错时

接口出错时回 4xx 或 5xx，内容是 {"detail": {"code", "message", "fix"}}：code 给程序判断，message 说发生了什么，fix 说下一步怎么做。

拨一通

POSThttps://aicall.lingshengai.com/api/v1/calls

给一个号码和这一通要说的话，我们拨出去。受理回 202；没受理回 200 并说明原因，见下方「没受理的原因」。

请求体（JSON）

字段	类型	必填	说明
`to`	`string`	否	拨给谁。国内手机号，缺省只能是你验证过的号码。
`instructions`	`string`	否	这一通要办的事，写给 AI 看。只对这一通有效。
`greeting`	`string`	否	接通后第一句话。不填就用缺省开场。
`voice`	`string`	否	音色。不填用缺省。

字段	类型	说明
`callId`	`integer \| null`	这一通的编号，拿去查结果。没受理时为 null。
`status`	`string`	queued：已排队，会拨出去；rejected：没受理。
`code`	`string`	没受理的原因码。受理时为空。
`message`	`string`	没受理的原因，一句话。

拨一通

curl -X POST https://aicall.lingshengai.com/api/v1/calls \
  -H "Authorization: Bearer lsk_你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
        "to": "13800000000",
        "instructions": "提醒对方今晚八点吃药，确认一声就挂",
        "greeting": "您好，是张先生吗？"
      }'

回来的 callId 拿去查这一通：GET /api/v1/calls/{callId}。

没受理的原因

没受理不算出错：回 200，status 是 rejected，code 是下面其中一个。额度用完的两种情况回 402，detail.code 是 quota_exhausted。

code	HTTP	意思
`not_verified`	200	这个号还没在这家店验证过，我们不会拨给它
`bad_number`	200	这不是一个能拨出去的国内手机号
`blocked`	200	这个号在免打扰名单上，我们不会再拨给它
`duplicate_24h`	200	24 小时之内已经拨过这个号了
`global_daily`	200	今天平台的外呼总量到上限了，明天再试
`quota_minutes`	402	这家店本月的通话分钟用完了
`trial_daily`	200	这家试用门店今天的外呼次数用完了
`trial_ended`	200	这家门店的试用已经结束了
`trial_minutes_used_up`	402	这家试用门店赠送的通话时长用完了
`line_not_open`	200	电话线路还没开通，这一通拨不出去
`line_unknown`	200	问不到电话线路现在通不通，这一通先不拨

查一通

GEThttps://aicall.lingshengai.com/api/v1/calls/{call_id}

这一通的状态、时长、费用、摘要、逐句转写和录音。

参数

字段	类型	必填	说明
`call_id`路径	`string`	是	拨号时回来的 callId。

字段	类型	说明
`callId`	`integer \| null`	编号。
`callUuid`	`string \| null`	通话的另一个编号，回调里也有。
`direction`	`string`	outbound：你拨出去的；inbound：打进来的。
`status`	`string`	queued 排队中 · in_progress 通话中 · ended 已挂断 · failed 没接通 · unknown 查不清。
`outcome`	`string`	结局的细分，比如 answered。
`phone`	`string`	对方号码。
`queuedAt`	`string \| null`	排进队列的时间（UTC）。
`answeredAt`	`string \| null`	接通时间（UTC），没接通为 null。
`endedAt`	`string \| null`	挂断时间（UTC）。
`durationSeconds`	`integer \| null`	接通到挂断的秒数。
`billableMinutes`	`integer \| null`	计费分钟。账还没出时为 null，不是 0。
`unitPriceFen`	`integer \| null`	每分钟单价，单位分。
`costFen`	`integer \| null`	这一通的费用，单位分。
`summary`	`string`	通话摘要。挂断后几分钟才有。
`category`	`string`	通话分类。
`transcript`	`object[]`	逐句转写：speaker、text、startMs、endMs。
`recordingUrl`	`string \| null`	录音地址，10 分钟内有效，要再听就再查一次。
`recordingExpiresInSec`	`integer \| null`	录音地址还有多少秒过期。

看用量

GEThttps://aicall.lingshengai.com/api/v1/usage

一段时间里打了几通、多少分钟、多少钱。不给时间就是本月。

参数

字段	类型	必填	说明
`from`查询参数	`string \| null`	否	开始日期或时刻，比如 2026-09-01。
`to`查询参数	`string \| null`	否	结束日期或时刻。只给日期时算到当天结束。

字段	类型	说明
`from`	`string`	统计开始（UTC）。
`to`	`string`	统计结束（UTC）。
`calls`	`integer`	通数。
`seconds`	`integer`	通话总秒数。
`minutes`	`integer`	计费总分钟。
`costFen`	`integer`	总费用，单位分。
`capMinutes`	`integer \| null`	本月额度分钟。没设额度就没有这一格。
`remaining`	`integer \| null`	本月还剩多少分钟。没设额度就没有这一格。
`cycleFrom`	`string \| null`	额度周期开始（UTC）。
`cycleTo`	`string \| null`	额度周期结束（UTC）。

看用了多少

curl https://aicall.lingshengai.com/api/v1/usage \
  -H "Authorization: Bearer lsk_你的令牌"

REST 接口

出错时

拨一通

没受理的原因

查一通

看用量

本页目录