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

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

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

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

## ツール引数

```json
{
  "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 と MiniMax Music 3.0

選択可能な音楽生成モデルには **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 定義](https://docs.beatra.ai/ja/docs/api-reference/operations/music/text_to_music_v1_music_text_to_music_post)
に従ってください。推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタム
アプリケーション向けです。