Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aioagi.tech/llms.txt

Use this file to discover all available pages before exploring further.

gpt-image-2 使用官方图像接口。你可以通过 /images/generations 创建图像，也可以通过 /images/edits 提交参考图并生成编辑结果。
AIOAGI 的 gpt-image-2 返回与官方一致，图片结果通过 b64_json 返回，不返回图片 URL。你需要先 Base64 解码再保存图片。

​
官方参考

​
创建图像

POST /images/generations 你可以用这个接口根据 prompt 直接生成图像。常见场景包括海报草图、产品配图、插画素材和视觉创意探索。

​
常用参数

参数类型说明
promptstring必填。输入图像描述。
modelstring可选。本文示例使用 gpt-image-2。你也可以按控制台展示切换到其他 GPT-Image 系列模型。
sizestring可选。常用值包括 1024x1024、1536x1024、1024x1536 或 auto。
qualitystring可选。GPT-Image 模型常用 low、medium、high 或 auto。
backgroundstring可选。可设为 transparent、opaque 或 auto。
output_formatstring可选。GPT-Image 模型常用 png、jpeg 或 webp。
output_compressionnumber可选。jpeg 或 webp 输出时可设置压缩比例。
partial_imagesnumber可选。流式响应中的中间图数量，取值通常为 0 到 3。
nnumber可选。生成图片数量。部分模型限制更严格，请以控制台和开发者指南为准。
moderationstring可选。GPT-Image 模型可使用 auto 或 low。
streamboolean可选。设为 true 后可以接收流式部分图像事件。
userstring可选。用于标识你的终端用户。
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 你可以提交一张或多张参考图，再结合提示词生成新的编辑结果。这个接口适合局部重绘、风格迁移、素材拼接和多图组合。

​
常用参数

参数类型说明
imagesarray必填。输入图像列表。GPT-Image 模型通常最多支持 16 张。
promptstring必填。描述你希望对输入图像做出的修改。
modelstring可选。本文示例使用 gpt-image-2。你也可以按控制台展示切换到其他 GPT-Image 系列模型。
input_fidelitystring可选。可设为 high 或 low，用于控制对原图的保真程度。
maskobject可选。可通过 file_id 或 image_url 指定遮罩图。
backgroundstring可选。可设为 transparent、opaque 或 auto。
qualitystring可选。常用值包括 low、medium、high 或 auto。
sizestring可选。常用值包括 1024x1024、1536x1024、1024x1536 或 auto。
output_formatstring可选。常用值包括 png、jpeg 或 webp。
output_compressionnumber可选。jpeg 或 webp 输出时可设置压缩比例。
partial_imagesnumber可选。流式响应中的中间图数量，取值通常为 0 到 3。
nnumber可选。生成图片数量。部分模型限制更严格，请以控制台和开发者指南为准。
moderationstring可选。GPT-Image 模型可使用 auto 或 low。
streamboolean可选。设为 true 后可以接收流式部分图像事件。
userstring可选。用于标识你的终端用户。

​
请求示例

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。