메인 콘텐츠로 건너뛰기

API キー発行 API を用いる方法

API キー発行 API を使う​

API キー発行 API を使って発行した API キーを利用する場合、以下のような実装方法が考えられます。

  1. アプリケーション利用者を何らかの方法で認証する
  2. 認証に成功した後、サーバ側で API キー発行 API を使用し、有効期限等を設定した API キーを発行してアプリケーションに送信する
  3. アプリケーションでは発行された API キーを使用して AmiVoice API を利用する

以下に、API キー発行 API の使い方を説明します。API の詳細については、リファレンスを参照してください。

エンドポイント​

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

リクエスト​

API キー発行 API を利用するためには、サービス ID（リクエストボディに指定し、パラメータ名は sid）とサービスパスワード（同、spw）、もしくは、マイページ上で API キー発行機能を付与して発行した API キー（Authorization ヘッダーに指定）のいずれかが必要になります。sidとspwには、マイページの「接続情報」に記載されている[サービス ID]と[サービスパスワード]を設定してください。

また、API キー発行 API では、有効期限と IP アドレス制限を付与することができます。有効時間（リクエストパラメータ名はepi）は任意に設定できます。epiに数値で設定する場合はミリ秒単位になります。その他の設定方法はリファレンスを参照してください。epiを省略した場合はデフォルト値として 30000（30 秒）が設定されます。API キーを発行してから、実際に AmiVoice API のリクエストを送信するまでの時間を想定して設定してください。IP アドレス制限を付与する場合は、ipaに API キーを利用できる接続元 IP アドレスを指定することができます。

API キー発行機能は、付与することができません。

노트

サービスパスワード（spw）とマイページへのログイン用のパスワードは異なります。

주의

sidとspwはリクエストボディにapplication/x-www-form-urlencoded形式で設定してください。クエリパラメータ（URL の末尾に?を付けて記載する方法）では指定しないでください。 リクエスト時の HTTP メソッドは、POSTです。

リクエスト例​

以下、curl コマンドを使って、API キーを発行してみます。

例1

IP アドレス 203.0.113.253 からのアクセスのみに制限し、有効期限を発行から 30 秒後に設定します。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={サービスID} \
     -d spw={サービスパスワード} \
     -d epi=30000 \
     -d ipa=203.0.113.253

sidとspwの代わりに API キーを使用する場合は、以下のようになります。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d epi=30000 \
     -d ipa=203.0.113.253 \
     -H "Authorization: Bearer {APIキー発行機能のあるAPIキー}"

例2

有効期限は、時間の単位を使った文字列（以下は２時間）で指定することも可能です。IP アドレスを範囲で指定して許可したい場合、CIDR で指定できます。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={サービスID} \
     -d spw={サービスパスワード} \
     -d epi=2h \
     -d ipa=203.0.113.0/24

例3

有効期限は日時指定も可能です。IP アドレスや、その範囲は、,（カンマ）またはスペースで区切って複数指定もできます。

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={サービスID} \
     -d spw={サービスパスワード} \
     -d epi=2026/07/31 \
     -d ipa=203.0.113.0/24,198.51.100.0/24

レスポンス​

リクエストに成功すると、レスポンスはプレーンテキストで、発行した API キーを返します。そのまま、リクエストパラメータのauthorization キーとして設定できます。

エラー時の対処方法​

発行した API キーによる接続認証が失敗するケース​

遅延（期限切れ）による認証エラー​

authorization キーによる認証要求を受け取るタイミングが、API キーに設定された有効期限日時を過ぎている場合、音声認識サービスは以下のようなエラーを返しますので、改めて API キーを取得してやり直してください。

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 キーの有効期限日時、-21s が有効期限からの遅延時間です。

s コマンド応答パケットではエラーが発生していない場合でも、最初の p パケット送信までに時間が経過して有効期限日時を過ぎてしまった場合には、最初の p パケット送信直後に以下のエラーレスポンスが返ります。

p can’t feed audio data to recognizer server

p パケット送信開始の成功後は、途中で有効期限切れになることはありません。

不正 ID、不正パスワードによる認証エラー​

API キー発行 API に指定するサービス ID・サービスパスワードが誤っている場合でも、API キーは発行されます。AmiVoice API のリクエスト時に、誤ったサービス ID、パスワードで作成された不正な API キーを指定すると、以下のような認証エラーを返します。

HTTP インタフェース のエラーレスポンス

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

WebSocket インタフェース のエラーレスポンス

s can't validate service authorization

この場合は、API キー発行依頼時に指定するサービス ID（sid）、サービスパスワード（spw）が正しい値になっているかを確認してください。