テキストから音楽生成

Agent の主経路

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

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

AI ガイド

ツール引数

{
  "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 指定が 必要です。未対応の組み合わせは黙って無視されず、バリデーションで失敗します。 音楽は前払いで、成功タスクごとに選択モデルのカタログ価格で課金されます。

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

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

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

REST で呼び出す

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