---
read_when:
    - エージェントによる音楽または音声の生成
    - 音楽生成プロバイダーとモデルの設定
    - music_generate ツールのパラメータを理解する
sidebarTitle: Music generation
summary: ComfyUI、fal、Google Lyria、MiniMax、OpenRouter のワークフローで music_generate を使用して音楽を生成する
title: 音楽生成
x-i18n:
    generated_at: "2026-07-26T09:48:08Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 3f2a8a4a36e47839c7896046a556f7bf84f6c168492e2de46736635fe2a9358e
    source_path: tools/music-generation.md
    workflow: 16
---

`music_generate` ツールは、ComfyUI、fal、Google、MiniMax、および
OpenRouter を基盤とする共有の音楽生成機能を通じて、音楽または音声を作成します。

<Note>
`music_generate` は、明示的な `agents.defaults.mediaModels.music` 設定、または
認証が設定されたプロバイダー（API キーが設定されている場合など）のうち、少なくとも 1 つの音楽生成プロバイダーが
利用可能な場合にのみ表示されます。
</Note>

セッションを基盤とするエージェント実行では、`music_generate` はバックグラウンドタスクとして開始され、
タスク台帳で進行状況を追跡した後、トラックの準備が完了するとエージェントを起動し、
ユーザーへの通知と完成した音声の添付を行えるようにします。完了処理を行う
エージェントは、セッションの可視返信契約に従います。設定されている場合は
自動的に最終返信を行い、セッションでメッセージツールが必要な場合は
`message(action="send")` を使用します。要求元のセッションが非アクティブであるか起動に失敗し、
生成された音声が返信にまだ含まれていない場合、OpenClaw は
不足している音声のみを含む冪等な直接フォールバックを送信します。

## クイックスタート

