テキスト読み上げエンドポイント

プラットフォームは AI Platform 互換のテキスト読み上げエンドポイントを提供します。利用可否は現在の API keys のグループとモデルカタログによって決まります。 まず GET /v1/models で利用可能な音声モデルが存在することを確認してから、このエンドポイントを呼び出してください。

リクエスト

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

リクエストパラメータ

音色、形式、話速の利用可能な範囲はモデルによって異なります。すべてのモデルが alloy や mp3 に対応していると仮定しないでください。 また、特定のモデルの音色一覧をコードにハードコードしないでください。

レスポンス

成功時

成功レスポンスの本文はバイナリ音声データであり、JSON ではありません。そのままファイルに書き込むか、クライアントへストリーミング転送してください。

# 保存为文件
curl ... --output speech.mp3

# 检查确实是音频而不是 JSON
file speech.mp3

失敗時

失敗時は error オブジェクトを伴う 2xx 以外のレスポンスを返します。構造はモデルのエンドポイントと同一です：

{
  "error": {
    "code": "invalid_parameter",
    "message": "..."
  }
}

よくある失敗原因：

サーバー側での実装の推奨事項

テキスト読み上げは同期エンドポイントで、レスポンスがそのまま音声データです。実装時は次に注意してください：

1. JSON として解析しないでください。まず HTTP ステータスと Content-Type を判定し、 失敗時のみ JSON として error を読み取ってください。
2. 音声をそのままブラウザへ透過転送する際に Content-Type の設定を忘れないでください。 忘れるとブラウザがテキストとして処理してしまいます。
3. input の長さを制御してください。非常に長いテキストは業務側で分割し、分割ごとに合成してから結合し、 1 回のリクエストで上限を超えないようにしてください。
4. 音声ファイルは自分のストレージへ転存することを推奨します。プラットフォームが返す一時的な結果に長期的に依存しないでください。
5. 業務バックエンドでは高頻度で重複する合成結果をキャッシュし、二重課金を避けてください。

非同期音声タスク

この同期エンドポイントのほか、プラットフォームは非同期の音声生成機能（BGM、効果音など）も提供しています。 これらのタスクのステータスと成果物はコンソールの「タスクログ」で照会でき、扱い方は 動画タスクと同様です。 作成後はタスク ID を保存し、照会エンドポイントで終端状態までポーリングしてください。重複して作成しないでください。

課金

音声エンドポイントの課金方式はモデルマーケットのモデル詳細に準じ、Token 単位、回数単位、時間単位のいずれかで課金される場合があります。 課金と精算のルールは課金と請求を参照してください。

関連ドキュメント

• エンドポイント概要
• 認証と基本仕様
• エラーコードとトラブルシューティング
• クイックスタート：初めてのテキスト読み上げ呼び出し