image - 生图 - 官方接口文档
与 OpenAI 官方 Images API 完全兼容,一次请求直接返回图片。第三方软件、OpenAI 官方 SDK 或现有代码,只需要改接口地址和密钥就能用。
先选对接口
| 你的情况 | 用哪个 |
|---|---|
| 在第三方软件里填写接口地址和密钥(软件只支持 OpenAI 官方格式) | 官方接口(本页) |
| 已有基于 OpenAI SDK 的代码,想直接换地址使用 | 官方接口(本页);想更稳定可以改用异步接口 |
| 自己写脚本或程序调用,尤其是生成大图、图生图、批量生成 | 异步接口(推荐,稳定性高) |
官方接口的局限
官方接口要一直保持连接,直到图片生成完毕。一张图通常需要 30 秒到几分钟,请求时间较长时,连接可能被网络中途截断(常见报错 524、连接超时)。这时图片已经生成并扣费,结果却拿不回来。
自己写程序时,请优先使用 异步接口:提交后立即返回,再分次查询结果,不会被截断。
开始之前
| 项目 | 内容 |
|---|---|
| 接口地址(Base URL) | https://naiccc.com/v1 |
| 鉴权方式 | 请求头 Authorization: Bearer 你的生图密钥 |
| 模型 | gpt-image-2 |
| 方法 | 路径 | 用途 |
|---|---|---|
POST | /v1/images/generations | 文生图(JSON) |
POST | /v1/images/edits | 图生图(multipart 表单或 JSON) |
密钥必须是 image 生图专用分组的密钥,创建方法、两个生图分组的区别(1K 分组、2/4K 分组),见异步接口文档的必须使用生图分组的密钥。两种接口使用同一把密钥。
在第三方软件中填写
各个软件的设置界面不同,一般按下面填写:
| 设置项 | 填写内容 |
|---|---|
| 接口类型 / 服务商 | 选择 OpenAI 或“OpenAI 兼容” |
| 接口地址(API 地址、Base URL) | https://naiccc.com/v1;如果软件会自动在末尾加 /v1,就只填 https://naiccc.com |
| API Key | 你的生图分组密钥 |
| 模型 | gpt-image-2(列表里没有时手动输入) |
| 超时时间(如果软件可以设置) | 建议 600 秒 |
填好后先生成一张 1024x1024 的图测试。能出图就说明配置正确;一直失败时,对照报错与处理检查。
文生图
curl https://naiccc.com/v1/images/generations \
-H "Authorization: Bearer $NAICCC_API_KEY" \
-H "Content-Type: application/json" \
--max-time 600 \
-d '{
"model": "gpt-image-2",
"prompt": "一只戴着宇航员头盔的橘猫,坐在月球表面,电影级光影",
"size": "1024x1024"
}'图生图
curl https://naiccc.com/v1/images/edits \
-H "Authorization: Bearer $NAICCC_API_KEY" \
--max-time 600 \
-F model=gpt-image-2 \
-F prompt="把背景换成海边日落,人物保持不变" \
-F [email protected]- 多张参考图:重复写
-F [email protected]。 - 遮罩:
-F [email protected],透明区域为可修改区域。 - 单个文件不超过 50 MB。
- 也可以用 JSON 传图:
"images": [{"image_url": "https://... 或 data:image/png;base64,..."}]。
以上 curl 写法适用于 macOS / Linux 终端;Windows 上用 curl 传中文提示词容易变成乱码,请使用下面的 PowerShell、Python 或 Node.js 示例。
返回结果
{
"created": 1731600045,
"data": [{ "b64_json": "iVBORw0KGgo...", "revised_prompt": "..." }],
"size": "1024x1024"
}把 data[i].b64_json 做 base64 解码即可得到图片。请求时设置了 "response_format": "url" 时,图片在 data[i].url 里,格式为 data:image/png;base64,...,不是可以下载的网址。
常用参数
| 参数 | 说明 |
|---|---|
prompt | 提示词(必填) |
size | 1024x1024、1536x1024、1024x1536、2048x2048、3840x2160 等,也可以写 1K、2K、4K。能用哪些尺寸取决于密钥所在分组 |
n | 张数,默认 1 |
quality | low / medium / high / auto |
output_format | png / jpeg / webp |
两种接口的参数通用,完整参数表和尺寸档位见异步接口文档的请求参数和尺寸档位。
示例:Windows PowerShell
复制整段,粘贴到 PowerShell 里回车即可,生成的图片保存为 out.png:
$headers = @{ Authorization = "Bearer $env:NAICCC_API_KEY" }
$body = @{ model = "gpt-image-2"; prompt = "赛博朋克风格的城市夜景,霓虹灯"; size = "1024x1024" } | ConvertTo-Json
"生成中,通常需要 30 秒到几分钟……"
$result = Invoke-RestMethod -Method Post -Uri "https://naiccc.com/v1/images/generations" -Headers $headers -ContentType "application/json; charset=utf-8" -Body ([Text.Encoding]::UTF8.GetBytes($body)) -TimeoutSec 600
if ($result.error) {
"生成失败:$($result.error.message)"
} else {
[IO.File]::WriteAllBytes("$PWD\out.png", [Convert]::FromBase64String($result.data[0].b64_json))
"已保存 $PWD\out.png"
}示例:Python(OpenAI 官方 SDK)
需要先安装:python -m pip install openai
import base64
import os
from openai import OpenAI
client = OpenAI(
base_url="https://naiccc.com/v1",
api_key=os.environ["NAICCC_API_KEY"], # 生图分组的密钥
timeout=600, # 生图耗时长,超时要设长
max_retries=0, # 不自动重试,避免同一张图重复扣费
)
def save_first_image(result, path):
"""保存第一张图。HTTP 200 但生成失败时,返回里没有 data,只有 error,SDK 不会报错,需要自己检查。"""
if not result.data:
error = (result.model_extra or {}).get("error") or {}
raise RuntimeError(f"生成失败:{error.get('message', error)}")
with open(path, "wb") as f:
f.write(base64.b64decode(result.data[0].b64_json))
print(f"已保存 {path}")
# 文生图
result = client.images.generate(
model="gpt-image-2",
prompt="赛博朋克风格的城市夜景,霓虹灯",
size="1024x1024",
)
save_first_image(result, "out.png")
# 图生图
with open("input.png", "rb") as image:
result = client.images.edit(
model="gpt-image-2",
prompt="把背景换成海边日落",
image=image,
)
save_first_image(result, "edit.png")示例:Node.js
Node.js 18 及以上版本可以直接运行,不需要安装依赖。保存为 nai_sync.mjs,运行 node nai_sync.mjs "提示词":
import { writeFile } from "node:fs/promises";
const prompt = process.argv[2] || "一只戴着宇航员头盔的橘猫";
const res = await fetch("https://naiccc.com/v1/images/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.NAICCC_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ model: "gpt-image-2", prompt, size: "1024x1024" }),
signal: AbortSignal.timeout(600_000), // 最多等待 600 秒
});
// 返回开头可能带有心跳空白,先去掉再解析
const data = JSON.parse((await res.text()).trim());
if (!res.ok || data.error) throw new Error(`生成失败:${data.error?.message ?? res.status}`);
await writeFile("out.png", Buffer.from(data.data[0].b64_json, "base64"));
console.log("已保存 out.png");报错与处理
| 情况 | 常见原因 | 怎么办 |
|---|---|---|
| HTTP 401 | 密钥错误、过期或被禁用 | 检查密钥 |
| HTTP 403 / 404 | 密钥不是生图分组(Image generation is not enabled for this group、not supported for this platform) | 换用 image 生图专用分组的密钥 |
| HTTP 400 | 缺少 prompt、图生图没传图、参数格式错误 | 按 error.message 修改请求 |
| HTTP 429 | 请求太频繁或同时进行的请求太多 | 降低频率后重试 |
HTTP 200,但返回里有 error | 生成过程中失败,比如内容审核未通过、生成失败 | 按 error.message 处理;失败不扣费 |
524、连接超时、连接被断开 | 请求时间太长,被网络中途截断 | 改用异步接口;客户端超时设为 600 秒 |
注意事项
- 客户端超时要设长一点,建议 600 秒。一张图通常要 30 秒到几分钟,大图和图生图更久。
- HTTP 200 不一定代表成功。 等待期间服务端会先发送空白字符作为心跳、保持连接,这时状态码已经是 200。之后如果生成失败,返回内容是
{"error": {...}},请检查返回里有没有error字段。 - 返回开头可能带有空白字符。 标准 JSON 解析和官方 SDK 都能正常处理;自己手写解析时,先去掉开头的空白再解析。
- 不要传
"stream": true,除非你的客户端会解析 SSE(服务器分段推送的数据格式)。 - 中途断开连接,图片仍会生成并扣费,但结果就拿不回来了。经常遇到这种情况,请改用异步接口。
- 不要开启自动重试。 断线后自动重新请求,会再生成一张、再扣一次费。上面的 Python 示例已经把重试关掉。