临境知远
API Reference

接口文档

所有接口都在同一个地址下，用同一个访问令牌（T）调用。语音识别与语音合成接口和 OpenAI 的格式一致，可以直接用 OpenAI 官方 SDK。

快速开始

  1. 在 申请接入 页面提交申请，审核通过后会收到以 sk-lj- 开头的访问令牌。
  2. 接口地址：https://服务地址/v1
  3. 在请求头加上 Authorization: Bearer 你的令牌，按下面的示例调用即可。

鉴权

每个请求都要在请求头带上令牌，两种写法任选：

Authorization: Bearer sk-lj-你的令牌
# 或
X-API-Key: sk-lj-你的令牌

令牌有有效期和额度，过期、停用或额度用完时接口会返回明确的错误信息。请勿把令牌写在网页前端或公开仓库里。

每个响应都带 X-Request-Id 头，遇到问题时把它发给我们可以快速定位。

语音识别

POST/v1/audio/transcriptions

上传一段音频或视频，同步返回识别文字。适合 5 分钟以内的音频，更长的录音请用 会议转写。支持 wav、mp3、m4a、aac、ogg、opus、flac、amr、webm、mp4 等常见格式。

参数类型必填说明
file文件是音频或视频文件
model字符串否固定填 sensevoice 即可（兼容 OpenAI 写法，填 whisper-1 也可以）
language字符串否语言提示：auto（默认，自动判断）、zh、en、yue、ja、ko
response_format字符串否json（默认）、text、verbose_json（带分段与时间戳）、srt、vtt
diarize布尔否true 时区分说话人，分段里返回 speaker
num_speakers整数否已知说话人数时填写，区分更准确
curl https://服务地址/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-lj-你的令牌" \
  -F file=@meeting.m4a \
  -F response_format=verbose_json

verbose_json 返回示例：

{
  "text": "大家好，今天我们讨论第四季度的计划。",
  "language": "zh",
  "duration": 4.32,
  "segments": [
    { "id": 0, "start": 0.12, "end": 4.2, "text": "大家好，今天我们讨论第四季度的计划。", "lang": "zh", "emotion": "NEUTRAL" }
  ]
}

会议转写（异步任务）

POST/v1/audio/transcriptions/jobs

适合长录音（默认最长 2 小时）。提交后立即返回任务编号，服务器在后台排队处理；处理完成后可以轮询查询，也可以填 callback_url 等待回调。

参数类型必填说明
file文件是音频或视频文件
language字符串否同语音识别
diarize布尔否区分说话人（默认最长支持 1 小时音频）
num_speakers整数否说话人数，1 到 20
callback_url字符串否完成或失败时 POST 任务结果到这个公网地址
# 1. 提交任务（diarize=true 表示区分说话人）
curl https://服务地址/v1/audio/transcriptions/jobs \
  -H "Authorization: Bearer sk-lj-你的令牌" \
  -F file=@meeting.mp3 -F diarize=true

# 2. 查询进度与结果（format 可选 json / text / srt / vtt）
curl "https://服务地址/v1/audio/transcriptions/jobs/<任务ID>?format=text" \
  -H "Authorization: Bearer sk-lj-你的令牌"

查询与取消

GET/v1/audio/transcriptions/jobs/{任务ID}?format=json|text|srt|vtt
GET/v1/audio/transcriptions/jobs
DELETE/v1/audio/transcriptions/jobs/{任务ID}

任务状态：queued 排队中、running 处理中（progress 为 0~1 的进度）、succeeded 成功、failed 失败、canceled 已取消。原始音频在服务器上保留 7 天后自动删除。

回调验签

回调请求带 X-Ljs-Signature 头，值为 HMAC-SHA256(key = sha256(你的令牌) 的十六进制字符串, message = 请求体) 的十六进制结果，可用于确认回调来自本服务：

import hashlib, hmac

key = hashlib.sha256(TOKEN.encode()).hexdigest().encode()
expected = hmac.new(key, request_body_bytes, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, request.headers["X-Ljs-Signature"])

文字识别

POST/v1/ocr

识别图片或 PDF 中的文字。支持 jpg、png、webp、bmp、tiff 和 PDF（默认单次最多 5 页）。可以用 multipart 上传 file，也可以用 JSON 传 base64：{"image": "base64..."}。

