外观
GPT Image 2 API 怎么调用？API Key、参数、图片编辑与错误排查（2026）
如果你条件有限，强烈推荐国内 API 站
这是站主自主搭建纯 GPT API 站，无需梯子，实时更新 GPT 最新模型（仅支持电脑端），价格是官方的 三分之一，操作简单，连接稳定，价格便宜，保证没有任何掺水、收集信息等低劣行为，保证爽用 GPT。
如果你搜索的是“GPT Image 2 API 怎么调用”，先分清两条路线：ChatGPT 网页里的创建图片按钮，和开发者调用图片 API，不是同一个产品入口。 网页端的模型名称、可用次数、套餐权益和界面按钮，不能直接当作 API 的模型 ID、价格或额度。真正开始开发前，应同时核对官方开发者文档、项目控制台和当前 API 返回结果。
本文核查日期为 2026 年 8 月 30 日。模型名称、接口版本、参数、价格、地区资格和限流策略都可能变化；文中的代码使用占位变量，目的是展示安全的接入方式，不把某个未经当前文档确认的型号写成永久结论。
一、先判断你需要网页功能还是 API
两者都能“生成图片”，但使用对象和责任边界不同：
| 对比项 | ChatGPT 网页生图 | 图片 API |
|---|---|---|
| 主要用户 | 普通用户、设计师、内容创作者 | 开发者、产品团队、自动化流程 |
| 使用入口 | ChatGPT 对话或图片页面 | 开发者项目、SDK 或 HTTP 请求 |
| 认证方式 | ChatGPT 账号与产品套餐 | API Key、OAuth 或网关令牌，按服务商规则执行 |
| 计费口径 | 由 ChatGPT 当前套餐和产品策略决定 | 通常按模型、输入/输出图片、尺寸、质量或调用量计算 |
| 可控程度 | 操作简单，参数受界面限制 | 可以接入网站、队列、审核、存储和业务数据库 |
| 需要维护什么 | 浏览器、账号和素材 | 密钥、预算、重试、日志、内容安全和数据存储 |
想先学习网页端上传参考图、局部修改和提示词，可以阅读 ChatGPT 图片生成与修改教程。如果要把图片生成嵌入自己的产品，就应该按 API 项目单独设计认证和成本控制。
二、模型 ID 不要只看搜索结果或网页标签
开发前按下面顺序核验：
不要把 ChatGPT 网页右下角显示的型号直接粘贴进程序，也不要因为第三方页面列出了 gpt-image-2 就推断官方项目已经获得同样的权限。
三、准备 API Key：先把密钥边界做好
1. 使用官方 API
在官方开发者平台创建项目并生成密钥后，把密钥写入服务器环境变量。例如：
text
IMAGE_API_KEY=替换为你自己的密钥
IMAGE_API_BASE_URL=https://api.example.com/v1
IMAGE_MODEL_ID=在当前文档确认的图片模型ID上面的域名和模型 ID 是占位符。正式使用时，IMAGE_API_BASE_URL、认证头和模型名必须以实际服务文档为准。
四、一个安全的 OpenAI 兼容请求骨架
很多网关提供 OpenAI 兼容的图片路径，但兼容并不代表所有参数都完全相同。下面示例只展示结构，先用占位模型和地址跑通认证，再按当前文档逐项增加参数。
cURL 示例
bash
curl "$IMAGE_API_BASE_URL/images/generations" \
-H "Authorization: Bearer $IMAGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$IMAGE_MODEL_ID"'",
"prompt": "一张适合中文科技博客封面的横图，主体明确，右侧留白，不生成文字或Logo",
"n": 1
}'运行前检查三点：
- 你的服务是否真的使用 /images/generations 路径；
- 当前模型是否接受 n、尺寸、质量和输出格式字段；
- 响应返回的是临时 URL、Base64，还是任务 ID，需要怎样下载或轮询。
不要把密钥直接写进脚本并提交到 Git。若在 PowerShell 中临时测试，可以先使用当前会话的环境变量，测试完立即清除；生产环境则应使用部署平台的密钥管理功能。
Python 示例
python
import os
import requests
base_url = os.environ["IMAGE_API_BASE_URL"].rstrip("/")
api_key = os.environ["IMAGE_API_KEY"]
model_id = os.environ["IMAGE_MODEL_ID"]
payload = {
"model": model_id,
"prompt": "生成一张简洁的产品发布会背景图，16:9 构图，主体靠左，右侧留白",
"n": 1,
}
response = requests.post(
f"{base_url}/images/generations",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=90,
)
response.raise_for_status()
result = response.json()
print(result)示例没有假设返回字段一定叫 url 或 b64_json。接入前先打印脱敏后的字段结构，再按照服务商文档写下载、过期和存储逻辑。
五、常用参数怎么选？先看模型实际支持范围
不同模型和网关可能支持不同字段。可以用下面的检查表和服务商文档逐项对照：
| 参数 | 常见作用 | 核验重点 |
|---|---|---|
| model | 指定图片模型 | 必须使用当前项目或网关返回的精确 ID |
| prompt | 描述主体、场景、构图和限制 | 是否有长度、语言或敏感内容限制 |
| size | 图片尺寸或比例 | 可选值、最大像素和费用是否变化 |
| quality | 质量/速度档位 | 是否改变计费、等待时间或开放资格 |
| background | 背景模式 | 是否支持透明、自动或纯色背景 |
| output_format | PNG、JPEG、WebP 等输出格式 | 是否支持透明通道和压缩质量 |
| n | 一次请求生成数量 | 并发、单次上限和费用如何计算 |
| user | 业务侧用户标识 | 是否进入日志、风控或用量统计 |
对于中文海报，建议把“画面内容”和“最终排版文字”分开处理：先让模型生成无文字或少文字的底图，再在前端或设计软件里叠加标题。这样更容易控制错别字、字体授权和品牌规范，也能减少重复生成的成本。
六、图片编辑和参考图：不要把 URL 当成永久文件
图片编辑通常需要一个原图，以及“保留什么、修改什么”的说明。常见输入形态包括：
- 上传文件的 multipart 请求；
- 可访问的图片 URL；
- Base64 或 data URL；
- 网关先上传素材，再返回临时文件 ID。
提示词可以按下面的结构写：
text
必须保留：主体位置、产品外形、主色、镜头角度。
只修改：背景替换为浅灰色，去掉桌面上的纸张。
不要改变：Logo 形状、产品比例、人物面部和手部数量。
输出要求：横向构图，适合网页首图；如无法保持一致，请说明不确定部分。不要把身份证、合同、客户名单、订单号或未获授权的人像直接上传到陌生 API。即使响应返回了图片 URL，也应确认它的有效期、访问权限、是否被服务端保存以及删除方式。
七、接入 Codex 或 Claude Code 时要分清协议
用户常说“把 API 接到 Codex”或“给 Claude Code 配一个 Base URL”，实际至少涉及四个变量：
- 客户端支持的协议路径；
- 服务商接受的认证头和请求体；
- 模型 ID 与路由映射；
- 工具调用、流式输出、上下文和错误格式是否兼容。
- 先在控制台确认是否有面向 Codex 或 Claude Code 的专用配置说明；
- 复制 Base URL 和模型 ID 时，不要把示例中的占位符当成真实值；
- 先用只读任务或最小请求测试，不要一开始就让客户端执行删除文件、发送消息或访问生产数据库的操作；
- 记录状态码、请求 ID、模型路由和消耗，但不要记录完整密钥或敏感提示词；
- 发现 401、404 或工具调用失败时，优先查协议和路由，不要反复重装客户端。
一个能生成文本的兼容接口，不代表它就支持图片生成，也不代表它能满足 Codex 或 Claude Code 的工具调用要求。每种客户端都应独立验收。
八、常见错误排查表
| 状态或现象 | 常见原因 | 建议顺序 |
|---|---|---|
| 400 | 字段不支持、模型 ID 错误、提示词或图片格式不合法 | 对照当前接口 Schema，先删除非必要参数 |
| 401 | Key 缺失、复制不完整或已撤销 | 检查环境变量和项目归属，不在聊天中粘贴完整 Key |
| 403 | 地区、组织、模型资格或内容策略限制 | 查看控制台说明，不能用换 Key 规避授权边界 |
| 404 | Base URL、路径或模型路由不匹配 | 确认是否应使用 /v1/images、/responses 或网关专用路径 |
| 413 | 图片或请求体过大 | 压缩图片、降低尺寸、分步上传并检查单文件上限 |
| 429 | 速率限制、余额不足或并发过高 | 限流、指数退避、预算告警，再核对余额和配额 |
| 5xx / 超时 | 上游波动、任务过重或网关排队 | 设置超时和有限重试，保存请求 ID，避免无限重放 |
| 返回成功但没有图片 | 结果是任务 ID、临时 URL 或异步状态 | 查看响应字段和轮询接口，不要假设固定 JSON 结构 |
API 调试时建议先用最短提示词、单张图片、最低风险素材和一次调用跑通链路；确认认证、路由、响应解析都正常后，再增加高质量档位、批量任务和并发。
九、成本、限流与生产部署建议
图片应用的成本不只来自“生成一次多少钱”，还包括失败重试、放大、编辑、存储、CDN 和人工审核。可以按下面的公式估算：
text
单个合格图片成本
=（生成调用 + 编辑调用 + 重试调用 + 存储/传输费用）
÷ 最终通过审核并交付的图片数量部署前至少设置：
- 每个用户、IP、项目的日/小时调用上限；
- 单次请求超时、最大重试次数和指数退避；
- 余额不足、429、5xx 和异常输出的告警；
- 原图与结果图的生命周期、访问权限和删除任务；
- 密钥轮换、撤销、权限分级和日志脱敏；
- 图片内容审核、版权记录和人工复核入口。
如果需要进一步计算文本模型和 Agent 的 Token 成本，可参考 GPT-5.6 API 价格与成本优化指南。图片 API 的实际计费项目仍应以对应模型和服务商的当日账单为准。
总结
GPT Image 2 API 的关键不是找到一个看起来最像官网的入口，而是把模型资格、接口协议、密钥安全、图片参数、成本和数据边界逐项核验。网页端的 ChatGPT Images 2.0 教程适合创作和提示词练习；API 则适合接入网站、工作流和自动化系统。