浏览文档目录

语音打字 API

语音打字:将短录音转换为可填入输入框、消息或文档的文字。

适用于编辑器、聊天输入框、表单和语音键盘。通过 HTTP 或 WebSocket 提交一段短语音,取得 text 后由调用方写入当前输入位置。接口负责生成文字,文字插入由客户端实现。只做语音转文字,原样返回识别结果,不做润色、词条替换或翻译。WebSocket 在 end 后返回最终文字,不提供逐字字幕。

在 API 控制台 创建 API Key,通过 Authorization: Bearer <API_KEY> 请求头认证。运行示例前,在服务端环境中设置 LECSYNC_API_KEY。API Key 应保存在服务端。

发起请求

POST /v1/voicetyping

支持 AAC(ADTS)、MP3、Ogg Opus、WAV,不支持 MP4 和视频文件。

bash
curl "https://api.lecsync.com/v1/voicetyping" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: voicetyping-example-001" \  -F "file=@recording.wav" \  -F "language=en" \  -F 'terms=["LecSync"]'

请求参数

使用 multipart/form-data,由 HTTP 客户端生成 boundary。表单中的 hotwords、terms 以 JSON 字符串传入,布尔字段使用 true 或 false。

字段类型必填说明
filefile是音频文件。
languagestring否音频语言代码,例如 zh、en;默认 auto,自动识别。
termsarray否最多 50 个热词(字符串,每个最多 120 字符),用于提高人名、术语的识别准确率。

响应

以下示例展示主要响应字段,实际响应还可能包含用量元数据。

json
{  "request_id": "req_example",  "status": "succeeded",  "text": "hello world",  "language": "en"}
字段说明
request_id请求标识,用于查询状态和排查问题,请保存。
text识别出的文字。
language识别到的语言;无法确定时为 null。

WebSocket 接入

在服务端创建连接,请求使用与 HTTP 相同的 JSON 参数,不含 file。响应返回 websocket_url、protocol、ticket、expires_at 和 limits。请在票据有效期内(60 秒)建立连接,每张票据只能使用一次。

bash
curl "https://api.lecsync.com/v1/voicetyping/connect" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: voicetyping-ws-example-001" \  -H "Content-Type: application/json" \  -d '{  "language": "en",  "terms": [    "LecSync"  ]}'

使用 [protocol, ticket] 作为 WebSocket 子协议。收到 ready 后,发送 16 kHz、单声道、小端 PCM16 二进制音频,不包含 WAV 文件头。每帧非空、字节数为偶数且不超过 65,536 字节。最后一帧后发送 {"type":"end"},等待 result 或 error。结果在说话结束后一次返回,不提供中间字幕。空闲超时为 60 秒。

javascript
const ws = new WebSocket(connection.websocket_url, [  connection.protocol,  connection.ticket,]);ws.onmessage = ({ data }) => {  const message = JSON.parse(data);  if (message.type === "ready") {    // pcmFrames: 16 kHz mono PCM16 ArrayBuffer[]    for (const frame of pcmFrames) ws.send(frame);    ws.send(JSON.stringify({ type: "end" }));  } else if (message.type === "result") {    console.log(message.text);  } else if (message.type === "error") {    console.error(message.error);  }};

结果查询与重试

每次新调用传入 Idempotency-Key,值为 1–128 个可见 ASCII 字符。保存该键;响应丢失时,使用相同键和相同参数重试。同键不同参数返回 409 IDEMPOTENCY_CONFLICT。请求仍在处理时,重复调用只返回已有状态。使用新键会创建新请求。

收到响应后请立即保存 text。语音打字正文不支持再次获取:GET /v1/voicetyping/requests/{request_id} 和重复请求只返回状态与用量,result_replay_supported=false。

bash
curl "https://api.lecsync.com/v1/voicetyping/requests/REQUEST_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

限制与用量

  • 文件大小上限: 20 MiB
  • 音频时长上限: 120 s

按最终文本字符数计量,不计空白字符。

usage.charge_cents 为本次费用,以美分十进制字符串表示。

错误处理

HTTP 错误响应包含 error、request_id,响应头中也有 X-Request-Id。排查问题时请提供该标识。

json
{  "error": "INVALID_INPUT",  "request_id": "req_example"}
HTTPerror处理方式
401UNAUTHORIZED检查 API Key 是否有效。
402INSUFFICIENT_BALANCE检查 API 余额后重试。
503ADMISSION_DISABLED当前账号暂不可使用该服务。
409IDEMPOTENCY_CONFLICT查询已有请求;不同输入请使用新键。
410RESULT_EXPIRED结果已过期,需要时重新提交。
413BODY_TOO_LARGE / AUDIO_TOO_LONG缩小文件或缩短音频。
415UNSUPPORTED_AUDIO_FORMAT转换为支持的音频格式。
422INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLE检查字段名称、类型及必填参数。
422UNSUPPORTED_LANGUAGE检查字段名称、类型及必填参数。
429RESOURCE_LIMIT按 Retry-After 等待后重试。
503MODEL_UNAVAILABLE / SERVICE_UNAVAILABLE查询已有请求状态,再决定是否重试。
504DEADLINE_EXCEEDED先查询请求状态,再决定是否新建请求。