見出し画像

Aivis Cloud APIでユーザー辞書を作成・利用する方法｜APIリクエスト例付き

Aivis Project

この記事はこんな方に向けた内容です。
・Aivis Cloud APIのユーザー辞書をAPIから作成したい方
・自社サービス名や商品名の読み方をシステムから登録したい方
・人名・地名・専門用語の読み方をAPIで管理したい方
・案件やブランド、顧客ごとに異なる辞書を利用したい開発者の方
・AivisSpeechで作った辞書をAivis Cloud APIへ取り込みたい方

⚠️ 本記事の内容は2026年8月時点のものです。 最新の仕様については、Aivis Cloud API ドキュメントをご確認ください。

皆さんこんにちは。
感情豊かな音声合成技術を誰もがかんたんに活用できる未来を目指す、Aivis Project です✨

「自社サービスの名前が、意図とは違う読み方になってしまう」
「ユーザーごとに異なる人名や専門用語を登録したい」
「複数の案件で使用する辞書を、システムから自動的に管理したい」

音声合成をサービスや業務システムへ組み込むと、このようなケースでユーザー辞書の管理が必要になることがあります。

Aivis Cloud APIでは、管理ダッシュボードからユーザー辞書を作成・編集できます。

一方で、SaaSやWebサービスへ音声合成機能を組み込む場合は、ダッシュボード上で手作業を行うだけでなく、ユーザー辞書の作成・更新・削除をAPIから自動化したいケースもあります。

たとえば、顧客やエンドユーザーごとに異なる辞書を用意する場合、APIから辞書を作成できれば、サービス側のユーザー登録や設定変更と連動して辞書を管理できます。

この記事では、Aivis Cloud APIのユーザー辞書をAPIから作成・更新する方法を中心に、単語の読み方とアクセントの指定、音声合成時の適用、AivisSpeechとの辞書データ共有まで、順番に分かりやすく解説します📚

なお、コードを書かずにユーザー辞書を設定したい場合は、Aivis Cloud APIダッシュボードの「ユーザー辞書」画面をご利用ください。


【結論】ユーザー辞書APIでできること

Aivis Cloud APIのユーザー辞書APIを利用すると、主に次の操作をシステムから行えます。

・ユーザー辞書を新しく作成する
・既存のユーザー辞書を取得・更新する
・登録する単語の読み方やアクセントを指定する
・単語の品詞や優先度を設定する
・顧客やエンドユーザーごとに辞書を作成する
・音声合成リクエストごとに使用する辞書を切り替える
・AivisSpeech Engine互換の辞書をインポートする
・クラウド上の辞書をAivisSpeech Engine互換形式でエクスポートする
・不要になったユーザー辞書を削除する

⚠️ ユーザー辞書を音声合成に適用するには、ユーザー辞書の作成と、音声合成リクエストでの辞書UUID指定の両方が必要です。

辞書を作成しただけでは、自動的にすべての音声合成へ適用されません。

それでは、ユーザー辞書APIの使い方を見ていきましょう✨

ユーザー辞書APIを利用する前の準備

ユーザー辞書APIを利用するには、Aivis Cloud APIのAPIキーまたはJWTアクセストークンが必要です。
一般的な外部システムからの利用では、APIキーを使用します。

APIキーは、Aivis Cloud APIのダッシュボードから発行できます。
APIリクエスト時は、次の形式でAuthorizationヘッダーへ設定してください。

Authorization: Bearer APIキー

⚠️APIキーは第三者に公開せず、ソースコードへ直接書き込まないようにしてください。
環境変数などを利用して安全に管理することをおすすめします。

また、ユーザー辞書を新しく作成するときは、辞書を識別するUUIDをクライアント側で生成します。

辞書に登録する単語にも、それぞれ別のUUIDが必要です。

なお、Aivis Cloud APIダッシュボードからユーザー辞書を作成する場合、利用者がUUIDを生成する必要はありません。
本記事では、ユーザー辞書をAPIから直接作成・管理する場合の手順を解説しています。

【手順1】ユーザー辞書を作成する

ユーザー辞書の作成と更新には、次のエンドポイントを使用します。

