URL 指定音声認識機能

非同期 HTTP インタフェースの v2 には、URL 指定音声認識機能があります。これは通常とは異なるエンドポイントを利用することで、音声ファイルをアップロードする代わりに、HTTPS でアクセス可能な音声ファイルの URL を指定して音声認識を実行することができるものです。

この API を利用するには以下のステップを実行します。

音声認識バッチを作成する
バッチの状態を確認する
session_id を取得する
音声認識結果を取得する

特徴

URL 指定音声認識機能を用いた非同期 HTTP インタフェースには、以下の特徴があります。

音声ファイルをアップロードする必要がありません
音声ファイルの URL だけで音声認識を開始できます
複数の音声ファイルを 1 回のリクエストで登録できます
Amazon S3 の Presigned URL や Azure Blob Storage の SAS URL などを利用できます
音声認識結果の取得方法は、通常の非同期 HTTP インタフェースと同じです

通常の非同期 HTTP インタフェースとの違い

項目	通常の非同期 HTTP インタフェース	URL 指定音声認識機能
音声ファイルの指定方法	音声ファイルをアップロード	音声ファイルの URL を指定
一度にリクエストできる音声ファイル数	1 ファイル	1～90 ファイル
エンドポイント	`https://acp-api-async.amivoice.com/v2/recognitions`	`https://acp-api-async.amivoice.com/v2/batch-recognitions`
管理単位	`session_id`	`batch_id` → `session_id`

利用の方法

URL 指定音声認識機能を用いた非同期 HTTP インタフェースの利用の流れは、以下のとおりです。

音声ファイル URL の登録
          ↓
      batch_id 取得
          ↓
     バッチ状態確認
          ↓
     session_id 取得
          ↓
      結果取得

1. 音声認識バッチを作成する

音声ファイルの URL 一覧を指定して、認識バッチを作成します。リクエストは、JSON 形式、multipart 形式が使用できます。

tip

JSON 形式と multipart 形式では機能上の違いはありません。

URL 一覧を JSON として生成しやすい場合は JSON 形式を、既存の multipart/form-data ベースの実装へ組み込みたい場合は multipart 形式を利用してください。

JSON 形式によるリクエスト

以下は、JSON 形式でリクエストする場合です。

POST https://acp-api-async.amivoice.com/v2/batch-recognitions
Authorization: Bearer {APIキー}
Content-Type: application/json

リクエスト例：

{
  "files": [
    {
      "url": "https://example.com/audio-1.wav",
      "content_id": "file001"
    },
    {
      "url": "https://example.com/audio-2.wav",
      "content_id": "file002"
    }
  ],
  "parameters": {
    "d": "grammarFileNames=-a-general"
  }
}

以下は curl によるリクエストの例です。

curl -X POST \
  "https://acp-api-async.amivoice.com/v2/batch-recognitions" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "url": "https://example.com/audio-1.wav",
        "content_id": "file001"
      },
      {
        "url": "https://example.com/audio-2.wav",
        "content_id": "file002"
      }
    ],
    "parameters": {
      "d": "grammarFileNames=-a-general"
    }
  }'

リクエストパラメータ

パラメータ	必須	説明
files	○	認識対象ファイルの一覧
files[].url	○	音声ファイルのURL
files[].content_id		ユーザー定義の識別子
parameters.d	○	全ファイルに共通する音声認識パラメータ
parameters.c		全ファイルに共通する音声フォーマット名

tip

dパラメータには、通常の非同期 HTTP インタフェースと同じ形式の音声認識パラメータを指定できます。詳細はリクエストパラメータを参照してください。

grammarFileNames=-a-general

指定した値は、バッチ内のすべてのファイルに共通して適用されます。

cパラメータで音声フォーマット名を指定する場合も、バッチ内のすべてのファイルに共通して適用されます。音声フォーマット名を指定する場合（ヘッダなしの音声フォーマットのデータを使用する場合）は、バッチ内のすべてのファイルのフォーマットを揃えてください。

