跳到主要内容

speech-assess API

speech-assess 是有道智云语音评测 HTTP API 的完整体中转。它保留有道原接口的核心字段风格，服务端负责读取 .env 中的 YOUDAO_APP_KEY、YOUDAO_APP_SECRET，自动生成 appKey、salt、curtime、signType=v2 和 sign，再转发到有道接口。

现有 /api/speech-score 保留为简化版接口；需要完全对接有道文档字段时使用 /api/speech-assess。

上游接口​

POST https://openapi.youdao.com/iseapi
Content-Type: application/x-www-form-urlencoded

本站接口​

GET  /api/speech-assess
GET  /api/speech-assess/health
POST /api/speech-assess

公网地址：

https://6767.chat/api/speech-assess

语音评测概念​

语音评测会自动对用户发音水平进行评价，输出完整度、流利度、准确度、综合分、单词级评分和音素级评分。它不是自由 ASR，而是跟读评测：text 必须和音频内容对应。

音频要求​

项要求
格式wav，不压缩，PCM 编码
采样率推荐 16000
位深16bit
声道单声道
编码后大小不超过 20M
单次最大时长120s
支持语言英文 en，中文 zh-CHS

转换示例：

ffmpeg -i input.mp3 -ar 16000 -ac 1 -sample_fmt s16 output.wav

请求参数​

/api/speech-assess 支持两种上传方式：

  • multipart/form-data：传 audio 文件，服务端自动转 Base64 作为 q。
  • application/x-www-form-urlencoded 或 JSON：直接传 q Base64 字符串。
字段名类型必填说明
audiofile否multipart 文件字段。传了 audio 时服务端自动生成 q。
qtext否音频文件 Base64 编码字符串。未传 audio 时必填。
texttext是音频对应的参考文本，例如 have a good day。
langTypetext是源语言，英文 en，中文 zh-CHS。也兼容简写字段 lang。
formattext否默认 wav。
ratetext否默认 16000。
channeltext否默认 1，仅支持单声道。
typetext否默认 1，仅支持 Base64 上传。
phoneSeqtext否音素序列 ip88，例如 boy 的 phoneSeq 为 bɔɪ。
salttext否UUID。不传时服务端生成。
curtimetext否秒级时间戳。不传时服务端生成。

客户端不需要传 appKey、sign、signType，也不应该传 appSecret。

curl 示例：文件上传​

curl -X POST "https://6767.chat/api/speech-assess" \
  -F "audio=@output.wav" \
  -F "text=have a good day" \
  -F "langType=en" \
  -F "format=wav" \
  -F "rate=16000" \
  -F "channel=1" \
  -F "type=1"

curl 示例：Base64 q​

audio_base64="$(base64 -w 0 output.wav)"

curl -X POST "https://6767.chat/api/speech-assess" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "q=${audio_base64}" \
  --data-urlencode "text=have a good day" \
  --data-urlencode "langType=en" \
  --data-urlencode "format=wav" \
  --data-urlencode "rate=16000" \
  --data-urlencode "channel=1" \
  --data-urlencode "type=1"

签名规则​

上游有道签名规则：

signType = v2
sign = sha256(appKey + input + salt + curtime + appSecret)

其中 input 由 Base64 后的音频字符串 q 计算：

q.length <= 20 ? q : q[:10] + q.length + q[-10:]

本站中转会自动完成签名。

返回结构​

本站返回结构：

{
  "success": true,
  "service": "speech-assess",
  "provider": "youdao",
  "upstream": "https://openapi.youdao.com/iseapi",
  "youdaoErrorCode": "0",
  "errorMessageZh": "成功",
  "raw": {
    "errorCode": "0",
    "refText": "have a good day",
    "overall": 100,
    "integrity": 100,
    "fluency": 100,
    "pronunciation": 100,
    "speed": 242.42421,
    "words": []
  }
}

raw 完整保留有道原始响应。

上游输出字段​

句子级字段​

字段类型含义二次开发建议
errorCodestring识别结果错误码，一定存在。先判断是否为 0，非 0 时展示 errorMessageZh。
requestIdstring请求 ID。记录到日志，方便排查供应商侧问题。
servicestring服务标识，例如 capt。一般仅用于调试。
versionstring服务版本号。可记录，用于观察供应商模型版本变化。
refTextstring请求的参考文本。展示用户本次跟读目标。
startnumber句子开始时间，单位秒。可用于音频波形高亮。
endnumber句子结束时间，单位秒。可用于截取有效发音段。
overallnumber句子综合评分。最适合做主分数。
integritynumber句子完整度得分。判断是否漏读、少读。
fluencynumber句子流利度得分。判断停顿、连贯性。
pronunciationnumber句子准确度得分。判断发音标准程度。
speednumber语速，单位为单词/分钟。可提示“过快/过慢”。
emotionnumber预留字段，目前未使用。不建议作为业务指标。
intonationstring预留字段，目前未使用。不建议作为业务指标。
wordsarray单词级评分数组。做逐词高亮、单词纠错、详情页的关键字段。

