Images API

两个端点：生成（文字 → 图）、编辑（图 + 文字 → 图）。响应都是 OpenAI 标准结构 data[0].b64_json。

我要做什么	端点	支持的模型
文字生成图片	`POST /v1/images/generations`	GPT Image、Nano Banana（Gemini）、Seedream、Qwen-Image、MAI Image 各系列
上传图片 + 指令改图	`POST /v1/images/edits`	GPT Image、Nano Banana（Gemini）、MAI Image

Seedream 和 Qwen-Image 不支持 /v1/images/edits，图生图走 generations 端点，但参考图字段不同：Seedream 用 image，Qwen 用 input_images，注意不要写反。Gemini 需要控制分辨率（512 至 4K）时走 Gemini 原生协议。各系列的参数差异见对应系列页。

快速开始

一个最小可运行的请求：生成一张 1024×1024 的图，解码后存成 output.png。

base_urlhttps://api.ofox.io/v1

文生图接口https://api.ofox.io/v1/images/generations

改图接口https://api.ofox.io/v1/images/edits

模型 IDopenai/gpt-image-2.5-flare

Python

gen.py


import base64
from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_OFOX_API_KEY",
    base_url="https://api.ofox.io/v1",
    timeout=600,  # 图像接口同步返回，耗时较长
)
 
resp = client.images.generate(
    model="openai/gpt-image-2.5-flare",
    prompt="白色桌面上的一个红苹果",
    size="1024x1024",
    quality="low",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

接口同步返回，客户端超时请设为 600 秒。 高画质、大尺寸及改图请求可能需要数分钟，见实测耗时。

各系列调用方式一致，换模型只改 model。取值范围与独有参数不同，见下方各参数说明。

生成图像


POST https://api.ofox.io/v1/images/generations

请求参数

下面的可选值与默认值适用于 GPT Image 系列（gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2）。其他系列有差异的地方单独注明。实测细节见 GPT Image 系列。

必填

model必填string

模型 ID，区分大小写，写错返回 404 model_not_found。

▸ 详情

支持的模型见本页开头的表格。建议写带厂商前缀的完整 ID，如 openai/gpt-image-2.5-flare。

prompt必填string

描述要生成的画面。

常用

sizestring· 默认 auto· 可选宽x高auto

输出尺寸。可自定义宽高，但要满足四条约束，否则返回 400 Invalid size。

▸ 详情

四条约束：

宽、高都能被 16 整除
最长边 ≤ 3840
宽高比在 1:3 到 3:1 之间
总像素 ≥ 655,360（768x768 不合法，1024x768 合法）

不传或传 auto 时由模型决定，实测返回 1254×1254。需要固定尺寸请显式传入。其他系列的尺寸规则不同，见对应系列页。详见 GPT Image · 尺寸。

qualitystring· 可选lowmediumhighxhighmaxauto

画质档位，直接影响价格。gpt-image-2 没有 xhigh / max。

▸ 详情

gpt-image-2 没有 xhigh / max，传了返回 400。
不接受 DALL·E 时代的 standard / hd，传了返回 400。
不传不等于 medium：由模型自己选档（实测选了 low）。想要画质和成本稳定，请显式指定。

其他系列大多没有档位，见对应系列页。详见 GPT Image · 画质。

ninteger· 默认 1· 可选1–10

生成张数，每张单独计费。Gemini 模型不支持，不要传。

output_formatstring· 默认 png· 可选pngjpegwebp

输出文件格式。

▶高级 · 7output_compression · background · moderation · stream · partial_images · input_images · extra_body.provider.type展开

output_compressioninteger· 可选0–100

压缩率，仅对 jpeg / webp 生效。

backgroundstring· 默认 opaque· 可选opaquetransparentauto

背景。transparent 需要支持 alpha 通道的格式（png / webp）。

moderationstring· 可选autolow

内容审核强度。

streamboolean· 可选truefalse

是否流式返回。配合 partial_images 可在生成过程中收到中间图。

partial_imagesinteger· 可选0–3

流式返回的中间图张数，需同时传 stream: true。按 OpenAI 官方说明，每张中间图额外计 100 个输出 token。

input_imagesstring[]· 可选1–3 张

参考图数组（URL 或 base64），仅 Qwen 系列支持，1–3 张。

▸ 详情

其他系列传了不报错也不生效；Seedream 的参考图字段是 image。

extra_body.provider.typestring· 可选azure_foundryopenai

指定供应商。可选，通常不需要，网关会自动路由。有内容审核方面的需求时可考虑指定；指定后若该供应商不可用，不会自动切换到其他供应商。

▸ 详情

等价写法是请求头 X-OfoxAI-Provider-Type。见进阶：指定供应商。

响应

200 OK（b64_json 已截断）


{
  "created": 1777385517,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
  ],
  "model": "openai/gpt-image-2.5-flare",
  "size": "1024x1024",
  "quality": "low",
  "usage": {
    "input_tokens": 13,
    "input_tokens_details": { "text_tokens": 13 },
    "output_tokens": 196,
    "output_tokens_details": { "image_tokens": 196 },
    "total_tokens": 209
  }
}

