图片生成
用一段文本提示词生成图片。接口兼容 OpenAI POST /v1/images/generations,同一个接口可以调用 GPT Image、DALL·E、Gemini / Imagen 等图片模型。需要基于已有图片修改时用图片编辑。
| 项 | 值 |
|---|---|
| 方法与路径 | POST /v1/images/generations |
| 鉴权 | Authorization: Bearer YOUR_API_KEY |
| Content-Type | application/json |
示例中的模型名只作演示。当前 Key 能用哪些模型,以
GET /v1/models的返回为准(见模型列表)。
快速示例
cURL
curl https://www.nextai-code.com/v1/images/generations \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
--max-time 600 \
-d '{
"model": "gpt-image-2",
"prompt": "一只坐在窗边看雨的橘猫,柔和自然光,插画风格",
"size": "1024x1024",
"quality": "medium",
"output_format": "png",
"n": 1
}' \
-o image-response.json
成功时 data 是图片数组,每项通常带 b64_json(base64 编码的文件内容):
{
"created": 1793966400,
"data": [
{"b64_json": "BASE64_IMAGE_DATA"}
]
}
把响应里每张图存成文件:
python3 - <<'PY'
import base64, json
from pathlib import Path
result = json.loads(Path("image-response.json").read_text())
for i, image in enumerate(result["data"], start=1):
if not image.get("b64_json"):
raise SystemExit(f"第 {i} 张返回的是 URL:{image.get('url')},下载方式见「响应」一节")
Path(f"image-{i}.png").write_bytes(base64.b64decode(image["b64_json"]))
print(f"image-{i}.png")
PY
后缀用 .png 是因为请求里写了 output_format: "png"。只改后缀不会转换图片格式。
Python(OpenAI SDK)
import base64, os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NEXTAI_API_KEY"],
base_url="https://www.nextai-code.com/v1",
timeout=600.0,
max_retries=0, # 生图慢且计费,避免结果未知时被 SDK 自动重复提交
)
response = client.images.generate(
model="gpt-image-2",
prompt="一只坐在窗边看雨的橘猫,插画风格",
size="1024x1024",
quality="medium",
n=1,
output_format="png",
)
for i, image in enumerate(response.data, start=1):
if not image.b64_json:
raise RuntimeError(f"返回的是 URL:{image.url}")
Path(f"sdk-image-{i}.png").write_bytes(base64.b64decode(image.b64_json))
Node.js(fetch,Node 18+)
const fs = require('node:fs');
async function main() {
const res = await fetch('https://www.nextai-code.com/v1/images/generations', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.NEXTAI_API_KEY}`,
},
body: JSON.stringify({
model: 'gpt-image-2',
prompt: '一只坐在窗边看雨的橘猫,插画风格',
output_format: 'png',
n: 1,
}),
signal: AbortSignal.timeout(600_000),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
const result = await res.json();
result.data.forEach((image, i) => {
if (!image.b64_json) throw new Error(`返回的是 URL:${image.url}`);
fs.writeFileSync(`node-image-${i + 1}.png`, Buffer.from(image.b64_json, 'base64'));
});
}
main().catch((e) => { console.error(e.message); process.exitCode = 1; });
请求参数
下表是通用字段。取值因模型而异,不要把一个模型的参数组合原样套到另一个模型上,详见下一节「按模型选择参数」。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 图片模型名。缺失时返回 缺少 model 参数 |
prompt |
string | 是 | 图片描述,可用中文 |
n |
integer | 否 | 输出张数,默认 1,最大 10(超过返回 n 参数不能大于 10)。模型自身上限可能更低 |
size |
string | 否 | 尺寸。GPT Image / DALL·E 用像素写法如 1024x1024;Gemini / Imagen 可用比例如 16:9。必须用字母 x,写成乘号 × 会被拒绝 |
quality |
string | 否 | 质量档位。GPT Image 是渲染质量,Gemini / Imagen 是分辨率档位,含义不同 |
response_format |
string | 否 | 返回编码:b64_json 或 url。是否生效取决于模型;GPT Image 固定返回 base64,建议省略 |
output_format |
string | 否 | 输出文件格式,如 png / jpeg / webp,仅对支持的模型有效 |
background |
string | 否 | 背景,如 auto / opaque / transparent |
output_compression |
integer | 否 | 0–100,JPEG / WebP 压缩率 |
moderation |
string | 否 | 审核强度,如 auto / low |
style |
string | 否 | 风格,DALL·E 3 使用(vivid / natural) |
user |
string | 否 | 终端用户标识,透传给模型服务商 |
stream |
boolean | 否 | 流式返回,仅部分模型支持;不能与 async 同时为 true |
partial_images |
integer | 否 | 流式时返回的中间图数量,仅支持的模型有效 |
watermark |
boolean | 否 | 水印开关,仅支持的模型有效 |
async |
boolean | 否 | 平台异步开关,默认 false。为 true 时立即返回任务 ID,见异步任务与素材下载 |
未列出的字段: 调用 GPT Image、DALL·E 等 OpenAI 系列模型时,表外的字段(含嵌套对象)会原样转发给模型服务商,直接写在请求体顶层即可,是否生效取决于模型。Gemini / Imagen 等经过协议转换的模型会拒绝表外字段。
按模型选择参数
GPT Image
| 参数 | 取值 |
|---|---|
size |
推荐 auto、1024x1024、1536x1024、1024x1536。别名 1k / 2k / 4k 会按 1024x1024 / 2048x2048 / 4096x4096 处理,模型不一定支持,建议直接写像素 |
quality |
auto、low、medium、high。省略时按 auto 处理 |
response_format |
建议省略,结果固定为 base64 |
background |
auto / opaque / transparent。透明背景需模型支持,并配合 PNG 或 WebP 输出 |
output_format |
png / jpeg / webp;新一代模型支持更多格式,见下方「GPT Image 新一代模型支持的参数」 |
output_compression |
0–100,仅 JPEG / WebP |
moderation |
auto / low;low 仍受模型内容安全限制 |
GPT Image 的 quality 不是 1K/2K/4K 分辨率,不要把 Gemini 示例中的 hd、ultra 用在这里。
部分型号由平台预先校验 size、quality、background 与 n(上限 10),不在范围内直接返回 400,错误信息形如 参数 size="..." 不支持,模型支持:...,按其中列出的取值调整即可;其他型号由模型服务商校验。自定义尺寸范围请查阅 OpenAI 图片接口参数。
GPT Image 新一代模型支持的参数
表外字段会原样转发,因此可以直接使用 OpenAI 新增的参数。以下参数参考 OpenAI 官方文档,是否可用取决于模型:
| 参数 | 说明 |
|---|---|
complexity |
low / medium / high,控制生成前的规划计算量,与 quality 独立;新一代模型默认 high |
output_format |
除 png / jpeg / webp 外还可为 svg / gif |
svg |
对象,{"model": "...", "reasoning": {"effort": "..."}},可选的 SVG 作者模型及推理投入;未开通时整个省略 |
frame_count |
GIF 帧数,2–16,默认 9 |
frame_duration_ms |
GIF 每帧时长,默认 200 ms;官方范围 20–2000 ms,按 10 ms 取整 |
生成 SVG 的请求体:
{
"model": "gpt-image-2",
"prompt": "面包店的简洁矢量标志,可编辑的路径和色块",
"output_format": "svg",
"complexity": "medium",
"n": 1
}
SVG 只能用于生成接口,要求 n=1,不支持流式、partial_images、output_compression、prompt_rewriter。b64_json 解码后是 UTF-8 SVG XML,保存为 .svg。响应可能附带独立的作者用量 svg_usage。
生成 GIF 的请求体:
{
"model": "gpt-image-2",
"prompt": "一盏轻轻摇摆的灯笼,首尾衔接的循环动画",
"output_format": "gif",
"frame_count": 9,
"frame_duration_ms": 200,
"size": "auto",
"n": 1
}
帧数、每帧尺寸与 n 共同受模型的像素预算限制,超限时减少其中之一。GIF 不支持流式、partial_images、mask、output_compression、prompt_rewriter。
DALL·E
平台会预先校验 DALL·E 的尺寸,不符合时直接返回 400:
| 系列 | size 可选值 |
默认 |
|---|---|---|
| DALL·E 2 | 256x256、512x512、1024x1024 |
size 默认 1024x1024 |
| DALL·E 3 | 1024x1024、1024x1792、1792x1024 |
size 默认 1024x1024,quality 默认 standard |
DALL·E 3 的 quality 取 standard / hd,不要套用 GPT Image 的取值。
Gemini / Nano Banana 与 Imagen
适用于通过本接口调用 Gemini 图片模型(含 Nano Banana 系列)和 Imagen 模型。想使用 Gemini 原生参数,见 Gemini 图像。
size:选比例,不定像素。 可直接写比例如 1:1、16:9、9:16、3:2、2:3(可用比例随模型变化);以下像素写法只映射为比例:
size 输入 |
映射比例 |
|---|---|
256x256 / 512x512 / 1024x1024 |
1:1 |
1792x1024 |
16:9 |
1024x1792 |
9:16 |
1536x1024 |
3:2 |
1024x1536 |
2:3 |
quality:选分辨率档位。
quality |
分辨率档位 |
|---|---|
standard / low / medium / auto / 1k |
1K |
hd / high / 2k |
2K |
ultra / 4k |
4K |
Gemini 也可以用 size 写 1k / 2k / 4k 指定档位;与 quality 同时出现且不一致时报错。Gemini 2 系列图像模型和初代 Nano Banana 只输出 1K,档位参数不生效。档位不承诺精确宽高,实际尺寸以生成文件为准。
示例请求体:
{
"model": "gemini-3.1-flash-image",
"prompt": "一只坐在窗边看雨的橘猫,插画风格",
"size": "16:9",
"quality": "hd",
"response_format": "b64_json",
"n": 1
}
通过本接口调用 Gemini / Imagen 时的限制(违反时一般返回 HTTP 422,提示「该接口或请求参数组合暂不支持」):
| 参数 | 限制 |
|---|---|
stream / partial_images |
不支持 |
response_format |
只接受 b64_json |
style、input_fidelity、mask |
不支持 |
background |
只接受 auto / opaque |
moderation |
只接受 auto |
output_format |
只接受 png |
output_compression |
不支持 |
watermark |
不能设为 false |
| 其他未识别字段 | 一律拒绝 |
Imagen 请用 quality 指定档位:hd / high 为 2K,ultra / 4k 为 4K,其余为 1K;不要用 size 写 1k / 2k / 4k。Imagen 只支持生成,不支持编辑;输出数量受模型限制,一般不超过 4。
xAI 与其他模型
xAI 图片模型(Grok Imagine 系列)只使用 model、prompt、n、response_format,其余字段(含 size、quality)会被忽略。其他模型取值各不相同,不要只改模型名就沿用全部参数;不确定时先用最少字段(model + prompt)调通。
响应
同步响应
默认(async 未设或为 false)请求会一直等到图片生成完毕再返回。
{
"created": 1793966400,
"data": [
{
"b64_json": "BASE64_IMAGE_DATA",
"url": "",
"revised_prompt": ""
}
]
}
| 字段 | 说明 |
|---|---|
created |
响应时间,Unix 秒 |
data[] |
图片数组。实际张数可能少于 n,请遍历全部 |
data[].b64_json |
图片文件的 base64 编码,解码即文件字节 |
data[].url |
图片地址,可能是平台素材地址或模型服务商的地址,见下文 |
data[].revised_prompt |
模型改写后的提示词(可选) |
usage、svg_usage 等 |
部分模型附带的用量等信息,不保证所有模型都有 |
模型服务商返回的其他字段会原样保留。
URL 结果怎么下载: 返回 URL 时,平台通常会把图片保存到你账号的素材库,url 形如 https://www.nextai-code.com/v1/materials/{asset_key}/content。这种地址需要带 API Key 下载,且有有效期,详见素材下载。如果 url 不是 nextai-code.com 域名,说明是模型服务商的临时地址,直接下载即可,不要带 NextAI Code 的 API Key。
保存后缀: output_format 决定文件格式,response_format 只决定返回编码,两者不是一回事。按请求的 output_format 选后缀:png → .png,jpeg → .jpg,webp → .webp,svg → .svg,gif → .gif;模型不支持该字段时,以实际文件内容或下载响应的 Content-Type 为准。
流式响应
stream: true 仅对支持图片流式的模型有效,响应为 text/event-stream,事件格式与 OpenAI 一致,需按 SSE 解析,不能用上面的 JSON 保存脚本。Gemini / Imagen 模型不支持流式。
异步响应
请求体加 "async": true,平台不等待生成,立即返回任务信息:
{
"task_id": "img_3f2a...",
"status": "QUEUED",
"progress": "0%",
"created": 1793966400
}
之后用 GET /v1/images/tasks/{task_id} 轮询结果。适用范围、状态流转和轮询示例见异步任务与素材下载。
错误
非 2xx 即失败,错误体为:
{"error": {"message": "错误描述", "type": "invalid_request_error", "code": "invalid_request"}}
本接口常见的参数错误:
| 情况 | HTTP | 处理 |
|---|---|---|
缺少 model |
400 | 补上模型名 |
n 大于 10 |
400 | 降低 n |
size 含乘号 × |
400 | 改用字母 x |
| DALL·E 尺寸不合法,或参数取值不在模型支持范围 | 400 | 按错误信息给出的可选值调整 |
async 与 stream 同时为 true |
400 | 关闭其中一个 |
| Gemini / Imagen 传入不支持的参数 | 422(部分为 400) | 按上文限制表移除。错误信息为统一提示,不会指出具体字段 |
5xx、网络断开或客户端超时时,结果是否已生成并计费并不确定。先保存响应头 X-Oneapi-Request-Id,联系客服确认后再决定是否重试,避免重复生成。耗时长的场景改用 async。示例中的 600 秒超时只是客户端等待上限,不是服务耗时承诺。
内容安全拦截的错误形式随模型变化,不要只匹配某一条错误文案。通用错误码(401、402、403、429 等)见错误码。