前言¶
在 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。