multipart 形式によるリクエスト

音声ファイルの URL 一覧は、multipart/form-data形式でも指定できます。

multipart 形式では、音声ファイルを添付するのではなく、URL 一覧を JSON 配列文字列としてaパラメータに指定します。

以下は curl によるリクエストの例です。

curl --request POST \
  'https://acp-api-async.amivoice.com/v2/batch-recognitions' \
  --form 'u={API_KEY}' \
  --form 'a=[{"url":"https://example.com/audio.wav","content_id":"123"}]' \
  --form 'd=grammarFileNames=-a-general'

リクエストパラメータ

パラメータ	必須	説明
u	△	APIキー。Authorizationヘッダーの代わりに指定できます
a	○	音声ファイル一覧を表すJSON配列文字列
d	○	全ファイルに共通する音声認識パラメータ
c		全ファイルに共通する音声フォーマット名

通常の非同期 HTTP インタフェースとは異なり、aパラメータは最後でなくても構いません。

tip

認証情報は、uパラメータのかわりに Authorization ヘッダーにBearer {API キー}の形式でも指定できます。この場合、uパラメータは省略できます。両方を指定した場合は、同じAPIキーである必要があります。

tip

dパラメータには、非同期 HTTP インタフェースと同じ形式の音声認識パラメータを指定できます。詳細はリクエストパラメータを参照してください。

grammarFileNames=-a-general

指定した値は、バッチ内のすべてのファイルに共通して適用されます。

a パラメータの形式

aには、認識対象ファイルの一覧を JSON 配列文字列として指定します。JSON 形式の場合のfiles配列に相当します。

[
  {
    "url": "https://example.com/audio-1.wav",
    "content_id": "123"
  },
  {
    "url": "https://example.com/audio-2.wav"
  }
]

各要素には以下を指定できます。

項目	必須	説明
url	○	音声ファイルを取得する HTTPS URL
content_id		ユーザー定義の識別子

レスポンス

レスポンス形式は、リクエストが JSON 形式の場合も multipart 形式の場合も同じです。すべてのファイルを受け付けた場合は、HTTP ステータス 202 を返します。

{
  "batch_id": "xxxxxxxx",
  "files": [
    {
      "url": "https://example.com/audio-1.wav",
      "status": "submitted",
      "session_id": null,
      "content_id": "file001"
    }
  ]
}

レスポンス項目

項目	説明
batch_id	バッチを識別するID
files[].url	登録した URL からクエリ文字列を取り除いたもの
files[].status	現在の状態
files[].session_id	対応するsession_id
files[].content_id	ユーザー定義の識別子

一部のファイルでエラーが発生した場合

一部の URL が無効であっても、他の有効な URL は処理されます。URL やcontent_idが 1 件でも無効な場合は、HTTP ステータス 207 を返します。すべてのファイルが無効な場合も 207 を返し、batch_idも発行されます。

レスポンス例：

{
  "batch_id": "xxxxxxxx",
  "files": [
    {
      "url": "https://example.com/audio-1.wav",
      "status": "submitted",
      "session_id": null
    },
    {
      "url": "http://example.com/audio-2.wav",
      "status": "error",
      "session_id": null,
      "error_message": "url must be an HTTPS URL"
    }
  ]
}

指定する URL について

指定する URL は HTTPS でアクセス可能である必要があります。

以下は利用できる URL の例です。

公開 URL
Amazon S3 Presigned URL
Azure Blob Storage SAS URL
Google Cloud Storage などの Signed URL

登録可能なファイル数

1 回のリクエストで最大 90 ファイルまで登録できます。

content_id

各音声ファイルには、任意の識別子としてcontent_idを設定できます。

{
  "url": "https://example.com/audio.wav",
  "content_id": "customer001"
}

指定したcontent_idはレスポンスにも含まれるため、アプリケーション側でのファイル管理や認識結果との対応付けに利用できます。

