1. 接口描述
接口请求域名： soe.tencentcloudapi.com 。
本接口可用于中英文发音评测数据传输。在使用本接口时需要注意：传输音频数据，必须在完成发音评估初始化接口之后调用，且SessonId要与初始化接口保持一致。分片传输时，尽量保证SeqId顺序传输（请确认SeqId由1开始）。音频源目前仅支持16k采样率16bit单声道编码方式，如有不一致可能导致评估不准确或失败。
默认接口请求频率限制：10000次/秒。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：TransmitOralProcess。 |
| Version | 是 | String | 公共参数，本接口取值：2018-07-24。 |
| Region | 否 | String | 公共参数，本接口不需要传递此参数。 |
| SeqId | 是 | Integer | 流式数据包的序号，从1开始，当IsEnd字段为1后后续序号无意义，当IsLongLifeSession不为1且为非流式模式时无意义。 注意：序号上限为3000，不能超过上限。 示例值：1 |
| IsEnd | 是 | Integer | 是否传输完毕标志，若为0表示未完毕，若为1则传输完毕开始评估，非流式模式下无意义。 示例值：0 |
| VoiceFileType | 是 | Integer | 1: raw/pcm 2: wav 3: mp3 4: speex 音频上传格式 示例值：1 |
| VoiceEncodeType | 是 | Integer | 语音编码类型 1:pcm 示例值：1 |
| UserVoiceData | 是 | String | 当前语音数据, 编码格式要求为BASE64且必须保证分片帧完整（16bit的数据必须保证音频长度为偶数）。格式要求参考音频上传格式 流式模式下需要将语音数据进行分片处理，参考：分片大小设置 如何进行流式分片参考：流式评测 示例值：VWtsR1JxeUpBd0JYUVZaRlptMTBJQkFBQUFBQkFBRUFnRDRBQUFCOUFBQUNBQkFBVEVsVFZCb0FBQUJKVGtaUFNWTkdWQTRBQUFCTVlYWm1OVFl1TVRrdU1UQXdBR1JoZEdGbWlRTUF5 |
| SessionId | 是 | String | 语音段唯一标识，一段完整语音使用一个SessionId，不同语音段的评测需要使用不同的SessionId。一般使用uuid(通用唯一识别码)来作为它的值，要尽量保证SessionId的唯一性。 示例值：stress_test_956938 |
| SoeAppId | 否 | String | 业务应用ID，与账号应用APPID无关，是用来方便客户管理服务的参数，新的 SoeAppId 可以在控制台【应用管理】下新建。如果没有新建SoeAppId，请勿填入该参数，否则会报欠费错误。使用指南：业务应用 |
| IsLongLifeSession | 否 | Integer | 长效session标识，当该参数为1时，session的持续时间为300s，但会一定程度上影响第一个数据包的返回速度。当InitOralProcess接口和TransmitOralProcess接口的IsLongLifeSession均为1时，才可生效。 |
| IsQuery | 否 | Integer | 查询标识，当该参数为1时，该请求为查询请求，请求返回该 Session 的评估结果。 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| PronAccuracy | Float | 发音精准度，取值范围[-1, 100]，当取-1时指完全不匹配，当为句子模式时，是所有已识别单词准确度的加权平均值，在reftext中但未识别出来的词不计入分数中。当为流式模式且请求中IsEnd未置1时，取值无意义。 示例值：65 |
| PronFluency | Float | 发音流利度，取值范围[0, 1]，当为词模式时，取值无意义；当为流式模式且请求中IsEnd未置1时，取值无意义。取值无意义时，值为-1 示例值：0.3 |
| PronCompletion | Float | 发音完整度，取值范围[0, 1]，当为词模式或自由说模式时，取值无意义；当为流式模式且请求中IsEnd未置1时，取值无意义。取值无意义时，值为-1 示例值：1 |
| Words | Array of WordRsp | 详细发音评估结果 |
| SessionId | String | 语音段唯一标识，一段语音一个SessionId |
| AudioUrl | String | 已废弃，不再保存语音音频文件下载地址 |
| SentenceInfoSet | Array of SentenceInfo | 断句中间结果，中间结果是局部最优而非全局最优的结果，所以中间结果有可能和最终整体结果对应部分不一致；中间结果的输出便于客户端UI更新；待用户发音完全结束后，系统会给出一个综合所有句子的整体结果。 |
| Status | String | 评估 session 状态，“Evaluating"：评估中、"Failed"：评估失败、"Finished"：评估完成 |
| SuggestedScore | Float | 建议评分，取值范围[0,100]，评分方式为建议评分 = 准确度（PronAccuracy）× 完整度（PronCompletion）×（2 - 完整度（PronCompletion）），如若评分策略不符合请参考Words数组中的详细分数自定义评分逻辑。 示例值：65 |
| RefTextId | Integer | 匹配候选文本的序号，在句子多分支、情景对 话、段落模式下表示匹配到的文本序号 注意：此字段可能返回 null，表示取不到有效值。 示例值：1 |
| KeyWordHits | Array of Float | 主题词命中标志，0表示没命中，1表示命中 注意：此字段可能返回 null，表示取不到有效值。 示例值：[] |
| UnKeyWordHits | Array of Float | 负向主题词命中标志，0表示没命中，1表示命中 注意：此字段可能返回 null，表示取不到有效值。 示例值：[] |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 传输语音进行发音评估
传输语音进行发音评估
输入示例
POST / HTTP/1.1
Host: soe.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: TransmitOralProcess
<公共请求参数>
{
"VoiceEncodeType": "1",
"UserVoiceData": "VWtsR1JxeUpBd0JYUVZaRlptMTBJQkFBQUFBQkFBRUFnRDRBQUFCOUFBQUNBQkFBVEVsVFZCb0FBQUJKVGtaUFNWTkdWQTRBQUFCTVlYWm1OVFl1TVRrdU1UQXdBR1JoZEdGbWlRTUF5",
"IsEnd": "0",
"VoiceFileType": "1",
"SessionId": "stress_test_956938",
"SeqId": "1"
}输出示例
{
"Response": {
"SuggestedScore": 99.52305,
"PronAccuracy": 99.52305,
"PronFluency": 0.93664527,
"PronCompletion": 1,
"RequestId": "1067cb5d-****-****-b1c6-6b*****72a0e",
"RefTextId": 0,
"KeyWordHits": [
0.0
],
"UnKeyWordHits": [
0.0
],
"Words": [
{
"KeywordTag": 0,
"MemBeginTime": 2330,
"MemEndTime": 3170,
"PronAccuracy": 99.52305,
"PronFluency": 0.93664527,
"ReferenceWord": "",
"Word": "thankyou",
"MatchTag": 0,
"PhoneInfos": [
{
"MemBeginTime": 2330,
"MemEndTime": 2530,
"PronAccuracy": 98.37366,
"DetectedStress": false,
"Phone": "th",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2530,
"MemEndTime": 2630,
"PronAccuracy": 99.75654,
"DetectedStress": false,
"Phone": "ae",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2630,
"MemEndTime": 2730,
"PronAccuracy": 99.75149,
"DetectedStress": false,
"Phone": "ng",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2730,
"MemEndTime": 2830,
"PronAccuracy": 99.767265,
"DetectedStress": false,
"Phone": "k",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2830,
"MemEndTime": 2910,
"PronAccuracy": 99.72817,
"DetectedStress": false,
"Phone": "y",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2910,
"MemEndTime": 3170,
"PronAccuracy": 99.7612,
"DetectedStress": false,
"Phone": "uw",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
}
]
}
],
"SessionId": "E6B94BA9-6***-B***-8***-9C4B****5176",
"AudioUrl": "",
"SentenceInfoSet": [
{
"SuggestedScore": 0,
"PronAccuracy": 99.52305,
"PronFluency": 0.93664527,
"PronCompletion": 1,
"KeyWordHits": [
0.0
],
"Words": [
{
"KeywordTag": 0,
"MemBeginTime": 2330,
"MemEndTime": 3170,
"PronAccuracy": 99.52305,
"PronFluency": 0.93664527,
"ReferenceWord": "",
"Word": "thankyou",
"MatchTag": 0,
"PhoneInfos": [
{
"MemBeginTime": 2330,
"MemEndTime": 2530,
"PronAccuracy": 98.37366,
"DetectedStress": false,
"Phone": "th",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2530,
"MemEndTime": 2630,
"PronAccuracy": 99.75654,
"DetectedStress": false,
"Phone": "ae",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2630,
"MemEndTime": 2730,
"PronAccuracy": 99.75149,
"DetectedStress": false,
"Phone": "ng",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2730,
"MemEndTime": 2830,
"PronAccuracy": 99.767265,
"DetectedStress": false,
"Phone": "k",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2830,
"MemEndTime": 2910,
"PronAccuracy": 99.72817,
"DetectedStress": false,
"Phone": "y",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
},
{
"MemBeginTime": 2910,
"MemEndTime": 3170,
"PronAccuracy": 99.7612,
"DetectedStress": false,
"Phone": "uw",
"ReferencePhone": "",
"ReferenceLetter": "",
"Stress": false,
"MatchTag": 0
}
]
}
],
"SentenceId": -1,
"RefTextId": 0,
"UnKeyWordHits": [
0.0
]
}
],
"Status": "Evaluating"
}
}5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| AuthFailure | CAM签名/鉴权错误。 |
| AuthFailure.AccountUnavailable | 账号未开通口语评测服务或账号已欠费隔离，请开通服务或检查账号状态。 |
| AuthFailure.InvalidAuthorization | 鉴权失败。 |
| FailedOperation | 操作失败。 |
| FailedOperation.ErrorGetSession | 会话缓存保存失败，请重新初始化。 |
| FailedOperation.EvaluateTimeout | 评测时间超出限制，请检查音频时间是否过长后重试。 |
| FailedOperation.EvaluateUnknownError | 引擎未知错误，请检查一下RefText是否正常后重试。 |
| FailedOperation.FailedGetEngineIP | 获取评测引擎IP失败，请稍后重试。 |
| FailedOperation.FailedGetResult | 结果缓存获取失败，请稍后重试。 |
| FailedOperation.FailedGetSession | 会话缓存获取失败，请稍后重试。 |
| FailedOperation.FailedGetSessionSeqID | 会话分片序号缓存获取失败，请稍后重试。 |
| FailedOperation.FailedGetUser | 用户信息缓存获取失败，请稍后重试。 |
| FailedOperation.FailedInit | 请求初始化失败，请检查参数后重新初始化。 |
| FailedOperation.FailedSetResult | 结果缓存保存失败，请稍后重试。 |
| FailedOperation.FailedSetSession | 会话缓存保存失败，请重新初始化。 |
| FailedOperation.FailedSetSessionSeqID | 会话分片序号缓存保存失败，请重新初始化。 |
| FailedOperation.FailedSetUser | 用户信息缓存保存失败，请稍后重试。 |
| FailedOperation.InternalServerError | 服务内部错误，请稍后重试或联系我们。 |
| FailedOperation.InvalidParameterValue | 引擎参数错误，请稍后重试。 |
| FailedOperation.JsonCodecError | Json编解码失败，请稍后重试。 |
| FailedOperation.NeedInitBeforeEvaluation | 引擎评估之前没有初始化，请重新初始化成功之后重新传输数据。 |
| FailedOperation.PastSeqIdLose | 前序分片缺失，请重新补发前序分片。 |
| FailedOperation.ResultExpired | 结果缓存已过期，请重新初始化成功之后重新传输数据。 |
| FailedOperation.SeqIdExpired | 分片序号缓存已过期，请重新初始化成功之后重新传输数据。 |
| FailedOperation.ServerOverload | 引擎服务器过载，请稍后重试。 |
| FailedOperation.ServiceTimeout | 评测超时，请通过轮询查询评测结果，后续请使用分片传输或减少单次传输音频时长。 |
| FailedOperation.SessionExpired | 会话缓存已过期，请重新初始化成功之后重新传输数据。 |
| FailedOperation.WaitPastSeqIdTimeout | 引擎等待前序分片超时，请重新补发前序分片。 |
| InternalError | 内部错误。 |
| InternalError.AudioProcessingFailed | 音频处理出错。 |
| InternalError.AuthorizeError | 服务未开通或已欠费。 |
| InternalError.BASE64DecodeFailed | BASE64解码错误。 |
| InternalError.CannotFindSession | 评估之前没有初始化或已过期。 |
| InternalError.FailToDecodeVoice | 语音解码失败。 |
| InternalError.IlegalServerResponse | 服务器应答非法 。 |
| InternalError.InitialParameterError | 初始化参数错误 。 |
| InternalError.InvalidSeqId | 分片序号错误。 |
| InternalError.InvalidWAVHeader | WAV头部格式非法或不在同一分片内。 |
| InternalError.LastSeqUnfinished | 前一个分片未处理完，请稍后重试。 |
| InternalError.MP3DecodeFailed | MP3转码发生错误。 |
| InternalError.NeedToInit | 进行评估之前没有进行初始化。 |
| InternalError.NoConversationFound | 使用的会话没有找到或已经被释放。 |
| InternalError.NoInitBeforeEvaluation | 评估之前没有初始化。 |
| InternalError.RefTxtEmpty | 检测到不支持的字符在输入文本。 |
| InternalError.RefTxtOov | 检测到不支持的字符在输入文本。 |
| InternalError.RefTxtTooLang | 输入文本太长。 |
| InternalError.ServerInternalError | 服务器内部错误。 |
| InternalError.ServerOverload | 服务器过载。 |
| InternalError.ServiceTimeout | 服务超时。 |
| InternalError.ShardNoStartWithOne | 分片序号错误应该从1开始。 |
| InternalError.StreamingvoicepkgTimeout | 流式语音包超时。 |
| InternalError.VoiceMsgOversized | 语音数据大于1MB。 |
| InternalError.WordLengthTooLong | 文本单词超过限制 。 |
| InvalidParameter | 参数错误。 |
| InvalidParameter.AuthorizeError | 服务未开通或已欠费。 |
| InvalidParameter.ErrorPhoneme | 请求参数RefText的音素Json解码失败，请参考API文档使用标准的Json格式。 |
| InvalidParameter.InitialParameterError | 初始化参数错误。 |
| InvalidParameter.InvalidAction | 请求参数Action不合法，请参考API文档检查参数Action的有效性。 |
| InvalidParameter.InvalidParameter | 请求参数不合法，请参考API文档检查参数的有效性。 |
| InvalidParameter.SeqIdLimitExceeded | 请求参数SeqId超过最大值限制，请参考API文档检查参数SeqId是否小于3000。 |
| InvalidParameter.VoiceMsgOversized | 语音数据大于1MB。 |
| InvalidParameterValue | 参数取值错误。 |
| InvalidParameterValue.AudioDataSizeLimitExceeded | 输入分片音频大小超过最大限制，请调整分片大小后重新传输数据。 |
| InvalidParameterValue.AudioDecodeFailed | 音频数据解码失败，请参考API文档中音频要求检查音频数据格式设置是否正确后重新传输数据。 |
| InvalidParameterValue.AudioLimitExceeded | 输入音频时长超过限制，请结束本次评测，后续请根据评测模式设置音频时长限制。 |
| InvalidParameterValue.AudioSizeMustBeEven | 输入音频异常，音频数据指针或音频⻓度必须为偶数，请参考API文档检查音频数据是否正确后重新传输数据。 |
| InvalidParameterValue.BASEDecodeFailed | BASE64解码错误。 |
| InvalidParameterValue.InvalidSeqId | 分片序号错误。 |
| InvalidParameterValue.InvalidWAVHeader | WAV头部格式非法或不在同一分片内。 |
| InvalidParameterValue.NoDocInList | 表单中没有文件。 |
| InvalidParameterValue.ParameterInvalid | 参数值无效，请检查ScoreCoeff参数输入是否在限制内。 |
| InvalidParameterValue.RefTextEmpty | 请求参数RefText无效或参考文本为空，请检查RefText是否为空。 |
| InvalidParameterValue.RefTextGrammarError | 请求参数RefText语法错误，请参考API文档检查文本格式，尤其是指定发音格式是否正确。 |
| InvalidParameterValue.RefTextLimitExceeded | 请求参数RefText的字数超过最大限制，请根据评测模式调整字数后重新初始化。 |
| InvalidParameterValue.RefTextOOV | 请求参数RefText包含OOV词汇，请使用指定发音或联系我们处理。 |
| InvalidParameterValue.RefTextPolyphonicLimitExceeded | 请检查参考文本中是否包含大量多音字，可通过发音描述块指定标准发音解决。 |
| InvalidParameterValue.RefTxtEmpty | 输入文本为空。 |
| InvalidParameterValue.RefTxtTooLang | 输入文本太长。 |
| InvalidParameterValue.SensitiveWords | 请求内容包含违禁词汇，请检查后重试。 |
| InvalidParameterValue.SessionIdInUse | SessionId已存在，建议使用uuid作为SessionId重新初始化。 |
| InvalidParameterValue.ShardNoStartWithOne | 分片序号错误应该从1开始。 |
| InvalidParameterValue.StreamingvoicepkgTimeout | 流式语音包超时。 |
| InvalidParameterValue.VadNotDetectedSpeak | 没有检测到语音。 |
| InvalidParameterValue.VoiceFileTypeNotFound | 语音文件格式参数VoiceFileType取值错误，请参考API文档检查语音文件格式VoiceFileType是否正确后重新传输数据。 |
| InvalidParameterValue.WAVHeaderDecodeFailed | WAV格式的音频数据第一个分片的数据长度小于44，头部数据不合法，请检查后重试。 |
| InvalidParameterValue.WordLengthTooLong | 文本单词超过限制。 |
| LimitExceeded | 超过配额限制。 |
| LimitExceeded.ConcurrencyLimitExceeded | 请求并发数超过配额限制，请减少并发数或联系我们调大并发限额。 |
| MissingParameter | 缺少参数错误。 |
| RequestLimitExceeded | 请求的次数超过了频率限制。 |
| ResourceInsufficient.ServerTimeout | 评测超时，请检查语音数据大小。 |
| ResourceUnavailable | 资源不可用。 |
| ResourceUnavailable.AuthorizeError | 服务未开通或已欠费。 |
| ResourceUnavailable.CannotFindSession | 评估之前没有初始化或已过期。 |
| ResourceUnavailable.ConcurrencyLimit | 使用并发超出限制。 |
| ResourceUnavailable.InitStreamNotSupport | 该接口不支持init_stream。 |
| ResourceUnavailable.InitStreamUnfinished | 初始化请求未完成，请稍后重试。 |
| ResourceUnavailable.LastSeqUnfinished | 前一个分片未处理完，请稍后重试。 |
| ResourceUnavailable.NoConversationFound | 使用的会话没有找到或已经被释放。 |
| ResourceUnavailable.NoInitBeforeEvaluation | 评估之前没有初始化。 |
