图片生成

POST /v1/images/generations

OpenAI 兼容的图片生成接口,当前主力模型为 gpt-image-2。支持同步异步两种模式:

  • 同步:一次请求阻塞到出图,直接返回图片(适合低并发、即时场景)。
  • 异步:提交后立即拿到任务 ID,再轮询取结果(适合大批量、避免长连接超时)。

可用模型

模型 分辨率档位 说明
gpt-image-2 1K / 2K / 4K 主力模型,通用生图与编辑。
gpt-image-2.5 1K 仅 1K 档位。
gpt-image-2.5-flare 1K / 2K / 4K 日常生图,出图更快。
gpt-image-2.5-sunburst 1K / 2K / 4K 精准编辑,擅长按指令改图。

以上模型均支持两种用法:

  • 文生图:POST /v1/images/generations(同步)或 POST /v1/images/generations/async(异步)。
  • 图生图:POST /v1/images/edits(同步)或 POST /v1/images/edits/async(异步),以 multipart 形式上传 imageprompt,尺寸/分辨率参数与文生图完全一致。

兼容写法:gpt-image-2-2K / gpt-image-2-4K 这两个模型名仍然可用,便于已有集成继续调用,它们分别等价于 gpt-image-2 搭配 resolution2K / 4K。新接入建议统一使用 gpt-image-2 + 参数的写法。

如何选择分辨率档位

gpt-image-2 支持 1K / 2K / 4K 三个分辨率档位——用同一个模型名,通过参数选择,不需要换模型。有两种等价写法:

  • resolution(推荐):直接指定档位 1K / 2K / 4K;画幅比例另用 size 指定,或不传(默认方图 1:1)。
  • size:传该档位对应的像素尺寸(见下方对照表),网关据此同时确定档位与画幅比例。
目标 请求体写法
1K(默认) 不传尺寸参数,或 "resolution": "1K"
2K 方图 "resolution": "2K",或 "size": "2048x2048"
2K 横图 16:9 "resolution": "2K", "size": "2560x1440",或直接 "size": "2560x1440"
4K 方图 "resolution": "4K",或 "size": "2880x2880"
4K 横图 16:9 "resolution": "4K", "size": "3840x2160",或直接 "size": "3840x2160"

gpt-image-2.5-flare / gpt-image-2.5-sunburst 用法完全相同;gpt-image-2.5 仅支持 1K。

同步:POST /v1/images/generations

请求参数

参数 类型 必填 说明
model string 模型 ID,如 gpt-image-2
prompt string 图片描述提示词。
n integer 生成数量,当前仅支持 1(默认 1)。
size string 图片尺寸,格式为 宽x高,如 1024x10242560x14403840x2160,也可传 auto。它同时决定画幅比例分辨率档位(见下方档位对照表)。不在对照表中的尺寸按像素面积归入档位:≤ 2,000,000 归为 1K;≤ 5,000,000 归为 2K;≤ 9,000,000 归为 4K;更大则返回 400。
resolution string 分辨率档位,取值 1K / 2K / 4K(大小写不敏感;也接受别名 image_size)。优先级高于 size 隐含的档位;与 size 搭配使用可固定画幅比例、单独指定档位。若指定的档位该模型不支持,返回 400。
quality string 画质档。gpt-image-2.5 系列取值为 low / medium / high / xhigh / max / auto;gpt-image-2 可选传入,当前不改变出图效果。该参数不影响分辨率档位。
response_format string 返回形式:b64_json(默认,图片以 base64 内联在 JSON 里)或 url(返回一个约 2 小时有效的下载链接,见下文「响应」)。传其他值返回 400。

档位优先级:resolution > size 隐含的档位 > 默认 1K。

提示:图片较大(2K/4K)或并发较高时,建议传 "response_format": "url",响应体只有几百字节,客户端按需下载图片即可。

分辨率档位对照表

画幅比例 1K 2K 4K
1:1 1024×1024 2048×2048 2880×2880
16:9 1280×720 2560×1440 3840×2160
9:16 720×1280 1440×2560 2160×3840
3:2 1248×832 2496×1664 3504×2336
2:3 832×1248 1664×2496 2336×3504
4:3 1152×864 2304×1728 3264×2448
3:4 864×1152 1728×2304 2448×3264
5:4 1120×896 2240×1792 3200×2560
4:5 896×1120 1792×2240 2560×3200
21:9 1456×624 3024×1296 3696×1584

模型按所选档位与画幅比例的原生分辨率出图,因此返回图片的实际像素尺寸可能与请求的 size 略有出入。

计费说明

图片生成的计费单位与单价以你所在站点的「定价说明」和 Portal 定价页为准。响应中的 usage 反映本次生成的 token 用量,可作为对账参考;档位越高,生成的图片越大,费用也相应更高。

请求示例

cURL

curl https://api.aiin1.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red fox running in snow, studio lighting",
    "n": 1
  }'

