图片生成
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 形式上传image与prompt,尺寸/分辨率参数与文生图完全一致。
兼容写法:
gpt-image-2-2K/gpt-image-2-4K这两个模型名仍然可用,便于已有集成继续调用,它们分别等价于gpt-image-2搭配resolution为2K/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高,如 1024x1024、2560x1440、3840x2160,也可传 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 编码的 PNGOpenAI 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-2、gpt-image-2.5-sunburst(擅长按指令改图)。 |
n |
integer | 否 | 生成数量,当前仅支持 1。 |
size / resolution / quality |
string | 否 | 与文生图语义一致,见上文参数表与档位对照表。 |
暂不支持
mask(蒙版)参数,传入会返回错误;请用prompt描述要修改的区域。图生图单次通常需要 1–3 分钟,高峰期可能更久。客户端读超时建议不低于 15 分钟,否则可能在出图前主动断开;也可以改用下文的异步图生图接口。
用链接传参考图(JSON 写法)
除了 multipart 上传文件,也可以用 Content-Type: application/json 直接传图片链接或 data URL,其余参数(model、prompt、size、resolution、quality、response_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=2KcURL(多张参考图,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=2560x1440Python
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 取值:queued → processing → succeeded(或 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"返回格式与异步文生图完全相同(queued → processing → succeeded / 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"])