CommunityImagegithub.com

image-api

通过用户配置的 OpenAI 兼容 Images API 生成图片、上传参考图和遮罩进行编辑并保存结果,支持自建服务、New API 和中转网关。用于 API 生图、图生图、参考图编辑、配置连接或查询模型。

Qu'est-ce que image-api ?

image-api is a Codex agent skill that 通过用户配置的 OpenAI 兼容 Images API 生成图片、上传参考图和遮罩进行编辑并保存结果,支持自建服务、New API 和中转网关。用于 API 生图、图生图、参考图编辑、配置连接或查询模型。.

Compatible avec~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/qch7/image-api-skill/tree/HEAD

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

通用 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。

Skills associés