使用 API Key 发行 API 的方法

使用 API Key 发行 API

在使用通过 API key 发行 API 发行的 API key 时，可以考虑以下实现方法：

以某种方式认证应用程序用户
认证成功后，服务器端使用 API key 发行 API，设置有效期等并发行 API key，然后发送给应用程序
应用程序使用发行的 API key 来使用 AmiVoice API

以下说明如何使用 API key 发行 API。有关 API 的详细信息，请参阅参考文档。

端点

POST https://acp-api.amivoice.com/issue_service_authorization

请求

要使用 API key 发行 API，需要在 MyPage 上授予 API key 发行功能后发行的 API key（在Authorization header 中指定），或者 Service ID（在请求体中指定，参数名为sid）和 Service Password（同样，spw）。使用sid和spw时，请设置 MyPage 的"Connection Information"中显示的 [Service ID] 和 [Service Password]。

此外，API key 发行 API 可以设置有效期和 IP 地址限制。有效时间（请求参数名为epi）可以任意设置。如果以数值设置epi，则以毫秒为单位。其他设置方法请参阅参考文档。如果省略epi，将设置默认值 30000（30 秒）。请根据预计从发行 API key 到实际发送 AmiVoice API 请求的时间来设置。如果要设置 IP 地址限制，可以在ipa中指定可以使用 API key 的源 IP 地址。

API key 发行功能无法授予。

备注

Service Password（spw）与用于登录 MyPage 的密码不同。
Service ID（sid）和 Service Password（spw）无法更改。请谨慎处理。
对于 2025/06/30 MyPage 改版后创建的账户，MyPage 上不会显示 Service ID 和 Service Password。请使用授予 API key 发行功能后发行的 API key。

警告

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

请求示例

以下使用 curl 命令来发行 API key。

示例1

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

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

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

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={ServiceID} \
     -d spw={ServicePassword} \
     -d epi=30000 \
     -d ipa=203.0.113.253

示例2

有效期也可以使用带时间单位的字符串（以下为 2 小时）指定。如果要以范围指定允许的 IP 地址，可以使用 CIDR 指定。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d epi=2h \
     -d ipa=203.0.113.0/24 \
     -H "Authorization: Bearer {API_KEY_WITH_API_KEY_ISSUANCE_FEATURE}"

示例3

有效期也可以指定日期时间。IP 地址或其范围可以用逗号（,）或空格分隔指定多个。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d epi=2026/07/31 \
     -d ipa=203.0.113.0/24,198.51.100.0/24 \
     -H "Authorization: Bearer {API_KEY_WITH_API_KEY_ISSUANCE_FEATURE}"

响应

请求成功时，响应将以纯文本形式返回发行的 API key。可以直接将其设置为请求参数中的authorization键。

发生错误时的处理方法

使用发行的 API Key 进行连接认证失败的情况

由于延迟（过期）导致的认证错误

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

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 是 API key 的有效期日期时间，-21s 是超过有效期的延迟时间。

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

p can't feed audio data to recognizer server

在 p 包发送开始成功后，中途不会出现有效期过期的情况。

由于无效 ID、无效密码导致的认证错误

即使指定给 API key 发行 API 的 Service ID 和 Service Password 不正确，API key 也会被发行。在 AmiVoice API 请求时，如果指定了使用错误的 Service ID 和 Service Password 创建的无效 API key，将返回以下认证错误。

HTTP 接口的错误响应

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

WebSocket 接口的错误响应

s can't validate service authorization

在这种情况下，请检查 API key 发行请求时指定的 Service ID（sid）和 Service Password（spw）是否为正确的值。