ASR 语音转文字接口文档

概述

项	说明
Base URL	`http://asr.aodianyun.com`(内网`http://asr.asr.svc.cluster.local`)
业务统一入口	`POST /asr/api`，通过 `cmd` 区分能力
鉴权	`access_id` + `signature`（与 MSS 签名算法一致）
请求体	`application/x-www-form-urlencoded`，字段 `parameter=<JSON>`

统一响应结构：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

code	含义
`0`	成功
`400`	参数/鉴权/业务校验失败
`500`	服务内部错误

签名算法

准备业务参数（不含 signature）
按 key 字典序排序
用与 PHP json_encode(..., JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_SLASHES) 一致的方式序列化为 JSON
- 数字保持数字类型（如 user: 41250，不要写成 "41250"）
- 斜杠、中文不转义
拼接：json字符串 + access_key
对结果做 MD5，输出 小写 hex，写入 signature

伪代码（PHP）：

ksort($param);
unset($param['signature']); // 若已存在则排除
$signature = md5(json_encode($param, JSON_UNESCAPED_UNICODE|JSON_UNESCAPED_SLASHES) . $accessKey);

鉴权相关配置：

配置项	说明
`ASR_SERVICE_ACCESS_ID`	服务端校验用的 access_id
`ASR_SERVICE_ACCESS_KEY`	服务端校验用的 access_key

调用方传入的 access_id 必须与服务端配置一致；cmd 必须参与签名。

1. 统一业务接口

`POST /asr/api`

Content-Type： application/x-www-form-urlencoded

Body：

parameter={"cmd":"...","access_id":"...","user":41250,...,"signature":"..."}

也支持直接 POST 原始 JSON，或 parameter= 前缀的 raw body。

公共字段

字段	类型	必填	说明
`cmd`	string	是	`transcribe` / `recognize` / `getTask`（大小写不敏感）
`access_id`	string	是	服务 access_id
`user`	int	是	用户 UIN
`signature`	string	是	签名

1.1 创建异步转写任务 — `cmd=transcribe`

创建业务任务并异步处理。若同一 user + file_url 已有最新 completed 记录，直接返回该任务（若传了 callback_url 会异步回调完成结果）。

请求参数

字段	类型	必填	说明
`cmd`	string	是	固定 `transcribe`
`user`	int	是	用户 UIN
`file_url`	string	是	音视频地址（也可用 `fileUrl`）
`callback_url`	string	否	完成后回调地址（也可用 `callbackUrl`）
`access_id`	string	是	鉴权 ID
`signature`	string	是	签名

请求示例

{
  "cmd": "transcribe",
  "access_id": "ltjg6cblz3y3unjq",
  "user": 41250,
  "file_url": "http://example.com/demo.mp4",
  "callback_url": "https://example.com/asr/callback",
  "signature": "<md5>"
}

curl

curl -X POST "http://localhost:8080/asr/api" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode 'parameter={"cmd":"transcribe","access_id":"...","user":41250,"file_url":"http://example.com/demo.mp4","signature":"..."}'

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "task_id": "3964b16b472748dab5f50d1c75b2f7d0",
    "task_status": "pending",
    "source_url": "http://example.com/demo.mp4",
    "uin": 41250
  }
}

data 字段	说明
`task_id`	业务任务 ID
`task_status`	任务状态
`source_url`	源文件地址
`provider`	服务商，如 `tingwu` / `mss`
`uin`	用户 UIN

1.2 同步识别 — `cmd=recognize`

同步等待识别结果返回。不入库、不走异步任务链路。

请求参数

字段	类型	必填	说明
`cmd`	string	是	固定 `recognize`
`user`	int	是	用户 UIN
`file_url`	string	是	音视频地址
`access_id`	string	是	鉴权 ID
`signature`	string	是	签名

请求示例

{
  "cmd": "recognize",
  "access_id": "ltjg6cblz3y3unjq",
  "user": 41250,
  "file_url": "http://example.com/demo.mp4",
  "signature": "<md5>"
}

成功响应

{
  "code": 0,
  "message": "ok",
  "data": {
    "result_text": "识别出的文字内容",
    "uin": 41250
  }
}