data[].b64_jsonstring

图片的 base64 编码，不带 data:image/png;base64, 前缀。

▸ 详情

解码后写文件；在浏览器里显示需要自己拼前缀。响应里没有 url 字段。

data[].indexinteger

图片序号，n > 1 时区分多张图。

sizestring

实际输出尺寸。没传 size 或传了 auto 时，从这里读出实际尺寸。

qualitystring

实际使用的画质档位。没传 quality 时，从这里确认实际用了哪一档。

background · output_formatstring

实际使用的背景与格式。不一定返回，不要依赖这两个字段。

usageobject

计费用量。output_tokens 为输出的图片 token，input_tokens_details.text_tokens 为提示词 token。

▸ 详情

按这里的数字核算单次成本。

编辑图像


POST https://api.ofox.io/v1/images/edits

此端点支持 GPT Image、Nano Banana（Gemini）、MAI Image。Seedream 和 Qwen-Image 调用会返回 400 endpoint_not_supported，请改用生成接口的参考图字段，见 Seedream、Qwen-Image。

请求参数

multipart/form-data，以表单字段提交，需上传图片文件。可选值与默认值同样适用于 GPT Image 系列。

必填

model必填stringform

模型 ID，规则同生成接口。支持的模型见本页开头的表格。

image必填fileform· 可选PNGJPEG

参考图，传本地文件（cURL 用 @ 前缀），不是 URL。

▸ 详情

多张时字段名写 image[] 重复传入。单张 ≤ 15 MB，请求体 ≤ 50 MB；张数网关不额外限制，建议不超过 16 张。

prompt必填stringform

编辑指令。

常用

maskfileform· 可选PNG（带 alpha）

局部重绘遮罩：带 alpha 通道的 PNG，尺寸与 image 一致，透明区域 = 要重画的部分。

▸ 详情

只在本端点生效，传到生成接口会被静默忽略。制作方法与实测效果见 GPT Image · mask 局部重绘。

sizestringform· 默认 auto· 可选宽x高auto

输出尺寸，约束同生成接口。

▸ 详情

不传或传 auto 时由模型决定，不保证与原图一致。要保持原尺寸请显式传入。

qualitystringform· 可选lowmediumhighxhighmaxauto

画质档位，规则同生成接口：gpt-image-2 没有 xhigh / max。

nintegerform· 默认 1· 可选1–10

生成张数，每张单独计费。

▶高级 · 1X-OfoxAI-Provider-Type展开

X-OfoxAI-Provider-Typestringheader· 可选azure_foundryopenai

指定供应商。可选，通常不需要，网关会自动路由。有内容审核方面的需求时可考虑指定；指定后若该供应商不可用，不会自动切换到其他供应商。

▸ 详情

本端点是 multipart 上传，想固定供应商时只能用请求头，表单字段 extra_body 会被静默忽略。见进阶：指定供应商。

响应

结构与生成接口相同，usage 里多出参考图的输入 token：

200 OK（b64_json 已截断）


{
  "created": 1777385669,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
  ],
  "model": "openai/gpt-image-2",
  "size": "auto",
  "quality": "low",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1024, "text_tokens": 17 },
    "num_input_images": 1,
    "output_tokens": 358,
    "total_tokens": 1399
  }
}

usage.input_tokens_details.image_tokensinteger

参考图折算成的输入 token。实测一张 1024×1024 的参考图计 1,024 个。改图比同尺寸的文生图贵，主要贵在这一项。

usage.num_input_imagesinteger

参考图张数。可以用它确认参考图确实被模型读取了。

其余字段同生成接口的响应。

支持的模型与价格见模型目录。

调用

Python

edit.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1", timeout=600)
 
with open("apple.png", "rb") as f:
    resp = client.images.edit(
        model="openai/gpt-image-2",
        image=f,
        prompt="把苹果改成绿色，其他保持不变",
        size="auto",
        quality="low",
    )
 
