前言¶
在 Cursor、Claude Code 等環境裏做海報、頭像或產品圖時，常見做法是手寫 curl 調第三方圖像 API，再把返回的 URL 或 base64 落盤。接口字段多、文生圖與編輯走不同端點，Agent 也容易在「只給文字」和「要改已有圖」兩種任務之間選錯流程。下面介紹 SkillHub 社區 Skill「GPT-image-2 圖片生成與編輯 詩云API」（座標 @user_cfdd25ec/gpt-image-2-shiyunapi，版本 1.0.0），它把詩云 API（ShiyunApi）上的 GPT-image-2 封裝成 Agent 可執行的腳本與說明，統一文生圖與圖片編輯兩類能力。
這是什麼¶
一句話定位：通過 GPT-image-2 完成文生圖，以及基於輸入圖片的編輯、局部重繪與多圖合成，底層由詩云 API 提供模型服務。
維護與分發：社區來源（community），發佈者爲 user_cfdd25ec，在 SkillHub 分類爲 design-media，標籤標明 requires_api_key=true。SkillHub 頁面：https://www.skillhub.cn/skills/user_cfdd25ec/gpt-image-2-shiyunapi。
核心功能¶
Skill 在 SKILL.md 中約定兩類任務及對應 HTTP 接口：
- 文生圖：
POST https://shiyunapi.com/v1/images/generations，由文本提示詞生成新圖；Agent 側運行scripts/generate_image.py。 - 圖片編輯：
POST https://shiyunapi.com/v1/images/edits，基於一張或多張png/jpg/jpeg/webp修改、換背景、風格調整或合成；運行scripts/edit_image.py。
判斷規則簡要如下：用戶只有文字、目標是「生成/畫一張新圖」時走文生圖；用戶提供或引用已有圖片、或要求「修改這張圖」時走編輯。視頻生成、純本地離線修圖、非 ShiyunApi 供應商等不在本 Skill 範圍內（除非用戶明確要求改用 ShiyunApi）。
可選參數包括模型（默認 gpt-image-2）、數量 n（1–10）、尺寸 size、質量 quality、輸出格式 format；編輯場景還可傳 mask 遮罩（透明區域爲待編輯位置）、background、moderation 等。腳本會把 URL 或 base64 響應保存爲圖片，必要時寫出 response.json 與 metadata.json 便於排錯。
安裝與啓用¶
通過 SkillHub 安裝¶
官方頁面提示：按 https://skillhub.cn/install/skillhub.md 安裝本 Skill。若本機已有 skillhub CLI，可將包裝到當前 Agent 的 skills 目錄（安裝時必須帶 --dir，否則默認落在 ./skills/ 且可能不被識別）：
skillhub install @user_cfdd25ec/gpt-image-2-shiyunapi --dir ~/.cursor/skills/
其他常見路徑（來自 SkillHub 安裝文檔）：Claude Code 爲 ~/.claude/skills/；Codex 爲 ~/.codex/skills/ 或項目下 .agents/skills/。按你實際使用的客戶端替換 --dir 即可。
未安裝 CLI 時，可先執行：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
API Key¶
調用前需要詩云 API Key。Skill 優先讀取環境變量 SHIYUN_API_KEY。用戶在對話中提供 Key 時，應通過 stdin 持久化，避免出現在命令行或日誌中：
python "scripts/save_api_key.py" --api-key-stdin
Key 創建地址：https://shiyunapi.com/console/token。不要把 Key 寫入 Skill 文檔、memory 或項目文件。
典型用法¶
以下示例來自 Skill 自帶的 references/examples.md；路徑請換成你工作區下的實際目錄。腳本需在 Skill 安裝目錄內執行（或寫全 generate_image.py / edit_image.py 的路徑）。
文生圖（頭像）：生成一張 1024×1024 的 PNG。
python "scripts/generate_image.py" \
--prompt "一隻戴着圓框眼鏡的橘貓頭像，乾淨背景，柔和光線，數字插畫風格" \
--size 1024x1024 \
--format png \
--output-dir "./output"
文生圖（產品海報）：
python "scripts/generate_image.py" \
--prompt "高端藍牙耳機產品海報，深藍漸變背景，科技感光效，中心產品展示，留出中文標題區域" \
--size 1024x1024 \
--quality auto \
--format png \
--output-dir "./output"
編輯：換背景（需先有輸入圖）：
python "scripts/edit_image.py" \
--image "./input/product.png" \
--prompt "保留產品主體和細節，將背景換成高級灰漸變攝影棚，增加柔和陰影" \
--model gpt-image-2 \
--output-dir "./output"
編輯：帶 mask 的局部重繪：
python "scripts/edit_image.py" \
--image "./input/room.png" \
--mask "./input/window_mask.png" \
--prompt "只修改透明遮罩區域，把窗外景色改成晴朗海景，室內其他區域保持不變" \
--model gpt-image-2 \
--output-dir "./output"
編輯：多圖合成（多次 --image）：
python "scripts/edit_image.py" \
--image "./input/person.png" \
--image "./input/bag.png" \
--prompt "將人物和包自然合成爲一張時尚街拍廣告圖，保持人物臉部不變，包在人物右手" \
--model gpt-image-2 \
--size 1024x1536 \
--output-dir "./output"
成功時腳本會輸出類似 {"code": 0, "files": [".../image_1.png"], "msg": "圖片生成或編輯成功"} 的 JSON；若響應結構無法解析爲圖片，可能得到 code: 202 並保存 response.json。
在 Agent 對話中，也可直接描述需求（生成海報、換背景、局部重繪等）；Skill 的觸發關鍵詞包含「文生圖」「圖片編輯」「ShiyunApi」「gpt-image-2」等，由 Agent 按 SKILL.md 選擇腳本與參數。
適用場景與注意¶
適合誰：需要在編碼助手內完成 GPT-image-2 文生圖或基於參考圖的編輯，且願意使用詩云 API 按量計費團隊的開發者或創作者。
使用前注意：
- 依賴網絡與有效 API Key；額度不足時需到
https://shiyunapi.com/console/topup充值。 - 文生圖文檔中
model與modal字段存在混寫，Skill 默認用model，異常時可查references/api_docs.md或--model-field auto（重試可能消耗額度）。 - 編輯單圖建議小於 25MB，遮罩 PNG 小於 4MB且與首張圖尺寸一致；
413多爲文件過大。 - 接口文檔與真實響應結構可能不完全一致，Skill 已說明需以實際返回爲準。
結尾¶
「GPT-image-2 圖片生成與編輯 詩云API」把 ShiyunApi 上的文生圖與編輯接口、參數約定和排錯說明收進一套 Agent Skill，減少手寫請求和流程誤判。安裝與詳情見 SkillHub：https://www.skillhub.cn/skills/user_cfdd25ec/gpt-image-2-shiyunapi；API 分發地址：https://api.skillhub.cn/user_cfdd25ec/gpt-image-2-shiyunapi。
