Codex 中转介绍

🧩 图像模型调用

gpt-image-2 / gpt-image-1.5 / gpt-image-1 文生图与参考图编辑完整参数与示例。
Nexoraivision 在 Codex 中转下同时提供 3 个图像模型gpt-image-2(推荐)、gpt-image-1.5gpt-image-1两种使用方式
  • 方式 1:HTTP API 直接调用(写代码集成场景)— 见本页主体内容
  • 方式 2:在 Codex CLI 内调用 Skill(聊天里说"画一张..."就出图)— 见 文末

接口总览

接口URL用途
Images GenerationsPOST /v1/images/generations文生图(纯文字 prompt 生成图片)
Images EditsPOST /v1/images/edits参考图编辑(基于上传图修改)

Base URLhttps://nexor.nexoraivision.com

一、文生图(Generations)

接口地址

POST https://nexor.nexoraivision.com/v1/images/generations
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

完整参数表

参数必填默认取值 / 说明
modelgpt-image-2(推荐)/ gpt-image-1.5 / gpt-image-1
prompt图片提示词,最长 32000 字符,越具体越好
sizeauto1024x1024 / 1536x1024 / 1024x1536 / auto
qualityautoauto / low / medium / high
backgroundautoauto / transparent / opaque(透明背景需 png/webp)
output_formatpngpng / jpeg / webp
output_compression100jpeg / webp 生效,范围 0-100(越高质量越好)
moderationautoauto / low(内容审核严格程度)
n1生成数量,建议 1-10
streamfalsetrue 启用流式
partial_images0配合 stream=true,返回 0-3 张进度图(详见 流式生成
user终端用户唯一标识(如 user-12345),用于审核回溯 / 滥用追踪
response_format 参数对 gpt-image- 无效*!OpenAI 的 gpt-image-* 系列模型只返回 base64b64_json),与 DALL-E 2/3 不同 —— 这是 OpenAI 官方限制,中转端无法改变。即使你传 "response_format": "url"也会被静默忽略,依然返回 b64_json。如何把 base64 转成 URL 见下方 响应处理 章节。
关于 size 非标准值:表里 4 个是 OpenAI 官方明确支持的值。其他比例(如 1920x10803840x2160)中转端可能容错接受,但最终是否真的输出该尺寸取决于上游模型,不保证。推荐固定用官方标准值,需要其他比例后期再缩放/裁切。

流式生成(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 计费:每张进度图都按一次完整生成计费!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
  }'

响应结构

无论你是否传 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"

方案 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

为什么 OpenAI 这么设计? gpt-image-* 是新一代多模态模型,OpenAI 不再像 DALL-E 那样代你存图(DALL-E 返回的 URL 有效期只有 1 小时也很反人类)。直接返回 b64 让你自己处理存储,更适合生产场景。

二、参考图编辑(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 透明通道);只重绘透明区域
sizeauto同文生图 4 个标准值
qualityauto同文生图
backgroundauto同文生图
output_formatpngpng / jpeg / webp
output_compression100jpeg/webp 有效(0-100
moderationautoauto / low
n1生成数量
input_fidelitylowlow / highhigh 强力保持原图主体(人脸 / 商品 / Logo 等特征)
streamfalse同文生图,支持流式
partial_images0同文生图,配合 stream 用
user终端用户标识,用于审核回溯
background=transparent 时,输出格式必须用 pngwebp,不要用 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))

模型对比

维度gpt-image-2gpt-image-1.5gpt-image-1
推荐用途当前默认推荐上一代过渡版经典稳定版
中文文字渲染最强一般较弱
复杂构图最强良好一般
速度较快最快
价格
默认就用 gpt-image-2。只有在批量生成、对成本敏感且效果要求不高的场景才考虑老版本。

Prompt 写作技巧

✅ 越具体越好

极简风格、蓝白配色、宣传海报、中文标题、留白充足好看的海报 出图质量高几倍

✅ 说清结构

「上半部分 X,下半部分 Y,左下角 Z」比让模型自由发挥更可控

✅ 给参考风格

仿 Apple 官网风格扁平化设计赛博朋克霓虹 这种风格关键词很有效

❌ 避免负面词

「不要文字」「没有人物」效果差。改成正向:「纯图标设计」「无人物风景」

常见报错与陷阱

文生图

现象原因解决
永远返回 b64_json,不返回 URLgpt-image-* 不支持 response_format: "url"参考 响应处理 三种方案
实际尺寸不是请求的尺寸传了非标准 size(如 3840x2160用 4 个官方标准值,需要其他比例后期缩放
400 报错说背景冲突background=transparent + output_format=jpegJPEG 不支持透明,用 pngwebp
中文乱码 / 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 模型权限

下一步

API 接口调用

Responses API + Chat Completions 文本接口

常见问题

计费、模型、性能等高频问题


在 Codex CLI 内调用 Skill 生成图

如果你不想自己写 HTTP 代码,而是想在 Codex CLI 聊天里直接说「画一张...」就出图,可以装一个图像生成 Skill(如开源的 baoyu-imagine)。

一、环境准备(必须先完成)

1. 安装 Python(要求 3.11+)

python.org 下载 .pkg 安装包,双击安装。验证:

python3 --version
# Python 3.11.x 或更高 即为成功

2. 安装 Node.js(要求 v22+)

nodejs.org 下载 LTS .pkg 安装包:

node --version
npx --version

两行都有版本号即成功。

二、安装图片生成 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

运行后会询问安装位置:

  • 当前项目:只在这个项目目录下生效
  • 全局用户(推荐):任何项目都能用

全局安装后技能文件路径:

系统路径
macOS / Linux~/.agents/skills/
WindowsC:\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

粘贴以下内容(把 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 + XY → 回车
  • Windows 记事本:Ctrl + S 保存关闭

三、验证配置

# 检查 .env
cat ~/.baoyu-skills/.env

# 检查 Skill 是否装成功
ls ~/.agents/skills/

ls/dir 输出应该能看到 baoyu-imagine 相关文件夹。

四、重启 Codex 并使用

配置完成后完全退出并重启 Codex(这步必须做,Skill 需要重新加载)。

重启后直接对 Codex 说:

> 帮我生成一张赛博朋克风格的城市夜景图片
> 画一个可爱的卡通猫咪头像,白色背景

Codex 会自动调用 gpt-image-2 技能生成图片,保存到本地。

五、Skill 模式常见问题

Skill 模式 vs HTTP API 直接调用

场景推荐方式
在 Codex CLI 聊天里随手生成几张图Skill 模式(说话就出图)
在自己的 web 应用 / 服务里集成图像生成HTTP API 直接调用
批量生成、自动化流程HTTP API 直接调用
在 PR / 文档里嵌入示意图Skill 模式或 API 都行