中转站API生图工具

要解决的问题

在利用 AI 进行图像生成时，开发者或创作者常常希望灵活选用 GPT-image2、Nano-Banana（如 Gemini 图像模型）等不同厂商的模型。然而，直接对接多个官方 API 带来管理负担：需要分别申请账号、管理不同的 API 密钥、处理多套调用格式，并可能产生更高的成本。中转站 正是解决这一问题的常见方案，它充当用户与模型间的转发聚合层，但如何高效、安全地通过中转站调用这些模型，仍需一个标准化的工具流程。

工作原理

本技能通过一个 Python 脚本 api_image.py，将上述复杂性封装成简洁的命令行操作。其核心能力与关键步骤如下：

1. 智能配置与初始化

• 自动协议识别：根据用户选择的模型类型（如 GPT-image2 或 Banana/Gemini），脚本自动确定底层使用 openai 或 gemini 协议，无需用户手动指定。
• 安全配置保存：首次使用时，由 Agent 引导用户输入中转站的 Base URL、模型 ID 和 API Key，脚本会将其加密保存到用户本地的 ~/.api-image/config.json 文件，避免密钥泄露。
• 连通性验证：配置完成后，脚本自动运行一次低成本测试生成，确保设置正确且中转站可达。

2. 核心生成能力

• 文生图 (text-to-image)：基于文本提示词生成全新图像。调用时无需重复传入配置信息。
• 图生图 (image-to-image)：支持基于参考图的编辑与生成。特别地，对于 OpenAI 协议（如 GPT-image2），脚本严格遵循官方要求，调用 /v1/images/edits 端点并真实上传参考图，确保功能完整。
• 灵活响应处理：能处理中转站返回的 Base64 数据或图片 URL，并自动根据实际图片字节修正文件后缀（如 .png, .jpeg）。

3. 关键执行规则

• 脚本遵循明确的配置优先级：命令参数 > 环境变量 > 本地配置文件 > 默认值。
• 对于超时或模糊的响应，不会自动重试，以防产生意外费用。

适用边界与注意点

本技能专注于提供一个可靠、简洁的 API 调用通道，并非全功能图像生成平台。使用时请注意：

• 支持范围：

- 支持基础的文生图、单图/多图参考生成以及 OpenAI 协议的多图编辑。
- 输入格式支持 PNG、JPEG、WebP。
- 不提供：遮罩局部重绘（inpainting）、对话式多轮生成状态管理、平台专属元数据处理等功能。

• 已知限制：

- GPT-image2 模型不支持透明背景生成，脚本会拒绝 --background transparent 参数。
- 运行时环境要求 Python 3.9 或更高版本，且仅依赖 Python 标准库，无需安装复杂的第三方包。

• 错误处理建议：

- 遇到 401/403 错误，请首先核对 API Key 有效性和账户余额。
- 遇到 404/405 错误，需检查 Base URL 是否正确以及中转站是否已开放对应模型的协议。
- 对于 429（限流）或 5xx（服务端错误），报告情况但不应连续重试。
- 超时或连接中断时，结果状态未知，应避免自动重发请求。

总之，这是一个旨在简化中转站调用流程的实用工具脚本，其稳定性和私密性最终取决于用户所选中转站的服务质量。