【Python】Custom Image API Skill，让Codex支持第三方GPT-IMAGE-2模型调用

03912

【Python】Custom Image API Skill，让 Codex 支持第三方 GPT-IMAGE- 2 模型调用
Custom Image API Skill：CodeX 调用 skill，让只有 Chat 接口的工具间接调用图片模型，该工具由 AI 生成，在 CodeX 做过测试完整可用。其他工具需要做一定的配置，根据相关工具的 skill 扩展来针对处理。最后有下载链接
一、背景：Chat 接口和图片接口不在同一条调用链上

很多 AI 工具的模型调用链默认面向对话模型，通常只会调用兼容 OpenAI 风格的：

  1. POST /chat/completions
 复制代码

例如：中转平台提供了当前顶流图片生成模型，gpt-image-2 模型。但 CodeX 等工具无法直接使用。因为 gpt-image-2 往往提供的是另一组 OpenAI 兼容接口：

  1. POST /images/generations
  2. POST /images/edits
 复制代码

这就导致：即使底层 provider 支持图片模型，上层工具也可能没有原生的图片请求入口，不能直接把一次对话调用转换为图片生成调用，更不能稳定地处理图片 URL、Base64 或图片二进制响应。
custom-image-api 的核心作用，就是在这两套协议之间提供一个轻量的桥接层：

  1. 上层工具的自然语言请求
  2.         -> 工具识别到图片生成指令
  3.         -> Skill 或本地脚本
  4.         -> OpenAI 兼容的 /images/generations 或 /images/edits
  5.         -> 图片 URL/Base64/ 二进制响应
  6.         -> 本地图片文件
  7.         -> 返回给上层工具展示或继续处理 
 复制代码
因此，它不是把图片模型“伪装成 Chat 模型”，而是让原本只有 Chat 调用能力的工具，通过 Skill/ 插件或本地脚本间接调用图片专用接口。

二、它解决了什么问题

图片接口接入时，除了请求路径不同，还存在一组重复工作：
  • 根据 Codex profile 找到模型和 provider；
  • 拼接 /images/generations 或 /images/edits 接口地址；
  • 从环境变量或 Codex 的 auth.json 读取认证信息；
  • 生成请求使用 JSON，图片编辑请求使用 multipart/form-data；
  • 兼容 URL、Base64、Data URI 和直接图片响应；
  • 把返回的图片下载、解码、识别格式并保存到本地；
  • 避免 API Key 出现在命令输出、错误信息和共享技能目录中。
custom-image-api 集中处理了这些协议细节。它是一套可被工具调用的适配 Skill。对于 Codex，它表现为 custom-image-api Skill；对于其他工具，也可以直接复用其中的 Python 脚本和配置约定。
从能力边界看，它把“上层只支持 Chat”与“底层支持图片接口”解耦了：
  1. 上层工具：负责理解用户意图、触发 Skill、展示结果
  2.                          |
  3.                          v
  4. 桥接层：负责配置、认证、请求编码、响应解析、文件保存
  5.                          |
  6.                          v
  7. 图片 provider：负责真正的 image2 或其他图片模型推理 
 复制代码
这里的 image2 可以理解为图片模型的具体名称，例如某个 provider 上配置的 gpt-image-2；真正决定能否使用的，是 provider 是否暴露兼容的图片接口。
  1. custom-image-api/
  2. ├── SKILL.md                    # Skill 的行为说明和调用约定
  3. ├── agents/
  4. │   └── openai.yaml             # 在 Codex 中显示的名称、描述和默认提示词
  5. ├── references/
  6. │   └── setup.md                # 可移植安装和配置说明
  7. └── scripts/
  8.     ├── generate_image.py       # 实际执行生成、编辑、下载和保存
  9.     └── self_test.py             # 不访问网络的协议和兼容性测试 
 复制代码
其中最重要的是 generate_image.py。它使用 Python 标准库完成 HTTP 请求、TOML 配置读取、multipart 编码、Base64 解码和图片文件保存，因此没有额外的第三方 Python 依赖。

四、运行前提

