PythonでAivisSpeechのAPIを使う方法｜音声合成・WAV保存・一括生成を解説

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

AivisSpeechは、画面上で文章を入力して音声を作るだけでなく、ローカルHTTP APIをPythonから操作できます。

APIを使えるようになると、台本から複数のWAVファイルを一括生成する、ほかのアプリから読み上げを実行する、話者スタイルや話速を処理ごとに切り替えるといった自動化が可能です。

この記事では、AivisSpeech Engineへの接続確認から、話者一覧の取得、音声合成、パラメータ調整、バッチ処理までを順番に解説します📚

【結論】音声合成は3つのAPI操作で実行できる

AivisSpeech Engineで音声を生成する基本的な流れは、次の3段階です。

1．GET  /speakers      利用できる話者とスタイルIDを取得
2．POST /audio_query   テキストから音声クエリを作成
3．POST /synthesis     音声クエリからWAVデータを生成

音声クエリとは、読み上げる文章と、話速・感情表現・音量などの設定をまとめたJSONデータです。/audio_queryで作成した音声クエリを/synthesisへ渡すことで、WAV形式の音声が返されます。

事前準備

AivisSpeechを起動する

AivisSpeechのHTTP APIは、AivisSpeechまたはAivisSpeech Engineが起動している間だけ利用できます。

次の手順で接続準備を確認してください。

1．AivisSpeechを起動する
2．音声合成エンジンの起動が完了するまで待つ
3．ブラウザでhttp://127.0.0.1:10101/docsを開く

Swagger UIと呼ばれるAPIドキュメント画面が表示されれば準備完了です。この画面では、現在のAivisSpeech Engineで利用できるエンドポイントやパラメータを確認できます。

⚠️ AivisSpeech Engineのデフォルトポートは10101です。起動オプションなどでポート番号を変更している場合は、この記事のURLも同じ番号へ置き換えてください。

requestsをインストールする

PythonからHTTP APIへアクセスするため、requestsをインストールします。ターミナルやコマンドプロンプトで次のコマンドを実行してください。

python -m pip install requests

Jupyter Notebook上でインストールする場合は、次のセルを実行します。

%pip install requests

すでにインストールされている場合は、この手順を省略できます。

ステップ1：AivisSpeech Engineへの接続を確認する

最初に、バージョン情報を取得する/versionへアクセスします。

import requests

BASE_URL = "http://127.0.0.1:10101"

response = requests.get(f"{BASE_URL}/version", timeout=5)
response.raise_for_status()

print(f"ステータスコード: {response.status_code}")
print(f"Engineバージョン: {response.json()}")

ステータスコードに200が表示されれば、Pythonから正常に接続できています。

接続エラーになる場合は、AivisSpeechが起動しているか、音声合成エンジンの起動が完了しているか、ポート番号が正しいかを確認してください。

ステップ2：話者とスタイルIDを取得する

音声合成では、使用する声を/speakersから取得したスタイルIDで指定します。

response = requests.get(f"{BASE_URL}/speakers", timeout=10)
response.raise_for_status()
speakers = response.json()

available_styles = []

for speaker in speakers:
    print(f"=== {speaker['name']} ===")

    for style in speaker["styles"]:
        style_id = style["id"]
        available_styles.append(
            (speaker["name"], style["name"], style_id)
        )
        print(f"  スタイル: {style['name']} / ID: {style_id}")

    print()

if not available_styles:
    raise RuntimeError("利用できる話者スタイルが見つかりませんでした。")

# 今回は、取得できた最初のスタイルを使用する
speaker_name, style_name, STYLE_ID = available_styles[0]
print(f"使用する声: {speaker_name} / {style_name} / ID: {STYLE_ID}")

AivisSpeech EngineのスタイルIDは、インストールされているモデルから生成されるグローバルな値です。
0や1のような固定値とは限らないため、実行環境の/speakersから取得した値を使用してください。

モデルを追加・変更した場合も、ハードコードした番号に頼らず、話者名とスタイル名を確認して選ぶ実装が安全です。

ステップ3：音声クエリを作成する

読み上げるテキストとスタイルIDを/audio_queryへ渡し、音声クエリを作成します。

TEXT = "こんにちは、AivisSpeechのAPIテストです。"

query_response = requests.post(
    f"{BASE_URL}/audio_query",
    params={
        "text": TEXT,
        "speaker": STYLE_ID,
    },
    timeout=30,
)
query_response.raise_for_status()

audio_query = query_response.json()

print(f"話速: {audio_query['speedScale']}")
print(f"音高: {audio_query['pitchScale']}")
print(f"感情表現の強さ: {audio_query['intonationScale']}")
print(f"テンポの緩急: {audio_query['tempoDynamicsScale']}")
print(f"音量: {audio_query['volumeScale']}")