2. バッチの状態を確認する

バッチの状態を確認します。

リクエスト

GET https://acp-api-async.amivoice.com/v2/batch-recognitions/{batch_id}
Authorization: Bearer {APIキー}

curlの例：

curl -H "Authorization: Bearer {APIキー}" \
  https://acp-api-async.amivoice.com/v2/batch-recognitions/{batch_id}

レスポンス例

{
  "batch_id": "<batch_id>",
  "files": [
    {
      "url": "https://example.com/audio-1.wav",
      "status": "processing",
      "session_id": "<session_id>",
      "content_id": "123"
    },
    {
      "url": "https://example.com/audio-2.mp3",
      "status": "submitted",
      "session_id": null
    }
  ]
}

ファイルの状態

状態	説明
submitted	受付済み
queued	認識処理待ち
started	認識処理開始
processing	認識処理中
completed	認識処理完了
error	エラー
deleted	`session_id`は発行済みだが、認識ジョブが削除・期限切れなどで見つからない状態

session_id について

音声ファイルごとに session_id が発行されます。

session_idが発行された後は、通常の非同期 HTTP インタフェースと同じ方法で音声認識ジョブの状態や認識結果を取得できます。詳しい取得手順は音声認識ジョブの状態をチェックし、結果を取得するを参照してください。

3. 音声認識結果を取得する

音声認識結果の取得方法は、通常の非同期 HTTP インタフェースと同じです。

リクエスト

GET https://acp-api-async.amivoice.com/v2/recognitions/{session_id}
Authorization: Bearer {APIキー}

curlの例：

curl \
  -H "Authorization: Bearer {APIキー}" \
  https://acp-api-async.amivoice.com/v2/recognitions/{session_id}

認識結果のフォーマットについては、音声認識の結果を参照してください。

エラー

本APIでは、エラーの発生箇所によって返却形式が異なります。

発生箇所	エラー項目
Batch API の HTTP エラー	`errorCode`, `errorMessage`
ファイル単位の処理エラー	`error_code`, `error_message`
音声認識処理エラー	レスポンスコードとメッセージを参照

Batch API の HTTP エラー

Batch API へのリクエストに問題がある場合や、サーバー側でエラーが発生した場合は、以下の HTTP エラーが返されます。

HTTP ステータス	errorMessage	主な原因
400	Invalid batch request	リクエスト形式不正、必須項目不足、files が空、登録件数超過など
401	No authorization header	バッチの状態確認で Authorization ヘッダーを指定していない
401	Invalid authorization header format	Authorization ヘッダーが`Bearer`の形式でない
401	Invalid authentication credentials	Authorization ヘッダーの API キーの形式が不正
401	Conflicting API keys	複数箇所で異なる API キーを指定した
401	Failed to authorize for the API key	バッチの作成で API キーを指定していない、または API キーの認証に失敗した
404	Not Found	指定した batch_id が存在しない、またはこの API キーで参照できるバッチではない
405	Method Not Allowed	サポートされていない HTTP メソッドを使用した
415	Unsupported media type	サポートされていない Content-Type を指定した
500	Internal server error	サーバー内部、または認証サービスでエラーが発生した
503	Service temporarily unavailable	一時的にサービスを利用できない

登録時の URL と content_id の検証エラー

登録時の音声ファイルの URL やcontent_idに問題がある場合、該当ファイルはエラーとなります。

すべてのファイルがエラーの場合でも、バッチは作成されます。

レスポンス例：

{
  "batch_id": "<batch_id>",
  "files": [
    {
      "url": "https://example.com/audio.wav",
      "status": "submitted",
      "session_id": null
    },
    {
      "url": "http://example.com/audio.wav",
      "status": "error",
      "session_id": null,
      "error_message": "url must be an HTTPS URL"
    }
  ]
}

error_messageと原因：

