image - 生图 - 异步接口文档
这篇写给自己写脚本或程序调用生图接口的用户。异步接口先提交任务、再分次查询结果,不怕生成时间长,稳定性高。请求格式兼容 OpenAI Images API(图片生成接口的通用格式),模型为 gpt-image-2。
先选对接口
| 你的情况 | 用哪个 |
|---|---|
| 自己写脚本或程序调用,尤其是生成大图、图生图、批量生成 | 异步接口(本页,推荐,稳定性高) |
| 在第三方软件里填写接口地址和密钥(软件只支持 OpenAI 官方格式) | 官方接口 |
| 已有基于 OpenAI SDK 的代码,想直接换地址使用 | 官方接口;想更稳定,按本页改两行换成异步接口 |
不写代码?看这两篇就够了
- 网页上直接生图:image - 生图 - 生图站
- 在 Codex 里输入 @nai 生图:Image - 生图 - 在codex中调用
开始之前
| 项目 | 内容 |
|---|---|
| 接口地址(Base URL) | https://naiccc.com |
| 鉴权方式 | 请求头 Authorization: Bearer 你的生图密钥 |
| 模型 | gpt-image-2 |
| 推荐调用方式 | 异步任务:先提交拿到 job_id,再轮询取结果 |
必须使用生图分组的密钥
在控制台左侧打开【api密匙】,创建密钥时选择 image 生图专用分组。用 Codex 或对话分组的密钥调用生图接口会被拒绝(403 或 404,见报错与处理)。