PUT /v1/user-dictionaries/{user_dictionary_uuid}

作成専用のPOSTエンドポイントはありません。

このPUTエンドポイントは、辞書の新規作成と更新を兼ねています。

・存在しない辞書UUIDを指定すると、新しいユーザー辞書を作成する
・既存の辞書UUIDを指定すると、その辞書の内容を完全に置き換える

新規作成時の辞書UUIDは、サーバーから払い出されるのではなく、クライアント側で事前に生成して指定します。

リクエストは、次のようなJSON形式です。

{
  "name": "自社用語辞書",
  "description": "サービス名・人名・専門用語",
  "word_properties": [
    {
      "uuid": "00000000-0000-4000-8000-000000000001",
      "surface": ["新田", "真剣佑"],
      "pronunciation": ["アラタ", "マッケンユウ"],
      "accent_type": [1, 3],
      "word_type": "PERSON_NAME",
      "priority": 5
    }
  ]
}

nameは最大100文字、descriptionは最大500文字です。どちらも省略でき、省略時は空文字列が設定されます。

word_propertiesには、辞書へ登録する単語の一覧を指定します。この項目は必須です。

⚠️ PUTは既存の内容への追加ではなく、辞書全体の完全置き換えです。

既存の単語を残したまま新しい単語を追加したい場合は、現在の辞書をGETで取得し、取得した内容に新しい単語を加えてからPUTで送り返してください。

なお、word_propertiesに空の配列を指定すると、辞書に登録されているすべての単語が削除されます。

{
  "name": "自社用語辞書",
  "description": "",
  "word_properties": []
}

辞書そのものと関連リソースを削除したい場合は、後述するDELETEエンドポイントを使用します。

【手順2】単語の指定方法を理解する

ユーザー辞書へ単語を登録するときは、主に次の項目を指定します。

・uuid
・surface
・pronunciation
・accent_type
・word_type
・priority

ここがユーザー辞書を設定するうえで、最も重要なポイントです。
項目ごとに見ていきましょう📚

uuid：単語を識別するUUID

uuidには、辞書へ登録する単語を識別するUUIDを指定します。

辞書自体のUUIDとは別に、単語ごとにもUUIDが必要です。

新しい単語を登録するときは、クライアント側で生成したUUIDを指定します。同じ単語UUIDを使用してPUTすると、そのUUIDに対応する単語情報が上書きされます。

surface：読み方を固定したい表記

surfaceには、読み方を固定したい単語の表記を指定します。

リクエスト時は、実際の文章に登場する表記をそのまま入力します。

"surface": ["AivisSpeech"]

複数のアクセント句に分ける場合は、次のように配列の要素を分けます。

"surface": ["新田", "真剣佑"]

⚠️ surfaceに指定した表記は、ユーザー辞書での処理に適した形式へ正規化されて返ります。
英数字が全角に変換されたり、表記によってはカタカナに変換されたりする場合があります。

たとえば、ipadと登録した場合、レスポンスではｉｐａｄのように全角へ変換されることがあります。リクエスト時とレスポンス時で見た目が変わっても、異常ではありません。

また、レスポンスにはnormalized_surfaceという項目が含まれることがあります。

normalized_surfaceは、英単語からカタカナへの変換など、テキスト正規化後の表記を確認するためのレスポンス専用項目です。リクエストに含めても無視されます。

pronunciation：カタカナで指定する発音

pronunciationには、単語の発音をカタカナで指定します。

"pronunciation": ["タンタンメン"]

複数のアクセント句に分ける場合は、それぞれの句に対応する発音を指定します。

"pronunciation": ["アラタ", "マッケンユウ"]

surface、pronunciation、accent_typeは、アクセント句ごとに1つずつ指定します。

例えば、surfaceを2つのアクセント句に分けた場合は、pronunciationとaccent_typeも2要素にそろえる必要があります。

{
  "surface": ["新田", "真剣佑"],
  "pronunciation": ["アラタ", "マッケンユウ"],
  "accent_type": [1, 3]
}

要素数が一致していない場合は、正しく登録できません。

accent_type：東京式アクセントを指定する

