オーディオ処理・ボーカル抽出・ステム分離

ノイズの多い録音や背景音楽からクリアな発話・ボーカルを抽出したり、ミックス済みの楽曲をステムに分離したり、トリム、シームレスなループ延長、フェード、EBU R128 ラウドネス正規化、形式変換などの決定論的なオーディオ処理を行います。

Agent の主経路

Universal Skill から MCP ツール beatra.audio.process を使います。1 つのツールで operation フィールドにより 3 つの機能系統すべてを扱い、どの呼び出しも課金対象の非同期タスクを返します。

1. ローカルのオーディオを beatra.assets.upload でアップロードし、返された artifact_id を source（MCP・REST ともにエイリアス audio も可）に渡します（または https_url を直接渡します）。speech:generate と music:generate のいずれかのスコープを持つトークンで beatra.audio.process を呼び出せます。
2. 制限、対応フォーマット、最新価格を確認する場合は、該当する capability を指定して beatra.models.list を呼びます。
3. 不透明な client_request_id を 1 つ作り、一度だけ送信して beatra.tasks.get で終端状態までポーリングします。

AI ガイド

ボーカル抽出

operation: "isolate_voice"（elevenlabs-audio-isolation、REST POST /v1/audio/isolation）は、背景音楽、部屋の残響、風切り音、交通騒音、雑踏を取り除き、クリアな発話やボーカルだけを抽出します。ボイスクローン、音声文字起こし、スピーチ変換の前にノイズの多い録音をクリーニングする用途に適しています。

{
  "operation": "isolate_voice",
  "source": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "format": "wav",
  "client_request_id": "isolate-opaque-1"
}

• 入力の制限：長さは 4.6 秒以上 300.0 秒（5 分）以下、ファイルサイズは 100 MB 以下です。4.6 秒未満または 300.0 秒超のクリップは課金前に 422 invalid_request（details.reason: "audio_too_short" または "audio_too_long"）で拒否され、クレジットは消費されません。MCP の beatra.audio.process と REST の POST /v1/audio/isolation のどちらでも入力参照として source と audio の両方を受け付けます（旧モデル名エイリアス "beatra-voice-isolate-v1" も "elevenlabs-audio-isolation" として正規化されます）。
• 任意の出力フォーマット指定：isolate_voice が受け付けるのは format（既定 "wav"、ほか "mp3"、"ogg"、"flac"、"m4a"、"ulaw_8k_wav"）、sample_rate（8000、16000、22050、24000、32000、44100、48000 Hz）、bitrate_kbps（非可逆の "mp3"、"ogg"、"m4a" で 64、128、192、256、320。"m4a" は最大 256）、channels（1 または 2）のみです。fade_in_ms、fade_out_ms、loudness_lufs、true_peak_db は isolate_voice には渡せません（必要な場合は抽出後に下記の決定論的オーディオ処理ユーティリティを呼び出してください）。
• コストと出力：入力音声の切り上げ分数に基づく前払いで、切り上げ 1 分あたり 721 クレジット です（60 秒以下は 721 クレジット、5 分は 3,605 クレジット）。伴奏ステムは作らず、抽出したボーカルのみを outputs: [{"role": "voice", ...}] に返します。

ステム分離

operation: "separate_stems"（beatra-stems-v1、REST POST /v1/audio/stems）は、ミックス済みの楽曲（最長 600 秒 / 10 分、100 MB 以下）をボーカルと各楽器のステムに分離します。

{
  "operation": "separate_stems",
  "source": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "mode": "two_stem",
  "client_request_id": "stems-opaque-1"
}

• mode: "two_stem"（既定、1 タスク 180 クレジット）：vocals（ボーカル）と instrumental（インストゥルメンタル、outputs[].role は "vocals"、"instrumental"）を返します。
• mode: "multi_stem"（1 タスク 360 クレジット）：最大 6 つのステム（vocals、drums、bass、guitar、piano、other、outputs[].role は "stem:vocals"、"stem:drums"、"stem:bass"、"stem:guitar"、"stem:piano"、"stem:other"）に分離します。
• 出力フォーマットはステム分離モデル側で決まり、separate_stems は format やローカル後処理パラメーターを受け付けません。

決定論的オーディオ処理ユーティリティ

beatra-audio-v1（REST POST /v1/audio/process）は、最長 3,600 秒（60 分、300 MB 以下）のオーディオに対して決定論的な後処理を 1 タスク一律 60 クレジット で実行します。

• trim：start_ms（>= 0、既定 0）と、end_ms（> start_ms）または target_duration_ms のいずれか一方を指定して区間を切り出します。
• loop：全体または部分区間（loop_start_ms 既定 0、loop_end_ms。ループ区間は 4,000 ミリ秒以上）を、target_duration_ms（1,000〜3,600,000 ミリ秒）または loop_count（2〜100 回）のいずれか一方でループ延長します。crossfade_ms（50〜3,000 ミリ秒、既定 500 ミリ秒）と end_with_fade（真偽値、既定 true）を指定できます。
• fade：fade_in_ms および／または fade_out_ms（0〜30,000 ミリ秒、少なくとも一方を指定）と fade_curve（既定 "tri"、ほか "exp"、"log"、"qsin"）でフェードをかけます。
• normalize_loudness：2 パスの EBU R128 ラウドネス正規化を行い、loudness_lufs（-30.0〜-9.0 LUFS、既定 -14.0）と true_peak_db（-9.0〜0.0 dBTP、既定 -1.0）に揃えます。
• convert_format：必須の format（"mp3"、"wav"、"ogg"、"flac"、"m4a"、または 8 kHz モノラル電話音声用 "ulaw_8k_wav"）へ変換・リサンプリングします（任意の sample_rate、bitrate_kbps、channels に対応）。
• 上記の決定論的操作ではいずれも、同一タスク内で任意の仕上げ指定（fade_in_ms、fade_out_ms、fade_curve、loudness_lufs、true_peak_db、format、sample_rate、bitrate_kbps、channels）を併用できます。

結果

すべての操作で "type": "audio_process"、"operation"、"outputs" が返ります（separate_stems では "mode"、決定論的ユーティリティでは "metrics" と "steps" も含まれます）。各 outputs[] 要素には role（isolate_voice は "voice"、two_stem は "vocals" / "instrumental"、multi_stem は "stem:<kind>"、決定論的ユーティリティは "main"）、artifact_id、CDN の url、mime_type、duration_seconds が入り、"role": "main" のみ計測された loudness_lufs と true_peak_db も含まれます。

{
  "type": "audio_process",
  "operation": "isolate_voice",
  "outputs": [
    {
      "role": "voice",
      "artifact_id": "artifact_01JZ...",
      "url": "https://cdn.beatra.ai/tenants/.../voice.wav",
      "mime_type": "audio/wav",
      "duration_seconds": 18.4
    }
  ]
}

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

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

REST で呼び出す

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