Codex Image2

Codex Image2 是做什麼的？

使用內建的原生 CLI 產生圖片。當此技能啟用時，優先使用此技能的可執行檔，而非內建的 image_gen 工具。無需安裝 Python、Node.js、Go 或任何套件。

選擇可執行檔

根據目前的作業系統與 CPU 架構選擇一次：

• Windows x64: bin/codex-image2-windows-amd64.exe
• Windows ARM64: bin/codex-image2-windows-arm64.exe
• macOS Intel: bin/codex-image2-darwin-amd64
• macOS Apple Silicon: bin/codex-image2-darwin-arm64

在 macOS 上，若執行權限未被保留，請執行 chmod +x <executable>。一般使用時請勿從原始碼編譯。

工作流程

對於設定請求，請使用下方的配置工作流程。在工作階段中第一次呼叫圖片功能之前，請先執行 status；如果尚未設定，請開啟 configure 並讓使用者在瀏覽器中完成設定後再開始產生圖片。

1. 判斷請求是產生新圖片、編輯現有圖片，還是多個不同的資產/變體。
2. 收集提示詞、預期用途、精確文字、視覺限制與避免項目。
3. 僅在必要範圍內調整提示詞。保留詳細的提示詞；對於籠統的提示詞，應有品味地進行澄清，但不要憑空虛構品牌、人物、標語或不相關的物體。
4. 根據需要執行選定的可執行檔：generate 用於單一提示詞、edit 用於修改現有圖片、generate-batch 用於 JSONL 工作。
5. 檢查每個產出結果的主題、構圖、文字準確性、限制條件以及可見瑕疵。
6. 如果需要修改，每次只更改一個目標面向，然後重新檢查。
7. 報告絕對輸出路徑、最終提示詞或提示詞組合、尺寸、品質與模型。

提示詞結構

僅使用相關行：

Asset type: <圖片將用於何處>
Primary request: <使用者的請求>
Scene/backdrop: <環境>
Subject: <主要主體>
Style/medium: <照片、插圖、3D 等>
Composition/framing: <鏡頭角度、裁切、位置、負空間>
Lighting/mood: <光線與情緒>
Color palette: <色調備註>
Text (verbatim): "<精確文字>"
Constraints: <必須保留或包含>
Avoid: <不得包含>

不要為了填滿結構而添加細節。對於圖片中的文字，請逐字引用並要求精確呈現。

產生單張圖片

& "<skill-dir>\bin\codex-image2-windows-amd64.exe" generate `
  --prompt "一個裝在玻璃瓶中的小型藍色星雲，產品攝影棚拍" `
  --size 1024x1024 `
  --quality auto `
  --out "output/imagegen/nebula.png"

對於長提示詞，請使用 --prompt-file。僅在需要相同提示詞的多個變體時使用 --n。不同的資產應屬於不同的呼叫或批次。

編輯圖片

在編輯之前，檢查每張輸入圖片。在提示詞中說明其角色並重複不變的項目，以避免無關的細節發生漂移。

& "<skill-dir>\bin\codex-image2-windows-amd64.exe" edit `
  --image "input/product.png" `
  --prompt "僅將背景替換為溫暖的棚拍背景，保持產品、標籤、比例與邊緣不變。" `
  --quality auto `
  --out "output/imagegen/product-edited.png"

若有多個參考或合成輸入，請重複使用 --image。若有相容的 PNG 遮罩可用，請使用 --mask mask.png 進行局部編輯。保留原始檔案，並一律將編輯結果寫入新的輸出路徑。

產生批次

在準備批次之前，請閱讀 references/batch-format.md。然後執行：

