スピーチ変換（ボイスチェンジャー）

元の録音のタイミング、間の取り方、感情表現を保ったまま、音声を対象のボイスに変換します。

元の録音の間合い、抑揚、感情表現を保ったまま、ソース音声を指定した Beatra の対象ボイスに変換します。

Agent の主経路

Universal Skill から MCP ツール beatra.speech.convert を使います。このツールは課金対象で、非同期タスクを返します。

まずスピーチ変換に対応する対象ボイスを選びます。beatra.voices.list に supports_speech_to_speech: true を渡して呼び出します（REST は GET /v1/voices?supports_speech_to_speech=true）。スピーチ変換に使えるのは capabilities.supports_speech_to_speech: true を持つボイス（ElevenLabs のプリセットボイス、および ready 状態の ElevenLabs クローンボイス）のみです。
元の音声ファイルを beatra.assets.upload でアップロードし、返された artifact_id を使います（または https_url を直接渡します）。
不透明な client_request_id を 1 つ作り、最終的な引数を一度だけ送信します。
beatra.tasks.get で終端状態までポーリングします。

AI ガイド

AI 連携 Markdown

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

Markdown

ツール引数

{
  "audio": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "voice": "voice_preset_elevenlabs_001",
  "model": "auto",
  "remove_background_noise": true,
  "format": "mp3",
  "client_request_id": "sts-opaque-1"
}

audio（必須。MCP・REST ともに入力エイリアスとして source も受け付けます）：artifact 参照（{"type": "artifact", "artifact_id": "..."}）または HTTPS URL（{"type": "https_url", "url": "https://..."}）。MP3、WAV、M4A、AAC、FLAC、OGG、Opus に対応します。長さは 1.0 秒以上 300.0 秒（5 分）以下、ファイルサイズは 50 MiB 以下です。範囲外の入力は課金前に 422 invalid_request で拒否されます。
voice（必須。MCP・REST ともに入力エイリアスとして voice_id も受け付けます）：スピーチ変換に対応する対象ボイスの voice_id（ボイス管理を参照）。MiniMax や Doubao のボイスを指定すると課金前に 422 invalid_request（details.reason: "voice_unsupported_for_speech_to_speech"）で拒否され、クレジットは消費されません。アクティブ化待ちまたは期限切れのボイスは 422 invalid_request（details.reason: "voice_pending_activation" または "voice_expired"）を返します。
model（任意、既定 "auto"）："auto" または "elevenlabs-sts-v2"。
remove_background_noise（任意、真偽値、既定 false）：変換前にソース録音の軽い環境ノイズを抑えます。BGM や強い屋外ノイズが含まれる場合は、先にボーカル抽出を実行してください。
stability（任意、0.0〜1.0）、similarity_boost（任意、0.0〜1.0）、style（任意、0.0〜1.0）、use_speaker_boost（任意、真偽値）：対象ボイスの表現力を調整する任意のパラメーター（ElevenLabs の voice_settings として適用されます）。
format（任意、既定 "mp3"）："mp3"（44.1 kHz）、"wav"（24 kHz 16-bit モノラル RIFF WAVE audio/wav コンテナ）、"opus"（48 kHz）、"pcm"（生データの 24 kHz 16-bit リトルエンディアンモノラル PCM、audio/pcm）に対応します。
seed（任意、整数 0〜4,294,967,295）：再現性を高めるためのシード値ヒント。
model_options（任意、オブジェクト）：モデル固有の拡張指定を渡すための前方互換フィールドです。

モデル・同時実行上限・コスト

選択可能なモデル、フォーマット、制限、クレジット単価の最新の事実源は capability: "speech_to_speech" を指定した beatra.models.list です。

elevenlabs-sts-v2：入力音声の切り上げ分数（ceil(duration_seconds / 60)）に基づく前払いで、切り上げ 1 分あたり 721 クレジット です（60 秒以下は 721 クレジット、5 分は 3,605 クレジット）。
スピーチ変換は、ElevenLabs の音声合成とアカウントごとの同時実行 2 件の上限（429 rate_limited、details.reason: speech_inflight_limit）を共有します。
voice に ElevenLabs のクローンボイスを指定した場合、必要に応じて保存済みサンプルから自動的にボイスを準備・復元してから変換します。

結果

スピーチ変換は単一機能のオーディオ処理であり、裏で文字起こしを自動実行することなく、変換後の音声のみを返します。

{
  "type": "speech_to_speech",
  "model": "elevenlabs-sts-v2",
  "voice_id": "voice_preset_elevenlabs_001",
  "audio": {
    "artifact_id": "artifact_01JY...",
    "url": "https://cdn.beatra.ai/tenants/.../converted.mp3",
    "duration_seconds": 14.2,
    "mime_type": "audio/mpeg",
    "size_bytes": 227840
  }
}

変換後の音声に字幕やタイムスタンプも必要な場合は、返された audio.artifact_id を音声文字起こしに渡してください。

タスクの状態とリカバリー

queued と running は失敗ではありません。同じ task_id をポーリングし続けてください。作成応答を失った場合は同じ client_request_id で同一の引数を再送し、入力が変わったら新しい ID を使います。失敗したタスクは自動で返金されます。アーティファクト URL は CDN アドレスです——速やかに自分のストレージへコピーしてください。

REST で呼び出す

プロトコル直結の統合では、固定の Idempotency-Key ヘッダーを付けて POST /v1/audio/speech-to-speech と共有タスクエンドポイントを使えます。生成されたAPI リファレンスを参照してください。推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタムアプリケーション向けです。