跳至主要内容

请求参数

本文介绍在使用 AmiVoice API 发送语音识别请求时可以设置的参数。虽然 HTTP 和 WebSocket 接口的发送方式不同，但可以设置的参数是相同的。

参数列表​

authorization(认证信息)和grammarFileNames(连接引擎名称)是必需的。其他参数是可选的。某些参数可能不适用于所有接口，请参考下表。

参数名称说明
必需
同步HTTP
WebSocket
异步HTTP
authorization认证信息●●●●
grammarFileNames连接引擎名称●●●●
profileIdprofile ID●●●
profileWords单词注册列表●●●
keepFillerToken控制自动删除填充词(无意义词语)●●●
segmenterProperties语音段检测和说话人区分的参数●●● （*1）
extension使用量统计标签●●●
maxDecodingTime最大识别处理时间●●●
maxResponseTime最大响应时间●●●
maxDecodingRate最大 RT●●●
targetResponseTime目标响应时间●●●
targetDecodingRate目标 RT●●●
recognitionTimeout识别完成超时●●●
resultUpdatedInterval识别中事件的间隔●
noInputTimeout等待语音开始超时●
loggingOptOut更改日志保存的有无●
contentId用户定义 ID●
compatibleWithSync结果格式的兼容性●
speakerDiarization说话人区分启用选项●
diarizationMinSpeaker说话人区分的最小预估说话人数●
diarizationMaxSpeaker说话人区分的最大预估说话人数●
sentimentAnalysis情绪分析启用选项●

（*1）在异步 HTTP 接口中，无法使用与说话人区分相关的参数

有关这些请求参数的发送方法，请参阅以下部分：

参数详情​

以下是各参数的详细说明。

必需参数​

authorization​

认证信息

使用 API 时必须设置认证信息。认证信息是在 MyPage 上显示的 [API key]，或者通过API Key获取的 API key。

警告

从浏览器应用程序连接到语音识别服务器时，考虑到认证信息泄露的风险，建议使用带有有效期限或 IP 地址限制的 API key。详情请参阅 API Key。

grammarFileNames​

连接引擎名称

指定该会话中要使用的语音识别引擎。每个会话指定一个。可设置的值请参考连接引擎名称列表或 MyPage。详情请参阅语音识别引擎。

可选参数​

profileId​

profile ID

profile 是存在于语音识别服务器上的每个用户的数据文件，用户可以为其命名并保存注册的单词。profile ID 是用于指定该数据文件的标识符。详情请参阅用户词典。

profileWords​

用户词典单词列表

可以注册在会话中有效的用户词典单词。对于 Hybrid 引擎的单词注册，每个单词以"显示<半角空格>读音"的格式注册。如果要指定类名，请使用"显示<半角空格>读音<半角空格>类名"的格式。对于 End to End 引擎的单词强调，格式为"显示<半角空格>替代显示<半角空格>单词强调度"登录。替代显示和单词强调度可以省略，但如果只省略替代显示，则格式为"显示<半角空格><半角空格>单词强调度"。无论是单词注册还是单词强调，多个单词之间用"|"（半角竖线）分隔。值的格式如下（以单词注册且未指定类名的情况为例）：

显示1 读音1|显示2 读音2|显示3 读音3|显示4 读音4

详情请参阅用户词典。

keepFillerToken​

控制自动删除填充词(无意义词语)

指定1或0。默认值为0。当不想自动删除语音识别结果中包含的填充词(如"あー"或"えー"等)时，指定1。另请参阅填充词自动删除。

填充词前后用半角"%"包围。以下是填充词的示例：

%あー%
%えー%
%おー%
%えっと%
提示

另请参阅 AmiVoice Tech Blog 上的How to choose whether to display or remove unnecessary words (fillers) with AmiVoice API。

segmenterProperties​

语音段检测参数

这是用于调节语音检测灵敏度等的参数。首先尝试默认设置，然后根据需要进行调整。可以设置以下参数：

同步 HTTP 接口和 WebSocket 接口的默认值是相同的，异步 HTTP 接口的一些值有所不同。后者的值在括号内显示。

警告

