Aivis Cloud API のエラー対処法｜よくある HTTP エラーと解決策

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

Aivis Cloud APIを使ったアプリケーション開発では、正常に音声を生成する処理だけでなく、エラーが起きたときに原因を正しく判断し、安全に復旧できる処理も欠かせません。

APIキーの設定ミス、クレジット不足、モデルUUIDの間違い、パラメータ不正、レート制限、音声合成サーバーの一時的な障害など、エラーの原因によって取るべき対応は異なります。

この記事では、Aivis Cloud APIの音声合成APIで定義されているHTTPエラーをごとに、原因の確認方法、リトライしてよいエラーの見分け方、本番運用で押さえておきたい実装ポイントを解説します📚

【最初に確認】AivisSpeech EngineとはAPI仕様が異なる

Aivis Cloud APIの音声合成エンドポイントは、次のURLです。

POST https://api.aivis-project.com/v1/tts/synthesize

最低限必要なリクエスト項目は、model_uuidとtextです。

{
  "model_uuid": "YOUR_MODEL_UUID",
  "text": "テスト音声です。"
}

エラーを調べる前に、参考にしているコードがAivis Cloud API向けのものか、ローカルのAivisSpeech Engine向けのものかを確認してください。

エラー調査で最初に確認する3つの情報

Aivis Cloud APIでエラーが発生したら、次の3つをセットで確認します。

1. HTTPステータスコード

401、402、404、422などの4xx系は、認証情報やリクエスト内容、利用状態を見直す必要があるエラーです。

500、502、503、504などの5xx系は、サーバーやサーバー間通信で一時的な問題が発生している可能性があります。

2. レスポンスボディ

レスポンスボディには、エラーの詳細が含まれる場合があります。
ステータスコードだけで判断せず、個人情報や機密情報に配慮したうえで内容を記録してください。

3. レスポンスヘッダー

音声合成APIでは、課金モードや使用量、レート制限を確認するためのカスタムヘッダーが用意されています。

課金モードによって返るヘッダーは異なります。エラーレスポンスにこれらのヘッダーが含まれている場合も、原因の切り分けに活用できます。

よくあるHTTPエラーと解決策

401 Unauthorized｜APIキーを確認する

401は、APIキーが設定されていない、または有効な認証情報として受け付けられなかった場合に返ります。

主な確認項目は次のとおりです。

・Authorizationヘッダーを送信しているか
・Bearerのあとに半角スペースを入れているか
・APIキーの前後に空白や改行が入っていないか
・環境変数から正しい値を読み込めているか
・ダッシュボード上で対象のAPIキーが有効か

Pythonでは、次のようにAPIキーを環境変数から読み込みます。

import os

api_key = os.environ.get("AIVIS_API_KEY")
if not api_key:
    raise RuntimeError("AIVIS_API_KEYが設定されていません。")

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

APIキーをソースコードへ直接記述したり、公開リポジトリへコミットしたりしないでください。
環境変数やシークレット管理サービスを利用し、ログにもAPIキーを出力しないようにします。

402 Payment Required｜クレジットと利用上限を確認する

402は、音声合成に利用できるクレジットが不足している場合に返ります。

従量課金のAPIキーでは、Cloud APIダッシュボードでクレジット残高を確認し、必要に応じてチャージしてください。

Aivisプレミアムで「追加使用量」を有効にしている場合でも、追加分に使うクレジットが不足している、または設定した月間利用上限へ到達していると402が返ります。

402は、待つだけでは基本的に解決しません。残高や利用上限を確認し、利用可能な状態へ戻してから再実行してください。

404 Not Found｜モデルの指定を確認する

音声合成APIで定義されている404は、指定したモデルUUIDの音声合成モデルが見つからない場合に返ります。

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

・model_uuidにタイプミスがないか
・AivisHubのモデル詳細ページに表示される正しいUUIDか
・非公開モデルの場合、自分のアカウントから利用できるモデルか（非公開モデルの場合、モデルを公開したアカウントにて発行したAPIキーのみが有効）
・限定公開モデルを利用する場合、UUIDではなくak_から始まるアクセスキーを指定しているか
・モデルをアップロードした直後ではないか

