メインコンテンツまでスキップ

ワンタイム APPKEY

APPKEYの安全な取り扱い​

APPKEY は、アプリケーションが AmiVoice API を利用する際の「サービス認証キー文字列」であり、漏洩すると悪用される恐れがあります。APPKEY をアプリケーションに埋め込むと、悪意のある第三者によってアプリケーションから APPKEY を取り出される可能性があります。一般に、ご自身が所有している APPKEY をアプリケーションの利用者のマシンには送付しないでください。代わりに流出しても影響範囲を最小限にできるように有効期限付きのワンタイム APPKEY を利用してください。

注記
  • ワンタイム APPKEY は、マイページに記載された APPKEY と同様の機能を持つ「サービス認証キー文字列」ですが、「発行日時と有効時間」にもとづいて「有効期限日時」が設定されている点が異なります。 また、接続元のIPアドレスの制限を設けることができます。
  • ワンタイム APPKEY に発行数の上限はありません。
注意
  • 特に Web アプリケーションの場合、HTML や JavaScript に APPKEY を記述すると、Web サイトの利用者から閲覧が可能ですので避けてください。
  • APPKEY をアプリケーションに埋め込むことが避けられない場合は、APPKEY を難読化、暗号化してください。難読化、暗号化することでアプリケーションから APPKEY を取り出すことが難しくなります。
  • 2025/06/30 のマイページリニューアル以前に作成されたアカウントの APPKEY 及び発行されたワンタイム APPKEY は削除出来ません。削除するには退会ののち新たにアカウントを作成する必要があります。
  • 2025/06/30 のマイページリニューアル以降にマイページ上で発行された APPKEY は、マイページ上で手動での削除が可能です。ワンタイム APPKEY 発行 API を使用して発行された APPKEY は、削除出来ません。

ワンタイム APPKEY を使う​

ワンタイム APPKEY を使う場合、以下のような実装方法が考えられます。

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

以下に、ワンタイム APPKEY 発行 API の使い方を説明します。

リクエスト​

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

注記

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

注意

sidとspwはリクエストボディにapplication/x-www-form-urlencoded形式で設定してください。クエリパラメータ（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={サービスID} \
     -d spw={サービスパスワード} \
     -d epi=30000 \
     -d ipa=203.0.113.253

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

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={サービスID} \
     -d spw={サービスパスワード} \
     -d epi=30000 \
     -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=30000 \
     -d ipa=203.0.113.0/24,198.51.100.0/24

レスポンス​

レスポンスはプレーンテキストで、ワンタイム APPKEY を返します。そのまま、リクエストパラメータのauthorization キーとして設定できます。

エラー時の対処方法​

ワンタイム APPKEY による接続認証が失敗するケース​

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

authorization キーによる認証要求を受け取るタイミングが、ワンタイム 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 に指定するサービス ID・サービスパスワードが誤っている場合でも、ワンタイム APPKEY は発行されます。AmiVoice API のリクエスト時に、誤ったサービス ID、パスワードで作成された不正なワンタイム APPKEY を指定すると、以下のような認証エラーを返します。

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

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

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

s can't verify service authorization

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

ワンタイム APPKEY 発行 API の詳細については、リファレンスのワンタイム APPKEY 発行 APIを参照してください。

非同期 HTTP インタフェース でワンタイム APPKEY を使う場合​

非同期 HTTP インタフェース でワンタイム APPKEY を利用する場合は、有効期限を十分に長くしてください。通常、音声認識開始までに数分の時間がかかります。また、混雑時にはごくまれにいったん停止してから、再開することもあり、認識途中でも認証が必要になることがあります。

APPKEY 発行可能な APPKEY​

2025/06/30 のマイページリニューアル以降、マイページ上では、APPKEY を発行することのできる APPKEY を発行できるようになりました。これによって発行した APPKEY は、ワンタイム APPKEY 発行 API のリクエスト時に、サービス ID（sid）とサービスパスワード（spw）の代わりに認証に使用することができます。 APPKEY 発行可能な APPKEY として発行する場合は、APPKEY 発行時の設定画面で、[APPKEY]の項目の[発行可能]のチェックボックスにチェックをいれてください。

ワンタイム APPKEY の削除​

2025/06/30 のマイページリニューアル以降にマイページ上で発行された APPKEY は、マイページ上で手動での削除が可能です。以下に手順を説明します。

  1. マイページのダッシュボードへアクセスします。このリンクから直接アクセスできます。マイページへのアクセスにはログインが必要です。
  2. [接続情報]より、削除したい APPKEY のチェックボックスにチェックを入れ、[削除]のボタンをクリックします。
  3. [APPKEYの削除]という確認画面が表示されるので、APPKEY に間違いがないことを確認の上、[削除]のボタンをクリックします。
  4. アカウントに登録されているメールアドレス宛に、認証コードが送られます。このコードをマイページに表示されている[認証コードの確認]画面に入力し、[送信]のボタンをクリックします。
  5. APPKEY の削除が完了し、アカウントに登録されているメールアドレス宛に、APPKEY 削除を知らせるメールが届きます。