# スピーチ変換（ボイスチェンジャー）
> 元の録音のタイミング、間の取り方、感情表現を保ったまま、音声を対象のボイスに変換します。

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

## Agent の主経路

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

1. まずスピーチ変換に対応する対象ボイスを選びます。`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 クローンボイス）のみです。
2. 元の音声ファイルを `beatra.assets.upload` でアップロードし、返された `artifact_id` を使います（または `https_url` を直接渡します）。
3. 不透明な `client_request_id` を 1 つ作り、最終的な引数を一度だけ送信します。
4. `beatra.tasks.get` で終端状態までポーリングします。

## AI ガイド

AI integration guide: https://docs.beatra.ai/llms/audio-speech-to-speech.md

## ツール引数

```json
{
  "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`（[ボイス管理](https://docs.beatra.ai/ja/docs/capabilities/speech/voices)を参照）。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 や強い屋外ノイズが含まれる場合は、先に[ボーカル抽出](https://docs.beatra.ai/ja/docs/capabilities/speech/audio-processing#ボーカル抽出)を実行してください。
- `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 の[音声合成](https://docs.beatra.ai/ja/docs/capabilities/speech/text-to-speech#上限とエラー)とアカウントごとの**同時実行 2 件の上限**（`429 rate_limited`、`details.reason: speech_inflight_limit`）を共有します。
- `voice` に ElevenLabs の[クローンボイス](https://docs.beatra.ai/ja/docs/capabilities/speech/voice-clone#elevenlabs明示指定成功時に利用可能)を指定した場合、必要に応じて保存済みサンプルから自動的にボイスを準備・復元してから変換します。

## 結果

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

```json
{
  "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` を[音声文字起こし](https://docs.beatra.ai/ja/docs/capabilities/speech/speech-to-text)に渡してください。

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

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

## REST で呼び出す

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