音声クエリにはアクセント句などの情報も含まれますが、基本的な調整では次の項目を押さえておけば十分です。

・speedScale：文章全体の話速
・intonationScale：選択した話者スタイルの感情表現の強さ
・tempoDynamicsScale：話す速さの緩急。AivisSpeech Engine独自の項目
・volumeScale：文章全体の音量
・pitchScale：文章全体の音高

⚠️ intonationScaleは、VOICEVOX ENGINEにおける一般的な「抑揚」と意味が異なります。
AivisSpeech Engineでは、選択したスタイルの感情表現をどの程度強く出すかを指定します。
また、ノーマルスタイルでは値が反映されない場合があります。

⚠️ pitchScaleを既定値の0.0から変更すると、音質が劣化する可能性があります。
声の印象を変えたい場合は、先に話者スタイルやintonationScale、tempoDynamicsScaleを調整するのがおすすめです。

ステップ4：WAVファイルを生成する

続いて、音声クエリを/synthesisへ送信します。レスポンスとして返された音声データを、そのままWAVファイルへ保存できます。

from pathlib import Path

synthesis_response = requests.post(
    f"{BASE_URL}/synthesis",
    params={"speaker": STYLE_ID},
    json=audio_query,
    timeout=120,
)
synthesis_response.raise_for_status()

output_path = Path("hello.wav")
output_path.write_bytes(synthesis_response.content)

print(f"音声ファイルを保存しました: {output_path.resolve()}")

実行したフォルダにhello.wavが作成されます。
音声プレイヤーで開き、読み上げ結果を確認してみてください🔊

ステップ5：音声生成を関数にまとめる

繰り返し使えるように、音声クエリの作成からWAVファイルの保存までを1つの関数にまとめます。

from pathlib import Path
import requests

BASE_URL = "http://127.0.0.1:10101"


def synthesize_to_wav(
    text,
    style_id,
    output_path,
    speed_scale=1.0,
    intonation_scale=1.0,
    tempo_dynamics_scale=1.0,
    volume_scale=1.0,
):
    """テキストを音声合成し、WAVファイルへ保存する。"""

    query_response = requests.post(
        f"{BASE_URL}/audio_query",
        params={"text": text, "speaker": style_id},
        timeout=30,
    )
    query_response.raise_for_status()
    audio_query = query_response.json()

    audio_query["speedScale"] = speed_scale
    audio_query["intonationScale"] = intonation_scale
    audio_query["tempoDynamicsScale"] = tempo_dynamics_scale
    audio_query["volumeScale"] = volume_scale

    synthesis_response = requests.post(
        f"{BASE_URL}/synthesis",
        params={"speaker": style_id},
        json=audio_query,
        timeout=120,
    )
    synthesis_response.raise_for_status()

    output_path = Path(output_path)
    output_path.parent.mkdir(parents=True, exist_ok=True)
    output_path.write_bytes(synthesis_response.content)

    return output_path

たとえば、少しゆっくりした話速で、感情表現とテンポの緩急を調整する場合は次のように呼び出します。

saved_path = synthesize_to_wav(
    text="パラメータを調整すると、読み上げの印象が変わります。",
    style_id=STYLE_ID,
    output_path="custom/slow_expressive.wav",
    speed_scale=0.85,
    intonation_scale=1.3,
    tempo_dynamics_scale=1.1,
)

print(f"保存しました: {saved_path.resolve()}")

最適な値はモデルやスタイルによって異なります。大きく変更するのではなく、既定値の1.0を基準に少しずつ調整してください。

ステップ6：複数の文章を一括で音声化する

先ほど作成した関数を使えば、複数の文章を順番に音声化できます。

script = [
    "こんにちは。今日のテーマは音声合成です。",
    "AivisSpeechは、ローカル環境で音声を生成できます。",
    "PythonからAPIを操作すると、一括生成も自動化できます。",
    "それでは、さっそく始めましょう。",
]

for index, text in enumerate(script, start=1):
    output_path = synthesize_to_wav(
        text=text,
        style_id=STYLE_ID,
        output_path=f"narration/{index:03d}.wav",
    )
    print(f"[{index}/{len(script)}] {output_path} ... 完了")

実行すると、narrationフォルダ内に001.wav、002.wavという連番のファイルが生成されます。

1行に1つのセリフを記載したscript.txtから読み込む場合は、次のように記述します。

from pathlib import Path

lines = Path("script.txt").read_text(encoding="utf-8").splitlines()
script = [line.strip() for line in lines if line.strip()]