1.3 查询任务 — `cmd=getTask`

按 task_id 查询异步任务；user 必须与任务归属用户一致。

请求参数

字段	类型	必填	说明
`cmd`	string	是	固定 `getTask`
`user`	int	是	用户 UIN
`task_id`	string	是	业务任务 ID
`access_id`	string	是	鉴权 ID
`signature`	string	是	签名

请求示例

{
  "cmd": "getTask",
  "access_id": "ltjg6cblz3y3unjq",
  "user": 41250,
  "task_id": "3964b16b472748dab5f50d1c75b2f7d0",
  "signature": "<md5>"
}

成功响应（进行中）

{
  "code": 0,
  "message": "ok",
  "data": {
    "task_id": "3964b16b472748dab5f50d1c75b2f7d0",
    "uin": 41250,
    "source_url": "http://example.com/demo.mp4",
    "task_status": "processing",
    "create_time": "2026-08-19T10:00:00Z",
    "update_time": "2026-08-19T10:05:00Z"
  }
}

成功响应（已完成）

{
  "code": 0,
  "message": "ok",
  "data": {
    "task_id": "3964b16b472748dab5f50d1c75b2f7d0",
    "uin": 41250,
    "source_url": "http://example.com/demo.mp4",
    "task_status": "completed",
    "srt_url": "http://ad-asr-oss.aodianyun.com/asr/xxx.srt",
    "result_text": "",
    "create_time": "2026-08-19T10:00:00Z",
    "update_time": "2026-08-19T10:10:00Z"
  }
}

成功响应（失败）

{
  "code": 0,
  "message": "ok",
  "data": {
    "task_id": "3964b16b472748dab5f50d1c75b2f7d0",
    "uin": 41250,
    "source_url": "http://example.com/demo.mp4",
    "task_status": "failed",
    "error": "失败原因",
    "create_time": "2026-08-19T10:00:00Z",
    "update_time": "2026-08-19T10:03:00Z"
  }
}

data 字段	说明
`task_id`	业务任务 ID
`uin`	用户 UIN
`source_url`	源文件地址
`task_status`	任务状态
`srt_url`	完成时返回字幕文件 URL
`result_text`	完成时固定返回空字符串
`error`	失败时返回错误信息
`tingwu_status` / `tingwu_result`	听悟侧状态/结果（如有）
`srt_error`	字幕相关错误（如有）
`create_time` / `update_time`	创建/更新时间

不返回： srt_content、callback_url、tingwu_task_id

任务状态

status	说明
`pending`	已创建，等待处理
`converting`	ffmpeg 转码中
`uploading`	上传 OSS 中
`submitted`	已提交上游识别
`processing`	上游处理中
`completed`	完成
`failed`	失败

常见错误

message	场景
`parameter参数不能为空`	未传 parameter
`parameter JSON无效`	JSON 解析失败
`access_id参数不能为空`	缺 access_id
`accessId错误`	access_id 与服务端不一致
`signature参数不能为空`	缺 signature
`签名错误`	签名计算不一致（常见：缺 `cmd`、`user` 类型不对）
`cmd参数无效`	cmd 不是 `transcribe` / `recognize` / `getTask`
`用户信息错误`	`user`/`uin` 缺失或 ≤ 0
`file_url参数不能为空`	创建/同步识别未传文件地址
`task_id参数不能为空`	查询未传任务 ID
`任务与用户信息不匹配`	查询时 user 与任务归属不一致

最后编辑: 广电云技术部文档更新时间: 2026-08-20 11:28 作者：广电云技术部

ASR服务

ASR 语音转文字接口文档

概述

签名算法

1. 统一业务接口

POST /asr/api

公共字段

1.1 创建异步转写任务 — cmd=transcribe

请求参数

请求示例

curl

成功响应

1.2 同步识别 — cmd=recognize

请求参数

请求示例

成功响应

1.3 查询任务 — cmd=getTask

请求参数

请求示例

成功响应（进行中）

成功响应（已完成）

成功响应（失败）

任务状态

常见错误

`POST /asr/api`

1.1 创建异步转写任务 — `cmd=transcribe`

1.2 同步识别 — `cmd=recognize`

1.3 查询任务 — `cmd=getTask`