🧩 图像模型调用
gpt-image-2(推荐)、gpt-image-1.5、gpt-image-1。两种使用方式:- 方式 1:HTTP API 直接调用(写代码集成场景)— 见本页主体内容
- 方式 2:在 Codex CLI 内调用 Skill(聊天里说"画一张..."就出图)— 见 文末
接口总览
| 接口 | URL | 用途 |
|---|---|---|
| Images Generations | POST /v1/images/generations | 文生图(纯文字 prompt 生成图片) |
| Images Edits | POST /v1/images/edits | 参考图编辑(基于上传图修改) |
Base URL:https://nexor.nexoraivision.com
一、文生图(Generations)
接口地址
POST https://nexor.nexoraivision.com/v1/images/generations
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
完整参数表
| 参数 | 必填 | 默认 | 取值 / 说明 |
|---|---|---|---|
model | ✅ | — | gpt-image-2(推荐)/ gpt-image-1.5 / gpt-image-1 |
prompt | ✅ | — | 图片提示词,最长 32000 字符,越具体越好 |
size | — | auto | 1024x1024 / 1536x1024 / 1024x1536 / auto |
quality | — | auto | auto / low / medium / high |
background | — | auto | auto / transparent / opaque(透明背景需 png/webp) |
output_format | — | png | png / jpeg / webp |
output_compression | — | 100 | 仅 jpeg / webp 生效,范围 0-100(越高质量越好) |
moderation | — | auto | auto / low(内容审核严格程度) |
n | — | 1 | 生成数量,建议 1-10 |
stream | — | false | true 启用流式 |
partial_images | — | 0 | 配合 stream=true,返回 0-3 张进度图(详见 流式生成) |
user | — | — | 终端用户唯一标识(如 user-12345),用于审核回溯 / 滥用追踪 |
response_format 参数对 gpt-image- 无效*!OpenAI 的 gpt-image-* 系列模型只返回 base64(b64_json),与 DALL-E 2/3 不同 —— 这是 OpenAI 官方限制,中转端无法改变。即使你传 "response_format": "url",也会被静默忽略,依然返回 b64_json。如何把 base64 转成 URL 见下方 响应处理 章节。size 非标准值:表里 4 个是 OpenAI 官方明确支持的值。其他比例(如 1920x1080、3840x2160)中转端可能容错接受,但最终是否真的输出该尺寸取决于上游模型,不保证。推荐固定用官方标准值,需要其他比例后期再缩放/裁切。流式生成(partial_images)
设置 stream: true + partial_images: 1~3 可以边生成边收到进度图,适合做交互式 UI(用户能看到逐步精细化的过程):
curl https://nexor.nexoraivision.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "极简风格 logo,蓝白配色,留白充足",
"size": "1024x1024",
"quality": "high",
"stream": true,
"partial_images": 2
}'
响应是 SSE 流,每个 partial 一个事件:
event: image.partial_image
data: {"index":0,"b64_json":"iVBORw...","created_at":1717000000}
event: image.partial_image
data: {"index":1,"b64_json":"iVBORw...","created_at":1717000001}
event: image.completed
data: {"data":[{"b64_json":"iVBORw..."}], "usage":{...}}
partial_images: 3 相当于跑 4 次(3 张进度 + 1 张终稿)。仅在交互式 UI 必要时开启。user 参数(建议生产环境必加)
把终端用户标识传给模型,OpenAI 一旦内容被举报或触发审核,可以快速定位是哪个用户触发的。强烈推荐 SaaS 产品加上:
{
"model": "gpt-image-2",
"prompt": "...",
"user": "user-12345"
}
不传也不影响功能,但出问题时只能全账户排查。
调用示例
curl https://nexor.nexoraivision.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "gpt-image-2",
"prompt": "一个极简风格的蓝白配色支付产品宣传海报,中文标题,留白充足",
"size": "1024x1024",
"quality": "high",
"background": "opaque",
"output_format": "png",
"moderation": "auto",
"n": 1
}'
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://nexor.nexoraivision.com/v1"
)
resp = client.images.generate(
model="gpt-image-2",
prompt="一个极简风格的蓝白配色支付产品宣传海报,中文标题,留白充足",
size="1024x1024",
quality="high",
background="opaque",
output_format="png",
n=1
)
# 写入文件
import base64
image_bytes = base64.b64decode(resp.data[0].b64_json)
with open("output.png", "wb") as f:
f.write(image_bytes)
import OpenAI from 'openai'
import fs from 'fs'
const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://nexor.nexoraivision.com/v1'
})
const resp = await client.images.generate({
model: 'gpt-image-2',
prompt: '一个极简风格的蓝白配色支付产品宣传海报,中文标题,留白充足',
size: '1024x1024',
quality: 'high',
background: 'opaque',
output_format: 'png',
n: 1
})
// 写入文件
const buf = Buffer.from(resp.data[0].b64_json, 'base64')
fs.writeFileSync('output.png', buf)
响应结构
无论你是否传 response_format,gpt-image-* 模型始终返回 b64_json:
{
"created": 1717000000,
"data": [
{
"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
}
]
}
响应处理
方案 1:直接保存为本地图片
# Linux / macOS
curl -s https://nexor.nexoraivision.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "gpt-image-2",
"prompt": "一只橘猫戴橙色围巾抱水獭,温暖插画风格",
"size": "1024x1024",
"quality": "high",
"output_format": "png",
"n": 1
}' \
| jq -r '.data[0].b64_json' \
| base64 -d > output.png
echo "saved as output.png"
$response = Invoke-RestMethod -Uri 'https://nexor.nexoraivision.com/v1/images/generations' `
-Method Post `
-Headers @{ 'Authorization' = 'Bearer YOUR_API_KEY' } `
-ContentType 'application/json' `
-Body (@{
model = 'gpt-image-2'
prompt = '一只橘猫戴橙色围巾抱水獭,温暖插画风格'
size = '1024x1024'
quality = 'high'
output_format = 'png'
n = 1
} | ConvertTo-Json)
[IO.File]::WriteAllBytes('output.png', [Convert]::FromBase64String($response.data[0].b64_json))
import base64, requests
resp = requests.post(
"https://nexor.nexoraivision.com/v1/images/generations",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"model": "gpt-image-2",
"prompt": "一只橘猫戴橙色围巾抱水獭,温暖插画风格",
"size": "1024x1024",
"quality": "high",
"output_format": "png",
"n": 1
}
).json()
with open("output.png", "wb") as f:
f.write(base64.b64decode(resp["data"][0]["b64_json"]))
import fs from 'fs'
const resp = await fetch('https://nexor.nexoraivision.com/v1/images/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gpt-image-2',
prompt: '一只橘猫戴橙色围巾抱水獭,温暖插画风格',
size: '1024x1024',
quality: 'high',
output_format: 'png',
n: 1
})
}).then(r => r.json())
fs.writeFileSync('output.png', Buffer.from(resp.data[0].b64_json, 'base64'))
方案 2:转 Data URL 直接嵌入网页
如果只是在网页里显示,无需下载到磁盘,可以直接用 data: URL:
const dataUrl = `data:image/png;base64,${resp.data[0].b64_json}`
// 直接给 <img> src
imgEl.src = dataUrl
适合单次展示场景。缺点:URL 极长(一张 1024x1024 的 PNG 大约 1-2MB 的 base64 字符串),不适合存数据库或缓存。
方案 3:上传到对象存储拿回真正的 URL
适合需要分享、长期保存、CDN 加速的生产场景。流程:
[Codex 调用] → b64_json → [base64 decode] → [上传到 S3/OSS/R2] → 返回 https://... URL
S3 上传示例(Node + AWS SDK):
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
const s3 = new S3Client({ region: 'us-east-1' })
const buf = Buffer.from(resp.data[0].b64_json, 'base64')
const key = `gen/${Date.now()}.png`
await s3.send(new PutObjectCommand({
Bucket: 'your-bucket',
Key: key,
Body: buf,
ContentType: 'image/png',
ACL: 'public-read'
}))
const publicUrl = `https://your-bucket.s3.amazonaws.com/${key}`
阿里云 OSS / 腾讯云 COS / Cloudflare R2 都是同样思路 —— 解码 base64 → 上传 → 拼 URL。
二、参考图编辑(Edits)
适合做「保留主体 + 局部替换」或「基于现有图再创作」。比纯文生图更稳定地继承原图构图和元素。
接口地址
POST https://nexor.nexoraivision.com/v1/images/edits
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY
上传要求
- 请求类型:
multipart/form-data - image:必传,支持
png/jpeg/webp - mask:可选,建议 PNG 且带透明通道
- 使用蒙版时,建议与原图保持相同尺寸,避免编辑区域偏移
- 单文件上传上限 20MB(原图与蒙版分别校验)
完整参数表
| 参数 | 必填 | 默认 | 说明 |
|---|---|---|---|
model | ✅ | — | 建议 gpt-image-2 |
image | ✅ | — | 原图文件,支持 png/jpeg/webp |
prompt | ✅ | — | 写清「保留什么、替换什么、输出风格」 |
mask | — | — | 蒙版图(PNG 透明通道);只重绘透明区域 |
size | — | auto | 同文生图 4 个标准值 |
quality | — | auto | 同文生图 |
background | — | auto | 同文生图 |
output_format | — | png | png / jpeg / webp |
output_compression | — | 100 | 仅 jpeg/webp 有效(0-100) |
moderation | — | auto | auto / low |
n | — | 1 | 生成数量 |
input_fidelity | — | low | low / high — high 强力保持原图主体(人脸 / 商品 / Logo 等特征) |
stream | — | false | 同文生图,支持流式 |
partial_images | — | 0 | 同文生图,配合 stream 用 |
user | — | — | 终端用户标识,用于审核回溯 |
background=transparent 时,输出格式必须用 png 或 webp,不要用 jpeg(JPEG 不支持透明通道)。input_fidelity: "high" 什么时候用?需要严格保留原图特征的场景必开:- 人物头像换背景(保持人脸特征)
- 商品图换场景(保持商品造型 / Logo)
- 包装设计调整(保持品牌元素)
input_fidelity 模型会更自由发挥,主体可能"长得像但不是同一个"。代价是开 high 后生成稍慢、单价稍高。input_fidelity 调用示例
curl https://nexor.nexoraivision.com/v1/images/edits \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=gpt-image-2" \
-F "prompt=把背景换成纯白摄影棚,保持人物表情和服装不变" \
-F "image=@portrait.png" \
-F "input_fidelity=high" \
-F "size=1024x1024" \
-F "quality=high" \
-F "output_format=png"
不带蒙版:整图参考编辑
整图作为参考,根据 prompt 改造:
curl https://nexor.nexoraivision.com/v1/images/edits \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=gpt-image-2" \
-F "prompt=保留人物姿态和构图,改成电商海报风格,背景换成浅色摄影棚,提升清晰度" \
-F "image=@source.png" \
-F "size=1024x1024" \
-F "quality=high" \
-F "background=auto" \
-F "output_format=png" \
-F "moderation=auto"
带蒙版:局部重绘(inpainting)
curl https://nexor.nexoraivision.com/v1/images/edits \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "model=gpt-image-2" \
-F "prompt=仅替换透明区域为蓝白科技风 UI 面板,其他区域保持不变" \
-F "image=@source.png" \
-F "mask=@mask.png" \
-F "size=1024x1024" \
-F "quality=high" \
-F "background=auto" \
-F "output_format=png" \
-F "moderation=auto"
Python / Node 调用编辑
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://nexor.nexoraivision.com/v1"
)
with open("source.png", "rb") as img, open("mask.png", "rb") as mask:
resp = client.images.edit(
model="gpt-image-2",
image=img,
mask=mask,
prompt="仅替换透明区域为蓝白科技风 UI 面板",
size="1024x1024",
quality="high",
output_format="png"
)
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(resp.data[0].b64_json))
import OpenAI, { toFile } from 'openai'
import fs from 'fs'
const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://nexor.nexoraivision.com/v1'
})
const resp = await client.images.edit({
model: 'gpt-image-2',
image: await toFile(fs.createReadStream('source.png')),
mask: await toFile(fs.createReadStream('mask.png')),
prompt: '仅替换透明区域为蓝白科技风 UI 面板',
size: '1024x1024',
quality: 'high',
output_format: 'png'
})
fs.writeFileSync('output.png', Buffer.from(resp.data[0].b64_json, 'base64'))
模型对比
| 维度 | gpt-image-2 | gpt-image-1.5 | gpt-image-1 |
|---|---|---|---|
| 推荐用途 | 当前默认推荐 | 上一代过渡版 | 经典稳定版 |
| 中文文字渲染 | 最强 | 一般 | 较弱 |
| 复杂构图 | 最强 | 良好 | 一般 |
| 速度 | 中 | 较快 | 最快 |
| 价格 | 高 | 中 | 低 |
gpt-image-2。只有在批量生成、对成本敏感且效果要求不高的场景才考虑老版本。Prompt 写作技巧
✅ 越具体越好
极简风格、蓝白配色、宣传海报、中文标题、留白充足 比 好看的海报 出图质量高几倍
✅ 说清结构
「上半部分 X,下半部分 Y,左下角 Z」比让模型自由发挥更可控
✅ 给参考风格
仿 Apple 官网风格、扁平化设计、赛博朋克霓虹 这种风格关键词很有效
❌ 避免负面词
「不要文字」「没有人物」效果差。改成正向:「纯图标设计」「无人物风景」
常见报错与陷阱
文生图
| 现象 | 原因 | 解决 |
|---|---|---|
永远返回 b64_json,不返回 URL | gpt-image-* 不支持 response_format: "url" | 参考 响应处理 三种方案 |
| 实际尺寸不是请求的尺寸 | 传了非标准 size(如 3840x2160) | 用 4 个官方标准值,需要其他比例后期缩放 |
400 报错说背景冲突 | background=transparent + output_format=jpeg | JPEG 不支持透明,用 png 或 webp |
| 中文乱码 / Windows curl 发不出去 | Windows CMD 编码问题 | 把 JSON 写入文件用 curl --data-binary @body.json |
参考图编辑
| 错误码 | 原因 | 解决 |
|---|---|---|
400 | 提示词为空、参数冲突(如透明背景 + JPEG) | 检查 prompt 和参数组合 |
400 / 422 | 蒙版尺寸与原图不一致 | 用图像工具把蒙版裁切到与原图相同尺寸 |
400 / 422 | 蒙版无透明通道 | 蒙版必须是带 alpha 通道的 PNG |
413 | 文件过大 | 单文件 ≤ 20MB;尝试压缩或换 webp |
401 / 403 | 密钥无效或未授权 | 控制台确认 Key 状态、是否分配了 image 模型权限 |
下一步
在 Codex CLI 内调用 Skill 生成图
如果你不想自己写 HTTP 代码,而是想在 Codex CLI 聊天里直接说「画一张...」就出图,可以装一个图像生成 Skill(如开源的 baoyu-imagine)。
一、环境准备(必须先完成)
1. 安装 Python(要求 3.11+)
从 python.org 下载 .pkg 安装包,双击安装。验证:
python3 --version
# Python 3.11.x 或更高 即为成功
从 python.org 下载 .exe 安装包。
安装后打开 cmd:
python --version
提示「找不到命令」需重启电脑让 PATH 生效。
2. 安装 Node.js(要求 v22+)
二、安装图片生成 Skill
方式 A:让 Codex 自动装(推荐新手)
打开 Codex,直接粘贴这段话发送:
帮我安装 `npx skills add https://github.com/jimliu/baoyu-skills --skill baoyu-imagine` 技能。
帮我在 ~/.baoyu-skills/.env 中添加下面配置:
OPENAI_API_KEY=sk-xxxx
OPENAI_BASE_URL=https://nexor.nexoraivision.com/v1
OPENAI_IMAGE_MODEL=gpt-image-2
OPENAI_IMAGE_API_DIALECT=openai-native
Codex 会自动完成安装和文件创建,之后把 sk-xxxx 替换成你真实的 Nexoraivision API Key。
方式 B:手动安装
步骤 1:运行安装命令
npx skills add https://github.com/jimliu/baoyu-skills --skill baoyu-imagine
npx skills add https://github.com/jimliu/baoyu-skills --skill baoyu-imagine
运行后会询问安装位置:
- 当前项目:只在这个项目目录下生效
- 全局用户(推荐):任何项目都能用
全局安装后技能文件路径:
| 系统 | 路径 |
|---|---|
| macOS / Linux | ~/.agents/skills/ |
| Windows | C:\Users\你的用户名\.agents\skills\ |
如果出现 Need to install the following packages: skills@x.x.x — OK? (y/n),输入 y 回车。
步骤 2:创建 .env 配置文件
mkdir -p ~/.baoyu-skills
nano ~/.baoyu-skills/.env
mkdir "%USERPROFILE%\.baoyu-skills"
notepad "%USERPROFILE%\.baoyu-skills\.env"
粘贴以下内容(把 sk-xxxx 换成真 Key):
OPENAI_API_KEY=sk-xxxx
OPENAI_BASE_URL=https://nexor.nexoraivision.com/v1
OPENAI_IMAGE_MODEL=gpt-image-2
OPENAI_IMAGE_API_DIALECT=openai-native
保存:
- macOS nano:
Ctrl + X→Y→ 回车 - Windows 记事本:
Ctrl + S保存关闭
三、验证配置
# 检查 .env
cat ~/.baoyu-skills/.env
# 检查 Skill 是否装成功
ls ~/.agents/skills/
type "%USERPROFILE%\.baoyu-skills\.env"
dir "%USERPROFILE%\.agents\skills\"
ls/dir 输出应该能看到 baoyu-imagine 相关文件夹。
四、重启 Codex 并使用
配置完成后完全退出并重启 Codex(这步必须做,Skill 需要重新加载)。
重启后直接对 Codex 说:
> 帮我生成一张赛博朋克风格的城市夜景图片
> 画一个可爱的卡通猫咪头像,白色背景
Codex 会自动调用 gpt-image-2 技能生成图片,保存到本地。
五、Skill 模式常见问题
Node.js 没安装成功或 PATH 没更新:
- 重装 nodejs.org LTS 版
- Windows 安装完必须重启电脑
- macOS 重新打开终端窗口
GitHub 访问不稳定。重试几次,或开代理后再执行。
- 检查
.env的OPENAI_API_KEY是否完整(sk-开头) - 路径正确性:
- macOS / Linux:
~/.baoyu-skills/.env - Windows:
C:\Users\你的用户名\.baoyu-skills\.env
- macOS / Linux:
- 改完重启 Codex 再试
Windows 的 ~ 不会自动展开。用 %USERPROFILE%:
C:\Users\你的用户名\.baoyu-skills\
- 确认 Skill 真的装了:
ls ~/.agents/skills/ - 检查
.env文件存在且内容正确 - 完全退出 Codex(不是关闭窗口,要 quit 进程),再启动
Token 已经消耗到模型端但本地保存失败:
- 看 Codex CLI 输出有没有错误信息
- 检查 Skill 配置的输出目录写权限
- 可以让 Codex 把图片以 base64 输出到终端,自己手动 decode 保存
Skill 模式 vs HTTP API 直接调用
| 场景 | 推荐方式 |
|---|---|
| 在 Codex CLI 聊天里随手生成几张图 | Skill 模式(说话就出图) |
| 在自己的 web 应用 / 服务里集成图像生成 | HTTP API 直接调用 |
| 批量生成、自动化流程 | HTTP API 直接调用 |
| 在 PR / 文档里嵌入示意图 | Skill 模式或 API 都行 |
