PUBLIC API · VERSION 1

语音识别 API

面向服务端、Web 和实时字幕场景的多租户语音转文字服务，支持文件识别、WebSocket 流式识别、英菲自动识别与租户用量查询。

开始接入下载完整文档

Base URL

https://asr-api.sonari.dev/v1

所有业务请求均通过 HTTPS / WSS 发送。

协议HTTPS / WSSTLS 加密传输

鉴权Bearer API Key租户级配额与计量

文件上限50 MBWAV / MP3 等常见格式

实时音频PCM16 LE建议每块 100–600 ms

鉴权

除健康检查外，每个请求都必须携带租户 API Key。

安全提示API Key 只显示一次。请保存在服务端密钥管理系统中，不要提交到 Git、日志或公开前端代码。

HTTP Header

Authorization: Bearer sk_live_YOUR_API_KEY

浏览器 WebSocket 无法设置自定义 Header 时，可使用 ?token=sk_live_... 查询参数。Key 缺失、无效、已吊销或租户已停用时返回 401，WebSocket 使用关闭码 4401。

一分钟快速开始

使用 curl 上传音频文件并获取文本。

1
获取 API Key
由 Sonari 管理员创建租户并签发 sk_live_...。
2
准备音频
使用 WAV、MP3 或其他常见音频文件，最大 50 MB。
3
发送请求
选择语言并调用文件识别接口。

curl

curl --request POST "https://asr-api.sonari.dev/v1/asr/file"   --header "Authorization: Bearer sk_live_YOUR_API_KEY"   --form "file=@sample.wav"   --form "lang=zh"

200 OK

{
  "text": "测试一下，这是识别结果。",
  "lang": "zh",
  "filtered": false,
  "sample_rate": 24000,
  "audio_seconds": 7.0,
  "elapsed_seconds": 0.1
}

文件识别

POST/v1/asr/file

字段	类型	必填	说明
`file`	File	是	WAV、MP3 等常见音频；服务端自动转为 16 kHz。
`lang`	String	否	默认 `zh`；可用值见语言支持。

Python · requests

import requests

url = "https://asr-api.sonari.dev/v1/asr/file"
headers = {"Authorization": "Bearer sk_live_YOUR_API_KEY"}
with open("sample.wav", "rb") as audio:
    response = requests.post(
        url,
        headers=headers,
        files={"file": audio},
        data={"lang": "enfil"},
        timeout=60,
    )
response.raise_for_status()
print(response.json()["text"])

Node.js · fetch

import fs from "node:fs";

const form = new FormData();
form.append("lang", "zh");
form.append("file", new Blob([
  fs.readFileSync("sample.wav")
]), "sample.wav");

const response = await fetch(
  "https://asr-api.sonari.dev/v1/asr/file",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_YOUR_API_KEY"
    },
    body: form
  }
);
console.log(await response.json());

WebSocket 流式识别

WS/v1/asr/stream

连接成功后先发送 start JSON，再持续发送裸 PCM16 小端音频字节。发送 commit 可结束一句并保持连接，发送 end 结束流。

1连接WSS + token

→

2start语言 / 采样率

→

3PCM16100–600 ms / 块

→

4partial / done字幕 / 最终稿

Browser WebSocket

const API_KEY = "sk_live_YOUR_API_KEY";
const url = "wss://asr-api.sonari.dev/v1/asr/stream?token="
  + encodeURIComponent(API_KEY);
const ws = new WebSocket(url);
ws.binaryType = "arraybuffer";

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "start",
    sample_rate: 16000,
    lang: "zh"
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === "partial") {
    console.log("字幕:", message.text);
  }
  if (message.type === "done") {
    console.log("最终稿:", message.full_text);
  }
};

// 持续发送 Int16Array 的 buffer
// ws.send(pcm16Chunk.buffer);
// 一句话结束：ws.send(JSON.stringify({type: "commit"}));
// 整个流结束：ws.send(JSON.stringify({type: "end"}));

音频要求16-bit 有符号小端 PCM，不带 WAV 文件头。采样率不是 16 kHz 时服务端会自动重采样。

语言支持

调用 GET /v1/languages 可获取当前实时能力。

zh中文普通话生产级 · 流式 partial

en英语生产级 · 流式 partial

id印尼语生产级 · rolling partial

fil菲律宾语生产级 · rolling partial

enfil英菲自动识别推荐 Taglish / 英菲混说

th泰语已启用 · rolling partial

查询租户用量

GET/v1/usage?days=30

curl

curl "https://asr-api.sonari.dev/v1/usage?days=30"   --header "Authorization: Bearer sk_live_YOUR_API_KEY"

200 OK

{
  "tenant": "proj_example",
  "window_days": 30,
  "requests": 1284,
  "audio_seconds": 5230.4,
  "errors": 3,
  "limits": {
    "rpm": 240,
    "max_concurrent_streams": 6
  }
}

响应与非语音过滤

音乐、背景噪声和静音不会被当成有效文字送给下游。

filtered: true当响应同时返回空 text 或 full_text 时，表示该段被识别为非语音。客户端应忽略，不要发送给 LLM 或字幕系统。

enfil 会在响应的 lang 字段中返回实际检测结果 en 或 fil。文件识别使用 text，流式最终结果使用 full_text。

限流与错误处理

每个租户拥有独立 RPM、并发流配额和用量统计。

状态码	类型	说明
`400`	`bad_request`	语言或请求参数无效。
`401`	`auth_error`	Key 缺失、无效、已吊销或租户停用。
`413`	`too_large`	文件超过上传限制。
`429`	`rate_limited`	RPM 超限；参考 `Retry-After`。
`502`	`upstream_error`	识别引擎暂时不可达或执行失败。

Error JSON

{
  "error": {
    "type": "auth_error",
    "message": "invalid or missing API key"
  }
}

WebSocket 鉴权失败使用关闭码 4401，并发流超限使用关闭码 4429。

接口清单

完整语音智能、声纹和事件 API 说明可下载 Markdown 文档查看。

GET/v1/health健康检查免鉴权

GET/v1/languages语言与能力矩阵需鉴权

POST/v1/asr/file文件语音识别需鉴权

WS/v1/asr/stream实时流式识别需鉴权

GET/v1/usage租户用量查询需鉴权

GET/v1/voice/capabilities语音智能能力需鉴权

POST/v1/voice/asr/fileASR + 语音智能事件需鉴权

WS/v1/voice/stream实时语音智能流需鉴权

准备开始？

获取租户 API Key 后即可接入

下载完整文档保存到项目，或查看机器可读的 OpenAPI JSON。

下载 Markdown OpenAPI JSON