Freebeat 生成

# Freebeat 生成

画像生成、画像編集、テキスト動画生成を 1 つの Freebeat 入口で扱いたい場合に使います。

## CLI コマンドを実行する前に

Freebeat CLI は npm パッケージであり、認証付き API クライアントです。先にインストールまたは更新します:

~~~bash
npm install -g freebeat-cli@latest
freebeat --help
~~~

生成前に Freebeat API キーが必要です。次のいずれかを使います:

~~~bash
freebeat auth set-api-key
printf '%s' "$FREEBEAT_API_KEY" | freebeat auth set-api-key --stdin
freebeat --api-key <apiKey> <command>
~~~

有料または長時間のワークフローを始める前に認証情報を確認します:

~~~bash
freebeat auth show
freebeat auth test
~~~

生の API キーを貼り付けたりログに残したりしないでください。ユーザーの端末、シークレットストア、環境変数で渡してもらいます。

## 対応モデル値

画像モデル:

- Nano Banana 2: --model 80
- Nano Banana Pro: --model 64
- Wan V2.7 Image: --model 99
- Wan V2.7 Pro Image: --model 100
- GPT-Image 2: --model 108

動画モデル:

- Pixverse C1: --model pixverse-c1 or 103
- Pixverse V6: --model pixverse-v6 or 94
- Sora 2 Pro: --model sora-2-pro or 56
- Kling V3 4K: --model kling-v3-4k or 112
- SeedDance 2.0: --model seedance-2.0 or 102
- SeedDance 2.0 Fast: --model seedance-2.0-fast or 101
- Wan V2.7 Video: --model wan-v2.7-video or 104
- HappyHorse: --model happy-horse or 111

使用前に必ずモデルを確認します:

~~~bash
freebeat models list image
freebeat models list video
freebeat models help --name <model>
~~~

## 画像を生成

~~~bash
freebeat image generate --model 80 --prompt "ネオン都市のアルバムカバー" --size 1024x1024 --count 1 --wait
freebeat image generate --model 108 --prompt "電子音楽シングル向けの映画風アルバムカバー" --resolution 1024x1024 --quality medium --wait
~~~

## 画像を編集

~~~bash
freebeat image edit --model 80 --image ref.png --prompt "映画風でキャンペーン向けに仕上げる" --wait
freebeat image edit --model 108 --image https://cdn.example.com/ref.png --prompt "映画風にする" --resolution 1024x1024 --quality medium --wait
~~~

## 動画を生成

~~~bash
freebeat video generate --model pixverse-c1 --prompt "速いカット、ネオン都市、動きのあるカメラ" --duration 5 --resolution 720p --aspect-ratio 16:9 --wait
freebeat video generate --model sora-2-pro --prompt "光る音楽フェスを走る幻想的な夜のドライブ" --duration 8 --resolution 720p --aspect-ratio 16:9 --wait
freebeat video generate --model seedance-2.0 --prompt "素早い照明変化のあるエネルギッシュなダンス" --duration 5 --resolution 720p --aspect-ratio 9:16 --wait
~~~

## モデル別の注意点

- GPT-Image 2 は --model 108 を使います。freebeat-cli 0.1.2 以降では、省略時に --quality medium と --resolution 1024x1024 が送信されます。1024x1024、1024x1536、1920x1088 などを --resolution で明示できます。
- Pixverse C1 と Pixverse V6 は --generate-audio に対応します。
- Kling V3 4K には --resolution 4k が必要です。
- Sora 2 Pro は duration 4、8、12 に対応します。
- SeedDance 2.0 と SeedDance 2.0 Fast は 720p 出力に対応します。

## 進行状況を確認

Open RPC の画像・動画コマンドは batch id と serial number を返します。従来の MV・エフェクトコマンドは task id を返します。

~~~bash
freebeat task status <batch-id>
freebeat task status <batch-id> --serial-no <serial-no>
freebeat task wait <batch-id> --serial-no <serial-no>
freebeat task status <task-id>
freebeat task wait <task-id>
freebeat task result <task-id>
~~~

別の Agent、スクリプト、CI が task id、batch id、serial number、結果 URL、credits、status を解析する場合は --json を使います。