accent_typeには、東京式アクセントにおいて、音の高さが下がる直前のモーラ位置を1始まりで指定します。

・0：平板型。単語内では音が下がらない
・1：1モーラ目のあとで下がる頭高型
・2：2モーラ目のあとで下がる
・3：3モーラ目のあとで下がる

モーラとは、日本語の音の長さを数える単位です。

基本的には、かな1文字分の音が1モーラに相当します。ただし、「キャ」「シュ」「チョ」のような拗音は、2文字で1モーラです。「ッ」「ン」「ー」は、それぞれ1モーラとして数えます。

例えば、公式APIドキュメントで示されている「新田 真剣佑」の例では、次のように指定します。

{
  "surface": ["新田", "真剣佑"],
  "pronunciation": ["アラタ", "マッケンユウ"],
  "accent_type": [1, 3]
}

読み方が合っているのに不自然に聞こえる場合は、accent_typeを見直してみてください。

発音そのものが正しくても、アクセント型がずれていると、別の単語のように聞こえることがあります⚠️

word_type：単語の品詞を指定する

word_typeには、登録する単語の品詞を指定します。

現在は、次の10種類から選択できます。

・PROPER_NOUN：固有名詞
・LOCATION_NAME：地名
・ORGANIZATION_NAME：組織名・施設名
・PERSON_NAME：人名
・PERSON_FAMILY_NAME：人名の姓
・PERSON_GIVEN_NAME：人名の名
・COMMON_NOUN：普通名詞
・VERB：動詞
・ADJECTIVE：形容詞
・SUFFIX：語尾

未指定の場合は、PROPER_NOUNが設定されます。

社名や団体名ならORGANIZATION_NAME、担当者名ならPERSON_NAMEというように、単語の実態に合った品詞を指定することで、前後の言葉とのつながりがより自然になります✨

priority：辞書を適用する優先度

priorityには、単語の優先度を0〜10の範囲で指定します。

数値が大きいほど、辞書適用時に優先して使用されます。未指定時は5が設定されます。

0と10は効き目が非常に強いため、安定利用を望むのであれば、5〜8の範囲での設定を推奨します。

まずは既定値の5で試し、辞書が意図どおりに適用されない場合に少しずつ上げる方法がおすすめです。

⚠️最初から最大値へ設定すると、意図しない文章でも単語が過剰に優先される可能性があるため注意してください。

【手順3】音声合成時にユーザー辞書を指定する

作成したユーザー辞書は、音声合成リクエストのuser_dictionary_uuidに辞書UUIDを指定することで適用できます。

使用するエンドポイントは、通常の音声合成と同じです。

POST /v1/tts/synthesize

リクエスト例は次のとおりです。

{
  "model_uuid": "音声合成モデルのUUID",
  "text": "AivisSpeechで音声を作ります。",
  "user_dictionary_uuid": "作成したユーザー辞書のUUID"
}

user_dictionary_uuidを指定しなかった場合は、Aivis Cloud APIのデフォルト辞書のみが適用されます。

つまり、ユーザー辞書は「作成」と「音声合成リクエストでの指定」の両方を行って、初めて音声へ反映されます。

一方で、音声合成リクエストごとに使用する辞書を切り替えられるのは、大きなメリットです✨

例えば、次のような運用ができます。

・企業ごとに固有の辞書を用意する
・ブランドや商品ごとに辞書を分ける
・SaaSのエンドユーザーごとに異なる辞書を割り当てる
・案件ごとに人名や専門用語の読み方を管理する

1つの共通辞書へすべての単語を詰め込むのではなく、用途に応じて分けておくと管理しやすくなります。

【手順4】ユーザー辞書を管理する

Aivis Cloud APIには、作成した辞書を取得・更新・削除するためのAPIも用意されています。

所有している辞書の一覧を取得する

GET /v1/user-dictionaries

認証中のユーザーが所有している辞書の一覧を取得できます。

レスポンスは作成日時の昇順で並び、各辞書について次の情報が返されます。

・uuid
・name
・description
・word_count
・created_at
・updated_at

指定した辞書の内容を取得する

