beatraドキュメント
音声とボイス

ボイス管理

音声合成に使えるボイスの照会、絞り込み、削除。

音声合成に使えるボイスの照会、絞り込み、削除。

Agent の主経路

Universal Skill から MCP ツール beatra.voices.list を使います。課金されない 読み取り専用の呼び出しで、プリセットボイスとあなたのアカウントにあるクローンボイスを 返します。

  1. category（preset / cloned）、language（BCP-47）、gender （male / female / neutral）、age_group（child / youth / adult / senior）、use_case（audiobook、narration、news、ads、 conversational、business、character、ivr、course、podcast、 gaming、shorts、education、support、social のいずれか）、model （対応モデル ID）、query（表示名に含まれる文字）、search（表示名または ペルソナに含まれる文字）、voice_id（1 つのボイスに完全一致）で絞り込みます。 status で一覧に含めるボイスを選びます：ready（既定。音声合成に使える ボイス）、pending_activation（有料アクティブ化を待つクローンの試聴）、 expired、any。
  2. 一覧はページ分割されます。limit（1–500、既定 50）と cursor（前ページの next_cursor）を使います。total_count は条件に合うボイスの総数で、最後の ページでは next_cursor が null です。
  3. 返された voice_id は音声合成 の voice フィールドにそのまま使えます。persona はボイスを 1 文で説明し、 preview_url（汎用サンプル）と preview_url_scene（主な用途のサンプル）で 選ぶ前に無料で試聴できます。

AI ガイド

AI 連携 Markdown

独自アプリケーションに組み込む場合は、この API ガイドを Claude や Codex などにコピーできます。

Markdown

ツール引数

{
  "category": "preset",
  "language": "zh-CN",
  "use_case": "audiobook",
  "age_group": "adult",
  "limit": 50
}

ボイスのエントリは次の形です：

{
  "voice_id": "voice_preset_niannian",
  "display_name": "念念",
  "category": "preset",
  "language": "zh",
  "gender": "female",
  "age_group": "adult",
  "use_case": ["audiobook", "narration"],
  "persona": "温柔细腻的女声，适合有声书与旁白。",
  "preview_url": "https://cdn.beatra.ai/voices/previews/voice_preset_niannian.mp3",
  "preview_url_scene": "https://cdn.beatra.ai/voices/previews/voice_preset_niannian_scene.mp3",
  "compatible_models": ["minimax-speech-2.8-hd", "minimax-speech-2.8-turbo"],
  "status": "ready"
}

別途アクティブ化が必要なモデルでクローンしたボイス（ボイスクローン を参照）は clone_model も持ち、アクティブ化待ちの間は preview（url、 text、language、version）と expires_at も含みます。その他のボイスの 項目は変わりません。既定（ready）の一覧にアクティブ化待ちのボイスが含まれない 場合、テキストの要約にその件数が示されます。

compatible_models には、そのボイスを読み上げられる音声モデルが並びます。ボイスはそれぞれ 1 つのエンジンに属するため、model は auto（この一覧から選びます）にするか、この中のモデルを指定してください。ほかのモデルは課金前に voice_model_incompatible で拒否されます。

レスポンスには next_cursor と total_count も含まれます。REST の GET /v1/voices は同じ絞り込み条件をクエリパラメーターで受け付けます（名前検索は query ではなく q）。

デフォルトボイスと名前の変更

beatra.voices.list は voices と並べて default_voice_id を返します。アカウントにデフォルトボイスがあればその voice_id、なければ null です。各ボイスの項目は変わりません。

ユーザーが求めたときだけ、beatra.voices.update で自分のクローンボイスの名前を変えるか、任意のボイス（クローンまたはプリセット）をデフォルトにします。課金はなく、ボイスを削除することはできません。アクティブ化待ちのボイスは名前を変更できますが、デフォルトにできるのは ready のボイスだけです。

{
  "voice_id": "voice_01JX...",
  "display_name": "鵬博士",
  "make_default": true
}

クローンボイスの削除

削除は REST のみです：

curl -X DELETE "$BEATRA_BASE_URL/voices/voice_01JX..." \
  -H "Authorization: Bearer $BEATRA_API_KEY"

204 を返します。削除できるのは自分でクローンしたボイスだけで、プリセット ボイスは削除できません。

アクティブ化が必要なモデルでクローンしたボイスの削除は取り消せません。 アクティブ化待ち（または期限切れ）のボイスは試聴とともに削除されます。 アクティブ化したボイスでは、アクティブ化の料金は返金されず、すでに送信済みの 音声合成タスクはそのまま完了します。アクティブ化の実行中に削除すると 409 conflict（details.reason: voice_operation_in_progress）になります。その タスクが終わってから削除してください。

REST で呼び出す

プロトコル直結の統合はボイスエンドポイントを直接使えます： 一覧 · 詳細 · 削除。 推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタム アプリケーション向けです。

最終更新

前のページ

ボイスクローン

次のページ

テキストから音楽生成

このページの内容

Markdown