GPT Image CLI
使用 gpt-image CLI 來產生使用者要求的圖片，並回傳其本機路徑。需要 Node.js 22+。預設模型為 gpt-image-2.6-flare；品質預設為 API 的 auto。除非使用者選擇其他設定，否則請保留這些預設值。
尋找 CLI 與設定
當已安裝 gpt-image 指令時，優先使用它。否則，使用 npm 從公開儲存庫直接執行已發行的 CLI：
npx --yes --package=github:zsio/openai-image-cli#v1.0.0 gpt-image --help
在後續範例中，使用相同的前綴來替代 gpt-image。當技能安裝在沒有獨立 CLI 安裝的機器上時，這個方法也適用。它不需要檢出程式碼或機器特定的路徑。
使用 gpt-image config show 檢查設定。只有 OPENAI_API_KEY 是必要的；大小、模型、品質、格式與輸出位置都有預設值。CLI 會優先讀取環境變數，然後讀取位於 ${XDG_CONFIG_HOME:-$HOME/.config}/gpt-image/.env 的使用者設定檔。gpt-image config path 會印出解析後的路徑。請尊重明確選擇的 --config 或 GPT_IMAGE_CONFIG。
如果未設定金鑰，請視需要執行 gpt-image config init，並告知使用者在本機檔案中填入 OPENAI_API_KEY。將金鑰保留在原始碼儲存庫和技能檔案之外；不要要求使用者將金鑰貼到對話中、列印出來，或將其放在命令參數中。使用 config show 檢查金鑰是否存在，切勿透過顯示設定檔來檢查。不要為了檢查設定而生成範例圖片；請使用 --dry-run 來預覽請求。
生成或編輯
對於新圖片，將提示作為單一參數傳遞。對於長提示或多行提示，請撰寫一個 UTF-8 提示檔，並使用 --prompt-file。
gpt-image generate "一隻戴著紅色圍巾的水彩小貓" --name kitten --json
gpt-image generate --prompt-file ./prompt.txt --out-dir ./assets --name cover --json
對於編輯或基於參考的生成，請使用 edit，並重複 --image 來指定多張參考。輸入順序很重要：第一張圖片是遮罩或標記層的主要圖片。
gpt-image edit "將背景改為雪山；保留人物的臉部和服裝" \
--image ./portrait.png --name snowy-portrait --json
gpt-image edit "將兩個產品放在同一張白色背景的產品照片中" \
--image ./product-a.png --image ./product-b.jpg --name product-pair --json
gpt-image edit "將透明遮罩區域替換為一個藍色花瓶" \
--image ./room.png --mask ./mask.png --name blue-vase --json
使用 --background transparent --format png 來產生透明去背的剪影或貼紙。對於現有透明資源的編輯，當這是請求的一部分時，請保留透明度。--mask 和 --markup 接受 PNG 檔案，且不能同時使用；它們的尺寸必須與第一張圖片相符。最多支援 16 張參考圖片，包括本機 PNG/JPEG/WebP、圖片 URL 和 OpenAI 檔案 ID。
提示應保留使用者的主題、精確要求的文字、風格和限制條件。對於編輯，請同時說明所需的變更和要保留的細節。不要擅自更改要求的圖片數量、模型或品質。每次 CLI 呼叫會產生一張最終圖片；重試功能已停用，因此在決定是否需要另一個收費請求之前，請先檢查失敗原因。
輸出與實用選項
- 預設輸出為系統暫存目錄中的唯一
name-YYYYMMDD-HHmmss-SSS-suffix資料夾。使用--name來設定實用的短檔名。 - 使用
--output FILE指定確切檔案路徑，或使用--out-dir DIR --name NAME指定目標目錄。這些選項不能同時使用。現有輸出檔案會保留。 - 使用
--json來讀取image_path、metadata_path、prompt_path、request_id和 API 使用量。進度資訊會輸出至 stderr。回傳實際儲存的圖片路徑；必要時使用可用的本機圖片檢視器預覽圖片。 --size WIDTHxHEIGHT、--quality auto|low|medium|high|xhigh|max、--background auto|opaque|transparent，以及--format png|jpeg|webp|gif|svg對應至 API 設定。仍適用模型/專案支援限制。- 當使用者選擇專門用於詳細視覺工作的分支時，使用
--model gpt-image-2.6-sunburst。對於未指定模型偏好的普通請求，請保留 Flare。 --stream --partial-images 1會儲存一個預覽以及最終圖片。只有完整的圖片才是最終結果。--params '{"complexity":"medium"}'或--params @params.json會傳遞額外的 API 欄位。n固定為 1。在使用不常見的選項之前，請先閱讀gpt-image --help。--timeout SECONDS涵蓋整個請求。如果發生逾時/取消，服務可能已經接受了該請求。請勿自動重新提交。
CLI 與 API 詳細資訊：https://github.com/zsio/openai-image-cli