for index, text in enumerate(script, start=1):
    output_path = synthesize_to_wav(
        text=text,
        style_id=STYLE_ID,
        output_path=f"from_file/{index:03d}.wav",
    )
    print(f"[{index}/{len(script)}] {output_path} ... 完了")

ローカルのAivisSpeech Engineは、一般的なPC上で1人が使うことを想定した製品です。
大量のリクエストを同時に送っても、PCへの負荷が増えるだけで処理が速くならない場合があります。
まずは上記のように、1件ずつ順番に処理してください。

ステップ7：同じ話者のスタイルを切り替える

1つのモデルに複数のスタイルが含まれている場合は、スタイルごとのIDを指定して表現を切り替えられます。

selected_speaker = speakers[0]
text = "今日はとても良い天気ですね。"

for index, style in enumerate(selected_speaker["styles"], start=1):
    output_path = synthesize_to_wav(
        text=text,
        style_id=style["id"],
        output_path=f"styles/{index:02d}_{style['id']}.wav",
    )
    print(
        f"{selected_speaker['name']} / {style['name']}"
        f" → {output_path}"
    )

スタイル名とIDはモデルごとに異なります。
必ず/speakersのレスポンスから取得したIDを使用してください。

VOICEVOX互換APIを流用するときの注意点

AivisSpeech EngineはVOICEVOX ENGINEをベースにしており、/speakers、/audio_query、/synthesisなどの基本的なAPIは概ね互換性があります。

ただし、URLのポート番号だけを変更すれば、すべてのコードがそのまま動くわけではありません。 主な違いは次のとおりです。

・AivisSpeech Engineのデフォルトポートは10101
・スタイルIDは話者UUIDなどから生成された32bit符号付き整数
・intonationScaleは「話者スタイルの感情表現の強さ」を表す
・AivisSpeech Engine独自のtempoDynamicsScaleが追加されている
・pitchScaleを変更すると音質が劣化する可能性がある
・一部のフィールドやエンドポイントは未対応、または挙動が異なる

/audio_queryのレスポンスを変更せず、そのまま/synthesisへ渡す基本的な処理は流用しやすい一方、音声クエリを編集するコードでは仕様差を確認する必要があります。

よくある質問（FAQ）

Q．Connection refusedと表示されます。

AivisSpeechまたはAivisSpeech Engineが起動していないか、ポート番号が異なる可能性があります。
まずブラウザでhttp://127.0.0.1:10101/docsを開けるか確認してください。

Q．422 Unprocessable Entityが返されます。

テキストやスタイルIDなど、リクエストの内容がAPI仕様と一致していない可能性があります。
スタイルIDを固定値で指定せず、/speakersから取得した値を使っているか確認してください。
詳細なエラー内容はresponse.textまたはresponse.json()で確認できます。

Q．VOICEVOX向けのPythonコードをそのまま使えますか？

基本的な音声合成の流れは似ていますが、完全互換ではありません。
特にスタイルID、AudioQueryのパラメータ、一部の未対応エンドポイントに違いがあります。
URLだけでなく、AivisSpeech EngineのAPIドキュメントと照合してください。

Q．Aivis Cloud APIでも同じコードを使えますか？

使えません。
AivisSpeech EngineとAivis Cloud APIではAPI仕様が異なります。
Aivis Cloud APIでは、APIキーによる認証を行い、POST /v1/tts/synthesizeへ専用のリクエストを送信します。

Q．複数の音声を同時に生成すれば速くなりますか？

必ずしも速くなりません。
AivisSpeech Engineは一般的なPCでのローカル利用を想定しており、大量の同時リクエストを処理するAPIサーバーとしては最適化されていません。
ローカルの一括生成は順番に処理し、多数のユーザーから同時に利用するシステムにはAivis Cloud APIまたはCitorasをご検討ください。

Q．APIを使うと入力テキストがクラウドへ送信されますか？

この記事で扱うAivisSpeech EngineのHTTP APIは、127.0.0.1で動くローカルAPIです。
音声合成処理はPC内で行われます。
ただし、AivisSpeechの初回起動時には、モデルや音声合成に必要なデータをダウンロードするためインターネット接続が必要です。

まとめ

AivisSpeechのHTTP APIを使えば、普段画面上で行っている音声生成を、Pythonから柔軟に自動化できます。

最初は1つの文章をWAVファイルへ保存するところから始め、話者スタイルの切り替えや台本の一括生成へ少しずつ広げてみてください✨

以上で、この記事はおしまいです。Aivis ProjectやAivisSpeechに関してご不明点やご相談がある場合には、お問い合わせフォームよりお気軽にご連絡ください。