<Tabs>
  <Tab title="共有プロバイダーを使用">
    <Steps>
      <Step title="認証を設定">
        少なくとも 1 つのプロバイダーに API キーを設定します。たとえば
        `GEMINI_API_KEY` または `MINIMAX_API_KEY` です。
      </Step>
      <Step title="デフォルトモデルを選択（任意）">
        ```json5
        {
          agents: {
            defaults: {
              musicGenerationModel: {
                primary: "google/lyria-3-clip-preview",
              },
            },
          },
        }
        ```
      </Step>
      <Step title="エージェントに依頼">
        _「ネオンの街を夜にドライブすることをテーマにした、明るいシンセポップのトラックを生成してください。」_

        エージェントは `music_generate` を自動的に呼び出します。ツールを
        許可リストに追加する必要はありません。
      </Step>
    </Steps>

    セッションを基盤とするエージェント実行がない場合（直接またはローカルのコンテキスト）、
    ツールはインラインで実行され、同じツール結果で最終メディアパスを返します。

  </Tab>
  <Tab title="ComfyUI ワークフロー">
    <Steps>
      <Step title="ワークフローを設定">
        ワークフローの JSON とプロンプト／出力 Node を使用して
        `plugins.entries.comfy.config.music` を設定します。
      </Step>
      <Step title="クラウド認証（任意）">
        Comfy Cloud の場合は、`COMFY_API_KEY` または `COMFY_CLOUD_API_KEY` を設定します。
      </Step>
      <Step title="ツールを呼び出す">
        ```text
        /tool music_generate prompt="柔らかなテープの質感を伴う温かみのあるアンビエントシンセのループ"
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

プロンプトの例：

```text
柔らかなストリングスを伴い、ボーカルのない映画的なピアノトラックを生成してください。
```

```text
日の出にロケットを打ち上げることをテーマにした、エネルギッシュなチップチューンのループを生成してください。
```

利用可能なプロバイダー／モデルを確認するには `action: "list"` を使用し、
セッションを基盤とするアクティブな音楽タスクを確認するには
`action: "status"` を使用します。

```text
/tool music_generate action=list
/tool music_generate action=status
```

直接生成の例：

```text
/tool music_generate prompt="ビニールの質感と穏やかな雨音を伴う、夢のようなローファイ・ヒップホップ" instrumental=true
```

## 対応プロバイダー

| プロバイダー | デフォルトモデル             | 参照入力       | 対応する制御                                            | 認証                                   |
| ---------- | ---------------------------- | ---------------- | ----------------------------------------------------- | -------------------------------------- |
| ComfyUI    | `workflow`                   | 最大 1 枚の画像 | ワークフローで定義された音楽または音声                       | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| fal        | `fal-ai/minimax-music/v2.6`  | なし             | `lyrics`, `instrumental`, `durationSeconds`, `format` | `FAL_KEY` または `FAL_API_KEY`             |
| Google     | `lyria-3-clip-preview`       | 最大 10 枚の画像 | `lyrics`, `instrumental`, `format`                    | `GEMINI_API_KEY`, `GOOGLE_API_KEY`     |
| MiniMax    | `music-2.6`                  | なし             | `lyrics`, `instrumental`, `format`（mp3 のみ）         | `MINIMAX_API_KEY` または MiniMax OAuth     |
| OpenRouter | `google/lyria-3-pro-preview` | 最大 1 枚の画像 | `lyrics`, `instrumental`, `durationSeconds`, `format` | `OPENROUTER_API_KEY`                   |

MiniMax は、同じモデルを共有する 2 つのプロバイダー ID を登録します。API キー認証用の
`minimax` と OAuth 用の `minimax-portal` です。モデル参照は認証経路に従います
（`minimax/music-2.6` と `minimax-portal/music-2.6`）。詳しくは
[MiniMax](/ja-JP/providers/minimax#music-generation) を参照してください。

fal は、デフォルトの MiniMax ベースのモデルに加えて、`fal-ai/ace-step/prompt-to-audio`（wav、歌詞なし、
インストゥルメンタル切り替えなし）と `fal-ai/stable-audio-25/text-to-audio`（wav、
プロンプトのみ）も提供します。Google のデフォルトである
`lyria-3-clip-preview` は mp3 のみを出力し、`lyria-3-pro-preview` は
wav にも対応します。MiniMax は `music-2.6-free`、`music-cover`、および
`music-cover-free` も提供します。OpenRouter は `google/lyria-3-clip-preview` も提供します。

### 機能マトリクス

`music_generate`、契約テスト、および共有ライブスイープで使用される
明示的なモード契約：

| プロバイダー | `generate` | `edit` | 編集上限   | 共有ライブレーン                                                         |
| ---------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------- |
| ComfyUI    |     ✓      |   ✓    | 1 枚の画像 | 共有スイープには含まれず、`extensions/comfy/comfy.live.test.ts` で対象となります |
| fal        |     ✓      |   —    | なし       | `generate`                                                                |
| Google     |     ✓      |   ✓    | 10 枚の画像 | `generate`, `edit`                                                        |
| MiniMax    |     ✓      |   —    | なし       | `generate`                                                                |
| OpenRouter |     ✓      |   ✓    | 1 枚の画像 | `generate`, `edit`                                                        |

## ツールパラメーター

<ParamField path="prompt" type="string" required>
  音楽生成プロンプト。`action: "generate"` では必須です。
</ParamField>
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
  `"status"` は現在のセッションタスクを返し、`"list"` はプロバイダーを確認します。
</ParamField>
<ParamField path="model" type="string">
  プロバイダー／モデルの上書き（例：`google/lyria-3-pro-preview`、
  `comfy/workflow`）。
</ParamField>
<ParamField path="lyrics" type="string">
  プロバイダーが明示的な歌詞入力に対応している場合の任意の歌詞。
</ParamField>
<ParamField path="instrumental" type="boolean">
  プロバイダーが対応している場合、インストゥルメンタルのみの出力を要求します。
</ParamField>
<ParamField path="image" type="string">
  単一の参照画像のパスまたは URL。
</ParamField>
<ParamField path="images" type="string[]">
  複数の参照画像（対応プロバイダーでは最大 10 枚）。
</ParamField>
<ParamField path="durationSeconds" type="number">
  プロバイダーが再生時間のヒントに対応している場合の、秒単位の目標再生時間。
</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>
  プロバイダーが対応している場合の出力形式のヒント。
</ParamField>
<ParamField path="filename" type="string">出力ファイル名のヒント。</ParamField>

<Note>
すべてのプロバイダーがすべてのパラメーターに対応しているわけではありません。OpenClaw は送信前に、
入力数などの厳格な上限を引き続き検証します。プロバイダーが再生時間に対応していても、
要求された値より短い最大値を使用する場合、OpenClaw は最も近い対応再生時間に
制限します。選択したプロバイダーまたはモデルが対応できない、真に未対応の任意のヒントは、
警告とともに無視されます。ツール結果では適用された設定が報告され、
`details.normalization` に要求値から適用値へのマッピングが記録されます。
</Note>

プロバイダー要求のタイムアウトは、オペレーター向け設定でのみ指定できます。OpenClaw は、設定されている場合は
`agents.defaults.mediaModels.music.timeoutMs` を使用し、
120000ms 未満の値を 120000ms に引き上げ、それ以外の場合はプロバイダー要求の
デフォルトを 300000ms に設定します。

## 非同期動作

セッションを基盤とする音楽生成は、バックグラウンドタスクとして実行されます。

- **バックグラウンドタスク：** `music_generate` はバックグラウンドタスクを作成し、開始済み／タスクの応答を
  直ちに返した後、完成したトラックを後続のエージェントメッセージで
  投稿します。
- **重複防止：** タスクが `queued` または `running` の間は、
  同じセッション内で後から行われた `music_generate` 呼び出しは、
  別の生成を開始する代わりにタスクの状態を返します。明示的に確認するには `action: "status"` を使用します。
  最近完了した同一の要求も 2 分間重複排除されます。
- **状態の確認：** `openclaw tasks list` または `openclaw tasks show <taskId>` は、
  キュー待ち、実行中、および終了状態を確認します。
- **完了時の起動：** OpenClaw は内部の完了イベントを同じセッションに
  挿入し、モデル自身がユーザー向けの後続メッセージを作成できるようにします。
- **プロンプトのヒント：** 同じセッションで後から行われるユーザー／手動ターンでは、
  音楽タスクがすでに実行中の場合に小さなランタイムヒントが提示されるため、モデルが
  `music_generate` を無条件に再度呼び出すことを防ぎます。
- **セッションなしのフォールバック：** 実際のエージェントセッションがない直接／ローカルのコンテキストでは
  インラインで実行され、同じターンで最終的な音声結果を返します。

### タスクのライフサイクル

音楽タスクは一般的なタスクレジストリと同じ状態を公開します（`timed_out`、
`cancelled`、および `lost` を含む完全な状態機械については、
[バックグラウンドタスク](/ja-JP/automation/tasks#task-lifecycle) を参照してください）。ほとんどの音楽実行は
次の状態を経由します。

| 状態       | 意味                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `queued`    | タスクが作成され、プロバイダーが受け入れるのを待機しています。                                           |
| `running`   | プロバイダーが処理中です（通常、プロバイダーと再生時間に応じて 30 秒から 3 分）。 |
| `succeeded` | トラックの準備が完了し、エージェントが起動して会話に投稿します。                                 |
| `failed`    | プロバイダーエラーまたはタイムアウト。エージェントがエラーの詳細とともに起動します。                                 |

CLI から状態を確認します。

```bash
openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```

## 設定

### モデルの選択

```json5
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
        fallbacks: ["fal/fal-ai/minimax-music/v2.6", "minimax/music-2.6"],
      },
    },
  },
}
```

### プロバイダーの選択順序

OpenClaw は次の順序でプロバイダーを試します。

1. ツール呼び出しの `model` パラメーター（エージェントが指定した場合）。
2. 設定の `musicGenerationModel.primary`。
3. 順番に `musicGenerationModel.fallbacks`。
4. 認証を基盤とするプロバイダーのデフォルトのみを使用した自動検出：
   - 現在のデフォルトテキストモデルのプロバイダーが音楽生成にも対応している場合は、
     そのプロバイダーが最初。
   - 残りの登録済み音楽生成プロバイダーを、
     プロバイダー ID のアルファベット順。

プロバイダーが失敗した場合、次の候補が自動的に試行されます。すべてが
失敗した場合、エラーには各試行の詳細が含まれます。

認証済みプロバイダー間の自動フォールバックは常に有効です。呼び出しごとの
`model` が優先されます。

## プロバイダーに関する注意事項

<AccordionGroup>
  <Accordion title="ComfyUI">
    ワークフロー駆動型であり、設定されたグラフと、プロンプトおよび出力フィールドの
    ノードマッピングに依存します。バンドルされた `comfy` Plugin は、
    音楽生成プロバイダーレジストリを通じて共有 `music_generate` ツールに
    接続されます。
  </Accordion>
  <Accordion title="fal">
    共有プロバイダー認証パスを通じて fal モデルエンドポイントを使用します。
    バンドルされたプロバイダーのデフォルトは `fal-ai/minimax-music/v2.6` で、
    プロンプトから音声を生成するリクエスト向けに `fal-ai/ace-step/prompt-to-audio` と
    `fal-ai/stable-audio-25/text-to-audio` も公開します。
    歌詞とインストゥルメンタルモードは MiniMax モデルでのみ使用でき、
    ほかの2つのモデルはプロンプトのみに対応します。
  </Accordion>
  <Accordion title="Google (Lyria 3)">
    Lyria 3 のバッチ生成を使用します。現在バンドルされているフローは、
    プロンプト、任意の歌詞テキスト、任意の参照画像に対応します。
    デフォルトの `lyria-3-clip-preview` モデルは mp3 のみを出力し、
    `lyria-3-pro-preview` モデルは wav にも対応します。
  </Accordion>
  <Accordion title="MiniMax">
    バッチ `music_generation` エンドポイントを使用します。プロンプト、任意の
    歌詞、インストゥルメンタルモード、および `minimax` API キー認証
    または `minimax-portal` OAuth による mp3 出力に対応します。
    `music-2.6-free`、`music-cover`、`music-cover-free` モデルも公開します。
  </Accordion>
  <Accordion title="OpenRouter">
    ストリーミングを有効にした OpenRouter チャット補完の音声出力を使用します。
    バンドルされたプロバイダーのデフォルトは `google/lyria-3-pro-preview` で、
    `openrouter/google/lyria-3-clip-preview` も公開します。
  </Accordion>
</AccordionGroup>

## 適切なパスの選択

- モデルの選択、プロバイダーのフェイルオーバー、および組み込みの非同期タスク／ステータスフローが必要な場合は、**共有プロバイダー基盤**。
- カスタムワークフローグラフ、または共有のバンドル済み音楽機能に含まれないプロバイダーが必要な場合は、**Plugin パス（ComfyUI）**。

ComfyUI 固有の動作をデバッグする場合は、
[ComfyUI](/ja-JP/providers/comfy)を参照してください。共有プロバイダーの
動作をデバッグする場合は、[fal](/ja-JP/providers/fal)、[Google（Gemini）](/ja-JP/providers/google)、
[MiniMax](/ja-JP/providers/minimax)、または[OpenRouter](/ja-JP/providers/openrouter)から始めてください。

## プロバイダー機能モード

共有の音楽生成コントラクトは、明示的なモード宣言に対応しています。

- プロンプトのみの生成には `generate`。
- リクエストに1つ以上の参照画像が含まれる場合は `edit`。

新しいプロバイダー実装では、明示的なモードブロックを使用することを推奨します。

```typescript
capabilities: {
  generate: {
    maxTracks: 1,
    supportsLyrics: true,
    supportsFormat: true,
  },
  edit: {
    enabled: true,
    maxTracks: 1,
    maxInputImages: 1,
    supportsFormat: true,
  },
}
```

`maxInputImages`、`supportsLyrics`、`supportsFormat` などの
従来のフラットフィールドだけでは、編集対応を示すには**不十分**です。ライブテスト、
コントラクトテスト、および共有 `music_generate` ツールがモード対応を
決定論的に検証できるように、プロバイダーは `generate` と
`edit` を明示的に宣言する必要があります。

## ライブテスト

共有のバンドル済みプロバイダー（fal、Google、MiniMax、OpenRouter）向けの
オプトイン式ライブカバレッジ：

```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
```

同じテストファイルを実行する、同等のリポジトリラッパー：

```bash
pnpm test:live:media:music
```

このライブファイルは、デフォルトで保存済み認証プロファイルより先に、すでに
エクスポートされているプロバイダー環境変数を使用します。また、プロバイダーが
編集モードを有効にしている場合は、`generate` と宣言済みの
`edit` の両方のカバレッジを実行します。現在のカバレッジ：

- `google`：`generate` と `edit`
- `fal`：`generate` のみ
- `minimax`：`generate` のみ
- `openrouter`：`generate` と `edit`
- `comfy`：共有プロバイダーの一括テストとは別の Comfy ライブカバレッジ

バンドルされた ComfyUI 音楽パス向けのオプトイン式ライブカバレッジ：

```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```

Comfy ライブファイルは、該当セクションが設定されている場合、Comfy の画像および
動画ワークフローも対象にします。

## 関連項目

- [バックグラウンドタスク](/ja-JP/automation/tasks) — 切り離された `music_generate` 実行のタスク追跡
- [ComfyUI](/ja-JP/providers/comfy)
- [設定リファレンス](/ja-JP/gateway/config-agents#agent-defaults) — `musicGenerationModel` の設定
- [Google（Gemini）](/ja-JP/providers/google)
- [MiniMax](/ja-JP/providers/minimax)
- [モデル](/ja-JP/concepts/models) — モデルの設定とフェイルオーバー
- [ツールの概要](/ja-JP/tools)
