图片生成

用一段文本提示词生成图片。接口兼容 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

BASH
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 编码的文件内容):

JSON
{
  "created": 1793966400,
  "data": [
    {"b64_json": "BASE64_IMAGE_DATA"}
  ]
}

把响应里每张图存成文件:

BASH
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)

PYTHON
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+)

JAVASCRIPT
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 的请求体:

JSON
{
  "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 的请求体:

JSON
{
  "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,档位参数不生效。档位不承诺精确宽高,实际尺寸以生成文件为准。

示例请求体:

JSON
{
  "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)请求会一直等到图片生成完毕再返回。

JSON
{
  "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,平台不等待生成,立即返回任务信息:

JSON
{
  "task_id": "img_3f2a...",
  "status": "QUEUED",
  "progress": "0%",
  "created": 1793966400
}

之后用 GET /v1/images/tasks/{task_id} 轮询结果。适用范围、状态流转和轮询示例见异步任务与素材下载。

错误

非 2xx 即失败,错误体为:

JSON
{"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 等)见错误码。

相关文档