语音识别接口

将音频转换为文本。

---

一、HTTP 识别接口

接口信息

• 接口路径: /v1/speech-to-text
• 请求方式: POST
• 认证方式: Header 中的 X-API-Key
• 响应方式: 同步返回 JSON 识别结果

请求头

参数名	类型	必填	说明
X-API-Key	string	是	应用密钥

注意： X-API-Key 用于验证账户信息，进入 控制台 → 项目空间，选择对应项目，左侧导航进入「API Key 管理」即可创建/查看。

请求参数

参数名	类型	必填	说明
audio_data	string	是	Base64 编码后的 raw PCM 音频数据；HTTP 同步识别要求音频时长至少 2 秒
audio_format	string	否	音频格式，仅支持 pcm16 / pcm_16000，默认 pcm16
language	string	否	识别语言，不传时自动识别

音频格式要求

参数	值
编码	16-bit Signed Little-Endian PCM
采样率	16000 Hz（pcm16 和 pcm_16000 均使用此采样率）
声道数	1（单声道）
最小时长	HTTP 同步识别至少 2 秒；更短会直接返回参数错误

响应参数

字段	类型	说明
text	string	最终识别文本
language	string	识别或请求指定的语言代码
confidence	number	置信度评分，范围通常为 0 ~ 1
duration_ms	number	音频时长，单位毫秒

成功响应示例

{
  "text": "hello, welcome to the speech recognition service",
  "confidence": 0.96,
  "duration_ms": 2480
}

短音频错误示例

当 audio_data 对应的 PCM 音频短于 2 秒时，接口返回以下错误。请提供至少 2 秒的音频：

{
  "error_code": 20014,
  "error_message": "音频时长至少需要2秒，才能进行同步语音识别",
  "succeed": false,
  "data": null
}

请求示例

AUDIO_DATA=$(base64 -i sample.pcm | tr -d '\n')

curl -X POST "https://api.vuilabs.cn/v1/speech-to-text" \
  -H "X-API-Key: your-secret-key-here" \
  -H "Content-Type: application/json" \
  -d "{
    \"audio_data\": \"${AUDIO_DATA}\",
    \"audio_format\": \"pcm16\"
  }"

调用示例

Python

import base64
import requests

with open("sample.pcm", "rb") as f:
    audio_data = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.vuilabs.cn/v1/speech-to-text",
    headers={"X-API-Key": "your-secret-key-here"},
    json={
        "audio_data": audio_data,
        "audio_format": "pcm16",
    }
)

print(response.json())

Node.js

const fs = require("fs");

const audioData = fs.readFileSync("sample.pcm").toString("base64");

const response = await fetch("https://api.vuilabs.cn/v1/speech-to-text", {
  method: "POST",
  headers: {
    "X-API-Key": "your-secret-key-here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    audio_data: audioData,
    audio_format: "pcm16",
  }),
});

console.log(await response.json());

---

二、WebSocket 流式识别接口

接口信息

• 接口路径: /v1/speech-to-text/stream
• 请求方式: GET
• 协议: WebSocket
• 认证方式: 非浏览器客户端可使用 Header 中的 X-API-Key；浏览器客户端可使用 Query 参数 api_key
• 响应方式: 通过 WebSocket 事件持续接收识别结果

鉴权方式

场景	方式	示例
非浏览器客户端	Header X-API-Key	X-API-Key: your-secret-key-here
浏览器客户端	Query api_key	wss://api.vuilabs.cn/v1/speech-to-text/stream?api_key=your-secret-key-here

浏览器 WebSocket API 无法自定义请求头，因此浏览器场景请使用 api_key 查询参数。

客户端发送消息

连接建立后，客户端需要先发送 JSON meta 消息，再持续发送二进制 PCM 音频块，最后发送结束消息。

1. 发送 meta 消息

{
  "meta": {
    "audio_format": "pcm16"
  }
}

字段	类型	必填	说明
meta.audio_format	string	否	音频格式，仅支持 pcm16 / pcm_16000，默认 pcm16
meta.language	string	否	识别语言，不传时自动识别

2. 发送音频块

发送 binary PCM chunks。音频数据格式与 HTTP 识别接口一致，必须为 raw PCM 二进制数据，不需要 Base64 编码。

3. 发送结束消息

{
  "is_final": true
}

响应事件

收到的消息为 JSON 文本，type 用于区分事件类型。

type	说明
asr_partial	中间识别结果，连接过程中可能返回多次
asr_final	最终识别结果
done	识别结束
error	识别失败

事件字段

字段	类型	说明
type	string	事件类型：asr_partial、asr_final、done、error
text	string	识别文本，部分事件可能为空
asr_text	string	识别文本的兼容字段，部分事件可能返回该字段
language	string	识别或请求指定的语言代码
confidence	number	置信度评分，范围通常为 0 ~ 1
audio_duration_ms	number	已识别音频时长，单位毫秒
code	number	错误码，仅 error 事件返回
message	string	错误信息，仅 error 事件返回

事件示例

{
  "type": "asr_partial",
  "text": "hello",
  "asr_text": "hello",
  "confidence": 0.82,
  "audio_duration_ms": 1200
}

{
  "type": "asr_final",
  "text": "hello, welcome to the speech recognition service",
  "asr_text": "hello, welcome to the speech recognition service",
  "confidence": 0.96,
  "audio_duration_ms": 2480
}

{
  "type": "done"
}

{
  "type": "error",
  "code": 400,
  "message": "invalid audio_format"
}

请求示例

Python

import asyncio
import json
import websockets

async def main():
    uri = "wss://api.vuilabs.cn/v1/speech-to-text/stream"
    headers = {"X-API-Key": "your-secret-key-here"}

    async with websockets.connect(uri, additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "meta": {
                "audio_format": "pcm16",
            }
        }))

        with open("sample.pcm", "rb") as f:
            while chunk := f.read(4096):
                await ws.send(chunk)

        await ws.send(json.dumps({"is_final": True}))

        async for message in ws:
            event = json.loads(message)
            print(event)
            if event.get("type") in ("done", "error"):
                break

asyncio.run(main())

Browser JavaScript

const ws = new WebSocket(
  "wss://api.vuilabs.cn/v1/speech-to-text/stream?api_key=your-secret-key-here"
);

ws.binaryType = "arraybuffer";

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    meta: {
      audio_format: "pcm16",
    },
  }));

  // 这里需要传入 raw PCM ArrayBuffer，可来自录音编码后的音频块。
  ws.send(pcmArrayBuffer);
  ws.send(JSON.stringify({ is_final: true }));
});

ws.addEventListener("message", (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
});

---

三、错误响应

HTTP 错误响应

请求失败时，响应体为统一 JSON 格式：

{
  "error_code": 20014,
  "error_message": "音频时长至少需要2秒，才能进行同步语音识别",
  "succeed": false,
  "data": null
}

常见错误

HTTP 状态码 / 事件 code	说明
10001	参数错误（如 audio_data 缺失、audio_format 不支持、meta 消息格式错误等）
20014	HTTP 同步识别音频短于 2 秒，无法继续进行同步语音识别
401	API Key 无效或未授权
429	请求频率超限
402	余额不足
500	服务异常

---

四、计费说明

具体计费规则、价格和免费额度请参见 产品计费。