Documentation Index
Fetch the complete documentation index at: https://docs.tkhub.ai/llms.txt
Use this file to discover all available pages before exploring further.
1. 概述
OpenAI 图片生成模型（gpt-image-2）支持两种生成模式：
| 模型名称 | 能力 | 说明 |
|---|
gpt-image-2 | 文生图 (Text-to-Image) | 根据文本提示词生成图片，调用 /v1/images/generations |
gpt-image-2 | 图片编辑 (Image Edit) | 根据参考图 + 文本提示词生成图片，调用 /v1/images/edits |
2. 接口地址
| 方法 | 路径 | Content-Type | 作用 |
|---|
| POST | /v1/images/generations | application/json | 文生图（无参考图） |
| POST | /v1/images/edits | multipart/form-data | 图片编辑（有参考图） |
| 环境 | Base URL |
|---|
| 生产环境 | https://api.openai.com |
$BASE_URL 表示，实际调用请替换为对应环境地址。
3. 认证
所有请求均需携带 API Key：
Authorization: Bearer <YOUR_API_KEY>
4. 文生图接口（/v1/images/generations）
无参考图时调用此接口，请求体为 JSON 格式。
4.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
model | string | 是 | 模型名称，如 gpt-image-2 |
prompt | string | 是 | 文本提示词 |
n | int | 可选 | 生成图片数量，默认 1 |
size | string | 可选 | 图片尺寸，如 1024x1024、1024x1536、1536x1024；默认 auto |
quality | string | 可选 | 图片质量：high / medium / low / auto |
moderation | string | 可选 | 内容审核级别，默认 low |
background | string | 可选 | 背景模式（仅 gpt-image-* 生效）：transparent / opaque / auto |
output_format | string | 可选 | 输出格式（仅 gpt-image-* 生效）：png / jpeg / webp |
5. 图片编辑接口（/v1/images/edits）
有参考图时调用此接口，请求体为 multipart/form-data 格式，参考图以文件形式上传。
5.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
image | file[] | 是 | 参考图文件（支持多值，同名 image 字段多文件上传） |
model | string | 是 | 模型名称，如 gpt-image-2 |
prompt | string | 是 | 文本提示词 |
n | int | 可选 | 生成图片数量，默认 1 |
size | string | 可选 | 图片尺寸；默认 auto |
quality | string | 可选 | 图片质量：high / medium / low / auto |
moderation | string | 可选 | 内容审核级别，默认 low |
background | string | 可选 | 背景模式（仅 gpt-image-* 生效）：transparent / opaque / auto |
output_format | string | 可选 | 输出格式（仅 gpt-image-* 生效）：png / jpeg / webp |
5.2 参考图素材要求
- 格式：JPEG / JPG / PNG / WEBP
- 大小：无硬性上限，建议 ≤ 10MB / 张
- 数量：支持多张参考图，同名
image 字段多值上传
6. 请求示例
6.1 文生图（generations）
curl -X POST $BASE_URL/v1/images/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "一只橘猫坐在窗台上，阳光洒在身上，油画风格",
"n": 1,
"size": "1024x1536",
"quality": "high",
"moderation": "low",
"background": "auto",
"output_format": "png"
}'
6.2 图片编辑（edits）
curl -X POST $BASE_URL/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-F "model=gpt-image-2" \
-F "prompt=将他们合并在一个图片里重画" \
-F "n=1" \
-F "size=1024x1536" \
-F "quality=low" \
-F "moderation=low" \
-F "image=@ref1.png" \
-F "image=@ref2.png"
7. 响应格式
7.1 成功响应
{
"created": 1777282922,
"data": [
{
"b64_json": "",
"revised_prompt": "跳舞的大象，动漫",
"url": ""
}
],
"model": "gpt-image-2",
"usage": {
"prompt_tokens": 0,
"completion_tokens": 0,
"total_tokens": 370,
"input_tokens": 12,
"output_tokens": 358,
"input_tokens_details": {
"cached_tokens": 0,
"text_tokens": 12,
"audio_tokens": 0,
"image_tokens": 0
}
}
}
| 字段 | 类型 | 说明 |
|---|
created | int | 任务创建时间戳 |
data | array | 图片结果数组 |
model | string | 使用的模型名称 |
usage | object | token 消耗统计 |
| 字段 | 类型 | 说明 |
|---|
b64_json | string | base64 编码的图片数据（与 url 二选一返回） |
revised_prompt | string | 模型修订后的提示词（可能对原始 prompt 做了改写） |
| 字段 | 类型 | 说明 |
|---|
prompt_tokens | int | 输入 prompt token 数（兼容旧版字段，通常为 0） |
completion_tokens | int | 输出 completion token 数（兼容旧版字段，通常为 0） |
total_tokens | int | 总消耗 token 数 |
input_tokens | int | 输入 token 数 |
output_tokens | int | 输出 token 数 |
input_tokens_details.cached_tokens | int | 命中缓存的 token 数 |
input_tokens_details.text_tokens | int | 文本输入 token 数 |
input_tokens_details.audio_tokens | int | 音频输入 token 数 |
input_tokens_details.image_tokens | int | 图片输入 token 数 |
7.2 错误响应
{
"error": {
"code": "InvalidParameter",
"message": "error description"
}
}
8. 错误码
| HTTP | code | 说明 |
|---|
| 400 | InvalidParameter | 请求参数错误（如 prompt 为空、图片格式不支持） |
| 401 | Unauthorized | API Key 无效或未提供 |
| 403 | Forbidden | 无权限调用该模型 |
| 429 | RateLimitExceeded | 触发频率限制 |
| 500 | InternalError | 服务内部错误 |
| 503 | ServiceUnavailable | 上游服务不可用，建议稍后重试 |
9. 计费说明
- 计费单位：按 token（
input_tokens + output_tokens）
- 命中缓存的 token 按缓存价格计费，低于正常输入价格
- 任务失败不计费
- 具体价格请查看平台「模型价格」页面
10. 常见问题
Q1：gpt-image-2 支持哪些输出格式？ A：支持 png（默认）、jpeg、webp，通过 output_format 参数指定。
Q2：如何生成透明背景图片？ A：设置 background 为 transparent，输出格式建议使用 png（仅 gpt-image-* 支持）。
Q3：generations 和 edits 接口如何选择？ A：无参考图（纯文生图）使用 /v1/images/generations；有参考图（图片编辑/融合）使用 /v1/images/edits。
Q4：edits 接口如何上传多张参考图？ A：使用同名 image 字段多值上传，如 -F "image=@ref1.png" -F "image=@ref2.png"。
Q5：revised_prompt 是什么？ A：模型可能对原始 prompt 做了改写或扩展，revised_prompt 即为模型实际使用的提示词文本。
Q6：quality 参数支持哪些值？ A：字符串枚举 high / medium / low / auto。
11. 快速接入清单
- 获取 API Key
- 确认调用环境，可访问 OpenAI API Base URL
- 选择接口：文生图 →
/v1/images/generations；图片编辑 → /v1/images/edits
- 图片编辑场景准备参考图文件，以
multipart/form-data 上传
- 发送请求，同步获取图片结果（
b64_json 或 url）
- 解码 base64 数据或下载 URL 保存图片