通用 API 生图
用本技能的 scripts/image_api.py 调用用户指定服务。文字生图使用 /images/generations,提供 --image 时自动使用 /images/edits 上传参考图。对话 Agent 负责理解需求和调用脚本,生图模型通过脚本的 --model 指定。
首次配置
先运行 check。缺少配置时,引导用户在本机交互终端运行 configure,依次填写 API Base URL、API Key、默认图片模型。Key 输入隐藏。Agent 执行环境无法交互时,把准确命令交给用户在本机终端执行,等配置完成再继续依赖该配置的请求。
将 <SKILL_DIR> 换成本技能实际绝对路径。
python "<SKILL_DIR>/scripts/image_api.py" check
python "<SKILL_DIR>/scripts/image_api.py" configure
配置默认写入 ~/.config/image-api/config.json。Windows 对应 %USERPROFILE%\.config\image-api\config.json。脚本限制凭据文件的访问权限,配置以本机明文 JSON 保存。技能目录与分享包只包含代码和说明。不要打印配置全文或鉴权头。
- URL 填
https://example.com会规范化为https://example.com/v1。填https://example.com/v1会直接使用。带路径前缀的地址按填写的 API 根路径使用,例如https://example.com/openai/v1。完整/images/generations或/images/edits地址也可识别。 - 默认模型为
gpt-image-2,用户可填写服务实际支持的模型 ID。 - 已有配置时会复用。仅在用户要调整连接或出现实际连接问题时重新配置。
- 自动化配置可用
configure --url "https://example.com/v1" --key-env IMAGE_SERVICE_KEY --model gpt-image-2。非交互配置必须同时提供--url、--key-env和--model。Key 从已设置的环境变量读取,避免写入命令行参数。当前任务已授权复用的本机凭据也可由 Agent 通过此方式配置。 --config "绝对路径"放在子命令前,可切换用户自己建立的独立配置文件。
调用
Python 3.10+。生成与校验图片需要 Pillow,缺失时在所选 Python 环境安装 python -m pip install Pillow,遵循当前环境的安装授权。
python "<SKILL_DIR>/scripts/image_api.py" models
python "<SKILL_DIR>/scripts/image_api.py" generate --prompt "一只橘猫坐在窗边,温暖的水彩插画" --out "output/imagegen/cat.png"
python "<SKILL_DIR>/scripts/image_api.py" generate --prompt-file "prompt.txt" --model "gpt-image-2" --size "1024x1024" --out "output/imagegen/cat-square.png"
python "<SKILL_DIR>/scripts/image_api.py" generate --image "reference.png" --prompt "保留角色外观,生成正面、侧面和背面三视图" --size "1536x1024" --quality high --out "output/imagegen/character-views.png"
python "<SKILL_DIR>/scripts/image_api.py" generate --image "character.png" --image "scene.jpg" --prompt "让参考角色出现在参考场景中" --out "output/imagegen/composite.png"
models查询/models,列表可能含文本模型。图片模型应根据服务支持情况选择。check只做本地配置检查。models只查询模型。generate会发送真实生成请求。- 通用参数有
--model、--size、--quality、--n、--response-format b64_json|url、--timeout。可选字段仅在指定时发送。默认单图,客户端等待上限 360 秒。脚本允许 1–10 张,服务可能有更小上限,chatgpt2api 1.8.0 为 1–4 张。 --image可重复,上传本地 PNG/JPEG/WebP,发送前验证图片内容。根据用户需求选择参考图,向已配置的服务上传。--mask接收带 alpha 通道的 PNG,尺寸需与第一张参考图一致,透明区域表示需要修改的区域。多参考图的遮罩作用范围由服务实现决定。- 按服务和模型支持情况传入
--background、--output-format png|jpeg|webp、--output-compression 0..100、--input-fidelity、--moderation、--style和--user。这些字段是可选透传,服务可能拒绝或忽略它们。chatgpt2api 1.8.0 的处理链路消费模型、提示词、尺寸、质量、张数、响应格式及图片/遮罩,其他字段需要独立确认。具体参数说明见 README.md。 --output-format指定请求服务返回的编码格式,--out扩展名决定最终本地文件格式。仅需本地格式转换时指定--out即可。--size表达请求的尺寸,交付时核对返回的实际像素,部分后端会返回相近尺寸。服务通过网关访问时优先选择b64_json,URL 模式依赖后端返回可访问的图片地址。下载失败的 JSON 返回download_url、http_status、completed_outputs和failed_output,可据此取回已生成结果。- 优先按用户指定路径保存。未指定时由 Agent 在当前项目
output/imagegen/选择有意义的文件名,传给--out。多图文件名加-1、-2等编号。已有文件会在发请求前拒绝覆盖。 - 支持响应
data[].b64_json和data[].url。URL 下载不会携带 API Key。图片逐张经 Pillow 完整解码验证后保存,支持 PNG、JPEG、WebP 输出。若输出扩展名要求与原图格式不同,脚本转码并在 JSON 中报告source_format和format。 - 一次生成只发送一次 POST。超时、下载或保存失败时先报告当前结果,保留已完成文件,检查服务记录或根据用户意图决定下一次操作。客户端等待参数无法改变服务内部的轮询超时。
- 本技能封装同步文字生图和参考图编辑。异步任务、流式响应和 Chat Completions-only 服务需要对应的协议实现。
交付
成功的 JSON 返回绝对文件路径、实际尺寸、格式、用量和耗时。用当前 Agent 的图像查看能力检查结果,再向用户交付图片和本地链接,注明实际模型及与需求相关的差异。输出 PNG/JPEG/WebP 图片,不用文字声称生成成功代替文件。
示例请求 用 image-api 生成一张雨夜城市插画,保存到当前项目 output/imagegen/city.png。