openapi: 3.0.3
info:
  title: 非同期 HTTP インタフェース
  version: v2
  description: |
    非同期 HTTP インタフェースは長時間の音声をテキスト化、文字起こしするためのノンブロッキングな HTTP API です。

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

    1. 音声認識ジョブを作成する
    2. ポーリングして音声認識ジョブの状態をチェックし、結果を取得する

    1 のジョブを生成する方法は、ログのあり・なしの指定方法などが異なりますが、同期 HTTP インタフェースとほぼ同じです。

    ## エンドポイント

    同期 HTTP インタフェースとは異なり、ログ保存のあり、なしに関わらずエンドポイントのベースは同じです。

    ```text
    v2（新版）の場合
    https://acp-api-async.amivoice.com/v2/recognitions

    v1（従来版）の場合
    https://acp-api-async.amivoice.com/v1/recognitions
    ```

    v1 と v2 の違いについては、[新しいバージョンについて](/amivoice-api/manual/async-http-interface/#async-v2)を参照してください。

    :::caution
    - 古いバージョンの非同期 HTTP インタフェースは、今後停止される予定です。ご利用中の方は、v2 への移行を行ってください。
    - v2 では現在、感情分析の機能を利用することができません。感情分析を利用する場合は、v1 をご利用ください。
    :::

servers:
  - url: https://acp-api-async.amivoice.com

tags:
  - name: job
    x-displayName: ジョブの作成
  - name: status
    x-displayName: ジョブの状態の確認、結果の取得

paths:
  /v2/recognitions:
    post:
      tags:
        - job
      summary: ジョブの作成
      operationId: createRecognitionJob
      x-position: 1
      security:
        - {}
        - bearerAuth: []
      description: |
        音声認識ジョブを作成します。

        :::caution[v1（従来版）について]
        従来版のジョブ作成エンドポイントは `POST https://acp-api-async.amivoice.com/v1/recognitions` です。リクエスト・レスポンスの形式は v2 と同じです。v1 は今後停止される予定のため、ご利用中の方は v2 への移行を行ってください。ただし、v2 では現在、感情分析の機能を利用できません。感情分析を利用する場合は v1 をご利用ください。
        :::

        :::caution
        - 音声データ以外はクエリパラメータでもマルチパートでも送信することができます。クエリパラメータに d パラメータを設定するとリクエストラインの上限を超える可能性があるため、マルチパートで送信することを推奨します。
        - クエリパラメータとマルチパートの両方に同じパラメータが指定されている場合、クエリパラメータに設定した値が優先されます。
        :::

      requestBody:
        required: true
        content:
          multipart/form-data:
            encoding:
              a:
                contentType: application/octet-stream
            schema:
              type: object
              required:
                - d
                - a
              properties:
                u:
                  type: string
                  description: |
                    APIキー

                    マイページに表示されているAPI キー、もしくは、 [API キー発行 API](/amivoice-api/manual/issue-api-key-with-api) を用いて発行した API キーを指定してください。
                    API キーを`Authorization`ヘッダー（`Authorization: Bearer {APIキー}`）で送ることもできます。その場合、`u`は省略できます。`u`または`Authorization`ヘッダーのいずれかが必須です。
                d:
                  type: string
                  description: |
                    音声認識のリクエストパラメータ

                    key-value 形式のパラメータを、半角スペース区切りで指定します。

                    例:

                    ```text
                    <キー>=<値> <キー>=<値> <キー>=<値> ...
                    ```

                    スペースが含まれる`<値>`は URL エンコードしてください。以下の例では、`grammarFileNames`と`profileWords`の2つのパラメータを指定しています。`profileWords`には表記が "www"、読みが、"とりぷるだぶる"という単語をセットしています。

                    ```text
                    grammarFileNames=-a-general profileWords=www%20%E3%81%A8%E3%82%8A%E3%81%B7%E3%82%8B%E3%81%A0%E3%81%B6%E3%82%8B
                    ```

                    `d`パラメータに指定できるパラメータは以下の通りです。各パラメータの詳細は、マニュアルの[リクエストパラメータ](/amivoice-api/manual/request-parameters)を参照してください。

                    | パラメータ名 | 必須 |
                    | ------------ | :--: |
                    | [grammarFileNames](/amivoice-api/manual/request-parameters#grammarfilenames) | ● |
                    | [profileId](/amivoice-api/manual/request-parameters#profileid) | |
                    | [profileWords](/amivoice-api/manual/request-parameters#profilewords) | |
                    | [keepFillerToken](/amivoice-api/manual/request-parameters#keepfillertoken) | |
                    | [segmenterProperties](/amivoice-api/manual/request-parameters#segmenterproperties)（*1） | |
                    | [extension](/amivoice-api/manual/request-parameters#extension) | |
                    | [maxDecodingTime](/amivoice-api/manual/request-parameters#maxdecodingtime) | |
                    | [maxResponseTime](/amivoice-api/manual/request-parameters#maxresponsetime) | |
                    | [maxDecodingRate](/amivoice-api/manual/request-parameters#maxdecodingrate) | |
                    | [targetResponseTime](/amivoice-api/manual/request-parameters#targetresponsetime) | |
                    | [targetDecodingRate](/amivoice-api/manual/request-parameters#targetdecodingrate) | |
                    | [recognitionTimeout](/amivoice-api/manual/request-parameters#recognitiontimeout) | |
                    | [confidenceLevel](/amivoice-api/manual/request-parameters#confidencelevel) | |
                    | [loggingOptOut](/amivoice-api/manual/request-parameters#loggingoptout) | |
                    | [contentId](/amivoice-api/manual/request-parameters#contentid) | |
                    | [compatibleWithSync](/amivoice-api/manual/request-parameters#compatiblewithsync) | |
                    | [speakerDiarization](/amivoice-api/manual/request-parameters#speakerdiarization) | |
                    | [diarizationMinSpeaker](/amivoice-api/manual/request-parameters#diarizationminspeaker) | |
                    | [diarizationMaxSpeaker](/amivoice-api/manual/request-parameters#diarizationmaxspeaker) | |
                    | [sentimentAnalysis](/amivoice-api/manual/request-parameters#sentimentanalysis)（*2） | |

                    （*1）非同期 HTTP インタフェースでは、話者ダイアライゼーションに関するパラメータ（`useDiarizer`など）は使えません。

                    （*2）`sentimentAnalysis`は v1 のみで利用できます。
                  example: grammarFileNames=-a-general speakerDiarization=True
                c:
                  type: string
                  description: |
                    音声フォーマット文字列

                    RAW データ（PCM）を送信する場合のフォーマット名です。設定できる値は[音声フォーマット](/amivoice-api/manual/audio-format#request-parameters)を参照してください。
                a:
                  type: string
                  format: binary
                  example: test.wav
                  description: |
                    音声データバイナリ

                    音声のバイナリデータを設定します。このデータは必ず HTTP マルチパートの最終パートにする必要があります。送信可能な音声データについては、開発ガイドの[音声フォーマット](/amivoice-api/manual/audio-format#request-parameters)を参照して下さい。
      responses:
        "200":
          description: |
            成功時のレスポンスは JSON フォーマットで以下の値を持ちます。

            | キー | 説明 |
            |-----------|------------------------------|
            | sessionid | ユーザーの音声認識リクエストに対するジョブの ID。ジョブの状態の確認、結果の取得の際に使います。 |
            | text | 常に...を返します。 |

            失敗時のレスポンスは JSON フォーマットで `results`、`text`、`code`、`message` を持ちます。`code`、`message` については[レスポンスコードとメッセージ](/amivoice-api/manual/response-code-and-message)を参照してください。
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/CreateJobSuccess"
                  - $ref: "#/components/schemas/CreateJobFailure"
              examples:
                success:
                  summary: 成功時
                  value:
                    sessionid: "017ac8786c5b0a0504399999"
                    text: "..."
                failure:
                  summary: 失敗時
                  value:
                    results:
                      - tokens: []
                        tags: []
                        rulename: ""
                        text: ""
                    text: ""
                    code: "-"
                    message: "received illegal service authorization"

  /v2/recognitions/{session_id}:
    get:
      tags:
        - status
      summary: ジョブの状態の確認、結果の取得
      operationId: getRecognitionJob
      x-position: 2
      security:
        - bearerAuth: []
      description: |
        指定した音声認識ジョブの状態と結果を取得します。
      parameters:
        - name: session_id
          in: path
          required: true
          description: |
            対象ジョブのセッションID

            [ジョブの作成](/amivoice-api/reference/async-http/create-recognition-job) API を実行した際に、成功レスポンスとして返却される `sessionid` の値を指定します。
            この ID を指定することで、ジョブの進捗状態（queued、processing など）の確認や、完了後の音声認識結果の取得を行います。
          schema:
            type: string
      responses:
        "200":
          description: |
            音声認識リクエストの状態`status`と付随する情報を返します。`status`は以下の 5 つの値をとります。

            | status | 説明 |
            |------------|--------------------------------------------|
            | queued | ジョブがキューに登録された状態。 |
            | started | ジョブがキューから取り出されて、実行環境を用意している状態。 |
            | processing | ジョブが実行されている状態。 |
            | completed | 音声認識プロセスから結果が得られた状態。`code`が空文字、つまり音声認識に成功した場合、`segments`に結果が含まれます。 |
            | error | ジョブを実行しようとしたとき、もしくは、ジョブの実行中に何らかのエラーが発生した状態。`error_message` にエラーの詳細を保存します。 |

            queued、started、processing、completed、error の各状態で含まれる情報について以下の表に整理します。各状態のそれぞれの頭文字の欄（q, s, p, c, e）で、A となっているものは常に含まれます。O となっているものは、その情報があればレスポンスに含まれます。

            | キー | q | s | p | c | e | 説明 |
            |---------------|---|---|---|---|---|-------------------------------------|
            | status | A | A | A | A | A | ジョブの状態。queued、started、processing、completed、error の状態をとる。 |
            | audio_md5 | | | A | A | O | 受信した音声ファイルの MD5 チェックサムの値。 |
            | audio_size | | | A | A | O | 受信した音声ファイルのサイズ。 |
            | content_id | O | O | O | O | O | ユーザーがリクエスト時に設定した contentId の値。 |
            | service_id | A | A | A | A | | サービスID。 |
            | segments | | | | A | | 発話単位の音声認識結果。 |
            | utteranceid | | | | A | | 認識結果情報 ID。 |
            | text | | | | A | | 「発話区間の認識結果」の全てを結合した全体の認識結果テキスト。 |
            | code | | | | A | | 結果を表す 1 文字のコード。 |
            | message | | | | A | | エラー内容を表す文字列。 |
            | error_message | | | | | A | エラー内容を表す文字列 |

            status が completed のときには音声認識の結果を JSON 形式で返します。同期 HTTP インタフェースと異なり、認識結果が発話単位で`segments`の下に配置されます。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatus"
              examples:
                error:
                  summary: error（エラー）のレスポンスの例
                  value:
                    status: "error"
                    audio_md5: "40f59fe5fc7745c33b33af44be43f6ad"
                    audio_size: 306980
                    service_id: "{YOUR_SERVICE_ID}"
                    session_id: "017c25ec12c00a304474a999"
                    error_message: "ERROR: Failed to transcribe in recognition process - amineth_result=0, amineth_code='o', amineth_message='recognition result is rejected because confidence is below the threshold'"
        "401":
          description: |
            認証に失敗した場合に返されます。

            | エラーメッセージ | エラーの状況 |
            |---|---|
            | No authorization header | Authorization ヘッダが設定されていない |
            | Invalid authorization header format | Authorization ヘッダのフォーマットが不正 |
            | Failed to authorize for the API key | 指定された API キーによる認証が失敗 |
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobErrorResponse"
              example:
                errorCode: 401
                errorMessage: "No authorization header"
        "404":
          description: |
            指定された `session_id` のジョブが見つからない場合に返されます。

            | エラーメッセージ | エラーの状況 |
            |---|---|
            | Specified session_id is not found | 指定された `session_id` のジョブが見つからない |

            正しい`session_id`を指定しているにも関わらず、このエラーが起きる場合、以下のようなケースが考えられます。

            - データ保存期間を過ぎたとき
            - リクエスト時のユーザーと異なったユーザーがジョブの状態や結果を取得しようとしたとき
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobErrorResponse"
              example:
                errorCode: 404
                errorMessage: "Specified session_id is not found"
        "500":
          description: |
            内部エラーの場合に返されます。

            | エラーメッセージ | エラーの状況 |
            |---|---|
            | - | 内部エラー。[こちら](https://acp.amivoice.com/inquiry_tech/)にご連絡下さい。 |
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobErrorResponse"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API キーを `Authorization` ヘッダー（`Authorization: Bearer {APIキー}`）に指定します。ジョブの作成では、リクエストパラメータ `u`（`u={APIキー}`）で指定することもできます。
  schemas:
    CreateJobSuccess:
      type: object
      title: 成功時
      properties:
        sessionid:
          type: string
          description: ユーザーの音声認識リクエストに対するジョブの ID。
        text:
          type: string
          description: 常に...を返します。
    CreateJobFailure:
      type: object
      title: 失敗時
      properties:
        results:
          type: array
          description: 配列（要素 1 個）
          items:
            type: object
            properties:
              tokens:
                type: array
                description: 配列（空）
                items:
                  type: object
              tags:
                type: array
                description: 配列（空）
                items:
                  type: string
              rulename:
                type: string
                description: 文字列（空）
              text:
                type: string
                description: 文字列（空）
        text:
          type: string
          description: 文字列（空）
        code:
          type: string
          description: 結果を表す 1 文字のコード。[レスポンスコードとメッセージ](/amivoice-api/manual/response-code-and-message)を参照してください。
        message:
          type: string
          description: エラー内容を表す文字列。[レスポンスコードとメッセージ](/amivoice-api/manual/response-code-and-message)を参照してください。
    JobStatus:
      type: object
      title: ジョブの状態
      properties:
        status:
          type: string
          enum:
            - queued
            - started
            - processing
            - completed
            - error
          description: ジョブの状態。
        audio_md5:
          type: string
          description: 受信した音声ファイルの MD5 チェックサムの値。
        audio_size:
          type: integer
          description: 受信した音声ファイルのサイズ。
        content_id:
          type: string
          description: ユーザーがリクエスト時に設定した contentId の値。
        service_id:
          type: string
          description: サービスID。
        session_id:
          type: string
          description: ジョブの ID。
        segments:
          type: array
          description: 発話単位の音声認識結果。status が completed のときのみ含まれます。
          items:
            $ref: "#/components/schemas/Segment"
        utteranceid:
          type: string
          description: 認識結果情報 ID。
        text:
          type: string
          description: 「発話区間の認識結果」の全てを結合した全体の認識結果テキスト。
        code:
          type: string
          description: 結果を表す 1 文字のコード。[レスポンスコードとメッセージ](/amivoice-api/manual/response-code-and-message)を参照してください。
        message:
          type: string
          description: エラー内容を表す文字列。[レスポンスコードとメッセージ](/amivoice-api/manual/response-code-and-message)を参照してください。
        error_message:
          type: string
          description: エラー内容を表す文字列。status が error のとき含まれます。
    Segment:
      type: object
      title: 発話単位の認識結果
      properties:
        results:
          type: array
          description: 「発話区間の認識結果」の配列
          items:
            type: object
            properties:
              confidence:
                type: number
                description: 信頼度(0 ～ 1 の値。 0:信頼度低, 1:信頼度高)
              starttime:
                type: integer
                description: 発話開始時間 （音声データの先頭が 0）
              endtime:
                type: integer
                description: 発話終了時間 （音声データの先頭が 0）
              tags:
                type: array
                description: 未使用（空配列）
                items:
                  type: string
              rulename:
                type: string
                description: 未使用（空文字）
              text:
                type: string
                description: 認識結果テキスト
              tokens:
                type: array
                description: 認識結果テキストの形態素の配列
                items:
                  type: object
                  properties:
                    written:
                      type: string
                      description: 形態素（単語）の表記
                    confidence:
                      type: number
                      description: 形態素の信頼度（認識結果の尤度）
                    starttime:
                      type: integer
                      description: 形態素の開始時間 （音声データの先頭が 0）
                    endtime:
                      type: integer
                      description: 形態素の終了時間（音声データの先頭が 0）
                    spoken:
                      type: string
                      description: 形態素の読み
                    label:
                      type: string
                      description: 話者ラベル（speaker0, speaker1, ...）リクエスト時に speakerDiarization=True が指定されたときのみ、結果に含まれます。
        text:
          type: string
          description: 発話区間の認識結果テキスト
    JobErrorResponse:
      type: object
      title: エラーレスポンス
      properties:
        errorCode:
          type: integer
          description: レスポンスコード。
        errorMessage:
          type: string
          description: エラーメッセージ。