curl https://服务地址/v1/ocr \
  -H "Authorization: Bearer sk-lj-你的令牌" \
  -F file=@photo.jpg
{
  "text": "整页文字，按行排版",
  "page_count": 1,
  "engine": "local",
  "pages": [
    {
      "page": 1, "width": 1280, "height": 960, "text": "...",
      "lines": [{ "text": "临境知远", "score": 0.99, "box": [[12, 30], [180, 30], [180, 62], [12, 62]] }]
    }
  ]
}

发票识别

POST/v1/ocr/invoice

上传发票（数电发票 PDF、扫描件或照片），返回结构化字段。数电发票 PDF 直接读取文件里的文字，准确率最高，建议优先上传 PDF 原件。

识别后会自动校验「金额 + 税额 = 价税合计」和大写金额；对不上、缺少关键字段或照片不清晰时，needs_review 为 true，并在 review_reasons 里说明原因。

curl https://服务地址/v1/ocr/invoice \
  -H "Authorization: Bearer sk-lj-你的令牌" \
  -F file=@invoice.pdf
{
  "source": "pdf_text",          // pdf_text 读取 PDF 文字 | ocr 图片识别
  "fields": {
    "invoice_type": "电子发票（普通发票）",
    "invoice_number": "24442000000123456789",
    "issue_date": "2026-10-20",
    "buyer_name": "广州某某科技有限公司",   "buyer_tax_id": "91440101MA5C......",
    "seller_name": "深圳某某餐饮管理有限公司", "seller_tax_id": "91440300MA5D......",
    "total_amount": 283.02, "total_tax": 16.98, "amount_with_tax": 300.0,
    "amount_in_words": "叁佰圆整", "drawer": "李四"
  },
  "items": [{ "name": "*餐饮服务*餐费", "tax_rate": "6%", "amount": 283.02, "tax": 16.98 }],
  "checks": [{ "name": "金额 + 税额 = 价税合计", "passed": true, "detail": "283.02 + 16.98 = 300.00" }],
  "needs_review": false,
  "review_reasons": []
}

语音合成

POST/v1/audio/speech
参数类型必填说明
input字符串是要合成的文字，默认单次最多 2000 字
voice字符串否音色，默认 female。可用：female（女声）、male（男声）；OpenAI 的 alloy、nova 等会自动对应
speed数字否语速 0.5 ~ 2.0，默认 1.0
response_format字符串否mp3（默认）、wav、opus、aac、flac、pcm（16 位单声道）
curl https://服务地址/v1/audio/speech \
  -H "Authorization: Bearer sk-lj-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"input": "你好，欢迎使用临境知远语音服务。", "voice": "female", "response_format": "mp3"}' \
  -o speech.mp3

返回音频文件本身，响应头 X-Audio-Seconds 是音频时长。可用音色也可以调用 GET /v1/voices 查询。

额度查询

GET/v1/usage

返回当前令牌的有效期、开通的服务、每项额度的上限和已用量。GET /v1/models 返回当前令牌可用的能力列表。

错误码

出错时返回对应的 HTTP 状态码，响应体格式与 OpenAI 一致：

{ "error": { "message": "本月语音识别额度不足：已用 598.5 分钟，本次需要 3.2 分钟，上限 600.0 分钟", "type": "rate_limit_error", "code": "quota_exceeded" } }
状态码code说明
400invalid_params / invalid_audio / …参数错误或文件无法解析
401missing_token / invalid_token没带令牌或令牌不存在
403token_expired / token_disabled / service_not_allowed令牌过期、被停用，或没有开通这项服务
413file_too_large / audio_too_long / text_too_long超过单次大小或时长限制
429rate_limited / quota_exceeded请求太频繁，或额度用完
503server_busy服务器繁忙，请按 Retry-After 头稍后重试
500 / 502internal_error / upstream_error服务内部错误，请带上 X-Request-Id 联系我们

限制说明

  • 同步语音识别：单个文件默认最长 5 分钟、50MB；会议转写：默认最长 2 小时、300MB。
  • 文字识别：单个文件默认最大 50MB，PDF 单次最多 5 页；每页 / 每张图计 1 张用量。
  • 语音合成：单次默认最多 2000 字，按字数计用量。
  • 每个令牌默认每分钟最多 60 次请求，具体以发放时的设置为准。
  • 服务器按顺序处理识别请求，高峰期可能需要排队，响应头 X-Queue-Ms 表示排队等待的毫秒数。