openapi: 3.0.3
info:
  title: 同期 HTTP インタフェース
  version: v1
  description: |
    同期 HTTP インタフェース は短い音声ファイルを簡単にテキスト化できる Web API です。

    ## エンドポイント

    音声認識をリクエストするエンドポイントです。ログ保存あり・なしで、エンドポイントが異なります。詳細は、[ログ保存](/amivoice-api/manual/log-retention)を参照してください。

    ```text
    POST https://acp-api.amivoice.com/v1/recognize　　　（ログ保存あり）
    POST https://acp-api.amivoice.com/v1/nolog/recognize （ログ保存なし）
    ```

servers:
  - url: https://acp-api.amivoice.com/v1
    description: ログ保存あり
  - url: https://acp-api.amivoice.com/v1/nolog
    description: ログ保存なし

tags:
  - name: recognize
    x-displayName: 音声認識リクエスト

paths:
  /recognize:
    post:
      tags:
        - recognize
      summary: 音声認識リクエスト
      operationId: recognize
      security:
        - {}
        - bearerAuth: []
      description: |
        音声データと認識用パラメータを送信し、認識結果を同期的に受け取ります。

        :::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) | |
                    | [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) | |
                    | [completeTimeout](/amivoice-api/manual/request-parameters#completetimeout)（*） | |
                    | [wildcardModelPenalty](/amivoice-api/manual/request-parameters#wildcardmodelpenalty)（*） | |

                    （*）「音声入力\_ルール」エンジン（`-a-rule-input-private`）でのみ利用可能です。
                  example: grammarFileNames=-a-general keepFillerToken=1
                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 形式の認識結果

            認識成功時は `code == ""` かつ `message == ""` かつ `text != ""` となります。
            認識失敗時は `code != ""` かつ `message != ""` かつ `text == ""` となります。

            ### code と message の一覧

            レスポンスに含まれる`code`と`message`に値が設定されているとリクエストに失敗したことがわかります。各コードの詳しい説明と対処方法は、マニュアルの[レスポンスコードとメッセージ](/amivoice-api/manual/response-code-and-message#table)を参照してください。

            | code | message |
            | :---: | ------- |
            | + | received unsupported audio format |
            | - | received illegal service authorization |
            | ! | failed to connect to recognizer server |
            | \> | failed to send audio data to recognizer server |
            | \< | failed to receive recognition result from recognizer server |
            | # | received invalid recognition result from recognizer server |
            | $ | timeout occurred while receiving audio data from client |
            | % | received too large audio data from client |
            | o | recognition result is rejected because confidence is below the threshold |
            | b | recognition result is rejected because recognizer server is busy |
            | x | recognition result is rejected because grammar files are not loaded |
            | c | recognition result is rejected because the recognition process is cancelled |
            | ? | recognition result is rejected because fatal error occurred in recognizer server |
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecognitionResult"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API キーを、`Authorization` ヘッダー（`Authorization: Bearer {APIキー}`）またはリクエストパラメータ `u`（`u={APIキー}`、マルチパートかクエリで送信）のいずれかで指定します。
  schemas:
    RecognitionResult:
      type: object
      title: 認識結果
      properties:
        results:
          type: array
          description: 「発話区間の認識結果」の配列 ※配列形式ですが要素数は常に 1 つです。
          items:
            $ref: "#/components/schemas/UtteranceResult"
        utteranceid:
          type: string
          description: |
            認識結果情報 ID。

            WebSocket 音声認識プロトコルの場合は、発話区間毎の認識結果情報に付与された ID となります。HTTP 音声認識プロトコルの場合は、1 セッションでアップロードされた（複数の発話区間を含む可能性のある）音声データ全体の認識結果情報に付与された ID となります。
        text:
          type: string
          description: 「発話区間の認識結果」の全てを結合した全体の認識結果テキスト
        code:
          type: string
          description: 結果を表す 1 文字のコード。認識成功時は空文字列です。
        message:
          type: string
          description: エラー内容を表す文字列。認識成功時は空文字列です。
    UtteranceResult:
      type: object
      title: 発話区間の認識結果
      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:
            $ref: "#/components/schemas/Token"
    Token:
      type: object
      title: 形態素
      properties:
        written:
          type: string
          description: 形態素（単語）の表記
        confidence:
          type: number
          description: 形態素の信頼度（認識結果の尤度）
        starttime:
          type: integer
          description: 形態素の開始時間 （音声データの先頭が 0）
        endtime:
          type: integer
          description: 形態素の終了時間（音声データの先頭が 0）
        spoken:
          type: string
          description: |
            形態素の読み。

            日本語エンジンの認識結果の spoken は平仮名です。
            英語エンジンの認識結果の spoken は読みではありません（無視してください）。
            中国語エンジンの認識結果の spoken はピンイン（pinyin）です。
