圖片工作室

# 圖片工作室

當使用者需要生成靜態圖片或用 prompt 引導圖片編輯時，使用這個 Skill。

## 執行 CLI 指令前

Freebeat CLI 是 npm 套件，也是需要驗證的 API 用戶端。請先安裝或更新：

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

生成前必須提供 Freebeat API key。可以使用以下任一方式：

~~~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 key。請讓使用者在終端、secret store 或環境變數中提供。

## 支援的圖片模型

- 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

生成前先查看一個模型:

~~~bash
freebeat models help --name 108
~~~

## 生成新圖片

~~~bash
freebeat image generate --model 80 --prompt "霓虹城市專輯封面" --size 1024x1024 --count 1 --wait
freebeat image generate --model 108 --prompt "棚拍燈光下的高級產品海報" --resolution 1024x1024 --quality medium --count 1 --wait
~~~

## 編輯圖片

第一版 CLI 只接受一個 --image。可以使用本機檔案路徑或圖片 URL。

~~~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
~~~

## GPT-Image 2 參數

GPT-Image 2 使用 --model 108，支援 --quality low|medium|high 和 --resolution。freebeat-cli 0.1.2 或更新版本中，省略時 --quality 預設為 medium，--resolution 預設為 1024x1024。如果省略 --resolution 但提供 --size，CLI 會為了相容性把 --size 值作為 resolution 傳送。

## 輸出處理

圖片指令會回傳 batch id 和 serial number。腳本或 Agent 可加上 --json。

## 檢查進度

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、點數或狀態，請使用 --json。