& "<skill-dir>\bin\codex-image2-windows-amd64.exe" generate-batch `
  --input "tmp/imagegen/jobs.jsonl" `
  --out-dir "output/imagegen" `
  --concurrency 2

設定圖片服務

• 執行 <executable> status 來檢查 configured、source、api_url 與 message。它絕不會回傳金鑰。
• configured 僅確認本機認證是可讀的；並不代表遠端驗證或圖片權限已通過。請勿僅憑 status 來聲稱 API 存取已驗證。
• 若是首次使用、憑證遺失或無法存取，或是要求變更設定，請執行 <executable> configure。這會啟動一個分離的本機設定頁面並立即返回。請勿使用 shell 指令碼將其背景化，或等待其伺服器結束。
• 告知使用者在瀏覽器中填入 API 位址與金鑰，然後點擊 保存配置。如果瀏覽器未自動開啟，請將返回的本機 url 作為可點擊的連結提供。此臨時連結在使用者的機器上有效期為 15 分鐘。
• 儲存時會先查詢所提交金鑰的模型列表。任何列出的 gpt-image 家族模型都允許正常儲存。該家族包括 gpt-image 以及開頭為 gpt-image- 的 ID，例如 gpt-image-1、gpt-image-1-mini 和 gpt-image-2.6。如果沒有列出家族模型，或列表不受支援/不相容，頁面會發出警告，並要求使用者明確點擊 仍然保存 才能儲存未經驗證的服務。認證/網路/速率限制/伺服器錯誤需要在儲存前修正。請勿為使用者點擊覆蓋按鈕。
• 請勿在對話中要求金鑰、將其放入指令或透過自動化填寫。使用者直接在本機頁面中輸入金鑰；只有該程式會處理它。
• 在使用者表示已儲存後，再次執行 status，如果已設定完成，則繼續原本的圖片請求。請勿在等待使用者輸入時反覆重新開啟頁面或輪詢。
• 已儲存的設定將在下次 CLI 呼叫時生效，無需重新啟動 Codex。現有的本機設定將作為完整的位址/金鑰對優先於傳統的環境變數。損壞的本機設定必須透過設定頁面修復，而非默默地回退到其他服務。
• 檢測連接 僅測試模型列表端點，並顯示目前金鑰的模型 ID，特別標示圖片模型與自動選擇。缺少或隱藏的模型會觸發警告，但這並不證明圖片 API 無法使用。編輯位址/金鑰會清除暫存的結果。選用的 測試生圖（可能計費） 需要使用者確認，並會無重試地發送一次圖片請求。請勿在設定過程中自動執行付費的測試。
• Windows 會以目前使用者的 DPAPI 加密金鑰；macOS 則將金鑰儲存在登入鑰匙圈中。macOS 可能會要求使用者解鎖或允許存取鑰匙圈。
• 使用者可以在本機頁面中點擊 顯示 來檢視已儲存的金鑰。隱藏會清除已顯示的已儲存金鑰，且頁面會在 30 秒後或頁面進入隱藏狀態時自動將其隱藏。請勿點擊顯示、檢查實際顯示的金鑰，或透過代理工具呼叫顯示端點。

組態與安全

• 讓 CLI 讀取認證資訊。請勿自行檢查憑證檔案或憑證儲存內容，也不要將金鑰複製到專案檔案、提示詞、日誌或回應中。設定頁面僅能透過 CLI 的平台認證後端儲存金鑰。
• 傳統的 CODEX_API_URL 和 CODEX_API_KEY 在沒有本機設定時仍受支援；其 URL 預設為 https://apinebula.ai/v1。建議新使用者使用本機設定頁面。現有的已儲存 URL 會被保留。
• 預設使用 --model auto（或省略該旗標）、尺寸 1024x1024 與品質 auto。CLI 會檢查已設定服務的模型列表，並優先選擇 gpt-image-2.5，然後是 gpt-image-2，再來是依 lexicographic ID 順序的第一個其他 gpt-image 家族模型。僅列出 gpt-image-2.6 的服務會使用該模型。當發現失敗或列表中沒有家族模型時，CLI 會直接呼叫 gpt-image-2。每個批次會依服務/憑證配對共享發現結果。
• 尊重明確指定的模型（使用 --model <name> 或批次資料列中的 model）；請勿習慣性地加上 --model gpt-image-2，因為這會覆蓋自動偏好。請從 CLI 結果中回報實際使用的模型。
• 乾執行（dry-run）不會查詢模型可用性；model_selection: auto 表示自動發現被跳過，其範例請求使用 gpt-image-2。
• 使用 --dry-run 來驗證請求，無需網路存取也不需要金鑰。
• 將專案相關的資產儲存在目前專案內。CLI 預設路徑為 output/imagegen/。
• 除非使用者明確授權且傳遞了 --force，否則請勿覆蓋檔案。
• 不保證原生透明輸出。請勿承諾此功能或默默切換工具。

失敗處理

• CLI 會在網路超時以及 HTTP 429/500/502/503/504/524 錯誤時使用有限制的指數退避進行重試。
• 若重複超時，建議使用 --quality low、方形尺寸、較少的並發工作或稍後重試。
• 請勿重試認證、驗證或其他一般的 4xx 錯誤。
• 在報告錯誤時，絕不能暴露 Authorization 標頭或完整的金鑰。