openapi: 3.0.3
info:
  title: ユーザー辞書登録
  version: v1
  description: |
    ユーザー辞書の登録単語のインポート、エクスポートを行うAPIです。

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

tags:
  - name: profilewords
    x-displayName: ユーザー辞書登録

paths:
  /profilewords/{dgn}/{pid}:
    get:
      tags:
        - profilewords
      summary: ユーザー辞書の登録単語の取得
      operationId: getProfileWords
      x-position: 1
      security:
        - bearerAuth: []
      description: |
        登録した単語の一覧をJSON形式で取得することができます。
      parameters:
        - $ref: "#/components/parameters/dgn"
        - $ref: "#/components/parameters/pid"
        - $ref: "#/components/parameters/adf"
      responses:
        "200":
          description: 登録した単語の一覧をJSON形式で返します。
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/HybridProfileWords"
                  - $ref: "#/components/schemas/E2EProfileWords"
        "401":
          $ref: "#/components/responses/Err401"
        "404":
          $ref: "#/components/responses/Err404"
        "500":
          $ref: "#/components/responses/Err500"
    post:
      tags:
        - profilewords
      summary: ユーザー辞書の単語の登録
      operationId: setProfileWords
      x-position: 3
      security:
        - bearerAuth: []
      description: |
        指定した音声認識エンジンとプロファイルIDのユーザー辞書の単語を置き換えることができます。

        リクエストボディの形式は、接続するエンジンによって異なります。

        - **ハイブリッドエンジン**: `written`（表記）と `spoken`（読み）で単語を登録します。`classname`（クラス名）は省略可能です。
        - **End to End エンジン**: `written`（表記）を `alternativewritten`（代替表記）に置き換えて単語を強調します。`biasing`（単語強調度、0 ～ 1、既定は 0.5）で強調の強さを指定します。

        End to End エンジンでは、同一の表記に対して複数の代替表記を指定することも可能です。この時、同一の表記の単語に対しては同一の単語強調度が適用されます。もしリクエスト時に同一の表記に対して異なる単語強調度を指定した場合、リクエスト中に一番最初に登場するものの単語強調度の値が採用されます。例えば、同一の表記「AMI」に単語強調度 0.8 と指定なしの 2 件を指定した場合、一番最初に登場するものに適用される値「0.8」が統一して適用されます。
      parameters:
        - $ref: "#/components/parameters/dgn"
        - $ref: "#/components/parameters/pid"
        - $ref: "#/components/parameters/adf"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/HybridProfileWords"
                - $ref: "#/components/schemas/E2EProfileWordsRequest"
            examples:
              hybrid:
                summary: ハイブリッドエンジンの場合
                value:
                  profilewords:
                    - written: "AMI"
                      spoken: "あみ"
                    - written: "AOI"
                      spoken: "あおい"
                    - written: "躑躅森"
                      spoken: "つつじもり"
                      classname: "名前"
              e2e:
                summary: End to End エンジンの場合
                value:
                  profilewords:
                    - written: "AMI"
                      alternativewritten: "アドバンストメディア"
                      biasing: 0.8
                    - written: "AMI"
                      alternativewritten: "あみ"
                    - written: "AOI"
                      alternativewritten: "あおい"
      responses:
        "200":
          description: |
            登録した単語の一覧をJSON形式で返します。
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/HybridProfileWords"
                  - $ref: "#/components/schemas/E2EProfileWords"
              examples:
                hybrid:
                  summary: ハイブリッドエンジンの場合
                  value:
                    profilewords:
                      - written: "AMI"
                        spoken: "あみ"
                      - written: "AOI"
                        spoken: "あおい"
                      - written: "躑躅森"
                        spoken: "つつじもり"
                        classname: "名前"
                e2e:
                  summary: End to End エンジンの場合
                  value:
                    profilewords:
                      - written: "AMI"
                        alternativewritten: "あみ"
                        biasing: 0.8
                      - written: "AMI"
                        alternativewritten: "アドバンストメディア"
                        biasing: 0.8
                      - written: "AOI"
                        alternativewritten: "あおい"
        "400":
          $ref: "#/components/responses/Err400"
        "401":
          $ref: "#/components/responses/Err401"
        "404":
          $ref: "#/components/responses/Err404"
        "422":
          $ref: "#/components/responses/Err422"
        "500":
          $ref: "#/components/responses/Err500"

  /profilewords/{dgn}/:
    get:
      tags:
        - profilewords
      summary: プロファイル一覧の取得
      operationId: getProfiles
      x-position: 2
      security:
        - bearerAuth: []
      description: |
        プロファイルの一覧をJSON形式で取得することができます。
      parameters:
        - $ref: "#/components/parameters/dgn"
        - $ref: "#/components/parameters/adf"
      responses:
        "200":
          description: プロファイルの一覧をJSON形式で返します。
          content:
            application/json:
              schema:
                type: object
                description: プロファイルの一覧
        "401":
          $ref: "#/components/responses/Err401"
        "404":
          $ref: "#/components/responses/Err404"
        "500":
          $ref: "#/components/responses/Err500"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API キーはAuthorizationヘッダーに指定してください。

        ```text
        Authorization: Bearer {APIキー}
        ```
  parameters:
    dgn:
      name: dgn
      in: path
      required: true
      description: |
        接続エンジン名

        `-a-general`などの接続エンジン名を指定します。指定できる値は[音声認識エンジンの一覧](/amivoice-api/manual/engines#list)を参照してください。パスパラメータとして設定します。
      schema:
        type: string
    pid:
      name: pid
      in: path
      required: true
      description: |
        プロファイルID

        任意の文字列。パスパラメータとして設定します。
      schema:
        type: string
    adf:
      name: adf
      in: query
      required: false
      description: |
        音声データ形式

        `16k`または`8k`のいずれかを指定します。指定しない場合は`16k`となります。[音声認識エンジン](/amivoice-api/manual/engines#list)によっては複数のサンプリングレートに対応していますが、ユーザー辞書は`8k`、`16k`でそれぞれ異なるエンジンとしてとりあつかうためにどちらかを指定する必要があります。クエリパラメータとして設定します。
        ただし、End to End エンジンの場合は`16k`も`8k`も同じエンジンとしてとりあつかうため、指定不要です。
      schema:
        type: string
        enum:
          - 16k
          - 8k
        default: 16k
  responses:
    Err400:
      description: |
        リクエストボディが正しくない時に返されます。

        | レスポンスボディ | エラーの状況 |
        |---|---|
        | `{"code":"-","message":"missing request body"}` | POST メソッドでリクエストされたのにリクエストボディが指定されていない時 |
        | `{"code":"-","message":"invalid request body (<optionalMessage>)"}` | リクエストボディが JSON として正しくない時 |
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: "-"
            message: "missing request body"
    Err401:
      description: |
        API キー（サービス認証キー文字列）の認証に失敗した時に返されます。

        | レスポンスボディ | エラーの状況 |
        |---|---|
        | `{"code":"-","message":"can't verify service authorization"}` | API キーの認証に失敗した時 |
        | `{"code":"-","message":"service authorization has expired: <expirationTime> (<expiresIn>)"}` | API キーの有効期限が切れている時 |
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: "-"
            message: "can't verify service authorization"
    Err404:
      description: |
        パスパラメータが指定されていない時に返されます。

        | レスポンスボディ | エラーの状況 |
        |---|---|
        | `{"code":"?","message":"missing dictation grammar file name"}` | 接続エンジン名 `<dgn>` が指定されていない時 |
        | `{"code":"?","message":"missing profile id"}` | プロファイル ID `<pid>` が指定されていない時 |
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: "?"
            message: "missing dictation grammar file name"
    Err422:
      description: |
        リクエストボディに指定された JSON が期待した形式でない時に返されます。

        | レスポンスボディ | エラーの状況 |
        |---|---|
        | `{"code":"?","message":"missing profile words"}` | JSON が期待した形式でない時 |
        | `{"code":"?","message":"invalid written: <written>"}` | 表記が正しくない時 |
        | `{"code":"?","message":"invalid spoken: <spoken>"}` | 読みが正しくない時 |
        | `{"code":"?","message":"invalid class name: <className>"}` | 単語クラスが正しくない時 |
        | `{"code":"?","message":"invalid alternative written: <alternativeWritten>"}` | 代替表記が正しくない時 |
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: "?"
            message: "missing profile words"
    Err500:
      description: |
        想定外の例外が発生した時に返されます。

        | レスポンスボディ | エラーの状況 |
        |---|---|
        | `{"code":"?","message":"unexpected exception occurred (<optionalMessage>)"}` | 想定外の例外が発生した時 |
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: "?"
            message: "unexpected exception occurred (<optionalMessage>)"
  schemas:
    HybridProfileWords:
      type: object
      title: ハイブリッドエンジンの場合
      properties:
        profilewords:
          type: array
          description: 単語登録情報。登録したい単語を配列形式で指定します
          items:
            type: object
            required:
              - written
              - spoken
            properties:
              written:
                type: string
                description: 表記。単語の表記を指定します
              spoken:
                type: string
                description: 読み。単語の読みを指定します
              classname:
                type: string
                description: クラス名。クラス名を指定します。設定しないときは省略可能です。
    E2EProfileWordsRequest:
      type: object
      title: End to End エンジンの場合
      description: |
        同一の表記に対して複数の代替表記を指定することも可能です。この時、同一の表記の単語に対しては同一の単語強調度が適用されます。もしリクエスト時に同一の表記に対して異なる単語強調度を指定した場合、リクエスト中に一番最初に登場するものの単語強調度の値が採用されます。例えば、同一の表記「AMI」に単語強調度 0.8 と指定なしの 2 件を指定した場合、一番最初に登場するものに適用される値「0.8」が統一して適用されます。
      properties:
        profilewords:
          type: array
          description: 単語強調情報。強調したい単語を配列形式で指定します
          items:
            type: object
            required:
              - written
            properties:
              written:
                type: string
                description: 表記。単語の表記を指定します
              alternativewritten:
                type: string
                description: 代替表記。「表記」に置き換える単語の表記を指定します
              biasing:
                type: number
                minimum: 0
                maximum: 1
                default: 0.5
                description: |
                  単語強調度。単語を強調する強さを指定します。0 ～ 1 の値が指定可能で、0 は強調しないことを、1は全体的な認識率を犠牲にしながらも強めに単語強調をすることを表します。何も指定しない場合、デフォルトで 0.5 になります
    E2EProfileWords:
      type: object
      title: End to End エンジンの場合
      properties:
        profilewords:
          type: array
          description: 単語強調情報。強調する単語が配列形式で得られます
          items:
            type: object
            properties:
              written:
                type: string
                description: 表記。単語の表記が得られます
              alternativewritten:
                type: string
                description: 代替表記。「表記」に置き換える単語の表記が得られます
              biasing:
                type: number
                description: 単語強調度。単語を強調する強さが得られます。値がデフォルトの 0.5 であるときは省略されます
    ErrorResponse:
      type: object
      title: エラーレスポンス
      properties:
        code:
          type: string
          description: エラーコード。エラーの種別を示すコード
        message:
          type: string
          description: エラーメッセージ。エラー内容の詳細を説明するテキスト
