同步 HTTP 接口

同步 HTTP 接口允许您将请求参数和语音数据发送到服务器，然后接收语音识别结果作为响应。

使用方法

发送语音识别请求

Endpoint 根据是否保存日志而有所不同。

POST https://acp-api.amivoice.com/v1/recognize　　　(保存日志)
POST https://acp-api.amivoice.com/v1/nolog/recognize (不保存日志)

关于两者的区别，请参阅日志保存。

将请求参数中的必需参数，即认证信息、连接引擎名称和语音数据分别指定为：

u={认证信息}
d={连接引擎名称}
a={二进制音频数据}

作为参数名称，通过 multipart POST 发送到服务器。二进制的音频数据必须放在 HTTP multipart 的最后一个部分。

让我们使用 curl 命令实际发送语音识别请求。使用会話_汎用引擎(-a-general)对样本中包含的音频文件(test.wav)进行语音识别，可以按以下方式操作。这里我们连接到"不保存日志"的 endpoint，不会在服务器上保留音频日志。

curl https://acp-api.amivoice.com/v1/nolog/recognize \
     -F u={APP_KEY} \
     -F d=-a-general \
     -F a=@test.wav

multipart POST 请求的 HTTP header 和 HTTP body 结构

结构如下：

POST https://acp-api.amivoice.com/v1/recognize
Content-Type: multipart/form-data;boundary=some-boundary-string

--some-boundary-string
Content-Disposition: form-data; name="u"

(这个部分存储<APPKEY>)
--some-boundary-string
Content-Disposition: form-data; name="d"

-a-general
--some-boundary-string
Content-Disposition: form-data; name="a"
Content-Type: application/octet-stream

(最后一个部分存储音频数据)
--some-boundary-string--

注意

在 a 参数之后设置的参数将被忽略。

例如，如果像下面这样将 u 参数放在最后，将会导致认证错误。

curl https://acp-api.amivoice.com/v1/nolog/recognize \
     -F d=-a-general \
     -F a=@test.wav \
     -F u={APP_KEY}      # 在a之后指定u

响应

{
  "results": [
    {
      "tokens": [],
      "tags": [],
      "rulename": "",
      "text": ""
    }
  ],
  "text": "",
  "code": ":"-",
  "message":"received illegal service authorization"
}

同样，如果像下面这样将 d 参数放在最后，将会出现找不到指定语音识别引擎的错误。

curl https://acp-api.amivoice.com/v1/nolog/recognize \
     -F u={APP_KEY} \
     -F a=@test.wav \
     -F d=-a-general      # 在a之后指定d

响应

{
  "results": [
    {
      "tokens": [],
      "tags": [],
      "rulename": "",
      "text": ""
    }
  ],
  "text": "",
  "code": "!",
  "message": "failed to connect to recognizer server (can't find available servers)"
}

关于响应，请参阅语音识别结果。

指定音频格式

如果发送的音频不是带有 header 的音频数据(如 WAV 或 Ogg)，则需要指定音频格式。音频格式需要在请求参数的 c 后面设置。

c={音频格式}

可以指定的音频格式请参阅音频格式对应表。

例如，要发送采样率为 16kHz、量化位数为 16 位、字节顺序为小端的音频文件 test.pcm，可以在参数 c 中指定 LSB16K，如下所示：

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={APP_KEY} \
     -F d=-a-general \
     -F c=LSB16K \
     -F a=@test.pcm

multipart POST 请求的 HTTP header 和 HTTP body 结构

结构如下：

POST https://acp-api.amivoice.com/v1/recognize
Content-Type: multipart/form-data;boundary=some-boundary-string

--some-boundary-string
Content-Disposition: form-data; name="u"

(这个部分存储<APPKEY>)
--some-boundary-string
Content-Disposition: form-data; name="d"

-a-general
--some-boundary-string
Content-Disposition: form-data; name="c"

LSB16K
--some-boundary-string
Content-Disposition: form-data; name="a"
Content-Type: application/octet-stream
(最后一个部分存储音频数据)
--some-boundary-string--

多个参数

如果您想设置除必需参数外的其他请求参数，例如 profile ID(profileId)，可以在 d 参数中设置多个参数，如下所示：

d=<key>=<value> <key>=<value> <key>=<value> ...

每个<key>=<value>对应使用半角空格或换行符分隔。
连接引擎名称是必需的，所以在这种情况下，请将 grammarFileNames=-a-general 指定为 key。

例：

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={APP_KEY} \
     -F d="grammarFileNames=-a-general profileId=:user01" \
     -F a=@test.wav

上述"<key>=<value>"中的<value>需要进行 URL 编码。例如，如果要在 profileWords 中设置一个显示为 "www"，读音为 "とりぷるだぶる" 的单词，需要将显示和读音之间的空格编码为 %20，将とりぷるだぶる编码为 %E3%81%A8%E3%82%8A%E3%81%B7%E3%82%8D%E3%81%A0%E3%81%B6%E3%82%8B。

curl https://acp-api.amivoice.com/v1/recognize \
     -F u={APP_KEY} \
     -F d="grammarFileNames=-a-general profileWords=hogehoge%20%E3%81%A8%E3%82%8A%E3%81%B7%E3%82%8D%E3%81%A0%E3%81%B6%E3%82%8B" \
     -F a=@test.wav

备注

请使用 UTF-8 字符编码
这里的 URL 编码使用的是半角空格转换为"%20"而不是"+"的方式

将参数作为 URL 查询字符串发送的情况

除 a 以外的参数，即 c、d 和 u，既可以作为 URL 查询字符串发送，也可以在 HTTP body 中以 multipart 方式发送。

备注

为了避免触及 HTTP header 大小限制，建议以 multipart 方式发送所有参数。
如果在 URL 查询字符串和 multipart 中都指定了相同的参数，查询参数的值将优先。
虽然 u 可以作为查询字符串发送，但由于可能留在通信路径的日志等中而泄露，请务必以 multipart 方式在 HTTP body 中发送。

如果将 d 参数作为查询字符串发送，需要再次对 d 参数的值进行 URL 编码。

https://acp-api.amivoice.com/v1/recognize?d=grammarFileNames%3D-a-general%20profileWords%3Dhogehoge%2520%25E3%2581%25BB%25E3%2581%2592%25E3%2581%25BB%25E3%2581%2592%25E3%2581%25A6%25E3%2581%2599%25E3%2581%25A8

"%" 转换为 "%25"，"=" 转换为 "%3D"，半角空格转换为 "%20"。

其他文档

API 参考请查看同步 HTTP 接口。
我们提供了一个客户端库（Hrp），它将使用 HTTP 接口时的通信处理和步骤封装成类库，只需实现语音识别应用程序所需的接口，就可以轻松创建语音识别应用程序。首先，请尝试运行示例程序 HrpTester。有关 Hrp 客户端库的接口规范，请参阅客户端库的 Hrp（HTTP 接口客户端）。

使用方法​

发送语音识别请求​

指定音频格式​

多个参数​

将参数作为 URL 查询字符串发送的情况​

其他文档​