参照オーディオから音楽生成

Agent の主経路

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

1. ローカルの参照オーディオを beatra.assets.upload でアップロードし、その artifact ID を使います。Beatra の音楽タスクが成功産出した artifact も そのまま使えます。
2. モデル・参照制約・価格が結果に影響する場合は capability: "reference_audio_to_music" で beatra.models.list を 呼びます。そうでなければ model: "auto" を使うか model を省略します。
3. 不透明な client_request_id を 1 つ作り、最終的な引数を一度だけ送信します。
4. 返されたタスクを beatra.tasks.get で終端状態までポーリングします。

AI ガイド

ツール引数

{
  "prompt": "Keep the groove of the reference track, shift it to a festive mood",
  "reference_audio": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "client_request_id": "music-cover-opaque-1"
}

reference_audio は artifact、HTTPS URL、data URI を受け付けます。

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

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

選択可能なモデル、参照オーディオの長さ・サイズ・フォーマット制約 （constraints.reference_audio）、プロンプト・歌詞の上限、タスク単価の 最新の事実源は beatra.models.list です。モデルカタログや価格表を agent の プロンプトに複製しないでください。

すべてのコントロールがすべてのモデルで使えるわけではありません——たとえば インストゥルメンタルの参照オーディオリクエストには、それを支えるモデルが 必要です。未対応の組み合わせは黙って無視されず、バリデーションで失敗します。 音楽は前払いで、成功タスクごとに選択モデルのカタログ価格で課金されます。

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

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

成功したタスクはテキストから音楽生成 と同じ clips[] 構造を返します（output.type は reference_audio_to_music）。アーティファクト URL は CDN アドレスです—— 速やかに自分のストレージへコピーしてください。

REST で呼び出す

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