Algovate/agnes-image

Agnes 生圖

agnes-img 是 agnes image generate 的包裝：同樣的參數，額外支援 2.5 模型和自動降級。 當前 2.5（agnes-image-2.5-flash）是預設，2.1（agnes-image-2.1-flash）作為降級與相容檔。

前置檢查

agnes key status

• "status": "missing" 表示未設定 Key。讓用戶打開 https://platform.agnes-ai.com 產生 API Key，然後執行 agnes key set <KEY>（寫入本地設定）或設定環境變數 AGNES_API_KEY。
• 不要編造 Key，也不要把 Key 寫進專案檔案或回覆正文。

模型選擇

需求	用法
預設（正式交付）	什麼都不傳 → agnes-image-2.5-flash
指定 2.1	--model 2.1
改預設檔	環境變數 AGNES_IMAGE_MODEL=2.1
關掉自動降級	--no-fallback（或 AGNES_IMAGE_FALLBACK=0）

• 優先級：--model > AGNES_IMAGE_MODEL > 預設 2.5。
• 2.5 回傳 5xx 時會自動用 2.1 重試一次，stderr 會印出 role=fallback；回覆裡應說明實際用的模型。
• stderr 總會印出 generated with <model>，據此在回覆中標註模型。

文生圖

agnes-img --prompt "描述" --size 2K

• 成功時 stdout 只有圖片 URL，模型名/任務 ID/降級資訊/錯誤走 stderr。
• --size 支援檔位 1K / 2K / 3K / 4K，也相容 1024x768 這類精確值（預設 1024x768）。
• 檔位預設 1:1；需要 16:9、9:16 等比例時傳對應的原生尺寸，例如 16:9 用 1312x736（1K）或 2624x1472（2K），9:16 用 736x1312。

圖生圖與多圖合成

agnes-img --prompt "改成賽博龐克夜景" --image ./ref.png
agnes-img --prompt "融合這兩張參考圖做海報" --image ./a.png --image ./b.png

• --image 可重複，支援本地路徑、公網 URL 或 Data URI；本地檔案會自動轉成 Data URI。
• 改圖時提示詞寫"保留什麼、改變什麼"效果更穩。

儲存與展示（必做）

URL 是臨時連結，必須下載到工作區：

mkdir -p output output/drafts
curl -sSL "<URL>" -o "output/agnes-$(date +%Y%m%d-%H%M%S).png"
ls -l output/*.png

• 確認檔案非空（file / 大小 > 0）後再交付。
• 用 read_image 預覽成圖；回覆裡用 ![說明](output/xxx.png) 展示，或按需 present。

輸出目錄約定（必須遵守）

output/                       交付圖，永久保留
  <subject>.png               主題主圖，如 eagle-hare.png
  <subject>-<variant>.png     同主題的另一種交付風格，如 eagle-hare-ink.png
output/drafts/                中間稿 / 被取代的版本，7 天後可清
  <subject>-<variant>-<YYYYMMDD-HHMM>.png

規則：

1. 交付圖直接落到 output/<主題>.png；命名用小寫連字號、英文語意化，不要 -v2、-final、-副本 這類暫字尾。
2. 被新版本取代的舊圖，在新圖確認交付後 mv 到 output/drafts/<主題>-<時間戳>.png，不要留在 output/ 裡混淆。
3. 沒打算交付的試驗稿（試構圖、試參數）直接寫 output/drafts/。
4. 清理一律用 agnes-gc，不要手動 rm 整個 output：

agnes-gc              # 預覽：drafts 中超過 7 天的
agnes-gc --apply      # 執行
agnes-gc --all        # 預覽：清空 drafts

agnes-gc 只允許作用於名為 drafts 的目錄，output/ 裡的交付圖永遠不會被它刪除。

常見問題

• {"ok":false,"error":{"type":"auth",...}}：Key 未設定或失效，先 agnes key status。
• type: "validation"：參數不合法（例如不支援的 model、缺少 --prompt），按 hint 修正，不要盲目重試。
• 2.5 報 5xx：會自動降級到 2.1；若 stderr 出現 role=fallback，說明這次是降級產物，交付時要說明。
• 生成通常 10–60 秒，Bash 逾時至少設 180000 ms。
• 一次只跑一個生成任務，避免並發刷額度。

相容說明

舊的 agnes image generate 仍然可用，但 --model 只接受 agnes-image-2.1-flash / agnes-image-2.0-flash，不支援 2.5。需要 2.5 或自動降級時一律用 agnes-img。