一次性 APPKEY

APPKEY 的安全处理

APPKEY 是应用程序使用 AmiVoice API 时的"服务认证密钥字符串"，如果泄露可能会被滥用。如果将 APPKEY 嵌入应用程序中，恶意第三方可能会从应用程序中提取 APPKEY。通常，请不要将您自己拥有的 APPKEY 发送到应用程序用户的机器上。相反，请使用具有有效期限的一次性 APPKEY，以便即使泄露也能将影响范围降到最低。

备注

一次性 APPKEY 与 MyPage 上列出的 APPKEY 具有相同的功能，是一个"服务认证密钥字符串"，但不同之处在于它根据"发行日期和有效时间"设置了"有效期限日期"。此外，还可以对连接源的 IP 地址进行限制。
一次性 APPKEY 的发行数量没有上限。

警告

特别是对于 Web 应用程序，请避免在 HTML 或 JavaScript 中写入 APPKEY，因为网站用户可能会看到它。
如果无法避免将 APPKEY 嵌入应用程序中，请对 APPKEY 进行混淆或加密。混淆或加密可以使从应用程序中提取 APPKEY 变得更加困难。
在 2025/06/30 MyPage 更新之前创建的账户的 APPKEY 以及发行的一次性 APPKEY 无法删除。要删除它们，需要退出会员后重新创建账户。
在 2025/06/30 MyPage 更新之后在 MyPage 上发行的 APPKEY 可以在 MyPage 上手动删除。使用一次性 APPKEY 发行 API 发行的 APPKEY 无法删除。

使用一次性 APPKEY

使用一次性 APPKEY 时，可以考虑以下实现方法：

通过某种方式对应用程序用户进行身份验证
身份验证成功后，在服务器端发行设置了有效期限的一次性 APPKEY 并发送给应用程序
应用程序使用一次性 APPKEY 来使用 AmiVoice API

以下说明如何使用一次性 APPKEY 发行 API。

请求

要使用一次性 APPKEY 发行 API，需要设置 Service ID （在请求正文中指定，参数名为 sid）和 Service Password （同样，spw），或者在 MyPage 上设置为"APPKEY 発行可能"并发行的 APPKEY（在 Authorization 标头中指定）。请将 MyPage 中"Connection Information"中列出的[Service ID]和[Service Password]设置为 sid 和 spw。

备注

服务密码与用于登录 MyPage 的密码不同。

警告

请以 application/x-www-form-urlencoded 格式在请求正文中设置 sid 和 spw。请不要使用查询参数（在 URL 末尾添加 ? 的方法）指定。请求时的 HTTP 方法为 POST。

有效时间(请求参数名为 epi)可以任意设置。如果将数值设置为 epi，则以毫秒为单位。有关其他设置方法，请参阅参考。如果省略 epi，则默认值设置为 30000(30 秒)。请考虑从发行一次性 APPKEY 到实际发送 AmiVoice API 请求之间的预期时间来进行设置。可以在 ipa 中指定可以使用 APPKEY 的 IP 地址。

让我们使用 curl 命令来发行一次性 APPKEY。

示例1

仅限 IP 地址 203.0.113.253 的访问，并将有效期限设置为发行后 30 秒。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={serviceId} \
     -d spw={service密码} \
     -d epi=30000 \
     -d ipa=203.0.113.253

如果使用 APPKEY 代替 sid 和 spw，则如下所示：

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d epi=30000 \
     -d ipa=203.0.113.253 \
     -H "Authorization: Bearer {可发行 APPKEY 的 APPKEY}"

示例 2

如果要按范围指定允许的 IP 地址，可以使用 CIDR 指定。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={serviceId} \
     -d spw={service密码} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24

示例3

IP 地址或其范围可以用逗号分隔多个指定。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={serviceId} \
     -d spw={service密码} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24,198.51.100.0/24

响应

响应是纯文本，返回一次性 APPKEY。可以直接将其设置为请求参数的 authorization key。

错误时的处理方法

使用一次性 APPKEY 连接认证失败的情况

由于延迟(过期)导致的认证错误

如果接收 authorization key 的认证请求的时间超过了一次性 APPKEY 设置的有效期限日期，语音识别服务将返回以下错误，请重新获取一次性 APPKEY 并重试。

HTTP 接口的错误响应

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket 接口的错误响应

s service authorization has expired: 20XX/XX/XX XX:XX:XX.000 +0000 (-21s)

s 响应中包含的 20XX/XX/XX XX:XX:XX.000 是一次性 APPKEY 的有效期限日期，-21s 是超过有效期限的延迟时间。

即使在 s 命令响应数据包中没有发生错误，如果在发送第一个 p 数据包之前经过的时间超过了有效期限日期，则在发送第一个 p 数据包后立即返回以下错误响应。

p can't feed audio data to recognizer server

在成功开始发送 p 数据包后，不会在中途过期。

由于非法 ID 导致的认证错误

即使在一次性 APPKEY 发行 API 中指定的 serviceId 和 service 密码不正确，也会发行一次性 APPKEY。在 AmiVoice API 请求时，如果指定了使用错误的 serviceId 和密码创建的非法一次性 APPKEY，将返回以下认证错误。

HTTP 接口的错误响应

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket 接口的错误响应

s can't verify service authorization

在这种情况下，请确认在请求一次性 APPKEY 发行时指定的 serviceId (sid)和 service 密码(spw)是否为正确值。

有关一次性 APPKEY 发行 API 的详细信息，请参阅参考中的一次性 APPKEY 发行 API。

在异步 HTTP 接口中使用一次性 APPKEY 时

在异步 HTTP 接口中使用一次性 APPKEY 时，请将有效期限设置得足够长。通常，开始语音识别需要几分钟的时间。此外，在繁忙时，极少数情况下可能会暂停然后重新开始，即使在识别过程中也可能需要认证。

可发行 APPKEY 的 APPKEY

自 2025/06/30 MyPage 更新以来，可以在 MyPage 上发行能够发行 APPKEY 的 APPKEY。使用这种方式发行的 APPKEY 可以在一次性 APPKEY 发行 API 请求时代替 Service ID （sid）和 Service Password （spw）用于认证。如果要将其作为可发行 APPKEY 的 APPKEY 发行，请在 Issue one-time APPKEY 的设置画面中，在 [APPKEY] 项目的 [発行可能] 复选框中打勾。

删除一次性 APPKEY

在 2025/06/30 MyPage 更新之后在 MyPage 上发行的 APPKEY 可以在 MyPage 上手动删除。以下是操作步骤：

访问 MyPage 的仪表板。可以通过此链接直接访问。访问 MyPage 需要登录。
在 [Connection Information] 中，勾选要删除的 APPKEY 的复选框，然后点击 [Delete] 按钮。
将显示 [Delete APPKEY] 的确认画面，确认 APPKEY 无误后，点击 [Delete] 按钮。
验证码将发送到注册到账户的电子邮件地址。将此代码输入到 MyPage 上显示的 [Authentication Code Confirmation] 画面中，然后点击 [Send] 按钮。
APPKEY 删除完成，通知 APPKEY 删除的电子邮件将发送到注册到账户的电子邮件地址。

APPKEY 的安全处理​

使用一次性 APPKEY​

请求​

响应​

错误时的处理方法​

使用一次性 APPKEY 连接认证失败的情况​

由于延迟(过期)导致的认证错误​

由于非法 ID 导致的认证错误​

在异步 HTTP 接口中使用一次性 APPKEY 时​

可发行 APPKEY 的 APPKEY​

删除一次性 APPKEY​