cURL(用 size 指定 16:9 的 2K)

curl https://api.aiin1.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red fox running in snow, studio lighting",
    "size": "2560x1440",
    "n": 1
  }'

cURL(用 resolution 单独指定档位)

curl https://api.aiin1.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "a red fox running in snow, studio lighting",
    "size": "1024x1024",
    "resolution": "2K",
    "n": 1
  }'

Python

import openai
 
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.aiin1.ai/v1",
)
 
resp = client.images.generate(
    model="gpt-image-2",
    prompt="a red fox running in snow, studio lighting",
    n=1,
)
b64 = resp.data[0].b64_json   # base64 编码的 PNG

OpenAI SDK 没有 resolution 这个原生字段,通过 extra_body 传入即可:

resp = client.images.generate(
    model="gpt-image-2",
    prompt="a red fox running in snow, studio lighting",
    size="1024x1024",
    n=1,
    extra_body={"resolution": "2K"},
)

图生图:POST /v1/images/edits

multipart/form-data 形式上传原图与提示词,返回格式与同步文生图相同(base64 内联)。

参数 类型 必填 说明
image file 输入图片,PNG / JPEG / WEBP,单张不超过 25 MB,整个请求合计不超过 32 MB。多张参考图时重复传 image[](或多个 image),最多 8 张
prompt string 编辑指令,描述要怎么改。
model string 模型 ID,如 gpt-image-2gpt-image-2.5-sunburst(擅长按指令改图)。
n integer 生成数量,当前仅支持 1
size / resolution / quality string 与文生图语义一致,见上文参数表与档位对照表。

暂不支持 mask(蒙版)参数,传入会返回错误;请用 prompt 描述要修改的区域。

图生图单次通常需要 1–3 分钟,高峰期可能更久。客户端读超时建议不低于 15 分钟,否则可能在出图前主动断开;也可以改用下文的异步图生图接口。

用链接传参考图(JSON 写法)

除了 multipart 上传文件,也可以用 Content-Type: application/json 直接传图片链接或 data URL,其余参数(modelpromptsizeresolutionqualityresponse_format 等)与 multipart 写法相同:

curl https://api.aiin1.ai/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "place the product from the first image onto the scene in the second image",
    "images": [
      "https://example.com/product.png",
      "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
    ],
    "size": "2560x1440",
    "response_format": "url"
  }'
  • images 数组的每一项可以是 https 链接data URL(data:image/png|jpeg|webp;base64,...)。也兼容 image 字段(字符串或数组),以及 OpenAI 风格的 {"image_url": "..."} / {"image_url": {"url": "..."}}
  • JSON 写法最多 8 张,不支持 mask
  • 链接要求:必须是 https、默认端口 443、可以从公网直接访问(不能是内网地址,不跟随重定向,请直接给最终地址);内容必须是 PNG / JPEG / WEBP 图片,单张不超过 25 MB,所有图片合计不超过 64 MB。
  • data URL 计入整个请求 32 MB 的上限(base64 会让体积增大约 1/3),大图建议用链接。
  • 任何一张图片拿不到或不合格,都会在出图前返回 400,不计费,报错信息会指出是第几张、什么原因,例如:
    {"error": {"type": "invalid_request_error", "message": "images[1]: host example.com answered HTTP 404"}}

cURL(单张图)

curl https://api.aiin1.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F image=@input.png \
  -F model=gpt-image-2.5-sunburst \
  -F prompt="turn the sky into a starry night, keep the fox unchanged" \
  -F resolution=2K

cURL(多张参考图,16:9 横图)

curl https://api.aiin1.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image[]=@product.png" \
  -F "image[]=@background.jpg" \
  -F model=gpt-image-2 \
  -F prompt="place the product from the first image onto the scene in the second image" \
  -F size=2560x1440

Python

import base64
import openai
 
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.aiin1.ai/v1",
    timeout=900,   # 图生图耗时较长,读超时至少 15 分钟
)
 
with open("input.png", "rb") as f:
    resp = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=f,                      # 多张参考图传列表: image=[f1, f2]
        prompt="turn the sky into a starry night, keep the fox unchanged",
        extra_body={"resolution": "2K"},
    )
 
with open("output.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))

响应

返回 base64 内联的图片:

{
  "created": 1730000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "..."
    }
  ],
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 18
    },
    "output_tokens": 7024,
    "output_tokens_details": {
      "image_tokens": 7024,
      "text_tokens": 0
    },
    "total_tokens": 7042
  }
}

前端展示时加前缀:data:image/png;base64,<b64_json>

"response_format": "url" 时,返回下载链接而不是 base64:

{
  "created": 1730000000,
  "data": [
    {
      "url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
      "revised_prompt": "..."
    }
  ],
  "usage": { "...": "与上面相同" }
}