GET /v1/user-dictionaries/{user_dictionary_uuid}

指定した辞書のメタデータと、登録されている単語情報を取得できます。

公式APIドキュメントでは、このレスポンスをPUTリクエストとして再利用し、辞書の状態を再現できると案内されています。

既存の辞書へ単語を追加したい場合は、次の流れで更新すると安全です。

  1. GETで現在の辞書を取得する

  2. word_propertiesへ新しい単語を追加する

  3. 同じ辞書UUIDへPUTする

PUTは完全置き換えであるため、現在の単語を取得せずに新しい単語だけを送ると、既存の単語が消えてしまいます。

ユーザー辞書を削除する

DELETE /v1/user-dictionaries/{user_dictionary_uuid}

指定したユーザー辞書と、関連するサーバー内部のリソースを削除します。

存在しない辞書や、他のユーザーが所有する辞書のUUIDを指定した場合は、404エラーが返されます。

削除した辞書は音声合成に適用できなくなるため、利用中のシステムがないことを確認してから削除してください⚠️

【応用】AivisSpeechと辞書データを共有する

Aivis Cloud APIでは、AivisSpeech Engine互換形式の辞書データをインポート・エクスポートできます。

これにより、AivisSpeechエディタで育てた「読み方 & アクセント辞書」を、Aivis Cloud APIでも活用できます✨

AivisSpeechの辞書をインポートする

POST /v1/user-dictionaries/{user_dictionary_uuid}/import

次のデータを、そのままインポートできます。

・AivisSpeechエディタの「読み方 & アクセント辞書」からエクスポートしたJSONファイル
・AivisSpeech Engineのユーザー辞書取得APIから取得したデータ
・Aivis Cloud APIのエクスポートAPIから取得したデータ

インポート先の辞書が存在しない場合は、新しい辞書が作成されます。
この場合、辞書のnameとdescriptionは空文字列になります。

すでに辞書が存在する場合は、その辞書へ単語が追加インポートされ、既存のnameとdescriptionは維持されます。

同じ単語UUIDがすでに登録されている場合の挙動は、overrideクエリパラメータで指定できます。

・override=false：既存の単語を優先し、インポート対象の単語をスキップする
・override=true：インポートするデータで既存の単語を上書きする

overrideの既定値はfalseです。

既存の辞書を意図せず上書きしたくない場合は、まず既定値のままインポートするのが安全です。

AivisSpeechで使える形式にエクスポートする

GET /v1/user-dictionaries/{user_dictionary_uuid}/export

Aivis Cloud APIで作成した辞書を、AivisSpeech Engine互換のJSON形式で取得できます。

取得したJSONファイルは、AivisSpeechエディタの「読み方 & アクセント辞書」設定からインポートできます。

この仕組みにより、次のような運用が可能です。

・AivisSpeechで読み方を調整し、完成した辞書をクラウドへ移す
・クラウドで管理している辞書を、社内のAivisSpeech環境へ配布する
・ローカル環境とクラウド環境で、同じ読み方とアクセントを共有する

ローカルとクラウドのどちらか一方に閉じることなく、辞書データを双方向に移動できるのが便利なポイントです🔊

よくある質問

Q. 辞書に登録したのに読み方が変わりません

次の項目を確認してください。

・音声合成リクエストでuser_dictionary_uuidを指定しているか
・指定した辞書UUIDが正しいか
・surfaceの表記が実際の入力テキストと合っているか
・pronunciationがカタカナで設定されているか
・priorityが低すぎないか

まずは、音声合成リクエストにuser_dictionary_uuidが含まれているか確認しましょう。

Q. 読み方は合っていますが、アクセントが不自然です

accent_typeを見直してください。

accent_typeには、音の高さが下がる直前のモーラ位置を1始まりで指定します。単語内で音が下がらない平板型は0です。

拗音、促音、長音などを含む場合は、モーラ数の数え方にも注意してください。

Q. ユーザー辞書はいくつ作れますか？

複数のユーザー辞書を作成し、音声合成リクエストごとに使い分けられます。