单词级字段：words[]​

words 是二次开发最重要的数组。前端可以把参考文本拆成单词后与 words[].word 对齐，按 words[].pronunciation 着色，再点击展开音素详情。

字段类型含义二次开发建议
wordstring单词文本，例如 have。用于逐词展示和定位。
IPAstring单词音标，例如 hæv。可展示标准音标。
startnumber单词开始时间，单位秒。可联动音频播放进度。
endnumber单词结束时间，单位秒。可做单词级音频片段回放。
pronunciationnumber单词准确度分数。低分单词应重点提示。
phonicsarray预留/扩展字段。当前可忽略。
phonemesarray音素级评分数组。做发音纠错、音素级提示的关键字段。

音素级字段：words[].phonemes[]​

phonemes 用于更细的发音纠错。常见做法是：当 judge=false 或 pronunciation 较低时，把该音素标红，并展示 calibration 告诉用户听起来像什么。

字段类型含义二次开发建议
phonemestring音素名称，例如 h、æ、eɪ。展示具体问题音素。
startnumber音素开始时间，单位秒。可跳转到音频中的具体位置。
endnumber音素结束时间，单位秒。可截取音素级片段。
pronunciationnumber音素准确度分数。比单词分更细，适合纠音。
judgeboolean是否发音正确，true 正确，false 错误。false 时优先提示用户。
calibrationstring如果发音错误，提示用户该发音像什么。作为纠音文案来源。
calibration-diphonestring预留字段，目前未使用。当前可忽略。
prominencenumber重音程度，分数越高越可能是重音，区间 [0, 100]。可辅助重音训练。
stress_refboolean标准答案是否认为该元音应发重音；辅音时无意义。与 stress_detect 对比判断重音是否正确。
stress_detectboolean用户该音素是否被检测为重音。可提示重音漏读或误读。

错误码中文说明​

本站会把常用错误码映射到 errorMessageZh。常见语音评测错误码如下：

错误码中文说明
0成功
101缺少必填的参数，请确保必填参数齐全，并确认参数书写正确。
102不支持的语言类型。
105不支持的签名类型。
108应用 ID 无效。
110无相关服务的有效实例，应用没有绑定服务实例。
113q 不能为空。
202签名检验失败，请检查应用 ID、应用密钥、编码和签名规则。
203访问 IP 地址不在可访问 IP 列表。
206时间戳无效导致签名校验失败。
401账户已经欠费。
411访问频率受限，请稍后访问。
9001不支持的语音格式。
9002不支持的语音采样率。
9003不支持的语音声道。
9004不支持的语音上传类型。
9005不支持的语音识别语言类型。
9301ASR 识别失败。
9303服务器内部错误。
9411访问频率受限，超过最大调用次数。
9412超过最大处理语音长度。
11001不支持的语音识别格式。
11002不支持的语音识别采样率。
11003不支持的语音识别声道。
11004不支持的语音上传类型。
11005不支持的语言类型。
11006识别音频文件过大。
11007识别音频时长过长，最大支持 120 秒。
11008识别文件为空。
11009不支持的识别文件类型。
11010识别音频时长过短。
11011识别的音频内容无效，不做评分。
11012识别的文本内容过短，不做评分。
11013非法的单词评测请求，不是单词。
11301口语评测请求失败。
11302口语评测请求超时。
11303口语评测限流，请稍后再试。
11304服务异常，请联系技术人员。
11411访问频率受限，请稍后访问。
11412超过最大请求时长。

未知错误码会返回：未知错误码，请参考有道智云错误代码列表。

更新日志​

2026-05-20 补充响应字段和示例​

  • 补充句子级、单词级 words[]、音素级 words[].phonemes[] 字段表。
  • 新增完整 JSON5 response 示例。
  • 示例文件保存为 docs/speech-assess-response-demo.json5。

2026-05-20 初始发布​

  • 新增 /api/speech-assess 完整体中转，按有道语音评测 HTTP API 字段风格转发。
  • 支持 audio 文件上传和 q Base64 两种方式。
  • 返回中补充 errorMessageZh 中文错误说明，并保留有道 raw 原始响应。

Response 示例​

示例文件也单独保存在 /docs/speech-assess-response-demo.json5，便于后续复制或二次处理。