链接约 2 小时有效,请在有效期内下载或转存;图片在 48 小时后删除。图片已生成但链接暂时无法生成时(极少见),返回 502 且不计费,可以直接重试。


异步:POST /v1/images/generations/async

请求体与同步文生图完全一致(model / prompt / n / size / resolution / quality,语义与上文相同),但立即返回任务 ID,不阻塞出图。适合批量生成或客户端不希望长连接等待的场景。

本节是异步文生图。异步图生图见文末「异步图生图」一节。

1. 提交任务

curl https://api.aiin1.ai/v1/images/generations/async \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red fox running in snow",
    "size": "2560x1440",
    "n": 1
  }'

返回 202 Accepted:

{
  "id": "nximg_xxxxxxxx",
  "status": "queued",
  "created": 1730000000,
  "object": "image.generation.async"
}

2. 轮询结果:GET /v1/images/generations/async/{job_id}

curl https://api.aiin1.ai/v1/images/generations/async/nximg_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

status 取值:queuedprocessingsucceeded(或 failed)。建议每 1–2 秒轮询一次,通常数秒到数十秒完成。

进行中:

{ "id": "nximg_xxxxxxxx", "status": "processing", "created": 1730000000 }

完成:

{
  "id": "nximg_xxxxxxxx",
  "status": "succeeded",
  "created": 1730000000,
  "data": [
    {
      "url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
      "revised_prompt": "..."
    }
  ],
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 18
    },
    "output_tokens": 7024,
    "output_tokens_details": {
      "image_tokens": 7024,
      "text_tokens": 0
    },
    "total_tokens": 7042
  }
}

失败:

{
  "id": "nximg_xxxxxxxx",
  "status": "failed",
  "created": 1730000000,
  "error": { "type": "upstream_error", "message": "generation failed", "code": "..." }
}

关于 url:与同步返回内联 base64 不同,异步成功时返回一个带签名的下载链接(有效期约 2 小时)。请在有效期内下载/转存,过期需重新生成。失败任务不计费。

参数说明

字段 说明
id 任务 ID(nximg_ 前缀),用于轮询。与你的 API Key 所属组织绑定,他人无法访问。
status queued / processing / succeeded / failed
data[].url 成功时的图片下载链接(presigned,约 2h 有效)。
data[].revised_prompt 模型改写后的提示词(可能为空)。
usage 成功时返回,结构与同步一致。

异步图生图:POST /v1/images/edits/async

同步图生图 POST /v1/images/edits 的异步版本。请求格式完全相同(multipart/form-data 上传文件,或 JSON 写法传图片链接,参数见上文「图生图」一节),但立即返回任务 ID,出图后再轮询取结果。图生图耗时较长(通常 1–3 分钟),批量或不想长时间保持连接时推荐使用。

与同步图生图的区别:

  • 输入图片最多 8 张,单张不超过 25 MB,整个请求合计不超过 32 MB。
  • 不支持 mask,传入会直接返回 400。
  • 成功时返回带签名的下载链接(约 2 小时有效),不是内联 base64。

1. 提交任务

curl https://api.aiin1.ai/v1/images/edits/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F image=@input.png \
  -F model=gpt-image-2 \
  -F prompt="turn the sky into a starry night, keep the fox unchanged" \
  -F resolution=2K

多张参考图时重复传 image[](或多个 image),与同步接口一致。

返回 202 Accepted:

{
  "id": "nximg_xxxxxxxx",
  "status": "queued",
  "created": 1730000000,
  "object": "image.edit.async"
}

2. 轮询结果:GET /v1/images/edits/async/{job_id}

curl https://api.aiin1.ai/v1/images/edits/async/nximg_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

返回格式与异步文生图完全相同(queuedprocessingsucceeded / failed,成功时 data[].url 为下载链接,并附 usage)。建议每 2–5 秒轮询一次。异步文生图和异步图生图的任务 ID 通用,也可以用 GET /v1/images/generations/async/{job_id} 查询。

Python 示例

import time
import requests
 
API = "https://api.aiin1.ai/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
 
# 1. 提交任务(多张参考图: files=[("image[]", f1), ("image[]", f2)])
with open("input.png", "rb") as f:
    job = requests.post(
        f"{API}/images/edits/async",
        headers=HEADERS,
        files=[("image", ("input.png", f, "image/png"))],
        data={
            "model": "gpt-image-2",
            "prompt": "turn the sky into a starry night, keep the fox unchanged",
            "resolution": "2K",
        },
        timeout=120,
    ).json()
 
# 2. 轮询结果
while True:
    r = requests.get(f"{API}/images/edits/async/{job['id']}", headers=HEADERS, timeout=30).json()
    if r["status"] in ("succeeded", "failed"):
        break
    time.sleep(3)
 
if r["status"] == "succeeded":
    img = requests.get(r["data"][0]["url"], timeout=120).content   # 链接约 2 小时有效
    open("output.png", "wb").write(img)
else:
    print(r["error"])