发音数据传输接口

最近更新时间:2024-04-11 01:20:46

我的收藏

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。

命令行工具

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 评估之前没有初始化。