gpt-image-2 使用官方图像接口。你可以通过 /images/generations 创建图像，也可以通过 /images/edits 提交参考图并生成编辑结果。
AIOAGI 的
gpt-image-2 返回与官方一致，图片结果通过 b64_json 返回，不返回图片 URL。你需要先 Base64 解码再保存图片。官方参考
创建图像
POST/images/generations
你可以用这个接口根据 prompt 直接生成图像。常见场景包括海报草图、产品配图、插画素材和视觉创意探索。
常用参数
| 参数 | 类型 | 说明 |
|---|---|---|
prompt | string | 必填。输入图像描述。 |
model | string | 可选。本文示例使用 gpt-image-2。你也可以按控制台展示切换到其他 GPT-Image 系列模型。 |
size | string | 可选。常用值包括 1024x1024、1536x1024、1024x1536 或 auto。 |
quality | string | 可选。GPT-Image 模型常用 low、medium、high 或 auto。 |
background | string | 可选。可设为 transparent、opaque 或 auto。 |
output_format | string | 可选。GPT-Image 模型常用 png、jpeg 或 webp。 |
output_compression | number | 可选。jpeg 或 webp 输出时可设置压缩比例。 |
partial_images | number | 可选。流式响应中的中间图数量，取值通常为 0 到 3。 |
n | number | 可选。生成图片数量。部分模型限制更严格，请以控制台和开发者指南为准。 |
moderation | string | 可选。GPT-Image 模型可使用 auto 或 low。 |
stream | boolean | 可选。设为 true 后可以接收流式部分图像事件。 |
user | string | 可选。用于标识你的终端用户。 |
response_format 是 dall-e-2 和 dall-e-3 的返回格式参数。GPT-Image 官方接口不支持该参数，gpt-image-2 返回 b64_json。请求示例
curl https://api.aiearth.dev/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-your-api-key" \
-d '{
"model": "gpt-image-2",
"prompt": "A cute baby sea otter",
"n": 1,
"size": "1024x1024",
"quality": "medium",
"background": "transparent",
"output_format": "png"
}'
Python 示例
下面的示例会从b64_json 解码图片，并保留原始响应日志，便于排查问题。
import base64
import requests
API_KEY = 'sk-your-api-key'
API_URL = 'https://api.aiearth.dev/v1/images/generations'
payload = {
"model": "gpt-image-2",
"prompt": "A product photo of a ceramic coffee cup on a wooden table.",
"n": 1,
"size": "1024x1024",
"quality": "medium",
"output_format": "png"
}
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
}
print("正在生成图片...")
response = requests.post(API_URL, headers=headers, json=payload)
response_text = response.text
print("\n原始响应:")
print(response_text)
log_path = "response_create.txt"
with open(log_path, "w", encoding="utf-8") as f:
f.write(response_text)
print(f"响应已保存: {log_path}\n")
if response.status_code == 200:
result = response.json()
print("请求成功!")
print(f"生成时间: {result['created']}")
image_data = result['data'][0]
output_path = "generated_image.png"
image_bytes = base64.b64decode(image_data['b64_json'])
with open(output_path, "wb") as f:
f.write(image_bytes)
print(f"图片已保存: {output_path}")
else:
print(f"请求失败: {response.status_code}")
print(f"错误信息: {response.text}")
官方返回结构
GPT-Image 官方接口通常返回b64_json，并可能包含 usage 用量信息。常见结构如下：
{
"created": 1713833628,
"data": [
{
"b64_json": "..."
}
],
"usage": {
"total_tokens": 100,
"input_tokens": 50,
"output_tokens": 50,
"input_tokens_details": {
"text_tokens": 10,
"image_tokens": 40
}
}
}
返回说明
gpt-image-2返回b64_json，你需要先 Base64 解码再保存图片。- 如果返回结果和预期不一致，请先检查脚本生成的
response_create.txt日志文件。 usage等统计字段可能随模型和请求参数略有差异，请以实际响应为准。- 如果你开启
stream: true，常见事件类型为image_generation.partial_image和image_generation.completed。
编辑图像
POST/images/edits
你可以提交一张或多张参考图，再结合提示词生成新的编辑结果。这个接口适合局部重绘、风格迁移、素材拼接和多图组合。
常用参数
| 参数 | 类型 | 说明 |
|---|---|---|
images | array | 必填。输入图像列表。GPT-Image 模型通常最多支持 16 张。 |
prompt | string | 必填。描述你希望对输入图像做出的修改。 |
model | string | 可选。本文示例使用 gpt-image-2。你也可以按控制台展示切换到其他 GPT-Image 系列模型。 |
input_fidelity | string | 可选。可设为 high 或 low，用于控制对原图的保真程度。 |
mask | object | 可选。可通过 file_id 或 image_url 指定遮罩图。 |
background | string | 可选。可设为 transparent、opaque 或 auto。 |
quality | string | 可选。常用值包括 low、medium、high 或 auto。 |
size | string | 可选。常用值包括 1024x1024、1536x1024、1024x1536 或 auto。 |
output_format | string | 可选。常用值包括 png、jpeg 或 webp。 |
output_compression | number | 可选。jpeg 或 webp 输出时可设置压缩比例。 |
partial_images | number | 可选。流式响应中的中间图数量，取值通常为 0 到 3。 |
n | number | 可选。生成图片数量。部分模型限制更严格，请以控制台和开发者指南为准。 |
moderation | string | 可选。GPT-Image 模型可使用 auto 或 low。 |
stream | boolean | 可选。设为 true 后可以接收流式部分图像事件。 |
user | string | 可选。用于标识你的终端用户。 |
请求示例
curl -X POST "https://api.aiearth.dev/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=gpt-image-2" \
-F "image[]=@body-lotion.png" \
-F "image[]=@bath-bomb.png" \
-F "image[]=@incense-kit.png" \
-F "image[]=@soap.png" \
-F "prompt=Create a lovely gift basket with these four items in it" \
-F "quality=high" \
-F "size=1024x1024" \
-F "output_format=png"
Python 示例
下面的示例兼容 URL 输入和本地文件输入，并从b64_json 解码保存结果图片。
import base64
from io import BytesIO
import requests
API_KEY = 'sk-your-api-key'
API_URL = 'https://api.aiearth.dev/v1/images/edits'
def download_image(url):
"""从URL下载图片并返回字节数据"""
response = requests.get(url)
if response.status_code == 200:
return response.content
raise Exception(f"下载图片失败: {response.status_code}")
images = [
"https://example.com/source-image.webp",
# "local_image.png",
]
prompt = "Add a watercolor effect to this image"
model = "gpt-image-2"
background = "transparent"
input_fidelity = "high"
quality = "high"
size = "1024x1024"
output_format = "png"
output_compression = 100
n = 1
moderation = "auto"
files = []
data = {}
for i, img in enumerate(images):
if img.startswith('http://') or img.startswith('https://'):
img_data = download_image(img)
files.append(('image[]', (f'image_{i}.webp', BytesIO(img_data), 'image/webp')))
else:
files.append(('image[]', open(img, 'rb')))
data['prompt'] = prompt
data['model'] = model
data['background'] = background
data['input_fidelity'] = input_fidelity
data['quality'] = quality
data['size'] = size
data['output_format'] = output_format
data['output_compression'] = str(output_compression)
data['n'] = str(n)
data['moderation'] = moderation
headers = {
'Authorization': f'Bearer {API_KEY}'
}
print("正在编辑图片...")
response = requests.post(API_URL, headers=headers, data=data, files=files)
response_text = response.text
print("\n原始响应:")
print(response_text)
log_path = "response_edit.txt"
with open(log_path, "w", encoding="utf-8") as f:
f.write(response_text)
print(f"响应已保存: {log_path}\n")
if response.status_code == 200:
result = response.json()
print("编辑成功!")
print(f"生成时间: {result['created']}")
print(f"背景类型: {result.get('background', 'N/A')}")
print(f"输出格式: {result.get('output_format', 'N/A')}")
print(f"输出质量: {result.get('quality', 'N/A')}")
print(f"输出尺寸: {result.get('size', 'N/A')}")
if 'usage' in result:
usage = result['usage']
print(f"\nToken使用:")
print(f" 输入tokens: {usage['input_tokens']} (图片: {usage['input_tokens_details']['image_tokens']}, 文本: {usage['input_tokens_details']['text_tokens']})")
print(f" 输出tokens: {usage['output_tokens']}")
print(f" 总计tokens: {usage['total_tokens']}")
for i, img_data in enumerate(result['data']):
image_bytes = base64.b64decode(img_data['b64_json'])
output_path = f"edited_image_{i+1}.{result.get('output_format', 'png')}"
with open(output_path, 'wb') as f:
f.write(image_bytes)
print(f"图片已保存: {output_path}")
if 'revised_prompt' in img_data:
print(f"修订提示词: {img_data['revised_prompt']}")
else:
print(f"请求失败: {response.status_code}")
print(f"错误信息: {response.text}")
for _, file_tuple in files:
if hasattr(file_tuple, 'close'):
file_tuple.close()
elif isinstance(file_tuple, tuple) and len(file_tuple) > 1:
file_obj = file_tuple[1]
if hasattr(file_obj, 'close'):
file_obj.close()
返回说明
gpt-image-2图像编辑请求返回b64_json，你需要先 Base64 解码再保存图片。- 如果返回结果和预期不一致，请先检查脚本生成的
response_edit.txt日志文件。 - 如果你开启
stream: true，常见事件类型为image_edit.partial_image和image_edit.completed。