junxxxxiao/gpt-image-2-apikey-skill

GPT Image 2 API Key

概覽

透過執行 scripts/generate_image.py，使用獨立設定的 gpt-image-2 提供者來生成或編輯圖片。當圖片生成應使用專屬的圖片 API 金鑰（而非 Codex 當前的 OpenAI/Codex 憑證）進行計費、驗證和隔離時，請使用此技能。

此技能刻意不讀取 OPENAI_API_KEY、Codex 驗證檔案或 ChatGPT/Codex 工作階段憑證。它只讀取由 --config 選擇的私密設定檔，或下方說明的預設設定檔。

解決的問題

此技能解決了一個常見的 Codex 工作流程問題：當前的 Codex 工作階段可能已使用一個 API 金鑰進行驗證，而圖片生成應使用另一個金鑰、另一個帳戶、另一個配額或 OpenAI 相容代理。

使用此技能可以：

• 將圖片生成憑證與 Codex 自身的憑證分開管理。
• 從 Codex 呼叫 gpt-image-2 或相容的圖片端點，且不在提示、命令或儲存庫檔案中暴露金鑰。
• 透過 /v1/images/generations 生成圖片。
• 透過 /v1/images/edits 以多部分上傳方式編輯現有圖片。
• 使用一或多張參考圖片進行編輯、重新設計樣式、商標處理、產品模型以及圖像到圖像的轉換。
• 可選擇為編輯提供遮罩圖片以進行區域限制編輯。
• 將生成的輸出儲存到明確的本地路徑，以便 Codex 顯示、檢查或傳遞給後續步驟。

使用情境

此技能適用於以下這類請求：

• 「生成一個包含文字 JunXxxxi 的商標。」
• 「使用這張參考圖片，將文字商標改為斜體。」
• 「將此商標文字改為銀色到黑色的金屬漸層。」
• 「使用 gpt-image-2 建立一個產品圖片，但使用我獨立的圖片 API 金鑰。」
• 「編輯此圖片，同時保留原始構圖。」
• 「使用自訂基礎 URL 的 OpenAI 相容圖片提供者。」

當請求的變更是簡單的像素級別轉換，且必須保留精確的幾何形狀（例如裁剪、調整大小、Alpha 轉換或完全確定性的顏色重新對應）時，請優先使用確定性的本地圖片處理，而非此技能。當使用者需要基於模型的視覺解釋、重新設計樣式或生成時，請優先使用此技能。

內容

gpt-image-2-apikey/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/
    └── generate_image.py

• SKILL.md：面向 Codex 的工作流程和使用者可讀的使用文件。
• agents/openai.yaml：可選的 Codex UI 元數據。
• scripts/generate_image.py：零依賴的 Python 3 腳本，用於呼叫生成或編輯端點。

該腳本同時支援 b64_json 和 URL 形式的圖片回應。URL 回應會立即下載並寫入請求的輸出路徑。

私密設定

預設設定檔路徑：

~/.config/gpt-image-2-apikey/config.json

設定檔必須包含圖片提供者的金鑰，而非當前 Codex 的 API 金鑰：

{
  "api_key": "在此填入圖片提供者金鑰",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-image-2"
}

建立檔案後，設定為私密權限：

chmod 600 ~/.config/gpt-image-2-apikey/config.json

僅在使用者明確指定另一個私密設定檔時，才使用 --config /path/to/config.json。

設定欄位

• api_key：必要。圖片提供者金鑰。除非明確有此意圖，否則不要使用 Codex 當前的 API 金鑰。
• base_url：可選。預設為 https://api.openai.com/v1。對於 OpenAI 相容的提供者，請將其保留在 API 根路徑，例如 https://example.com/v1。
• model：可選。預設為 gpt-image-2。
• extra_body：可選物件。這些值會合併到請求主體中，用於提供者特定的欄位。

良好的 base_url 範例：

{
  "base_url": "https://api.openai.com/v1"
}

{
  "base_url": "https://www.packyapi.com/v1"
}

除非您有意固定一個確切的端點，否則請勿在 base_url 中包含 /images/generations 或 /images/edits。腳本通常會自動附加正確的端點。

使用方式

從技能目錄執行：

python3 scripts/generate_image.py \
  --prompt "一張霧面黑色機械鍵盤放在胡桃木書桌上的乾淨產品照片" \
  --out /absolute/path/to/output.png \
  --size 1024x1024 \
  --quality high

如果省略 --edit-image，腳本會呼叫：

POST <base_url>/images/generations

透過新增 --edit-image 來編輯一或多張參考圖片：

python3 scripts/generate_image.py \
  --prompt "將此商標轉換為斜體銀色到黑色漸層文字，同時保留確切拼寫" \
  --edit-image /absolute/path/to/input.png \
  --out /absolute/path/to/edited.png \
  --size 1024x1024 \
  --quality high

如果存在 --edit-image，腳本會呼叫：

POST <base_url>/images/edits

對於遮罩編輯，新增 --mask /absolute/path/to/mask.png：

python3 scripts/generate_image.py \
  --prompt "僅將背景改為乾淨的工作室灰色，保留主體" \
  --edit-image /absolute/path/to/source.png \
  --mask /absolute/path/to/mask.png \
  --out /absolute/path/to/edited.png \
  --quality high

對多圖片編輯重複使用 --edit-image：

python3 scripts/generate_image.py \
  --prompt "將圖一的產品與圖二的背景氛圍結合" \
  --edit-image /absolute/path/to/product.png \
  --edit-image /absolute/path/to/background-reference.png \
  --out /absolute/path/to/combined.png

當使用者需要在特定位置取得檔案時，請務必提供絕對的 --out 路徑。如果省略，腳本會將時間戳記的 PNG 寫入當前工作目錄。

