1. 接口描述
接口请求域名： soe.tencentcloudapi.com 。
初始化发音评估过程，每一轮评估前进行调用。语音输入模式分为流式模式和非流式模式，流式模式支持数据分片传输，可以加快评估响应速度。评估模式分为词模式和句子模式，词模式会标注每个音节的详细信息；句子模式会有完整度和流利度的评估。
默认接口请求频率限制：10000次/秒。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：InitOralProcess。 |
| Version | 是 | String | 公共参数，本接口取值：2018-07-24。 |
| Region | 否 | String | 公共参数，本接口不需要传递此参数。 |
| SessionId | 是 | String | 语音段唯一标识，一段完整语音使用一个SessionId，不同语音段的评测需要使用不同的SessionId。一般使用uuid(通用唯一识别码)来作为它的值，要尽量保证SessionId的唯一性。 示例值：stress_test_956938 |
| RefText | 是 | String | 被评估语音对应的文本，仅支持中文和英文。 句子模式下不超过个 30 单词或者中文文字，段落模式不超过 120 单词或者中文文字，中文评估使用 utf-8 编码，自由说模式RefText可以不填。 关于RefText的文本键入要求，请参考评测模式介绍。 如需要在评测模式下使用自定义注音（支持中英文），可以通过设置「TextMode」参数实现，设置方式请参考音素标注。 示例值：again |
| WorkMode | 是 | Integer | 语音输入模式 0：流式分片 1：非流式一次性评估 推荐使用流式分片传输。 示例值：0 |
| EvalMode | 是 | Integer | 评测模式 0：单词/单字模式（中文评测模式下为单字模式） 1：句子模式 2：段落模式 3：自由说模式 4：单词音素纠错模式 5：情景评测模式 6：句子多分支评测模式 7：单词实时评测模式 8：拼音评测模式 关于每种评测模式的详细介绍，以及适用场景，请参考评测模式介绍。 示例值：0 |
| ScoreCoeff | 是 | Float | 评价苛刻指数。取值为[1.0 - 4.0]范围内的浮点数，用于平滑不同年龄段的分数。 1.0：适用于最小年龄段用户，一般对应儿童应用场景； 4.0：适用于最高年龄段用户，一般对应成人严格打分场景。苛刻度影响范围参考：苛刻度影响范围 示例值：3.5 |
| SoeAppId | 否 | String | 业务应用ID，与账号应用APPID无关，是用来方便客户管理服务的参数，新的 SoeAppId 可以在控制台【应用管理】下新建。如果没有新建SoeAppId，请勿填入该参数，否则会报欠费错误。使用指南：业务应用 |
| IsLongLifeSession | 否 | Integer | 长效session标识，当该参数为1时，session的持续时间为300s，但会一定程度上影响第一个数据包的返回速度，且TransmitOralProcess必须同时为1才可生效。 |
| StorageMode | 否 | Integer | 音频存储模式，此参数已废弃，无需设置，设置与否都默认为0不存储； 注：有存储需求的用户建议自行存储至腾讯云COS对象存储使用。 |
| SentenceInfoEnabled | 否 | Integer | 输出断句中间结果标识 0：不输出 1：输出，通过设置该参数 可以在评估过程中的分片传输请求中，返回已经评估断句的中间结果，中间结果可用于客户端 UI 更新，输出结果为TransmitOralProcess请求返回结果 SentenceInfoSet 字段。 |
| ServerType | 否 | Integer | 评估语言 0：英文（默认） 1：中文 |
| IsAsync | 否 | Integer | 异步模式标识 0：同步模式 1：异步模式（一般情况不建议使用异步模式） 可选值参考服务模式。 |
| TextMode | 否 | Integer | 输入文本模式 0: 普通文本 1：音素结构文本 |
| Keyword | 否 | String | 主题词和关键词 示例值：keyword |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| SessionId | String | 语音段唯一标识，一个完整语音一个SessionId |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 SOE初始化请求示例
输入示例
POST / HTTP/1.1
Host: soe.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: InitOralProcess
<公共请求参数>
{
"ScoreCoeff": "1",
"TextMode": "0",
"ServerType": "0",
"SessionId": "30716e3c-8cf2-452e-ab0f-f4cec2c36d3d",
"RefText": "this",
"WorkMode": "0",
"EvalMode": "1"
}输出示例
{
"Response": {
"RequestId": "923afe12-5c5e-4e42-914e-ae66d207ce2c",
"SessionId": "30716e3c-8cf2-452e-ab0f-f4cec2c36d3d"
}
}示例2 初始化发音评估过程
初始化发音评估过程
输入示例
POST / HTTP/1.1
Host: soe.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: InitOralProcess
<公共请求参数>
{
"SessionId": "stress_test_956938",
"ScoreCoeff": "3.5",
"RefText": "again",
"WorkMode": "0",
"EvalMode": "0"
}输出示例
{
"Response": {
"RequestId": "xxxxxx",
"SessionId": "xxxxxx"
}
}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.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.BASE64DecodeFailed | BASE64解码错误。 |
| InternalError.IlegalServerResponse | 服务器应答非法 。 |
| InternalError.InitialParameterError | 初始化参数错误 。 |
| InternalError.InvalidSeqId | 分片序号错误。 |
| InternalError.InvalidWAVHeader | WAV头部格式非法或不在同一分片内。 |
| InternalError.NoConversationFound | 使用的会话没有找到或已经被释放。 |
| InternalError.RefTxtOov | 检测到不支持的字符在输入文本。 |
| InternalError.ServerInternalError | 服务器内部错误。 |
| InternalError.ServerOverload | 服务器过载。 |
| InternalError.ServiceTimeout | 服务超时。 |
| 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.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 | 请求并发数超过配额限制，请减少并发数或联系我们调大并发限额。 |
| RequestLimitExceeded | 请求的次数超过了频率限制。 |
| ResourceInsufficient.ServerTimeout | 评测超时，请检查语音数据大小。 |
| ResourceUnavailable.AuthorizeError | 服务未开通或已欠费。 |
| ResourceUnavailable.CannotFindSession | 评估之前没有初始化或已过期。 |
| ResourceUnavailable.ConcurrencyLimit | 使用并发超出限制。 |
| ResourceUnavailable.InitStreamNotSupport | 该接口不支持init_stream。 |
| ResourceUnavailable.InitStreamUnfinished | 初始化请求未完成，请稍后重试。 |
| ResourceUnavailable.LastSeqUnfinished | 前一个分片未处理完，请稍后重试。 |
| ResourceUnavailable.NoConversationFound | 使用的会话没有找到或已经被释放。 |
| ResourceUnavailable.NoInitBeforeEvaluation | 评估之前没有初始化。 |