モデルをアップロードしてから音声合成バックエンドへ反映されるまで、最大5分程度かかる場合があります。
アップロード直後にモデル関連のエラーが出る場合は、少し待ってから再確認してください。

URL自体がhttps://api.aivis-project.com/v1/tts/synthesizeになっているかも確認しましょう。
旧形式の/audio_queryなど、存在しないパスへ送信した場合も404になります。

422 Unprocessable Entity｜リクエスト内容を見直す

422は、JSONとして受け取ったリクエストの項目や値が、API仕様に適合していない場合に返ります。

代表的な原因は次のとおりです。

・必須のmodel_uuidまたはtextがない
・textが空、または3000文字を超えている
・model_uuidやspeaker_uuidがUUIDとして不正
・speaking_rateなどの数値が許容範囲外
・存在しない話者UUIDやスタイルIDを指定している
・同時指定できないstyle_idとstyle_nameを両方送っている

たとえば、次のリクエストはtextが空で、speaking_rateも上限を超えています。

{
  "model_uuid": "YOUR_MODEL_UUID",
  "text": "",
  "speaking_rate": 3.0
}

エラー本文にloc、msg、typeなどの検証情報が含まれている場合は、どの項目が不正と判断されたかを確認します。

429 Too Many Requests｜レート制限の回復を待つ

429は、音声合成APIのレート制限に到達した場合に返ります。

Aivisプレミアムには、現在1分間に10リクエストまでのレート制限があります。「追加使用量」が無効の状態で上限を超えると、制限が回復するまで429になります。

「追加使用量」を有効にすると、定額枠を超えた分だけ従量課金クレジットを使って音声生成を継続できます。ただし、クレジット不足や月間利用上限への到達時は402になります。

429を受け取ったら、レスポンスにX-Aivis-RateLimit-Requests-Resetが含まれているか確認し、記載された秒数以上待ってから再試行してください。

500・502・503・504｜一時的なサーバーエラーへ対処する

5xx系のエラーは、Aivis Cloud APIと音声合成サーバーの間の通信や、音声合成処理で問題が発生した場合に返ります。

・500 Internal Server Error：音声合成サーバーへの接続中に不明なエラーが発生
・502 Bad Gateway：音声合成サーバーへの接続に失敗
・503 Service Unavailable：音声合成サーバーで障害が発生、または音声合成に失敗
・504 Gateway Timeout：音声合成サーバーへの接続がタイムアウト

まず数十秒~1分程度待ってから、数回再試行します。
同じテキストやモデルで繰り返し発生する場合は、別の短いテキストや別モデルでも確認し、入力依存かサービス全体の問題かを切り分けてください。

広範囲で長時間続く場合は、Aivis Project公式Xなどで障害・メンテナンス情報をご確認いただくほか、お問い合わせフォームからご報告ください。

リトライしてよいエラーと、先に修正すべきエラー

設定や利用状態を直すまでリトライしないエラー
401 / 402 / 404 / 422

401や422を何度再送しても、APIキーやリクエスト内容を直さない限り成功しません。無駄な再送を防ぐため、ステータスコードごとに処理を分けます。

指数バックオフとジッターを実装する

一時的なエラーへ再試行するときは、待機時間を徐々に延ばす「指数バックオフ」と、リクエストが同じ瞬間へ集中するのを防ぐランダムな待ち時間「ジッター」を組み合わせます。

次は、Pythonのrequestsを使った基本例です。

import random
import time
import requests

RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}


def get_wait_seconds(response, attempt):
    if response.status_code == 429:
        reset = response.headers.get("X-Aivis-RateLimit-Requests-Reset")
        if reset is not None:
            try:
                return max(float(reset), 1.0) + random.uniform(0, 0.5)
            except ValueError:
                pass

    return min(2**attempt, 30) + random.uniform(0, 1)


def synthesize_with_retry(url, headers, payload, max_attempts=4):
    for attempt in range(max_attempts):
        try:
            response = requests.post(
                url,
                headers=headers,
                json=payload,
                timeout=(10, 120),
            )
        except requests.ConnectTimeout:
            if attempt == max_attempts - 1:
                raise
            time.sleep(min(2**attempt, 30) + random.uniform(0, 1))
            continue

        if response.status_code == 200:
            return response.content

        if response.status_code not in RETRYABLE_STATUS_CODES:
            raise RuntimeError(
                f"Aivis Cloud API error: "
                f"status={response.status_code}, body={response.text[:500]}"
            )

        if attempt == max_attempts - 1:
            response.raise_for_status()

        time.sleep(get_wait_seconds(response, attempt))

    raise RuntimeError("音声合成に失敗しました。")