命令參考

--prompt       必要的圖片提示或編輯指令。
--out          輸出圖片路徑。額外輸出會在副檔名之前使用 -2、-3 等。
--config       私密設定檔路徑。預設為 ~/.config/gpt-image-2-apikey/config.json。
--model        覆蓋設定檔中的模型。
--size         提供者支援的圖片尺寸。預設：1024x1024。
--quality      low、medium、high 或 auto。預設：auto。
--n            圖片數量。預設：1。
--format       png、jpeg 或 webp。預設：png。
--edit-image   針對 /v1/images/edits 的輸入圖片路徑。可重複。
--mask         可選的編輯用 PNG 遮罩路徑。
--timeout      HTTP 逾時秒數。預設：600。
--dry-run      在不呼叫 API 的情況下，印出編輯過的端點、主體和檔案清單。

在進行實際呼叫之前，使用 --dry-run 檢查設定、端點路由或編輯是否將使用預期的輸入檔案：

python3 scripts/generate_image.py \
  --prompt "僅乾執行" \
  --edit-image /absolute/path/to/input.png \
  --out /absolute/path/to/output.png \
  --dry-run

乾執行輸出會將授權資訊編輯為 Bearer ***redacted***。

提示指引

對於生成：

• 明確說明資產類型、主體、風格、佈局和所需的文字。
• 將確切的可見文字放在引號中。
• 在處理商標、海報或 UI 圖形時，包含「無額外文字、無浮水印」。
• 對於最終的商標、大量文字的圖片、產品照片和精緻交付物，使用 quality high。
• 對於便宜的探索和快速草稿，使用 quality low。

對於編輯：

• 描述要進行的變更，而非整張圖片，除非整張圖片都應重新詮釋。
• 明確指出必須保留的內容：文字拼寫、佈局、構圖、面部身份、產品形狀、顏色或背景。
• 對於文字密集型圖形，請在提示中重複確切的拼寫和大寫。
• 在提供者支援的情況下，使用遮罩進行精準編輯。

編輯提示範例：

編輯提供的商標圖片。保留確切文字「JunXxxxi」和相同的文字商標佈局。將字體改為向右傾斜的斜體。將文字填充更改為金屬漸層，從左上方的亮銀色到右下方的深黑色。保持乾淨的白色背景。請勿新增額外文字、圖示、浮水印、邊框或裝飾元素。

隔離規則

• 請勿將 Codex 當前的 API 金鑰傳遞或複製到此技能。
• 請勿讀取 OPENAI_API_KEY；該腳本會刻意忽略它。
• 請勿印出 api_key 或設定檔內容。該腳本僅在 --dry-run 中報告編輯過的設定摘要。
• 如果設定檔缺失，請告知使用者建立私密設定檔。除非使用者明確要求，否則請勿代表他們建立包含真實秘密的檔案。
• 如果提供者使用 OpenAI 相容的端點，請在私密設定中設定 base_url。腳本會在生成時附加 /images/generations，在編輯時附加 /images/edits。

設定注意事項

• 將 config.json 保留在 Git 之外。切勿提交真實的 API 金鑰。
• 對私密設定檔使用檔案模式 600。
• 將 base_url 保留在 API 根路徑（.../v1），除非提供者另有文件說明。
• 如果提供者需要自訂請求欄位，請將它們放在 extra_body 下。
• 如果提供者不支援 gpt-image-2，請將 model 設定為提供者相容的模型名稱。
• 如果提供者僅支援 URL 回應，腳本將會下載回傳的 URL。
• 如果提供者在 b64_json 中回傳 base64 圖片，腳本將會直接解碼。
• 網路呼叫可能會對設定的提供者帳戶產生費用。

包含提供者特定欄位的範例：

{
  "api_key": "在此填入圖片提供者金鑰",
  "base_url": "https://example.com/v1",
  "model": "gpt-image-2",
  "extra_body": {
    "moderation": "auto"
  }
}

失敗處理

• 缺少設定檔或缺少 api_key：報告設定檔路徑和必要欄位。
• HTTP 錯誤：顯示狀態碼和提供者的錯誤主體，但絕不包含金鑰。
• 不支援的提供者回應：報告頂層回應鍵，不儲存任何檔案。
• 多張圖片：第一張圖片使用 --out；其他圖片在副檔名之前加上 -2、-3 等。

限制

• 此技能是一個 API 包裝器，而非完整的圖形編輯器。對於精確的裁剪、調整大小、向量匯出或保證像素完美的字體變更，請使用確定性的本地工具。
• 基於模型的圖片編輯可能會改變確切的文字、字距或幾何形狀。對於商標和文字商標，請在交付前檢查結果。
• 多部分編輯的相容性可能會因不同的 OpenAI 相容提供者而異。如果編輯失敗但生成正常，請檢查提供者是否支援使用多部分 image 上傳的 /v1/images/edits。
• 該腳本目前為了相容多圖片而使用多部分欄位名稱 image[] 發送編輯圖片。如果提供者需要不同的欄位名稱，請為該提供者調整 scripts/generate_image.py。
• 真正的透明背景行為取決於提供者/模型支援。如果需要透明 PNG，請在生成後驗證 Alpha 通道。

發布注意事項

在將此技能發布到 GitHub 時：

• 包含 SKILL.md、agents/openai.yaml 和 scripts/generate_image.py。
• 請勿包含 ~/.config/gpt-image-2-apikey/config.json。
• 除非是有意為之的範例，否則請勿包含生成的圖片。
• 如果此技能位於較大的儲存庫中，請為本地設定檔、輸出和暫存圖片新增 .gitignore 條目。