テキストから音楽生成

テキストの説明と歌詞から、ボーカル曲またはインストゥルメンタル楽曲を生成します。

Agent の主経路

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

産出物を確定します：ボーカル入りかインストか、ムード、ユーザーが歌詞を提供するか。
モデル・コントロール・制約・価格が結果に影響する場合は capability: "text_to_music" で beatra.models.list を呼びます。そうでなければ model: "auto" を使うか model を省略します。
不透明な client_request_id を 1 つ作り、最終的な引数を一度だけ送信します。
返されたタスクを beatra.tasks.get で終端状態までポーリングします。

AI ガイド

AI 連携 Markdown

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

Markdown

ツール引数

{
  "prompt": "Upbeat city pop for a summer evening drive",
  "instrumental": false,
  "lyrics": "Evening wind sweeps across the rooftop\nNeon lights flicker on one by one",
  "client_request_id": "music-text-opaque-1"
}

instrumental: true はインストゥルメンタルのみを生成し、lyrics を同時に指定できません。

モデル・コントロール・コスト

共通コントロールは prompt、lyrics、instrumental、title、 model_options です。各コントロールは選択したモデルのメタデータに従ってのみ使用します。

選択可能なモデル、プロンプト・歌詞の長さ上限、ボーカル歌詞の要件、モデルファミリーオプション、タスク単価の最新の事実源は beatra.models.list です。モデルカタログや価格表を agent のプロンプトに複製しないでください。

model_options.* のモデルファミリーオプションには明示的な model 指定が必要です。未対応の組み合わせは黙って無視されず、バリデーションで失敗します。音楽は前払いで、成功タスクごとに選択モデルのカタログ価格で課金されます。

選択可能な音楽生成モデルには Suno 6（suno-v6、suno-v5.5、suno-v5、suno-v4.5）および MiniMax Music 3.0（minimax-music-3.0、minimax-music-2.6）が含まれます。どちらもセクションタグ（[Verse]、[Chorus]、[Bridge]、[Outro]）付きのフルボーカル楽曲と、インストゥルメンタル生成（instrumental: true）の両方に対応しています。最新の 1 曲あたりのクレジット価格やモデル固有オプションは capability: "text_to_music" で beatra.models.list を呼び出して確認してください。

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

queued と running は失敗ではありません。同じ task_id をポーリングし続け、実行中だからといって代替リクエストを送らないでください。作成応答を失った場合は、同じ client_request_id で同一の引数を再送します。入力が少しでも変わったら新しい ID を使います。失敗したタスクは自動で返金されます。

成功したタスクは 1 つ以上の clips[] を返し、それぞれにタイトル、任意の歌詞、音声アーティファクトが含まれます。アーティファクト URL は CDN アドレスです——速やかに自分のストレージへコピーしてください。

REST で呼び出す

プロトコル直結の統合は POST /v1/music/text-to-music と共有タスクエンドポイントを使えます。生成された API 定義に従ってください。推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタムアプリケーション向けです。