默认值可能会在没有预先通知的情况下发生变更。

  • threshold
    • 用于判断是否为语音的得分阈值，得分大于或等于此值时被视为语音。降低此值会使语音更容易被检测到，减少语音中断或末尾被截断的情况，但也会增加误检测的可能性。在有较多噪音的环境中，如果误检测明显，可以增大此值。
    • 默认值为 5000（8000）。
  • preTime
    • 当被视为语音的时间持续一定时间后，系统会进入语音段检测状态，此值用于指定这个"一定时间"的长度。如果短语音无法被检测到或语音开头容易被截断，可以减小此值。如果短噪音的误检测较多，可以增大此值。
    • 单位为毫秒，默认值为 100（100）。请以 50 的倍数指定。
  • postTime
    • 当语音段末尾被视为非语音的时间持续一定时间后，系统会结束语音段检测状态，此值用于指定这个"一定时间"的长度。如果语音中途被分割，可以增大此值。如果两个语音段连在一起，可以减小此值。
    • 单位为毫秒，默认值为 550（800）。
  • preForcedTime
    • 当进入语音段检测状态时，此值用于指定从被视为语音的最初时刻向前回溯多长时间作为语音段的开始点。如果语音开头容易被截断，可以增大此值。
    • 单位为毫秒，默认值为 350（350）。
  • postForcedTime
    • 当语音段检测状态结束时，此值用于指定从被视为非语音的最后时刻向后延伸多长时间作为语音段的结束点。如果语音末尾容易被截断，可以增大此值。如果实时响应性变差，可以减小此值。
    • 单位为毫秒，默认值为 350（350）。
  • powerThreshold
    • 在判断是否为语音时，如果还要考虑音量（功率），此值用于指定得分的阈值。需要与threshold分开设置，设为 0 或更小的值则无效。如果得分低于阈值，则被视为非语音。如果背景中的小声音容易被检测到，可以增大此值。
    • 默认值为 100（100）。
  • decayTime
    • 可以在经过一定时间后单调减小postTime的值，使语音更容易被切断，此值用于指定这个"一定时间"。如果检测到的语音段过长，可以减小此值。
    • 单位为毫秒，默认值为 5000（15000）。

以下是针对不同使用场景的参数推荐值：

参数
适用于多数场景的推荐值（同步 HTTP、WebSocket 接口的默认值）
声音非常小的场景推荐值
有大量背景音乐、保持音或非稳态噪音等场景的推荐值
threshold500050009000
preTime100100100
postTime550550550
preForcedTime350350350
postForcedTime350350350
powerThreshold1000100
decayTime500050005000

与说话人区分相关的参数

这些是与说话人区分相关的参数。仅在同步 HTTP 和 WebSocket 接口中可设置。可以设置以下参数：

  • useDiarizer
    • 设置为1时，在同步 HTTP 或 WebSocket 接口中启用说话人区分。默认为禁用。详情请参阅说话人区分。
  • diarizerAlpha
    • 这是一个控制同步 HTTP 或 WebSocket 接口中说话人区分新说话人出现概率的参数。指定的值越大，新说话人出现的概率越高；指定的值越小，新说话人出现的概率越低。diarizerAlpha=0是特殊情况，将被视为指定了 1e-30。但是，对于支持 8kHz 音频的引擎，例如使用通用引擎（-a-general）并发送采样率为 8kHz 的音频时，将被视为指定了 1e-10。如果不设置，则默认为diarizerAlpha=0。
  • diarizerTransitionBias
    • 这是一个控制同步 HTTP 或 WebSocket 接口中说话人区分说话人切换概率的参数。指定的值越大，说话人切换的概率越高；指定的值越小，说话人切换的概率越低。diarizerTransitionBias=0是特殊情况，将被视为指定了 1e-20。如果不设置，则默认为diarizerTransitionBias=0。
参数设置方法​

在segmenterProperties=后面添加参数设置。同时设置多个参数时，各参数之间用半角空格分隔。

使用 curl 命令的同步 HTTP 接口设置示例​

设置多个参数时，插入的半角空格需要 URL 编码为%20。

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={API_KEY} \
     -F d="grammarFileNames=-a-general segmenterProperties=threshold=4000%20postTime=600" \
     -F a=@test.wav
WebSocket 接口设置示例​

将设置给segmenterProperties的整个参数用双引号"..."括起来。

s 16K -a-general authorization={API_KEY} segmenterProperties="preTime=200 useDiarizer=1 diarizerAlpha=1e-20"

extension​

使用量统计标签

当多个系统、环境或最终用户共用同一个 AmiVoice API 账户时，可以设置统计标签以获取按任意属性分类的使用量。详情请参阅使用量统计标签。

maxDecodingTime​

最大识别处理时间

已用识别处理时间>maxDecodingTime\text{已用识别处理时间} > \text{maxDecodingTime}

当出现上述情况时，用于强制中断语音识别处理的功能。单位为毫秒。

默认值为 0，当为 0 时，此功能无效。

maxResponseTime​

最大响应时间

已用识别处理时间>输入的音频时长+maxResponseTime\text{已用识别处理时间} > \text{输入的音频时长} + \text{maxResponseTime}

当出现上述情况时，用于强制中断语音识别处理的功能。请注意，此参数只有在接收完所有音频数据后才会生效。

默认值为 0，当为 0 时，此功能无效。

maxDecodingRate​

最大 RT

已用识别处理时间>输入的音频时长×maxDecodingRate\text{已用识别处理时间} > \text{输入的音频时长} \times \text{maxDecodingRate}

当出现上述情况时，用于强制中断语音识别处理的功能。请注意，此参数只有在接收完所有音频数据后才会生效。

默认值为 -1，当为负值时，此功能无效。

RT 是表示语音识别处理速度的数值，通过 RT = 识别处理所用时间 / 输入的音频时长 计算得出。

targetResponseTime​

目标响应时间

计算"临时 RT"，其中 临时 RT=已用识别处理时间已输入的音频时长\text{临时 RT} = \frac{\text{已用识别处理时间}}{\text{已输入的音频时长}}，