两个生图分组的区别:
| 分组 | 能生成的尺寸 | 说明 |
|---|---|---|
| image - 生图 | 只有 1K(最长边不超过 1024) | 想要 1K 以上的尺寸,请用 2/4K 分组 |
| image - 2/4K 分组 | 2K、4K | 此分组无售后 |
每张图的价格以控制台里分组旁的说明为准。
把密钥放进环境变量
不要把密钥直接写进代码,放在环境变量(系统里保存配置的地方,程序可以读取)NAICCC_API_KEY 里。本文所有示例都从这里读取密钥。
Windows(PowerShell):
# 永久生效:执行后需要重新打开终端
[Environment]::SetEnvironmentVariable("NAICCC_API_KEY", "你的生图密钥", "User")
# 只在当前窗口生效
$env:NAICCC_API_KEY = "你的生图密钥"macOS / Linux:
export NAICCC_API_KEY="你的生图密钥"为什么推荐异步接口
生成一张图通常需要 30 秒到 2 分钟,大尺寸更久。同步接口要一直保持连接等待结果,超过约 100 秒就可能被网络中途切断(常见报错 524):图已经生成并扣费,结果却拿不到。
异步接口提交后立即返回一个任务编号 job_id,之后每次查询都是很短的请求,不会被切断。
快速开始
下面的示例都会:提交文生图任务 → 每 3 秒查询一次 → 成功后把图片保存为 out.png。
Windows PowerShell
复制整段,粘贴到 PowerShell 里回车即可:
$headers = @{ Authorization = "Bearer $env:NAICCC_API_KEY" }
$body = @{ model = "gpt-image-2"; prompt = "一只戴着宇航员头盔的橘猫,坐在月球表面,背景是地球"; size = "1024x1024" } | ConvertTo-Json
$job = Invoke-RestMethod -Method Post -Uri "https://naiccc.com/v1/jobs/images/generations" -Headers $headers -ContentType "application/json; charset=utf-8" -Body ([Text.Encoding]::UTF8.GetBytes($body))
"已提交 job_id = $($job.job_id)"
do {
Start-Sleep -Seconds 3
$result = Invoke-RestMethod -Uri "https://naiccc.com/v1/jobs/$($job.job_id)" -Headers $headers
"状态:$($result.status)"
} while ($result.status -in @("queued", "processing"))
if ($result.status -eq "succeeded") {
[IO.File]::WriteAllBytes("$PWD\out.png", [Convert]::FromBase64String($result.data[0].b64_json))
"已保存 $PWD\out.png"
} else {
"生成失败:$($result.error.message)"
}curl(macOS / Linux)
需要先安装 jq(命令行 JSON 处理工具)。
JOB=$(curl -s -X POST https://naiccc.com/v1/jobs/images/generations \
-H "Authorization: Bearer $NAICCC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-image-2","prompt":"赛博朋克风格的城市夜景,霓虹灯","size":"1024x1024"}' \
| jq -r .job_id)
echo "job_id = $JOB"
while :; do
RESP=$(curl -s -H "Authorization: Bearer $NAICCC_API_KEY" "https://naiccc.com/v1/jobs/$JOB")
STATUS=$(echo "$RESP" | jq -r .status)
echo "status = $STATUS"
case "$STATUS" in
succeeded) echo "$RESP" | jq -r '.data[0].b64_json' | base64 -d > out.png; echo "已保存 out.png"; break ;;
failed) echo "$RESP" | jq .error >&2; exit 1 ;;
*) sleep 3 ;;
esac
done接口一览
| 方法 | 路径 | 用途 | 请求体 |
|---|---|---|---|
POST | /v1/jobs/images/generations | 提交文生图任务 | JSON |
POST | /v1/jobs/images/edits | 提交图生图任务 | multipart 表单或 JSON |
GET | /v1/jobs/{job_id} | 查询任务状态、取结果 | 无 |
请求体与 OpenAI 官方的 /v1/images/generations、/v1/images/edits 一致。已有代码只需把路径里的 /v1/images/ 改成 /v1/jobs/images/,再加一段轮询。
两个提交接口都支持查询参数 timeout_seconds:任务最长运行秒数,默认 300,范围 1~600,超过 600 会直接返回 400。大尺寸或复杂改图建议设为 540~600:
POST /v1/jobs/images/edits?timeout_seconds=600文生图
POST /v1/jobs/images/generations
Authorization: Bearer 你的生图密钥
Content-Type: application/json{
"model": "gpt-image-2",
"prompt": "极简风格的咖啡店 logo,白底,线条图标",
"size": "1024x1024",
"n": 1,
"quality": "high",
"output_format": "png"
}提交成功返回 HTTP 202:
{ "job_id": "job_3f8b2c...", "status": "queued", "created_at": 1731600000 }不要传 stream
异步接口不支持 "stream": true,带上会直接返回 400。
图生图
图生图(改图、参考图生成)有两种传图方式,任选其一。
方式一:上传本地文件(推荐)
使用 multipart 表单(可以上传文件的请求格式)。下面是 macOS / Linux 终端的 curl 写法;Windows 上用 curl 传中文提示词容易变成乱码,建议使用后面的 Python 或 Node.js 示例。
curl -s -X POST "https://naiccc.com/v1/jobs/images/edits" \
-H "Authorization: Bearer $NAICCC_API_KEY" \
-F model=gpt-image-2 \
-F prompt="把背景换成赛博朋克风格的城市夜景,保留人物不变" \
-F size=1024x1024 \
-F [email protected]- 多张参考图:重复写
image字段,例如-F [email protected] -F [email protected];也兼容image[]写法。 - 遮罩:加
-F [email protected]。遮罩图中透明的区域是允许修改的部分,尺寸需要与原图一致。 - 单个文件不超过 50 MB,支持 PNG、JPEG、WebP。
- 不要手动设置
Content-Type,让程序自动生成表单格式。
方式二:JSON 传图片链接或 base64
适合图片已经在网上,或者程序里已经拿到 base64(把图片转成文字的编码)的情况:
{
"model": "gpt-image-2",
"prompt": "把这两张图的主体融合成一张海报",
"size": "1024x1024",
"images": [
{ "image_url": "https://example.com/a.png" },
{ "image_url": "data:image/png;base64,iVBORw0KGgo..." }
],
"mask": { "image_url": "data:image/png;base64,..." }
}images必填,每一项的image_url可以是公网能访问的 http(s) 链接,也可以是data:开头的 base64。mask可选,格式同上。- 不支持
file_id。
查询任务结果
GET /v1/jobs/{job_id}
Authorization: Bearer 你的生图密钥建议每 3 秒查询一次,响应头里的 Retry-After: 3 也是这个意思。
任务状态的变化顺序:
queued(排队中) → processing(生成中) → succeeded(成功)
↘ failed(失败或超时)还没完成
{ "job_id": "job_3f8b2c...", "status": "processing", "created_at": 1731600000 }成功
与 OpenAI Images API 的返回相同,另外多了 job_id、status、created_at、completed_at 四个字段:
{
"job_id": "job_3f8b2c...",
"status": "succeeded",
"created_at": 1731600000,
"completed_at": 1731600045,
"data": [
{ "b64_json": "iVBORw0KGgo...", "revised_prompt": "..." }
],
"size": "1024x1024"
}data 是数组,生成几张图就有几项。每一项的图片在下面某个字段里:
| 字段 | 内容 | 怎么保存 |
|---|---|---|
b64_json | base64 字符串(默认) | base64 解码后写入文件 |
url | data:image/png;base64,... 格式的数据(请求时设置 "response_format": "url" 才会返回) | 去掉第一个逗号及前面的部分,再 base64 解码 |
url 不是下载链接
url 字段里是图片数据本身,不是可以下载的网址,拿它去发请求会失败。网页里可以直接放进 <img> 的 src 显示。
失败
失败时 HTTP 状态码仍然是 200,失败原因在返回内容里:
{
"job_id": "job_3f8b2c...",
"status": "failed",
"created_at": 1731600000,
"completed_at": 1731600007,
"http_status": 502,
"error": { "type": "upstream_error", "message": "..." }
}判断成功与否,请以 status 字段为准,不要只看 HTTP 状态码。
请求参数
通用参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | 模型名,默认 gpt-image-2 |
prompt | string | 是 | 提示词,中文、英文都可以 |
size | string | 否 | 图片尺寸,见尺寸档位。不传时由模型决定 |
n | int | 否 | 生成张数,默认 1 |
quality | string | 否 | low / medium / high / auto |
output_format | string | 否 | png(默认)/ jpeg / webp |
output_compression | int | 否 | 压缩率 0~100,只对 jpeg、webp 有效 |
background | string | 否 | auto / opaque / transparent(透明背景需要配合 png 或 webp) |
moderation | string | 否 | 内容审核强度:auto(默认)/ low |
response_format | string | 否 | b64_json(默认)/ url |
图生图专用
| 参数 | 类型 | 说明 |
|---|---|---|
image | 文件,可重复 | 方式一(上传文件)的输入图 |
images | 数组 | 方式二(JSON)的输入图:[{ "image_url": "..." }] |
mask | 文件或对象 | 遮罩,透明区域为可修改区域 |
input_fidelity | string | high / low。high 更贴近原图细节,比如人脸、文字 |
参数会原样交给模型,某个参数是否生效以模型实际能力为准;不支持的组合会在任务结果里返回错误。
尺寸档位
尺寸按输出图片的最长边分为三档:
| 档位 | 最长边 | 常用尺寸 |
|---|---|---|
| 1K | 不超过 1024 | 1024x1024、1024x768、768x1024 |
| 2K | 1025~2048 | 1536x1024(横)、1024x1536(竖)、2048x2048、2048x1152 |
| 4K | 超过 2048 | 3840x2160(横)、2160x3840(竖) |
size也可以直接写1K、2K、4K。- 能用哪些档位取决于密钥所在的分组,见必须使用生图分组的密钥。
- 传
auto或不传时,按实际生成的尺寸计算。n张图按张数分别计费。 - 尺寸越大越慢,4K 建议加上
?timeout_seconds=600。
报错与处理
报错分两类:请求本身被拒绝(HTTP 状态码不是 2xx),以及任务执行失败(HTTP 200,但 status 是 failed)。
请求被拒绝
| HTTP | error.type | 常见原因 | 怎么办 |
|---|---|---|---|
| 400 | invalid_request_error | 请求格式错误、缺少 prompt、图生图没传图、带了 stream、timeout_seconds 超过 600 | 按 error.message 修改请求 |
| 401 | authentication_error | 密钥错误、过期或被禁用 | 检查密钥 |
| 403 | permission_error | 密钥所在分组没有开通生图(Image generation is not enabled for this group) | 换用生图分组的密钥 |
| 404 | not_found_error | ① 查询的 job_id 不存在、已被取过或已过期;② 密钥不是生图分组(not supported for this platform) | ① 重新提交;② 换用生图分组的密钥 |
| 429 | rate_limit_error | 请求太频繁或同时进行的任务太多 | 降低频率后重试 |
任务失败
error.type | 说明 |
|---|---|
upstream_error | 生成失败或超时(http_status 多为 502、504) |
| 其他 | 内容审核未通过、参数组合不被模型支持等,具体看 error.message |
失败不扣费,超时导致的失败同样不扣费。
使用规则(必读)
- 结果只能取一次。 拿到
succeeded或failed后,服务端会立即删除这个任务,再查同一个job_id会返回 404。请在拿到结果的那次请求里就把图片保存好。 - 结果保留 10 分钟。 任务完成后 10 分钟内没有来取,会被自动清理。
- 任务默认最长运行 5 分钟。 超时会标记为
failed,可以用?timeout_seconds=延长到最多 10 分钟。 - 只要图片生成成功就会计费。 即使没有来取结果、或者中途断开,也会照常扣费。
- 密钥之间互相隔离。 只有提交任务的那把密钥能查到这个任务。
- 提示词会原样交给模型。 服务端已要求模型不改写、不翻译、不扩写提示词,客户端不需要再加“防改写”之类的前缀。返回的
revised_prompt仅供参考。 - 不要在网页前端直接调用。 那样会把密钥暴露给所有访问者;请在自己的后端调用。
完整示例:Python
需要先安装依赖:python -m pip install requests
保存为 nai_image.py,设置好环境变量 NAICCC_API_KEY 后使用:
# 文生图
python nai_image.py "一只戴着宇航员头盔的橘猫,坐在月球表面,电影级光影"
# 指定尺寸、张数
python nai_image.py "赛博朋克城市夜景" --size 1024x1024 --n 2
# 图生图(可以多次传 --image)
python nai_image.py "把背景换成海边日落" --image photo.png
# 带遮罩、延长超时
python nai_image.py "把天空换成极光" --image photo.png --mask mask.png --timeout 600# -*- coding: utf-8 -*-
"""naiccc 异步生图示例:文生图 / 图生图,提交 → 轮询 → 保存。"""
import argparse
import base64
import os
import sys
import time
from pathlib import Path
import requests
BASE_URL = "https://naiccc.com"
def submit(session, args):
"""提交任务,返回 job_id。传了 --image 就走图生图,否则走文生图。"""
params = {"timeout_seconds": args.timeout}
fields = {"model": args.model, "prompt": args.prompt, "n": args.n}
if args.size:
fields["size"] = args.size
if args.quality:
fields["quality"] = args.quality
if not args.image:
resp = session.post(f"{BASE_URL}/v1/jobs/images/generations",
params=params, json=fields, timeout=30)
else:
paths = [Path(p) for p in args.image]
mask = Path(args.mask) if args.mask else None
for p in paths + ([mask] if mask else []):
if not p.is_file():
sys.exit(f"找不到文件:{p}")
handles = []
try:
files = []
for p in paths:
handles.append(p.open("rb"))
files.append(("image", (p.name, handles[-1])))
if mask:
handles.append(mask.open("rb"))
files.append(("mask", (mask.name, handles[-1])))
# 表单里的值必须是字符串;不要手动设置 Content-Type
data = {k: str(v) for k, v in fields.items()}
resp = session.post(f"{BASE_URL}/v1/jobs/images/edits",
params=params, data=data, files=files, timeout=120)
finally:
for h in handles:
h.close()
if resp.status_code not in (200, 202):
sys.exit(f"提交失败 HTTP {resp.status_code}:{resp.text}")
job_id = resp.json()["job_id"]
print(f"已提交 job_id={job_id}")
return job_id
def poll(session, job_id, max_wait):
"""轮询直到任务结束,返回成功结果;失败则退出。"""
started = time.time()
while time.time() - started < max_wait:
resp = session.get(f"{BASE_URL}/v1/jobs/{job_id}", timeout=30)
if resp.status_code != 200:
sys.exit(f"\n查询失败 HTTP {resp.status_code}:{resp.text}")
result = resp.json()
status = result.get("status")
print(f"\r状态:{str(status):<10} 已等待 {time.time() - started:5.0f}s", end="", flush=True)
if status == "succeeded":
print()
return result
if status == "failed":
err = result.get("error") or {}
sys.exit(f"\n任务失败:[{err.get('type')}] {err.get('message')}")
time.sleep(int(resp.headers.get("Retry-After", 3)))
sys.exit(f"\n等待超过 {max_wait}s,停止查询")
def decode_image(item):
"""从 data[] 的一项里取出图片,兼容 b64_json 和 data: 两种格式。"""
if item.get("b64_json"):
return base64.b64decode(item["b64_json"])
url = item.get("url") or ""
if url.startswith("data:"):
return base64.b64decode(url.split(",", 1)[1])
return None
def save(result, out_dir, ext):
out = Path(out_dir)
out.mkdir(parents=True, exist_ok=True)
stamp = time.strftime("%Y%m%d_%H%M%S")
for i, item in enumerate(result.get("data") or []):
content = decode_image(item)
if not content:
print(f"第 {i + 1} 张没有图片数据,跳过")
continue
path = out / f"{stamp}_{i + 1}.{ext}"
path.write_bytes(content)
print(f"已保存 {path.resolve()}")
def main():
parser = argparse.ArgumentParser(description="naiccc 异步生图")
parser.add_argument("prompt", help="提示词")
parser.add_argument("--image", action="append", help="参考图路径,可重复;传了就走图生图")
parser.add_argument("--mask", help="遮罩图路径(透明区域为可修改区域)")
parser.add_argument("--model", default="gpt-image-2")
parser.add_argument("--size", default="1024x1024", help="如 1024x1024 / 1536x1024 / 3840x2160")
parser.add_argument("--n", type=int, default=1, help="生成张数")
parser.add_argument("--quality", choices=["low", "medium", "high", "auto"])
parser.add_argument("--timeout", type=int, default=300, help="任务最长运行秒数,1-600")
parser.add_argument("--out", default="outputs", help="保存目录")
args = parser.parse_args()
if args.mask and not args.image:
parser.error("--mask 需要配合 --image 使用")
api_key = os.environ.get("NAICCC_API_KEY", "").strip()
if not api_key:
sys.exit("请先设置环境变量 NAICCC_API_KEY(必须是生图分组的密钥)")
session = requests.Session()
session.headers["Authorization"] = f"Bearer {api_key}"
t0 = time.time()
job_id = submit(session, args)
result = poll(session, job_id, max_wait=args.timeout + 60)
save(result, args.out, ext="png")
print(f"完成,总耗时 {time.time() - t0:.1f}s")
if __name__ == "__main__":
main()完整示例:Node.js
Node.js 18 及以上版本自带所需功能,不需要安装依赖。保存为 nai_image.mjs:
node nai_image.mjs "一只戴着宇航员头盔的橘猫" # 文生图
node nai_image.mjs "把背景换成海边日落" photo.png # 图生图import { readFile, writeFile } from "node:fs/promises";
import { basename } from "node:path";
const BASE_URL = "https://naiccc.com";
const API_KEY = process.env.NAICCC_API_KEY;
const headers = { Authorization: `Bearer ${API_KEY}` };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function submit(prompt, imagePaths = []) {
let res;
if (imagePaths.length === 0) {
// 文生图:JSON
res = await fetch(`${BASE_URL}/v1/jobs/images/generations`, {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({ model: "gpt-image-2", prompt, size: "1024x1024" }),
});
} else {
// 图生图:表单上传(不要手动设置 Content-Type)
const form = new FormData();
form.append("model", "gpt-image-2");
form.append("prompt", prompt);
form.append("size", "1024x1024");
for (const p of imagePaths) {
form.append("image", new Blob([await readFile(p)]), basename(p));
}
res = await fetch(`${BASE_URL}/v1/jobs/images/edits`, { method: "POST", headers, body: form });
}
if (!res.ok) throw new Error(`提交失败 HTTP ${res.status}: ${await res.text()}`);
return (await res.json()).job_id;
}
async function poll(jobId, maxWaitMs = 360_000) {
const deadline = Date.now() + maxWaitMs;
while (Date.now() < deadline) {
const res = await fetch(`${BASE_URL}/v1/jobs/${jobId}`, { headers });
if (!res.ok) throw new Error(`查询失败 HTTP ${res.status}: ${await res.text()}`);
const data = await res.json();
console.log(`状态:${data.status}`);
if (data.status === "succeeded") return data;
if (data.status === "failed") throw new Error(`任务失败:${data.error?.message}`);
await sleep(3000);
}
throw new Error("等待超时");
}
function toBuffer(item) {
if (item.b64_json) return Buffer.from(item.b64_json, "base64");
if (item.url?.startsWith("data:")) return Buffer.from(item.url.split(",")[1], "base64");
return null;
}
const [prompt, ...images] = process.argv.slice(2);
if (!API_KEY) throw new Error("请先设置环境变量 NAICCC_API_KEY");
if (!prompt) throw new Error("用法:node nai_image.mjs <提示词> [参考图...]");
const jobId = await submit(prompt, images);
console.log(`已提交 job_id=${jobId}`);
const result = await poll(jobId);
for (const [i, item] of result.data.entries()) {
const buf = toBuffer(item);
if (buf) {
const file = `output_${Date.now()}_${i + 1}.png`;
await writeFile(file, buf);
console.log(`已保存 ${file}`);
}
}常见问题
提交后一直是 processing,正常吗?
正常。1K 图一般 30~90 秒,2K、4K 或图生图会更久。只要没有超过 timeout_seconds,继续查询即可。
查询返回 404 Job not found?
可能是:① 这个任务的结果已经取过一次(结果只能取一次);② 完成后超过 10 分钟没有来取,已被清理;③ 查询用的不是提交时那把密钥。
生成的图和提示词描述不太一样?
服务端已经要求模型原样使用你的提示词,不需要再加防改写的前缀。效果不理想时,建议把提示词写得更具体:主体、风格、构图、光线、色调分开描述。
OpenAI 官方格式的接口 /v1/images/generations 还能用吗?
能用,主要给第三方软件使用,见 image - 生图 - 官方接口文档。它要一直保持连接等结果,请求时间长时可能被截断,自己写程序请用本文的异步接口。