{
    "intonation": "",  // 预留字段，目前未使用
    "refText": "have a good day",  //待评测语音对应的文本
    "pronunciation": 100,  //句子发音准确度
    "start": 0.180000, //音频开始时间，秒
    "words": [  //单词信息列表
        {
            "phonics": [],
            "pronunciation": 70.216576,  //单词准确度分数
            "start": 0.180000,  //单词开始时间，秒
            "end": 0.450000,  //单词结束时间，秒
            "IPA": "hæv",  //单词音标
            "word": "have",  //单词文本
            "phonemes": [  //音标信息列表
                {
                    "stress_ref": false,  //元音重音参考(即标准重音)，如果为true，说明参考答案认为该元音应该发重音，辅音时无意义
                    "pronunciation": 44.661324,  //音标准确度评分
                    "stress_detect": false,  //在一个单词中，用户该音标发音不为重音
                    "phoneme": "h",  //音标名称
                    "start": 0.180000,  //音标开始时间，秒
                    "end": 0.330000,  //音标结束时间，秒
                    "judge": true,  //判断音标是否错误，true为发音正确，false为发音错误，同时calibration给出提示
                    "calibration": "h",  //判断音标是否错误，true为发音正确，false为发音错误，同时calibration给出提示
                    "calibration-diphone": "",  // 预留字段，目前未使用
                    "prominence": 0  //重音程度，当前音标越可能是重音，分数区间[0 100]
                },
                {
                    "stress_ref": false,
                    "pronunciation": 67.160324,
                    "stress_detect": false,
                    "phoneme": "æ",
                    "start": 0.330000,
                    "end": 0.390000,
                    "judge": true,
                    "calibration": "æ",
                    "calibration-diphone": "",
                    "prominence": 0
                },
                {
                    "stress_ref": false,
                    "pronunciation": 98.828072,
                    "stress_detect": false,
                    "phoneme": "v",
                    "start": 0.390000,
                    "end": 0.450000,
                    "judge": true,
                    "calibration": "v",
                    "calibration-diphone": "",
                    "prominence": 0
                }
            ]
        },
        {
            "phonics": [],
            "pronunciation": 100,
            "start": 0.450000,
            "end": 0.510000,
            "IPA": "ə",
            "word": "a",
            "phonemes": [
                {
                    "stress_ref": false,
                    "pronunciation": 100,
                    "stress_detect": false,
                    "phoneme": "ə",
                    "start": 0.450000,
                    "end": 0.510000,
                    "judge": true,
                    "calibration": "ə",
                    "calibration-diphone": "",
                    "prominence": 0
                }
            ]
        },
        {
            "phonics": [],
            "pronunciation": 100,
            "start": 0.510000,
            "end": 0.720000,
            "IPA": "ɡʊd",
            "word": "good",
            "phonemes": [
                {
                    "stress_ref": false,
                    "pronunciation": 100,
                    "stress_detect": false,
                    "phoneme": "ɡ",
                    "start": 0.510000,
                    "end": 0.600000,
                    "judge": true,
                    "calibration": "ɡ",
                    "calibration-diphone": "",
                    "prominence": 0.284910
                },
                {
                    "stress_ref": false,
                    "pronunciation": 100,
                    "stress_detect": false,
                    "phoneme": "ʊ",
                    "start": 0.600000,
                    "end": 0.690000,
                    "judge": true,
                    "calibration": "ʊ",
                    "calibration-diphone": "",
                    "prominence": 0.999990
                },
                {
                    "stress_ref": false,
                    "pronunciation": 100,
                    "stress_detect": false,
                    "phoneme": "d",
                    "start": 0.690000,
                    "end": 0.720000,
                    "judge": true,
                    "calibration": "d",
                    "calibration-diphone": "",
                    "prominence": 1.000000
                }
            ]
        },
        {
            "phonics": [],
            "pronunciation": 100,
            "start": 0.720000,
            "end": 1.170000,
            "IPA": "deɪ",
            "word": "day",
            "phonemes": [
                {
                    "stress_ref": false,
                    "pronunciation": 100,
                    "stress_detect": false,
                    "phoneme": "d",
                    "start": 0.720000,
                    "end": 0.840000,
                    "judge": true,
                    "calibration": "d",
                    "calibration-diphone": "",
                    "prominence": 0.967651
                },
                {
                    "stress_ref": false,
                    "pronunciation": 95.965294,
                    "stress_detect": false,
                    "phoneme": "eɪ",
                    "start": 0.840000,
                    "end": 1.170000,
                    "judge": true,
                    "calibration": "eɪ",
                    "calibration-diphone": "",
                    "prominence": 1.000000
                }
            ]
        }
    ],
    "fluency": 100,  //句子流利度
    "errorCode": "0",  //识别结果错误码，一定存在
    "version": "capt-onetime-en:online-V2.0.8",  // 服务版本号
    "speed": 242.424210,  // 句子语速（单词/分钟）
    "integrity": 100,  //句子完整度
    "emotion": 0,  // 预留字段，目前未使用
    "service": "capt",  // 服务标识
    "requestId": "4e9e84ef-dc06-4899-9f24-8c5043dd672d",  // 请求ID
    "overall": 100,  //句子综合评分
    "end": 1.170000  //句子结束时间，秒
}