この例のtimeout=(10, 120)は、接続タイムアウト10秒・読み取りタイムアウト120秒という設定例です。最適な値は、テキスト長、使用モデル、実際の生成時間、アプリケーションの応答要件に合わせて調整してください。

無制限に再送しない

リトライ回数には上限を設け、失敗後はキューへ戻す、処理を保留する、ユーザーへ再実行を案内するなどの処理へ切り替えます。

現行の公開API仕様には、同一リクエストの重複処理を防ぐための冪等性キーは記載されていません。クライアント側で読み取りタイムアウトや通信切断が発生した場合、サーバー側で処理がどこまで進んだか判断できない可能性があります。同じリクエストを無制限に再送する設計は避けてください。

デバッグしやすい実装にする4つのポイント

1. curlで最小構成を試す

アプリケーション内でエラーが出た場合は、curlで最小構成のリクエストを送り、APIキー・モデルUUID・エンドポイントのどこに問題があるかを切り分けます。

curl -sS \
  -D response-headers.txt \
  -o response-body.bin \
  -w "HTTP Status: %{http_code}\n" \
  -X POST "https://api.aivis-project.com/v1/tts/synthesize" \
  -H "Authorization: Bearer ${AIVIS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model_uuid": "YOUR_MODEL_UUID",
    "text": "テスト音声です。",
    "output_format": "mp3"
  }'

response-headers.txtにはレスポンスヘッダー、response-body.binには成功時の音声データ、またはエラー時のレスポンスボディが保存されます。

2. 調査に必要な情報だけをログへ残す

エラー時は、次の情報を構造化して記録すると原因を追いやすくなります。

・発生日時
・HTTPステータスコード
・呼び出したエンドポイント
・モデルUUID
・入力テキストの文字数
・レスポンスボディ
・課金・レート制限に関するレスポンスヘッダー
・リトライ回数

APIキーをログへ記録してはいけません。入力テキストにも個人情報や機密情報が含まれる可能性があるため、本文全体ではなく文字数や内部管理用IDを記録する設計が安全です。

3. 開発環境と本番環境のAPIキーを分ける

用途別にAPIキーを分けると、テストのリクエストと本番利用を区別しやすくなります。APIキー名も「開発環境」「本番環境」など、ダッシュボードで識別できる名前にしておくと管理しやすくなります。

4. 失敗した処理を追跡できるようにする

バッチ処理やキュー処理では、失敗したテキストをその場で破棄せず、内部IDと失敗理由を記録します。一定回数を超えた処理はデッドレターキューなどへ移し、あとから再確認できる状態にしておきましょう。

よくある質問（FAQ）

Q. タイムアウトしたリクエストは、そのまま再送しても大丈夫ですか？

接続前にタイムアウトしたと判断できる場合は再送しやすい一方、リクエスト送信後の読み取りタイムアウトでは、サーバー側で音声合成が進んでいる可能性があります。

公開仕様には冪等性キーが記載されていないため、読み取りタイムアウトを無条件で再送するのではなく、回数を制限し、重複処理やクレジット消費の可能性を考慮してください。

Q. 障害時にAivisSpeechへ自動で切り替えられますか？

可能ですが、Aivis Cloud APIとAivisSpeech EngineのAPIには互換性がありません。URLだけを差し替えるのではなく、それぞれのリクエスト・レスポンス形式へ変換する別のアダプター実装が必要です。

また、AivisSpeechを動かす端末、利用するモデル、処理能力、ライセンス条件なども事前に確認してください。ローカル環境をフォールバック先にする場合は、通常時から定期的に動作確認しておくことが重要です。

まとめ

エラーハンドリングは、単に例外を捕捉するための処理ではありません。原因を正しく分類し、再試行してよいエラーだけを安全に処理できる設計が、サービスの安定性と利用者の体験を守ります✨

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

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