📦 GPT-image-2 图片生成与编辑 诗云API 翻译： GPT-image-2 图片生成与编辑 使用 诗云 API

ShiyunApi GPT-image-2 图片生成与编辑功能 通过诗云API / ShiyunApi 的 GPT-image-2 图片接口完成两类任务： 文生图：POST https://shiyunapi.com/v1/images/generations，由文本提示词生成全新图片。 图片编辑：POST https://shiyunapi.com/v1/images/edits，基于一张或多张输入图片进行修改、局部重绘、换背景、风格调整或合成。 核心判断： 用户只提供文字并要求“生成、画、做、设计一张新图片”时，走文生图流程，运行 scripts/generate_image.py。 用户提供或引用已有图片，并要求“修改、参考、合成、换背景、局部重绘、把这张图改成……”时，走图片编辑流程，运行 scripts/edit_image.py。 用户需求是视频、本地离线修图、截图、压缩、裁剪或其他供应商时，不使用本技能，除非用户明确要求切换到 ShiyunApi。 能力边界 支持： 中文/英文提示词文生图。 海报、头像、封面、插画、产品图、电商图、宣传图、概念图、角色设定图、场景图等新图片生成。 基于一张或多张 png / jpg / jpeg / webp 图片进行编辑。 换背景、保留主体、改变风格、多图合成、局部补全或重绘。 可选使用 mask 遮罩图进行局部编辑；完全透明区域表示需要编辑的位置。 指定模型、数量、尺寸、质量、输出格式、背景透明度、审核级别等参数。 保存 URL 图片、base64 图片或原始 JSON 响应。 不支持： 视频生成、图生视频、视频续写。 本地离线图片处理、截图、压缩、裁剪、无 API 的离线修图。 非 ShiyunApi 的图片供应商，除非用户明确要求改用 ShiyunApi。 执行流程 判断任务类型： 无输入图片且目标是创建新图：选择文生图。 有输入图片、参考图、遮罩或“修改这张图”的目标：选择图片编辑。 提取提示词；缺失时先询问用户想生成什么或如何修改图片。 编辑场景提取待编辑图片路径；缺失时先询问用户提供图片文件。 校验 API Key：优先读取 SHIYUN_API_KEY。 用户直接提供 API Key 时，运行 scripts/save_api_key.py --api-key-stdin 持久化；通过 stdin 传入，不写入文档、日志或 memory。 需要确认接口限制时读取 references/api_docs.md；需要示例时读取 references/examples.md；遇到失败时读取 references/troubles.md。 根据任务类型运行对应脚本。 检查输出：有图片则交付图片；只有 JSON 则说明响应结构和下一步。 参数 通用参数 prompt：必填，图片生成或编辑提示词。 model：可选，默认 gpt-image-2。 n：可选，默认 1，范围 1 到 10。 size：可选，默认 1024x1024；常用 1024x1024、1536x1024、1024x1536、auto。 quality：可选，默认 auto；常用 high、medium、low、auto。 format：可选，默认 png，用于保存图片，可为 png / jpeg / webp。 output_dir：可选，默认应使用当前工作区下的任务专属目录。 文生图专用参数 model_field：可选，默认 model；接口字段异常时可用 modal 或 auto。 format：会作为 JSON 请求体字段传给接口。 图片编辑专用参数 image / images：必填，待编辑图片路径，可传一张或多张。 mask：可选，遮罩 PNG；透明区域表示要编辑的位置；应小于 4MB 且尺寸与第一张图片一致。 background：可选，默认 auto，支持 transparent、opaque、auto。 moderation：可选，默认 auto，支持 low、auto。 response_format：可选，仅 dall-e-2 使用；gpt-image-2 默认按 base64/URL 响应解析，不要主动传该参数。 调用脚本 文生图 python "scripts/generate_image.py" \ --prompt "一只穿宇航服的小龙虾，赛博朋克海报风格" \ --model gpt-image-2 \ --n 1 \ --size 1024x1024 \ --quality auto \ --format png \ --output-dir "C:/path/to/output" 编辑单张图片 python "scripts/edit_image.py" \ --image "C:/path/to/input.png" \ --prompt "保留主体，把背景改成雪山日出，真实摄影风格" \ --model gpt-image-2 \ --n 1 \ --size 1024x1024 \ --quality auto \ --output-dir "C:/path/to/output" 编辑多张参考图并合成 python "scripts/edit_image.py" \ --image "C:/path/to/person.png" \ --image "C:/path/to/product.png" \ --prompt "将人物和产品自然合成到同一张电商海报中，保留人物面部特征" \ --model gpt-image-2 \ --output-dir "C:/path/to/output" 局部编辑 python "scripts/edit_image.py" \ --image "C:/path/to/input.png" \ --mask "C:/path/to/mask.png" \ --prompt "只修改透明遮罩区域，将天空改成晚霞" \ --output-dir "C:/path/to/output" 保存用户提供的 API Key python "scripts/save_api_key.py" --api-key-stdin 通过 stdin 传入 Key，避免把 Key 暴露在命令文本、日志或历史记录中。 脚本行为 scripts/generate_image.py： 发送 POST https://shiyunapi.com/v1/images/generations。 添加 Content-Type: application/json、Accept: application/json、Authorization: Bearer 。 校验 prompt、n、quality、format、size。 默认使用请求字段 model；必要时支持 --model-field modal。 使用 --model-field auto 时，仅在疑似参数校验失败后重试 alternate field；提醒用户重试可能消耗额度。 scripts/edit_image.py： 发送 POST https://shiyunapi.com/v1/images/edits。 添加 Accept: application/json、Authorization: Bearer ，请求体使用 multipart/form-data。 校验 image、mask、prompt、n、size、quality、background、moderation、response_format。 将每个 --image 作为 image 字段重复上传，兼容多图数组语义。 两个脚本都会： 遇到 url 字段时下载图片。 遇到 b64_json、base64、image_base64 字段时保存图片。 遇到未知结构时保存 response.json。 输出 metadata.json 记录接口、状态、原始响应路径和保存文件路径。 输出 成功时： { "code": 0, "files": ["C:/path/to/image_1.png"], "msg": "图片生成或编辑成功" } 未返回图片但有响应时： { "code": 202, "raw_response": "C:/path/to/response.json", "msg": "已保存原始响应，请根据接口返回继续处理" } 异常处理 未检测到 API Key：提示进入 https://shiyunapi.com/console/token 创建 Key，并设置 SHIYUN_API_KEY。 401 / 403：提示检查 API Key 和 Bearer 授权格式。 余额/额度不足：提示进入 https://shiyunapi.com/console/topup 充值后重试。 400 / 422： 文生图优先检查 prompt、model/modal、n、size、quality、format。 图片编辑优先检查图片格式/大小、prompt、model、n、size、quality、mask。 413：提示图片文件过大；编辑场景单图应小于 25MB，遮罩应小于 4MB。 非 2xx：提取 error、message、msg、code、detail 后说明失败原因。 多次出现错误，但无法确定原因提示进入 https://shiyunapi.com/customersupport 联系客服寻求帮助。 未知响应：保存原始响应并总结 HTTP 状态，不暴露密钥。 已知接口文档问题 文生图文档 schema 写 modal，示例请求写 model；默认先用 model。 图片编辑文档中标题/标签/model 名称存在 GPT Image-1 与 GPT-image-2 混写；本合并技能默认使用 gpt-image-2。 响应示例可能是 chat completion 结构，不一定是真实图片生成/编辑结构。 Header 表中 Authorization 标为可选，但实际按必填处理。 安全规则 不把 API Key 写入 SKILL.md、reference