临时RT≈已输入的音频时长+targetResponseTime已输入的音频时长\text{临时RT} \approx \frac{\text{已输入的音频时长} + \text{targetResponseTime}}{\text{已输入的音频时长}}

为达到上述状态，在语音识别处理过程中，动态调节语音识别处理速度与识别率之间平衡的功能。单位为毫秒。当“截至目前输入的语音时长”不足 1 秒，或“截至目前所耗费的识别处理时间”低于“截至目前输入的语音时长”（即“暂定 RT”尚未达到 1）时，该功能不会生效。

默认值为 0，当为 0 时，此功能无效。

targetDecodingRate​

目标 RT

将"暂定 RT"计算为：暂定 RT=到目前为止的识别处理时间到目前为止输入的语音时间\text{暂定 RT} = \frac{\text{到目前为止的识别处理时间}}{\text{到目前为止输入的语音时间}}，

暂定RT≈targetDecodingRate\text{暂定RT} \approx \text{targetDecodingRate}

在语音识别处理过程中，动态调节语音识别的处理速度和识别率的平衡的功能。当"到目前为止输入的语音时间"不足1秒，或者"到目前为止的识别处理时间"低于"到目前为止输入的语音时间"（即"暂定 RT"未达到1以上）时，该功能不会启动。

默认值为 -1，当为负值时，此功能无效。

recognitionTimeout​

识别完成超时

当语音识别处理在一定时间内（即recognitionTimeout）未完成时，强制中断处理并获取当前的中间识别结果的功能。单位为毫秒。当此功能启用时，如果在一个语音段落中成功完成语音识别，即使未达到recognitionTimeout设置的时间，后续语音段落也不会进行识别处理。但是，如果语音识别处理的结果是该语音段落全部被识别为填充词而被拒绝，或者未能获得识别结果，则会继续对下一个语音段落进行识别处理。

对于同步 HTTP 接口和异步 HTTP 接口，从服务器开始接收客户端语音的时刻开始计算 recognitionTimeout；对于 WebSocket 接口，从检测到第一个发话段落的开头时刻开始计算。请注意，recognitionTimeout 的时间长度是指识别处理所需的时间，与音频数据的时间不同。

默认值为 0，当为 0 时，此功能无效。

例如，对于问答式语音机器人等场景，快速找到包含有效识别结果的发话段落更为重要，而不需要对后续发话段落进行识别处理时，此功能特别有效。启用此功能时，如果发话中途段落被打断导致无法获得必要的识别结果，请调整 segmenterProperties 的 postTime 参数。

提示

关于recognitionTimeout和noInputTimeout的详细行为和具体使用方法，请参考技术博客『AmiVoice API 更新解析 使用语音机器人新参数缩短响应等待时间』。

WebSocket API 特有参数​

resultUpdatedInterval​

识别中事件的间隔

以毫秒为单位指定发送识别中事件的间隔。

  • 设置为 0 时不发送识别中事件。
  • 每经过指定的时间就发送一次识别中事件。如果在指定的时间内语音识别的中间结果没有更新，则会发送在前一个中间识别结果末尾添加一个"."的结果。如果指定的值包含小于 100 的小数部分，则会向上取整到 100 的倍数。

noInputTimeout​

发话开始等待超时

当在一定时间（= noInputTimeout）内未检测到发话段落时，强制结束语音识别会话并取消所有后续识别处理的功能。单位为毫秒。此时间长度是指语音识别处理所需的时间，与音频数据的时间不同。

会话结束时，客户端将收到"e timeout occurred"错误。

默认值为 0，当为 0 时，此功能无效。

提示

关于recognitionTimeout和noInputTimeout的详细行为和具体使用方法，请参考技术博客『AmiVoice API 更新解析 使用语音机器人新参数缩短响应等待时间』。

异步 HTTP 接口特有参数​

loggingOptOut​

更改日志保存的有无

loggingOptOut=<True|False> 指定是否保存日志。设置为 True 时，系统在会话期间不会保存日志。默认为 False。

contentId​

用户定义 ID

contentId=<任意字符串> 可以指定用户自定义的任意字符串。该字符串将包含在会话期间的状态和结果响应中。默认为 None。

compatibleWithSync​

结果格式的兼容性

compatibleWithSync=<True|False> 以与同步 HTTP 接口兼容的格式输出结果。默认为 False。

speakerDiarization​

说话人区分启用选项

speakerDiarization=<True|False> 启用说话人区分。默认为 False。详情请参阅说话人区分。

diarizationMinSpeaker​

说话人区分的最小预估说话人数

diarizationMinSpeaker=<int> 仅在启用说话人区分时有效，可以指定音频中包含的最小说话人数。需要设置为 1 或更大。默认为 1。详情请参阅说话人区分。

diarizationMaxSpeaker​

说话人区分的最大预估说话人数

diarizationMaxSpeaker=<int> 仅在启用说话人区分时有效，可以指定音频中包含的最大说话人数。需要设置为不小于 diarizationMinSpeaker 的值。默认为 10。详情请参阅说话人区分。

sentimentAnalysis​

情绪分析启用选项

sentimentAnalysis=<True|False> 启用情绪分析。默认为 False。

详情请参阅情绪分析。