需要满足以下条件：
  • 已安装并启用支持个人 Skill 的 Codex。
  • Python 3.11 或更高版本。脚本使用标准库 tomllib 读取 config.toml。
  • 一个支持以下接口的 OpenAI 兼容图片服务：
    • POST /images/generations
    • POST /images/edits
  • 图片服务返回 URL、Base64、Data URI，或直接返回 image/* 响应。

五、CodeX 安装 Skill

将完整的 custom-image-api 目录复制到个人 Skill 目录：
Windows：
  1. %USERPROFILE%\.codex\skills\custom-image-api\
 复制代码
macOS/Linux：
  1. ~/.codex/skills/custom-image-api/
 复制代码
复制完成后，重新启动一个 Codex task，使 Skill 元数据重新加载。不要把 API Key、auth.json、个人 config.toml、生成图片或机器相关的绝对路径复制到 Skill 目录中。

六、配置 Codex

在 Codex 的 config.toml 中配置一个图片 provider 和 custom-image profile。示例：
  1. [model_providers.team-image]
  2. name = “team-image”
  3. base_url = “https://image-api.example.com/v1”
  4. env_key = “TEAM_IMAGE_API_KEY”
  6. [profiles.custom-image]
  7. model_provider = “team-image”
  8. model = “gpt-image-2”
 复制代码
然后在本机设置 TEAM_IMAGE_API_KEY 环境变量。密钥不应写入 Skill、提示词或团队共享配置。
如果 provider 使用 Codex 已有的 OpenAI 认证，也可以配置：
  1. [model_providers.openai-image]
  2. name = “openai-image”
  3. base_url = “https://api.openai.com/v1”
  4. requires_openai_auth = true
  6. [profiles.custom-image]
  7. model_provider = “openai-image”
  8. model = “gpt-image-2”
 复制代码
此时脚本会从 Codex 的 auth.json 读取已经保存的 OPENAI_API_KEY。脚本还兼容 experimental_bearer_token，但不建议在共享模板中使用，因为它会把凭据直接放进 config.toml。

Endpoint 地址如何解析

脚本会根据 base_url 自动得到最终接口：
base_url
生成接口
编辑接口

https://hosthttps://host/v1/images/generationshttps://host/v1/images/edits
https://host/v1https://host/v1/images/generationshttps://host/v1/images/edits
已包含 /images/generations 或 /images/edits 按资源替换按资源替换

因此 provider 的 URL 可以配置在 host 根路径，也可以配置在 /v1 路径。

七、安装验证

先运行离线自测：
  1. python scripts\self_test.py
 复制代码
预期输出包含：
  1. {“ok”: true}
 复制代码
再运行配置检查。这个命令不会请求图片，但会读取 profile、provider、模型、认证来源并计算两个 endpoint：
  1. python scripts\generate_image.py –check
 复制代码
示例输出结构如下，认证信息只显示来源，不显示密钥：
  1. {
  2.   “ok”: true,
  3.   “profile”: “custom-image”,
  4.   “provider”: “team-image”,
  5.   “model”: “gpt-image-2”,
  6.   “auth_source”: “environment:TEAM_IMAGE_API_KEY”,
  7.   “generation_endpoint”: “https://image-api.example.com/v1/images/generations”,
  8.   “edit_endpoint”: “https://image-api.example.com/v1/images/edits”
  9. }
 复制代码

八、生成图片

没有输入图片时，脚本自动选择生成流程，向 /images/generations 发送 JSON：
  1. python scripts\generate_image.py `
  2.   –prompt “a red circle on a clean white background” `
  3.   –output-dir “C:\Users\me\Pictures\generated”
 复制代码

对应的请求主体大致是：

  1. {
  2.   “model”: “gpt-image-2”,
  3.   “prompt”: “a red circle on a clean white background”,
  4.   “n”: 1,
  5.   “size”: “auto”
  6. }
 复制代码

常用参数：

  1. python scripts\generate_image.py `
  2.   –prompt “editorial product photo of a glass bottle” `
  3.   –output-dir “C:\Users\me\Pictures\generated” `
  4.   –size “1024×1024” `
  5.   –count 2 `
  6.   –quality high `
  7.   –response-format b64_json `
  8.   –filename-prefix bottle
 复制代码
支持的主要参数包括：
  • –size：图片尺寸，默认 auto；
  • –count：数量，范围为 1 到 10；
  • –quality、–style：按 provider 能力传递；
  • –response-format：auto、url 或 b64_json；
  • –filename-prefix：输出文件名前缀。

九、编辑图片

传入 –image 后，脚本自动选择编辑流程，并使用 multipart/form-data 请求 /images/edits：
  1. python scripts\generate_image.py `
  2.   –prompt “replace only the background with a quiet beach at sunset; keep the product unchanged” `
  3.   –image “C:\Users\me\Pictures\product.png” `
  4.   –output-dir “C:\Users\me\Pictures\edited” `
  5.   –input-fidelity high
 复制代码
编辑提示词最好明确写出不变量，例如“只修改背景，保留主体的形状、文字、颜色和细节”。这样可以降低模型误改主体的概率。–input-fidelity high 适合身份、产品细节或版式敏感的编辑，但是否真正生效取决于 provider。

多张输入图和 mask

可以重复使用 –image：
  1. python scripts\generate_image.py `
  2.   –prompt “combine the subject from the first image with the lighting reference from the second image” `
  3.   –image “C:\images\subject.png” `
  4.   –image “C:\images\lighting-reference.png” `
  5.   –mask “C:\images\mask.png” `
  6.   –output-dir “C:\images\output”
 复制代码
单张输入使用 multipart 字段 image；多张输入会重复使用 image[]；mask 使用 mask 字段。mask 的黑白区域语义由具体图片服务定义，使用前应参考 provider 文档。

十、响应处理和文件保存

脚本会识别以下响应形式：
  • {“data”: […] }
  • {“images”: […] }
  • {“output”: […] }
  • 条目中的 url、b64_json、base64、b64、image_base64 或 image 字段；
  • 直接返回的 image/png、image/jpeg 等图片响应。
如果返回 URL，脚本会单独下载图片，且不会把 API Key 转发给图片 URL 所在的主机。如果返回 Base64，脚本会解码 Data URI 或普通 Base64 数据。
输出目录不存在时会自动创建。文件名默认类似：
  1. generated-image-01.png
 复制代码

如果文件已存在，脚本会追加数字后缀，避免覆盖原文件。程序最后输出 JSON，例如：

  1. {
  2.   “operation”: “generate”,
  3.   “files”: [“C:\images\output\generated-image-01.png”]
  4. }
 复制代码
脚本还会根据图片文件签名识别 PNG、JPEG、GIF、BMP、TIFF、WebP 和 AVIF，无法判断格式时会报错，而不是写出一个扩展名错误的文件。单次 API 响应上限为 100 MB。

十一、在 Codex 中如何使用

安装和配置完成后，可以直接用自然语言提出图片任务，例如：
  1. 使用 custom-image-api 生成一张极简风格的产品海报，主色为黑白，输出到当前任务目录。
 复制代码

也可以显式指定 Skill：

  1. $custom-image-api 将这张图片的背景替换成纯白，保持主体、文字和比例不变，并检查生成文件是否可以正常打开。
 复制代码
Skill 的默认行为包括：判断是生成还是编辑、组织完整提示词、调用脚本、验证输出文件，并在 Codex 对话中显示结果图片。

十二、其他工具理论上也能使用

这个方案的关键逻辑位于 scripts/generate_image.py，并不依赖 Codex 的 Chat 模型推理接口。脚本只需要以下输入：
  • 一个 prompt；
  • 一个符合约定的 Codex 配置或等价 provider 配置；
  • 可选的输入图片、mask 和图片参数；
  • 一个可写的输出目录。
它最终执行的是普通 HTTP 请求，并把图片保存为本地文件。因此，理论上 WorkBuddy、Qorder、其他 Agent 框架、IDE 插件或自动化任务系统，只要具备以下任一能力，就可以复用这个方案：
  • 能加载类似 Skill 或插件；
  • 能执行 Python 脚本；
  • 能直接调用 OpenAI 兼容的 /images/generations 和 /images/edits 接口。
不同工具只需要替换“如何触发”和“如何展示结果”这两部分，图片接口调用、认证、响应解析和文件落盘逻辑可以保持不变。这也是它比只在某个客户端内部增加图片按钮更容易迁移的原因。
需要注意的是，“理论上可复用”不代表所有工具可以直接复制目录即用。目标工具仍需要提供自己的 Skill/ 插件加载机制、配置位置、凭据管理方式以及本地文件展示能力。

十三、常见问题排查 1. 找不到 tomllib

说明 Python 版本低于 3.11。升级 Python，或在 Codex Desktop 中使用 load_workspace_dependencies 返回的 bundled Python 3.11+ 路径。

2. Codex configuration not found

检查 CODEX_HOME 是否指向正确的 Codex 配置目录，以及该目录下是否存在 config.toml。通常不需要设置 CODEX_HOME，脚本会使用默认的用户目录。

3. Missing Codex configuration value

检查 [profiles.custom-image] 是否存在 model_provider 和 model，并确认对应的 [model_providers.<provider>] 中有 base_url。

4. 认证变量未设置

如果配置了 env_key = “TEAM_IMAGE_API_KEY”，必须在当前进程环境中设置同名变量。不要把变量名误写成 API Key 本身。

5. HTTP 404 或接口路径错误

确认 provider 是否真的兼容 /images/generations 和 /images/edits，并用 –check 查看脚本计算出的 endpoint。若服务商只实现了其中一个接口，另一种操作无法使用。

6. 返回结果无法解析

检查服务是否返回了支持的 JSON 字段或 image/* Content-Type。只有文本 URL、Base64 字段和直接图片响应会被识别；其他自定义响应格式需要修改 image_candidates 或在 provider 侧增加兼容层。

十四、安全和工程注意事项

  • API Key 只放在环境变量或 Codex 的认证文件中，不放进提示词、Skill 文件和共享仓库。
  • 脚本对 HTTP 错误输出做了密钥脱敏，但仍应避免把完整响应日志上传到公共渠道。
  • 返回的远程图片会被下载，生产环境应限制 provider 返回的 URL 来源，并设置合理的网络超时。
  • –filename-prefix 会过滤危险字符，输出文件采用独占创建，不会覆盖已有文件。
  • 当前实现是命令行适配器，不包含任务队列、重试、并发控制、图片内容审核或持久化存储。这些能力应由上层系统补充。

skill 下载链接

下载:https://wwapk.lanzouq.com/ivYWS42inzeh 密码:d6dx

© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
📃源码分享📝站长笔记
# Python# Codex# API# Image# 配置# Custom# 图片生成# 桥接层
喜欢就支持一下吧
点赞12 分享
guixiang的头像-神游资源网
飞鹰控安卓远控源码仅供学习！已移除核心代码-神游资源网
飞鹰控安卓远控源码仅供学习！已移除核心代码
飞鹰控安卓远控源码仅供学习！已移除核心代码
2个月前 140
超级变色龙·画画躲猫猫辅助工具1.6.0-神游资源网
超级变色龙·画画躲猫猫辅助工具1.6.0
超级变色龙·画画躲猫猫辅助工具1.6.0
2个月前 87
安卓TV电视应用工具 野草助手 v2.4.2-神游资源网
安卓TV电视应用工具 野草助手 v2.4.2
安卓TV电视应用工具 野草助手 v2.4.2
2个月前 74
PC原神·Shimmy无敌倍功无冷却6.6国际服-神游资源网
PC原神·Shimmy无敌倍功无冷却6.6国际服
PC原神·Shimmy无敌倍功无冷却6.6国际服
2个月前 74
超级变色龙·超级猎手内部多功能免费辅助1.0.2-神游资源网
超级变色龙·超级猎手内部多功能免费辅助1.0.2
超级变色龙·超级猎手内部多功能免费辅助1.0.2
2个月前 73
《千层登塔》中文版-神游资源网
《千层登塔》中文版
《千层登塔》中文版
2个月前 69
相关推荐
飞鹰控安卓远控源码仅供学习！已移除核心代码-神游资源网
飞鹰控安卓远控源码仅供学习！已移除核心代码
飞鹰控安卓远控源码仅供学习！已移除核心代码
2个月前 140
一梦软件库h5端源码打包-神游资源网
一梦软件库h5端源码打包
一梦软件库h5端源码打包
2个月前 58
2026年7月最新去水印小程序原码全开源带30+各种个工具-神游资源网
2026年7月最新去水印小程序原码全开源带30+各种个工具
2026年7月最新去水印小程序原码全开源带30+各种个工具
1个月前 56
全新多平台电商代付商城-网恋神器-神游资源网
全新多平台电商代付商城-网恋神器
全新多平台电商代付商城-网恋神器
3个月前 55
全网今日热榜源码1.0-神游资源网
全网今日热榜源码1.0
全网今日热榜源码1.0
1个月前 55
在线聊天室带后台朋友圈群聊功能-神游资源网
在线聊天室带后台朋友圈群聊功能
在线聊天室带后台朋友圈群聊功能
3个月前 55
评论 抢沙发

请登录后发表评论

    暂无评论内容