前言¶

在 Cursor、Claude Code 等環境裏讓 Agent 畫圖，常見做法是手寫一段調用 OpenAI 兼容 /v1/images/generations 的腳本，或把 base URL、API Key 寫死在對話裏。網關若只暴露 /v1/models 而不支持標準生圖路徑，還容易把「能列出 gpt-image-2」誤判成「一定能出圖」。下面介紹 SkillHub 社區技能 @user_fdb96f95/gpt-image-2（gpt-image-2生圖技能）：按固定流程發現配置、校驗模型、調用接口並把 b64_json 保存爲本地文件。

這是什麼¶

gpt-image-2生圖技能 是面向任意 AI Agent 的通用生圖模塊，座標 @user_fdb96f95/gpt-image-2，當前 SkillHub 版本 1.1.2，來源爲 community，分類 design-media，發佈者 user_fdb96f95。官方頁面：SkillHub 技能頁，資源地址 https://api.skillhub.cn/user_fdb96f95/gpt-image-2。

技能標籤標明 requires_api_key=true：需要自備 OpenAI 兼容網關的 API Key，技能本身不在文檔中保存真實密鑰。

核心功能¶

依據技能包 SKILL.md，已覈實能力包括：

1. 自動發現 OpenAI 兼容 API：優先讀環境變量 OPENAI_BASE_URL / OPENAI_API_KEY、CLAWTO_BASE_URL / CLAWTO_API_KEY；若無，再從宿主 config.yaml 映射 model.base_url、model.api_key、auxiliary.vision.base_url、auxiliary.vision.api_key 等字段。
2. 驗證 gpt-image-2 支持：對同一 base URL 與同一組憑證請求 /v1/models，確認列表中存在 gpt-image-2。
3. 調用生圖接口：向 {base_url}/images/generations 提交 JSON（model、prompt、size 等），超時建議 180 秒或更長。
4. 保存本地文件：解析響應中的 data[0].b64_json，解碼寫入 PNG 等文件。
5. 運維與安全約定：不跳過 SSL 校驗；模型列表與生圖請求必須使用同一網關；尺寸不支持時從 2048x1024 回退到 1024x1024；附帶 references/clawto-api-notes.md 記錄部分網關的非標準路徑行爲。

安裝與啓用¶

安裝 SkillHub CLI¶

若尚未安裝，可先檢查版本：

command -v skillhub && skillhub --version

未安裝時可執行（僅 CLI）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

完整安裝說明見 https://skillhub.cn/install/skillhub.md。

安裝本技能¶

安裝時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 且可能不被識別。本技能在索引中的安裝方式爲：

skillhub install gpt-image-2 --namespace user_fdb96f95 --dir <你的 skills 目錄>

常見路徑示例（來自 SkillHub 安裝文檔）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下的 .agents/skills/

也可將下面提示交給 Agent，讓其按官方安裝文檔拉取 @user_fdb96f95/gpt-image-2：

請根據 https://skillhub.cn/install/skillhub.md，安裝 @user_fdb96f95/gpt-image-2。

安裝後按所用客戶端要求重啓或刷新 Agent，使技能生效。

配置 API¶

在 shell 或宿主環境中注入（示例，請替換爲真實值）：

export OPENAI_BASE_URL="https://你的網關/v1"
export OPENAI_API_KEY="你的密鑰"

技能同樣支持 CLAWTO_BASE_URL / CLAWTO_API_KEY 命名；具體以 SKILL.md 中的發現順序爲準。

典型用法¶

下面步驟與技能文檔一致，便於在終端或 Agent 會話中復現。

1、檢查是否已配置環境變量

python3 - <<'PY'
import os
candidates = [
    ('OPENAI_BASE_URL', 'OPENAI_API_KEY'),
    ('CLAWTO_BASE_URL', 'CLAWTO_API_KEY'),
]
for base_var, key_var in candidates:
    base = os.getenv(base_var)
    key = os.getenv(key_var)
    if base and key:
        print(f'{base_var}={base}')
        print(f'{key_var}=SET')
        break
else:
    print('no_api_found')
PY

2、驗證 /v1/models 是否包含 gpt-image-2

先將 API_BASE_URL、API_KEY 設爲發現到的值，再執行：

python3 - <<'PY'
import os, json, urllib.request, ssl
base = os.environ['API_BASE_URL'].rstrip('/')
key = os.environ['API_KEY']
url = f'{base}/models'
req = urllib.request.Request(url, headers={'Authorization': f'Bearer {key}'})
ctx = ssl.create_default_context()
with urllib.request.urlopen(req, context=ctx, timeout=30) as r:
    data = json.loads(r.read().decode('utf-8', 'ignore'))
    models = [m.get('id') for m in data.get('data', [])]
    print('has_gpt_image_2=', 'gpt-image-2' in models)
    print(models)
PY

3、調用 gpt-image-2 生圖

python3 - <<'PY'
import os, json, urllib.request, ssl
base = os.environ['API_BASE_URL'].rstrip('/')
key = os.environ['API_KEY']
api = f'{base}/images/generations'
payload = json.dumps({
    'model': 'gpt-image-2',
    'prompt': 'a stylish female livestream host in a professional streaming studio, smiling, modern lighting, realistic, safe and tasteful, no suggestive pose',
    'size': '1024x1024'
}).encode()
req = urllib.request.Request(api, data=payload, headers={
    'Authorization': f'Bearer {key}',
    'Content-Type': 'application/json'
})
ctx = ssl.create_default_context()
with urllib.request.urlopen(req, context=ctx, timeout=180) as r:
    print(r.status)
    print(r.read().decode('utf-8', 'ignore'))
PY

4、將響應 JSON 中的 b64_json 寫入文件

先把上一步響應保存爲 response.json，再解碼：

python3 - <<'PY'
import json, base64, pathlib
body = json.loads(open('response.json').read())
out = pathlib.Path('gpt_image_2.png')
out.write_bytes(base64.b64decode(body['data'][0]['b64_json']))
print(out)
PY

在對話裏使用時，可直接用自然語言描述畫面（技能文檔提供了英文示例 prompt，可按直播間、產品展示等場景替換）。若用戶指定輸出目錄，技能要求 Agent 記住該路徑並在後續默認寫入。

適用場景與注意¶

適合誰

• 已在使用 OpenAI 兼容網關、且網關模型列表含 gpt-image-2 的開發者。
• 希望 Agent 按統一流程「發現配置 → 驗模 → 生圖 → 落盤」，而不是每次臨時拼 curl 的團隊。

限制與坑

• 部分網關僅在 /v1/models 中展示 gpt-image-2，但標準 /v1/images/generations 仍返回 404 或需走其它路徑；技能附帶的網關筆記以 api.clawto.link 爲例說明了這種情況，不能僅憑模型列表判斷可生圖。
• 返回多爲 b64_json 而非圖片 URL；401、400、insufficient balance 需分別檢查憑證、尺寸與賬戶額度。
• SkillHub 頁面統計（截至資料抓取）：評分 100000，下載 10194，安裝 2；實際可用性仍取決於你的網關與 Key。

結尾¶

gpt-image-2生圖技能把「發現 OpenAI 兼容 API、驗證 gpt-image-2、調用生圖並保存文件」寫成 Agent 可執行的固定步驟，適合作爲通用生圖模塊掛在 Cursor、Claude Code、Codex 等環境。安裝與詳情見 https://www.skillhub.cn/skills/user_fdb96f95/gpt-image-2，資源入口 https://api.skillhub.cn/user_fdb96f95/gpt-image-2。