openapi: 3.0.3
info:
  title: 同步 HTTP 接口
  version: v1
  description: |
    同步 HTTP 接口是一个可以轻松将短音频文件转换为文本的 Web API。

    ## endpoint

    用于请求语音识别的 endpoint。根据是否保存日志，endpoint 不同。详情请参考[日志保存](/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
        - 除音频数据外，可以通过查询参数或 multipart 发送。由于在查询参数中设置 d 参数可能会超出请求行的上限，因此建议通过 multipart 发送。
        - 如果在查询参数和 multipart 中都指定了相同的参数，则优先使用查询参数中设置的值。
        :::
      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

                    请指定在 MyPage 中显示的 API key，或[使用 API Key 发行 API 的方法](/amivoice-api/manual/issue-api-key-with-api)发行的 API key。
                    也可以通过`Authorization` header（`Authorization: Bearer {API_KEY}`）发送 API key。此时可以省略`u`。`u`或`Authorization` header 二者必须指定其一。
                d:
                  type: string
                  description: |
                    语音识别请求参数

                    以半角空格分隔指定 key-value 格式的参数。

                    例:

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

                    包含空格的`<value>`请进行 URL 编码。以下示例指定了`grammarFileNames`和`profileWords`两个参数。在`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 multipart 的最后一个部分。关于可发送的音频数据，请参考开发指南中的[音频格式](/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 key 通过 `Authorization` header（`Authorization: Bearer {API_KEY}`）或请求参数 `u`（`u={API_KEY}`，以 multipart 或查询参数发送）之一指定。
  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）。
