Image2Codex Gateway OpenAPI YAML ↓

CODEX IMAGE GENERATION

图片生成与参考图编辑，
由 Codex 驱动。

兼容 OpenAI Images API 的核心请求形状。每次请求创建独立临时线程，Codex 调用内置 imagegen，并返回签名 URL 或 Base64。

BASE URL
01

认证

所有生成请求都需要使用服务端配置的 IMAGE2_API_KEY。通过标准 Bearer Header 发送：

HTTP
Authorization: Bearer YOUR_IMAGE2_API_KEY
服务端集成专用

普通用户通过手机号会话使用 /api/jobs，不能获得此 Key。这里的同步接口不扣用户次数，仅供可信服务端调用。调试密钥仅保留在当前页面。

02
POST/v1/images/generations

同步生成一张图片。调用方超时需覆盖排队时间与服务端生成超时（默认 300 秒）；网页用户使用异步任务接口。

请求参数

字段类型说明
prompt 必填string

图片描述，1–8000 字符。

modelstring

兼容字段；实际 Codex 模型由服务端配置。

ninteger

当前只能为 1。

response_formatenum

url 或 b64_json，默认 URL。

cURL 示例

SH
curl BASE_URL/v1/images/generations \
  -H "Authorization: Bearer YOUR_IMAGE2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image2-codex",
    "prompt": "一只戴宇航员头盔的橘猫，电影感摄影，无文字",
    "n": 1,
    "response_format": "url"
  }'
TRY IT

在线调试

请求发送到当前域名
02B

单图 / 多图参考编辑

POST /v1/images/edits 使用 multipart/form-data，按上传顺序编号。支持 1～12 张静态 JPG、PNG、WebP，每张最多 10 MB、合计最多 40 MB、单图最多 2400 万像素。归一化时移除 EXIF 并将长边缩至最多 2048。一次请求输出一张图片。

curl http://127.0.0.1:8787/v1/images/edits \
  -H "Authorization: Bearer YOUR_IMAGE2_API_KEY" \
  -F "images=@base.jpg" \
  -F "images=@style.png" \
  -F "prompt=保持图1人物和构图，仅参考图2的色调调整光线" \
  -F "response_format=url"

单图编辑只上传一个 images 字段。参考图的所有权、计费、作品记录由 /api/ 下的网页服务处理；此同步接口不建立用户作品记录。

网页异步链路

手机号登录 → POST /api/uploads → POST /api/jobs → GET /api/jobs/:id → GET /api/assets/:id。提交任务需要唯一 requestKey；所有修改操作需要 X-Studio-Request: 1。详见项目 README。

03

响应格式

url 返回一小时有效的 HMAC 签名下载地址；b64_json 直接返回 PNG 的 Base64 内容。

JSON
{
  "created": 1788020915,
  "data": [{
    "url": "https://image.example.com/v1/images/…png?expires=…&sig=…",
    "revised_prompt": "经过图片工具优化后的描述"
  }]
}
04

错误码

400请求参数错误invalid_request_error
401Bearer Key 无效authentication_error
429队列已满或 Codex 额度受限rate_limit_error
502Codex 或图片生成失败server_error
504生成超时server_error
05

健康检查

GET /healthz

HTTP 进程是否工作。

GET /readyz

Codex App Server 是否完成初始化。