openapi: 3.0.3
info:
  title: Synchronous HTTP Interface
  version: v1
  description: |
    The Synchronous HTTP interface is a Web API that allows easy conversion of short audio files to text.

    ## Endpoint

    This is the endpoint for requesting speech recognition. The endpoint differs depending on whether logging or no logging. For details, please see [Logging](/amivoice-api/manual/log-retention).

    ```text
    POST https://acp-api.amivoice.com/v1/recognize　　　(logging)
    POST https://acp-api.amivoice.com/v1/nolog/recognize (no logging)
    ```

servers:
  - url: https://acp-api.amivoice.com/v1
    description: Logging
  - url: https://acp-api.amivoice.com/v1/nolog
    description: No logging

tags:
  - name: recognize
    x-displayName: Speech Recognition Request

paths:
  /recognize:
    post:
      tags:
        - recognize
      summary: Speech Recognition Request
      operationId: recognize
      security:
        - {}
        - bearerAuth: []
      description: |
        Sends audio data and recognition parameters, and receives recognition results synchronously.

        :::caution
        - Parameters other than audio data can be sent either as query parameters or multipart. Setting the d parameter as a query parameter may exceed the request line limit, so sending as multipart is recommended.
        - If the same parameter is specified in both query parameters and multipart, the value set in the query parameter takes precedence.
        :::
      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 Key

                    Specify the API key displayed on MyPage, or the API key issued using the [API Key Issuance API](/amivoice-api/manual/issue-api-key-with-api).
                    You can also send the API key in the `Authorization` header (`Authorization: Bearer {API_KEY}`). In that case, `u` can be omitted. Either `u` or the `Authorization` header is required.
                d:
                  type: string
                  description: |
                    Speech recognition request parameters

                    Key-value format parameters are specified separated by half-width spaces.

                    Example:

                    ```text
                    <key>=<value> <key>=<value> <key>=<value> ...
                    ```

                    URL encode `<value>` if it contains spaces. In the following example, two parameters, `grammarFileNames` and `profileWords`, are specified. For `profileWords`, a word with written "www" and spoken "とりぷるだぶる" is set.

                    ```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
                    ```

                    The following parameters can be specified in the `d` parameter. For details of each parameter, see [Request Parameters](/amivoice-api/manual/request-parameters) in the manual.

                    | Parameter Name | Required |
                    | ------------ | :--: |
                    | [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)（*） |  |

                    （*）Available only with the `-a-rule-input-private` engine.
                  example: grammarFileNames=-a-general keepFillerToken=1
                c:
                  type: string
                  description: |
                    Audio format string

                    Format name when sending RAW data (PCM). For settable values, please see [Audio Format](/amivoice-api/manual/audio-format#request-parameters).
                a:
                  type: string
                  format: binary
                  example: test.wav
                  description: |
                    Audio data binary

                    Set the binary data of the audio. This data must be in the final part of the HTTP multipart. For sendable audio data, please see [Audio Format](/amivoice-api/manual/audio-format#request-parameters) in the development guide.
      responses:
        "200":
          description: |
            Recognition result in JSON format

            On successful recognition, `code == ""` and `message == ""` and `text != ""`.
            On failed recognition, `code != ""` and `message != ""` and `text == ""`.

            ### List of codes and messages

            When values are set in `code` and `message` included in the response, it indicates that the request has failed. For details of each code and how to handle it, see [Response Codes and Messages](/amivoice-api/manual/response-code-and-message#table) in the manual.

            | 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: |
        Specify the API key either in the `Authorization` header (`Authorization: Bearer {API_KEY}`) or in the request parameter `u` (`u={API_KEY}`, sent as multipart or a query parameter).
  schemas:
    RecognitionResult:
      type: object
      title: Recognition Result
      properties:
        results:
          type: array
          description: Array of "recognition results for speech segments" *The array always contains only 1 element.
          items:
            $ref: "#/components/schemas/UtteranceResult"
        utteranceid:
          type: string
          description: |
            Recognition result information ID.

            For the WebSocket speech recognition protocol, it is the ID assigned to the recognition result information for each speech segment. For the HTTP speech recognition protocol, it is the ID assigned to the recognition result information for the entire audio data uploaded in one session (which may include multiple speech segments).
        text:
          type: string
          description: Overall recognition result text combining all "recognition results for speech segments"
        code:
          type: string
          description: 1-character code representing the result. It is an empty string on successful recognition.
        message:
          type: string
          description: String representing the error content. It is an empty string on successful recognition.
    UtteranceResult:
      type: object
      title: Recognition Result for Speech Segment
      properties:
        confidence:
          type: number
          description: "Confidence (value from 0 to 1. 0: low confidence, 1: high confidence)"
        starttime:
          type: integer
          description: Utterance start time (0 is the beginning of the audio data)
        endtime:
          type: integer
          description: Utterance end time (0 is the beginning of the audio data)
        tags:
          type: array
          description: Unused (empty array)
          items:
            type: string
        rulename:
          type: string
          description: Unused (empty string)
        text:
          type: string
          description: Recognition result text
        tokens:
          type: array
          description: Array of morphemes of the recognition result text
          items:
            $ref: "#/components/schemas/Token"
    Token:
      type: object
      title: Morpheme
      properties:
        written:
          type: string
          description: Written form of the morpheme (word)
        confidence:
          type: number
          description: Confidence of the morpheme (likelihood of recognition result)
        starttime:
          type: integer
          description: Start time of the morpheme (0 is the beginning of the audio data)
        endtime:
          type: integer
          description: End time of the morpheme (0 is the beginning of the audio data)
        spoken:
          type: string
          description: |
            Spoken form of the morpheme.

            The spoken in Japanese engine recognition results is in hiragana.
            The spoken in English engine recognition results is not a reading (please ignore it).
            The spoken in Chinese engine recognition results is pinyin.