現在は一律の作成上限を定めてはいませんが、「無制限」とは断定せず、大量の辞書を運用する場合は事前にお問い合わせいただけますと幸いです。

Q. 単語を1つだけ追加したい場合も、辞書全体を送り直す必要がありますか？

通常のPUTエンドポイントは完全置き換えです。

GETで現在の辞書を取得し、word_propertiesへ新しい単語を追加してからPUTで送り返してください。

AivisSpeech Engine互換データを追加する場合は、追加インポート用のエンドポイントも利用できます。

Q. surfaceに指定した英字が全角になって返ってきました

正しい仕様です。
surfaceは、ユーザー辞書での処理に適した表記へ正規化されて返ります。

そのため、英数字が全角になったり、表記によってはカタカナに変換されたりする場合があります。
入力時と見た目が異なっても、基本的には正常な動作であるため問題ありません。

Q. 辞書を作成すれば、すべてのAPIキーで利用できますか？

ユーザー辞書は、辞書を所有するAivisアカウントにひもづきます。

同じAivisアカウントで発行したAPIキーからは、そのアカウントが所有するユーザー辞書を利用できます。
別のAivisアカウントが所有する辞書にはアクセスできません。

Q. 複数の辞書を同時に適用できますか？

音声合成リクエストのuser_dictionary_uuidには、1つの辞書UUIDを指定します。

複数の辞書に分かれている単語を同時に使いたい場合は、必要な単語を1つの辞書へまとめる運用をご検討ください。

Q. ダッシュボードで作成したユーザー辞書もAPIから利用できますか？

はい、利用できます。

Aivis Cloud APIダッシュボードでユーザー辞書を作成し、画面に表示されるユーザー辞書UUIDを音声合成リクエストのuser_dictionary_uuidへ指定してください。

APIから作成した辞書と、ダッシュボードから作成した辞書は、同じAivisアカウントのユーザー辞書として管理されます。

Q. ダッシュボードとユーザー辞書APIは、どのように使い分ければよいですか？

少数の辞書や単語を手作業で管理する場合は、グラフィカルに操作できるAivis Cloud APIダッシュボードが便利です。

顧客やエンドユーザーごとに辞書を作成する場合や、辞書の作成・更新をシステムから自動化する場合は、ユーザー辞書APIが適しています。

まとめ

この記事では、Aivis Cloud APIのユーザー辞書を、APIから作成・管理する方法について解説しました。

ポイントをまとめると、次のとおりです。

・ユーザー辞書はPUTで新規作成・更新する
・辞書UUIDと単語UUIDはクライアント側で生成する
・PUTは辞書全体の完全置き換えとして動作する
・既存の辞書を更新するときは「GET → 加工 → PUT」の流れが安全
・surface、pronunciation、accent_typeはアクセント句ごとに要素数をそろえる
・accent_typeでは、音の高さが下がる直前のモーラ位置を1始まりで指定する
・priorityは1〜9が推奨され、既定値は5
・音声合成時はuser_dictionary_uuidへ使用する辞書UUIDを指定する
・AivisSpeech Engine互換の辞書データをインポート・エクスポートできる
・不要になった辞書はDELETEエンドポイントで削除できる

Aivis Cloud APIダッシュボードを利用すれば、画面上からユーザー辞書を作成・編集できます。

一方、ユーザー辞書APIを利用すると、顧客やエンドユーザーごとの辞書作成、既存辞書の更新、AivisSpeechとのデータ連携などをシステムから自動化できます。

特に、複数の顧客やユーザーへ音声合成機能を提供するサービスでは、ユーザー辞書をAPIから管理することで、それぞれに適した読み方やアクセントを柔軟に適用できます。

まずはテスト用のユーザー辞書を1つ作成し、短いテキストで読み方が正しく反映されるか確認してみてください。

ぜひユーザー辞書APIを活用し、Aivis Cloud APIの日本語読み上げを、サービスや業務システムに合わせて最適化してみてください📚

以上で、この記事はおしまいです。

Aivis ProjectやAivis Cloud APIに関してご不明点やご相談がある場合は、お問い合わせフォームよりお気軽にご連絡ください。

いいなと思ったら応援しよう！