with open("apple_edited.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

edit.ts


import OpenAI, { toFile } from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({
  apiKey: 'YOUR_OFOX_API_KEY',
  baseURL: 'https://api.ofox.io/v1',
  timeout: 600_000, // 毫秒
})
 
const resp = await client.images.edit({
  model: 'openai/gpt-image-2',
  image: await toFile(fs.createReadStream('apple.png'), 'apple.png'),
  prompt: '把苹果改成绿色，其他保持不变',
  size: 'auto',
  quality: 'low',
})
 
fs.writeFileSync('apple_edited.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


curl -X POST 'https://api.ofox.io/v1/images/edits' \
  --max-time 600 \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -F 'model="openai/gpt-image-2"' \
  -F 'prompt="把苹果改成绿色，其他保持不变"' \
  -F 'image=@/path/to/apple.png' \
  -F 'size="auto"' \
  -F 'quality="low"'

image 字段传本地文件路径（cURL 用 @ 前缀），不是 URL。

实测对比：

原图	编辑后

错误

出错时返回 HTTP 错误码和下面的结构（实测）：

400 Bad Request


{
  "error": {
    "code": null,
    "message": "The model 'gpt-image-2' does not support quality 'xhigh'.",
    "param": null,
    "request_id": "fbe4f24c-779d-41a0-8b3a-c62886cdd1ae",
    "type": "image_generation_user_error"
  }
}

code 可能为 null。请按 HTTP 状态码和 message 判断。

状态码	报错	原因	怎么改
400	`Invalid size '…'`	尺寸不满足四条约束	按 size 的规则调整
400	`does not support quality '…'` 或取值无效	`gpt-image-2` 传了 `xhigh` / `max`；或传了 `standard` / `hd`	改用 quality 列出的值
400	`Unknown parameter: '…'`	传了不支持的字段，如 DALL·E 的 `style`	去掉该字段
400	`Invalid image file or mode for image 1`	参考图不是 PNG / JPEG；或 mask 不是带 alpha 的 PNG、尺寸与原图不一致	检查 image 与 mask
400	`provider_type_unavailable`	指定的供应商不提供该模型	去掉供应商参数，让网关自动路由
404	`model_not_found`	模型 ID 拼错或大小写不对	从本页表格复制完整 ID
429	`rate_limit_exceeded`	超过每个团队 100 RPM；多建 Key 不会提高上限	降低并发，退避后重试

联系支持时，请附上响应里的 request_id 和报错信息（HTTP 状态码与 error.message）。建议在日志里记录它们。

进阶：指定供应商

可选，通常不需要。 GPT Image 三个模型（gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2）都由 azure_foundry 和 openai 两家承载，生成和编辑都支持。不指定时网关自动路由。

有内容审核方面的需求时可以指定供应商。指定后请求只会发往该供应商；该供应商不可用时，不会自动切换到其他供应商。

指定未承载该模型的供应商会返回 400 provider_type_unavailable。

供应商	说明	内容审核（`gpt-image-2`）
`azure_foundry`	微软云托管	较严格
`openai`	OpenAI 官方 API	相对宽松

openai/gpt-image-2 的两个供应商审核尺度不同。提示词反复被拒时，可以显式指定 openai。未指定时请求会被加权分流，可能落到 azure_foundry。

文生图 `/v1/images/generations`

JSON 请求体，请求体字段 extra_body.provider.type 与请求头 X-OfoxAI-Provider-Type 两种写法均可。

Python

gen_pinned.py


resp = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A simple red apple on a white table",
    size="1024x1024",
    extra_body={"extra_body": {"provider": {"type": "openai"}}},
)

TypeScript

gen_pinned.ts


const resp = await client.images.generate({
  model: 'openai/gpt-image-2',
  prompt: 'A simple red apple on a white table',
  size: '1024x1024',
  extra_body: { provider: { type: 'openai' } },
})

cURL

Terminal


curl https://api.ofox.io/v1/images/generations \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "...",
    "n": 1,
    "size": "1024x1024",
    "extra_body": { "provider": { "type": "openai" } }
  }'

使用官方 OpenAI SDK 时，extra_body 需作为请求体中的字面量键存在。TypeScript SDK 在参数对象中直接书写 extra_body 即可。Python SDK 的 extra_body= 参数会把内容合并到请求体顶层，因此需额外嵌套一层，或改用请求头。

图生图 `/v1/images/edits`

multipart 上传，没有 JSON 请求体可供嵌套 extra_body，因此只能使用请求头。

Terminal


curl https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "X-OfoxAI-Provider-Type: openai" \
  -F "model=openai/gpt-image-2" \
  -F "prompt=..." \
  -F "image=@input.png"

SDK 写法：Python 传 extra_headers={"X-OfoxAI-Provider-Type": "openai"}；TypeScript 在第二个参数传 { headers: { 'X-OfoxAI-Provider-Type': 'openai' } }。

在 /v1/images/edits 上，作为表单字段传递的 extra_body 会被静默忽略：图片照常生成，但约束不生效。请改用 X-OfoxAI-Provider-Type。

完整参考见 API · 供应商路由。

官方文档与更多

官方文档描述的是直连 OpenAI 的行为。与 OfoxAI 实测不一致时，以本站实测为准。

OpenAI 官方

OfoxAI 系列页

Images API

快速开始

Python

cURL

生成图像

请求参数

响应

编辑图像

请求参数

响应

调用

Python

TypeScript

cURL

错误

进阶：指定供应商

文生图 /v1/images/generations

Python

TypeScript

cURL

图生图 /v1/images/edits

官方文档与更多

文生图 `/v1/images/generations`

图生图 `/v1/images/edits`