error_message	原因
url must be an HTTPS URL	HTTPS 以外の URL を指定した、または URL 形式が不正
could not resolve the URL host to an IP address	ホスト名の DNS 解決に失敗した
url host resolves to a disallowed network	プライベート IP アドレスやループバックアドレスなど、利用できないアドレスが指定された
invalid parameter (content_id)	`content_id` に半角スペースが含まれる

ファイル単位のエラー

ファイル単位のエラーでは、処理段階に応じて error_code や error_message が返されます。登録時の URL や content_id の検証エラーには error_code は含まれず、error_message が返されます。以下は、error_code も含まれる処理エラーの例です。

{
  "url": "https://example.com/audio.wav",
  "status": "error",
  "session_id": null,
  "error_code": "^",
  "error_message": "invalid parameter"
}

音声認識処理におけるエラーコードおよびエラーメッセージの詳細については、レスポンスコードとメッセージを参照してください。

共通パラメータエラーについて

dパラメータはバッチ内のすべてのファイルに共通して適用されます。

例外として、dを省略した場合やdにエンジンモードの指定がない場合は、バッチを作成しません。このときは HTTP ステータス 200 で次のレスポンスを返し、batch_idは含まれません。この確認は、API キーが有効かどうかの確認より先に行います。ただし、API キーの未指定、Authorization ヘッダーの形式の誤り、複数の場所の API キーの不一致は、先に HTTP ステータス 401 を返します。

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

それ以外の音声認識パラメータの不正は、各ファイルの認識処理時に判定され、ファイル単位のエラーとして返される場合があります。

例：

{
  "batch_id": "xxxxxxxx",
  "files": [
    {
      "url": "https://example.com/audio-1.wav",
      "content_id": "file-1",
      "status": "error",
      "session_id": null,
      "error_code": "^",
      "error_message": "invalid parameter (loggingOptOut)"
    },
    {
      "url": "https://example.com/audio-2.wav",
      "content_id": "file-2",
      "status": "error",
      "session_id": null,
      "error_code": "^",
      "error_message": "invalid parameter (loggingOptOut)"
    }
  ]
}

バッチ内の複数ファイルで同じエラーが発生している場合は、共通のdに問題がないか確認してください。

制限事項

URL は HTTPS でアクセス可能である必要があります
1 回のリクエストで登録できる音声ファイル数は最大 90 件です
音声ファイルサイズは 2,147,483,647 バイト (約 2 GiB) 以下である必要があります
音声認識結果の保存期間は、非同期 HTTP インタフェースと同じです

特徴​

通常の非同期 HTTP インタフェースとの違い​

利用の方法​

1. 音声認識バッチを作成する​

JSON 形式によるリクエスト​

リクエストパラメータ​

multipart 形式によるリクエスト​

リクエストパラメータ​

a パラメータの形式​

レスポンス​

レスポンス項目​

一部のファイルでエラーが発生した場合​

指定する URL について​

登録可能なファイル数​

content_id​

2. バッチの状態を確認する​

リクエスト​

レスポンス例​

ファイルの状態​

session_id について​

3. 音声認識結果を取得する​

リクエスト​

エラー​

Batch API の HTTP エラー​

登録時の URL と content_id の検証エラー​

ファイル単位のエラー​

共通パラメータエラーについて​

制限事項​

特徴

通常の非同期 HTTP インタフェースとの違い

利用の方法

1. 音声認識バッチを作成する

JSON 形式によるリクエスト

リクエストパラメータ

multipart 形式によるリクエスト

リクエストパラメータ

a パラメータの形式

レスポンス

レスポンス項目

一部のファイルでエラーが発生した場合

指定する URL について

登録可能なファイル数

content_id

2. バッチの状態を確認する

リクエスト

レスポンス例

ファイルの状態

session_id について

3. 音声認識結果を取得する

リクエスト

エラー

Batch API の HTTP エラー

登録時の URL と content_id の検証エラー

ファイル単位のエラー

共通パラメータエラーについて

制限事項