# 参照オーディオから音楽生成
> 参照オーディオのスタイルをベースに新しい音楽を生成します。

参照オーディオのスタイルをベースに新しい音楽を生成します。

## 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 ガイド

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

## ツール引数

```json
{
  "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 を使います。失敗したタスクは自動で返金されます。

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

## REST で呼び出す

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