快速开始
GPT-Image 图像生图聚合平台的统一接口,覆盖 GPT-Image 2.6 / 2.5 / 2.0 三款模型。文生图和参考图改图使用同一个端点,传了参考图就自动走改图链路。
https://your-hostAuthorization: Bearer sk-relay-...application/json(不接受 multipart)application/json,图片默认返回线上 URLcurl -X POST https://your-host/v1/images/generations \
-H "Authorization: Bearer sk-relay-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6",
"prompt": "橘猫在窗台,午后阳光,胶片质感",
"size": "1:1"
}'
curl -X POST https://your-host/v1/images/generations \
-H "Authorization: Bearer sk-relay-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6",
"prompt": "保留人物与服装,把背景换成雪山日落",
"images": ["https://your-cdn.com/reference.png"],
"size": "2:3"
}'
http(s) URL。传入 data:、base64 或本地路径会直接返回 400,请求不会发往上游。
curl -X POST https://your-host/v1/images/generations \
-H "Authorization: Bearer sk-relay-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6",
"prompt": "雪山日出,超广角",
"resolution": "2K",
"size": "16:9",
"platform": "cangyuan"
}'
platform 默认 auto,由网关按价格与平台顺序挑选。指定 cangyuan / grsai / juxchen 后,本次请求只会调用该平台;该平台关闭、没有对应模型或 Key 全部冷却时直接返回 400 / 503,不会悄悄换平台。
鉴权与 Key 生命周期
注册后系统自动分配一把专属 Key,格式为 sk-relay- 加 48 位十六进制字符。所有 /v1 接口都要在请求头里携带:
Authorization: Bearer sk-relay-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- API Key 长期有效,没有过期时间。它不随网页登录会话过期,也不会因为长期未调用而失效。
- Key 只在三种情况下失效:用户主动重置 Key、账号被管理员禁用、账号被删除。重置后旧 Key 立即失效,没有过渡期。
- 账户页显示的「网页登录会话有效期」只约束浏览器里的登录状态(Cookie),与 API Key 无关。会话过期只需要重新登录,不影响已接入的调用方。
- Key 泄露时请立刻到 我的账户 重置,并更新调用方配置。
接口总览
| 接口 | 说明 | 是否计费 |
|---|---|---|
POST/v1/images/generations | 生图 + 改图统一入口;带 images 即改图 | 成功出图才计费 |
GET/v1/images/tasks/{id} | 轮询异步任务状态与结果 | 否 |
GET/v1/models | 可用统一模型列表 | 否 |
GET/health | 服务健康状态 | 否 |
/v1/images/edits 作为旧版别名仍然可用,但新接入请统一使用 /v1/images/generations。两者行为一致:是否改图由请求里有没有参考图决定。发起生图 / 改图
同步模式会一直等到图片生成完成(通常 10–120 秒,复杂任务更久),直接返回结果;异步模式立即返回任务 ID,再轮询结果。两种模式请求参数完全一致。
请求参数
| 参数 | 类型 / 默认 | 说明 |
|---|---|---|
prompt | string · 必填 | 提示词,中英文均可,上限 32000 字符。 |
model | string · gpt-image-2.6 | gpt-image-2.6 / gpt-image-2.5 / gpt-image-2.0(三者参数完全一致,2.5 / 2.0 不支持 GIF / SVG 与 mask)。gpt-image-2 作为 2.0 的等价别名接受。不存在 -flare / -1k / -2k / -4k 的模型名:分辨率档位用 resolution 指定,画幅用 size 指定,质量档用 quality 指定,后台自动匹配对应上游模型。三个模型族互不顶替:点名哪个就只调用哪个。 |
platform | string · auto | 指定平台:auto(默认,按价格 / 平台顺序自动选)或 cangyuan / grsai / juxchen(也接受中文名「沧元 / Grsai / 聚星尘」)。指定后只调用该平台,不再跨平台兜底;该平台无法处理本次请求时返回 400。别名:provider、platform_id。 |
resolution | string · 1K | 分辨率档位:1K / 2K / 4K,与画幅完全独立。1K + 1:1(1024×1024)和 2K + 1:1(2048×2048)是两次不同的生成。别名:tier、image_resolution。其他值返回 400。 |
size | string · auto | 画幅:比例(下表 15 个,如 1:1、16:9、1:3)、像素(1024x1024,宽高须为 16 的倍数)或 auto。不支持 1K / 2K / 4K 写法(返回 400,提示改用 resolution)。只传 resolution 时按 1:1 展开。 |
quality | string · auto | auto / low / medium / high / xhigh / max。low 与 auto、不传完全等价,都按底价档处理;medium 及以上会自动切换到高质量模型档(调用方不用改 model)。 |
images | string[] · 无 | 参考图 URL 数组,最多 16 张。传了它就是改图。字段别名:image、image_url、image_urls、reference_image、reference_images、ref_images。只接受公网 http(s)。 |
mask_url | string · 无 | 局部重绘蒙版 URL(透明区域为重绘区)。必须同时提供参考图;仅部分通道支持。gpt-image-2.5 / gpt-image-2.0 不支持 mask(返回 400)。 |
output_format | string · png | png / jpeg / webp / gif / svg。GIF / SVG 仅 gpt-image-2.6 支持;gpt-image-2.5 / gpt-image-2.0 传 GIF / SVG 会返回 400。 |
background | string · auto | auto / opaque / transparent。透明背景只支持 png / webp。 |
complexity | string · 无 | none / low / medium / high / xhigh / max。控制生成前的规划投入;传入后会自动切到高质量模型档,且仅部分通道支持。gpt-image-2.5 / gpt-image-2.0 不支持该参数(返回 400)。 |
response_format | string · url | url 或 b64_json。异步任务只支持 url。 |
async | boolean · false | 设为 true 时立即返回 202 与任务 ID;也可以改用请求头 Prefer: respond-async。 |
n | number · 1 | 固定为 1,传其他值返回 400。需要多张请并发调用。 |
frame_count | number · 上游默认 | 仅 gif:2–64。部分通道实际上限为 16,超出会被路由过滤。 |
frame_duration_ms | number · 上游默认 | 仅 gif:20–2000 毫秒。 |
output_compression | number · 无 | 仅 jpeg / webp,0–100。 |
档位与画幅(两个独立参数)
resolution 只决定「多清晰」,size 只决定「什么形状」。两者组合后才能确定画布:
| 请求 | 档位 | 实际画布 | 命中通道(示例) |
|---|---|---|---|
不传 resolution 与 size | 1K | 1024×1024 | 底价档 |
"resolution":"1K","size":"1:1" | 1K | 1024×1024 | 底价档 |
"resolution":"2K","size":"1:1" | 2K | 2048×2048 | 高质量档 2K |
"resolution":"4K","size":"1:1" | 4K | 2880×2880 | 高质量档 4K |
"resolution":"2K","size":"16:9" | 2K | 2048×1152 | 高质量档 2K |
"resolution":"4K","size":"16:9" | 4K | 3840×2160 | 高质量档 4K |
"size":"2048x1152"(未传 resolution) | 2K | 2048×1152 | 高质量档 2K |
- 档位:
1K(默认)/2K/4K。2K / 4K 会自动匹配支持该档的上游模型,调用方不需要改model;底价模型只出 1K,所以 2K / 4K 一定走高质量档(vip / flare),不会下发给 1K 的 base 模型。 - 比例:
1:1、16:9、9:16、4:3、3:4、3:2、2:3、5:4、4:5、21:9、9:21、1:3、3:1、2:1、1:2。未列出的比例(例如7:5)返回400并列出可选值,不会被悄悄吸到最接近的档位。 - 像素:
1024x1024这种写法,宽高必须是 16 的倍数,最长边 ≤ 3840,总像素 655360–8294400,长宽比不超过 3:1。不传resolution时,像素会按同一比例就近匹配档位(例如3072x1536→ 2K、1280x3840→ 4K),画布按你给的像素原样下发。 - 两者同时传:
resolution优先,size只提供比例。例如"resolution":"4K","size":"1024x1024"会生成 2880×2880,而不是 1024×1024。 - auto:等同于 1:1,档位仍由
resolution决定。
画布表(比例 × 档位)
| 比例 | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024×1024 | 2048×2048 | 2880×2880 |
| 16:9 | 1280×720 | 2048×1152 | 3840×2160 |
| 9:16 | 720×1280 | 1152×2048 | 2160×3840 |
| 4:3 | 1152×864 | 2304×1728 | 3264×2448 |
| 3:4 | 864×1152 | 1728×2304 | 2448×3264 |
| 3:2 | 1536×1024 | 2048×1360 | 3504×2336 |
| 2:3 | 1024×1536 | 1360×2048 | 2336×3504 |
| 5:4 | 1120×896 | 2240×1792 | 3200×2560 |
| 4:5 | 896×1120 | 1792×2240 | 2560×3200 |
| 21:9 | 1456×624 | 2912×1248 | 3840×1648 |
| 9:21 | 624×1456 | 1248×2912 | 1648×3840 |
| 2:1 | 1536×768 | 3072×1536 | 3840×1920 |
| 1:2 | 768×1536 | 1536×3072 | 1920×3840 |
| 1:3 | 688×2048 | 1024×3072* | 1280×3840 |
| 3:1 | 2048×688 | 3072×1024* | 3840×1280 |
1:3 / 3:1 的 1K 与 4K 两个像素值,2K 由网关按同族插值补齐(短边 1024,保持严格比例与 16 的倍数)。Grsai 底价模型与聚星尘不支持这两个比例,会落到支持像素下发的 flare 通道。gpt-image-2.6 的通道为例;不同通道、不同档位的画布可能略有差异,后台会按该通道的档位表展开,并把最终尺寸写进 relay.size。平台选择
platform 只影响「去哪家平台调用」,不影响模型族、档位和计价规则。默认 auto:网关先按模型族过滤(2.0 / 2.5 / 2.6 互不顶替),再按当前路由模式选择:cost 模式严格取成本最低的路由(同价才按档位族与平台顺序拆解),priority 模式按平台顺序。
| platform | 平台 | 可承载模型 | 实际顺序 |
|---|---|---|---|
auto(默认) | 自动 | 三家都可 | 按 routing.mode 与平台顺序自动挑最便宜 / 最靠前的可用路由 |
cangyuan / 沧元 | 沧元 | gpt-image-2.6 / 2.5 / 2.0 | 只在这家找路由;1K 底价最便宜,2K / 4K 走它的 flare 档 |
grsai / Grsai | Grsai | gpt-image-2.6 / 2.5 / 2.0 | 只在这家找路由;底价模型只出 1K,2K / 4K 走 flare / vip(三档同价) |
juxchen / 聚星尘 | 聚星尘 | gpt-image-2.6 / 2.5 / 2.0(无底价档) | 只在这家找路由;2K / 4K 与高质量档最便宜,但不承载 1K 底价请求 |
- 硬约束:指定平台后其他平台连候选都不进,不会因为「另一家更便宜」而改道。
- cost 模式只看成本:同样能处理的请求里选最便宜的一条,即使对方只有高质量档;成本完全相同才按「同档位路由 → 平台顺序」拆解。
- 不跨平台兜底:指定平台被管理员关闭、该平台的这个模型被关停、没有 Key 或 Key 全在冷却,都会直接报错,错误信息里带平台名与原因。
- 模型族仍然优先:
platform=juxchen+model=gpt-image-2.6只会命中聚星尘的 2.6 路由;不会因为 2.5 更便宜就换成 2.5。 - 未知平台:拼错或使用已下线的平台(如
agnes)返回400,message 会列出当前可选平台。 - 异步任务、测试台、管理后台的路由预览都支持同一个
platform参数。
relay.platform 是实际调用平台,relay.platform_requested 是请求指定的值(auto 表示未指定),relay.platform_mode 为 auto / pinned。同步响应
成功返回 200,结构与 OpenAI 图片接口兼容,并额外带 relay 元数据:
{
"created": 1762764000,
"model": "gpt-image-2.6",
"data": [
{ "url": "https://cdn.example.com/result/abc123.png" }
],
"relay": {
"platform": "cangyuan",
"platform_label": "沧元",
"platform_requested": "auto",
"platform_pinned": false,
"platform_mode": "auto",
"upstream_model": "gpt-image-2.6",
"tier": "1K",
"resolution": null,
"matched_family": "base",
"size": "1024x1024",
"quality": "auto",
"quality_requested": null,
"price_cny": 0.12,
"model_upgraded": false,
"upgrade_reasons": [],
"key_id": "a1b2",
"request_id": "req_9f2c7d1a4b",
"references": 0,
"adjustments": [],
"dropped_params": [],
"attempts": 1,
"attempts_detail": [],
"elapsed_ms": 19934
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
data[0].url | string | 结果图片线上地址;response_format=b64_json 时为 data[0].b64_json。 |
relay.platform | string | 实际调用的上游平台:grsai / cangyuan / juxchen。 |
relay.platform_requested | string | 请求里的 platform 归一后的值;未指定时为 auto。 |
relay.platform_pinned | boolean | 是否被请求钉死在某个平台(true 表示没有跨平台路由)。 |
relay.platform_mode | string | auto(网关自动选)或 pinned(按请求指定平台调用)。 |
relay.upstream_model | string | 该平台实际调用的上游模型名(内部切换结果)。1K 底价档通常是 gpt-image-2.6;2K / 4K 或高质量档会是 gpt-image-2.6-flare / gpt-image-2.6-flare-2k 等。 |
relay.model_upgraded | boolean | 是否因为参数(尺寸 / quality / complexity / 参考图数量)从底价档切到了高质量档。 |
relay.upgrade_reasons | string[] | 触发切换的具体参数,例如 ["resolution=2K"] 或 ["size=2048x2048(2K,超过底价档上限)"]。空数组表示按底价档执行。 |
relay.tier | string | 实际档位 1K / 2K / 4K。 |
relay.resolution | string | null | 调用方显式传入的 resolution;为空表示未指定,档位由像素或默认 1K 推导。 |
relay.size | string | 实际生效画布(宽x高)。后台按最终命中的通道与档位展开,可能与请求像素略有差异。 |
relay.price_cny | number | 本次调用价:从账户余额实际扣除的金额,取自后台「价格配置」里的模型 × 档位价格表,与走哪家平台、平台成本多少无关。平台成本价不对外返回,只在管理后台与后台日志里可见。 |
relay.request_id | string | 请求 ID;异步任务里与任务 ID 相同,可在后台日志中检索。 |
relay.adjustments | array | 上游不支持、已被剥离或改写的参数明细:{ param, action, from, to, reason }。action 为 dropped(丢弃)或 replaced(改写成 to)。为空数组表示请求参数全部原样生效。 |
relay.dropped_params | string[] | 被丢弃的参数名,等价于 adjustments 中 action=dropped 的 param 列表。响应头 X-Relay-Adjusted 也会列出全部被调整的参数名(逗号分隔)。 |
relay.elapsed_ms | number | 端到端耗时(毫秒)。 |
异步任务与轮询
生成通常需要几十秒,网关、Serverless 或移动端容易在等待中超时。此时用异步模式:提交后立即拿到任务 ID,再用轮询接口取结果。异步和同步走同一条生成链路,计价、路由和结果完全一致。
提交异步任务
两种等价写法:请求体加 "async": true,或请求头加 Prefer: respond-async。
curl -X POST https://your-host/v1/images/generations \
-H "Authorization: Bearer sk-relay-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6",
"prompt": "雨夜霓虹街道,电影感,广角",
"resolution": "2K",
"size": "16:9",
"async": true
}'
{
"id": "req_9f2c7d1a4b",
"object": "image.generation.task",
"status": "queued",
"created": 1762764000,
"created_at": "2026-11-11T03:20:00.000Z",
"updated_at": "2026-11-11T03:20:00.000Z",
"model": "gpt-image-2.6",
"request": {
"model": "gpt-image-2.6",
"prompt_chars": 12,
"size": "16:9",
"size_pixels": "2048x1152",
"resolution": "2K",
"tier": "2K",
"quality": null,
"quality_requested": null,
"output_format": "png",
"requires_flare": true,
"upgrade_reasons": ["resolution=2K"],
"references": 0
},
"poll_after_ms": 2000,
"status_url": "https://your-host/v1/images/tasks/req_9f2c7d1a4b"
}
- 任务提交时会先校验参数和路由;参数错误立即返回
400,不会创建任务。 - 并发名额从提交开始占用,直到任务完成或失败才释放。轮询请求本身不占并发。
- 任务记录保留 24 小时(
server.taskTtlHours),过期后轮询返回404 task_not_found。 - 只有任务所属用户(同一把 API Key)能查询;管理员 Token 可查全部。
轮询结果
任务进行中返回 200,响应头带 Retry-After: 2。推荐间隔 2 秒起步,逐次退避到 5–10 秒,最长轮询 10 分钟。
| status | 含义 | 后续动作 |
|---|---|---|
| queued | 已入队,等待执行 | 继续轮询 |
| processing | 已发往上游,正在生成 | 继续轮询 |
| succeeded | 成功,data 与 relay 就绪 | 取图,停止轮询 |
| failed | 失败,error 给出原因 | 按错误码决定重试或修改参数 |
{
"id": "req_9f2c7d1a4b",
"object": "image.generation.task",
"status": "succeeded",
"created": 1762764000,
"created_at": "2026-11-11T03:20:00.000Z",
"updated_at": "2026-11-11T03:20:26.000Z",
"model": "gpt-image-2.6",
"request": { "model": "gpt-image-2.6", "resolution": "2K", "size": "16:9", "tier": "2K", "references": 0 },
"poll_after_ms": null,
"status_url": "https://your-host/v1/images/tasks/req_9f2c7d1a4b",
"data": [
{ "url": "https://cdn.example.com/result/def456.png" }
],
"relay": {
"platform": "juxchen",
"platform_label": "聚星尘",
"upstream_model": "gpt-image-2.6-flare",
"tier": "2K",
"resolution": "2K",
"size": "2048x1152",
"price_cny": 0.042,
"request_id": "req_9f2c7d1a4b",
"references": 0,
"elapsed_ms": 26112
}
}
{
"id": "req_9f2c7d1a4b",
"object": "image.generation.task",
"status": "failed",
"created": 1762764000,
"updated_at": "2026-11-11T03:20:12.000Z",
"model": "gpt-image-2.6",
"request": { "model": "gpt-image-2.6", "resolution": "2K", "size": "16:9", "tier": "2K", "references": 0 },
"poll_after_ms": null,
"status_url": "https://your-host/v1/images/tasks/req_9f2c7d1a4b",
"error": {
"message": "所有平台均调用失败:juxchen 429:rate limited",
"type": "all_providers_failed",
"code": "all_providers_failed",
"status": 502
}
}
轮询示例(JavaScript)
async function waitForImage(taskId, apiKey) {
const base = 'https://your-host';
let delay = 2000;
const deadline = Date.now() + 10 * 60 * 1000;
while (Date.now() < deadline) {
const res = await fetch(`${base}/v1/images/tasks/${taskId}`, {
headers: { Authorization: `Bearer ${apiKey}` }
});
const task = await res.json();
if (!res.ok) throw new Error(task?.error?.message || `HTTP ${res.status}`);
if (task.status === 'succeeded') return task.data[0].url;
if (task.status === 'failed') throw new Error(task.error?.message || '生成失败');
await new Promise((r) => setTimeout(r, delay));
delay = Math.min(10000, Math.round(delay * 1.5));
}
throw new Error('轮询超时');
}
轮询示例(Python)
import time, requests
def wait_for_image(task_id, api_key, base="https://your-host"):
delay = 2.0
deadline = time.time() + 600
while time.time() < deadline:
r = requests.get(f"{base}/v1/images/tasks/{task_id}",
headers={"Authorization": f"Bearer {api_key}"}, timeout=30)
r.raise_for_status()
task = r.json()
if task["status"] == "succeeded":
return task["data"][0]["url"]
if task["status"] == "failed":
raise RuntimeError(task["error"]["message"])
time.sleep(delay)
delay = min(10.0, delay * 1.5)
raise TimeoutError("polling timeout")
错误码
所有错误响应统一为:
{
"error": {
"message": "人类可读的错误说明",
"type": "invalid_request_error",
"code": "validation_error",
"details": {}
}
}
| HTTP | code | 说明 / 建议 |
|---|---|---|
| 400 | invalid_request | 参数不合法(prompt 为空、size 越界、n≠1、参考图不是 URL、未知平台、指定平台无法处理该请求等)。按 message 修正后重试。 |
| 400 | payload_too_large | 请求体超过上限。参考图请用 URL,不要内联 base64。 |
| 401 | missing_api_key | 没有携带 Authorization 头。 |
| 401 | invalid_api_key | Key 不存在或已被重置。到账户页复制最新 Key。 |
| 403 | user_disabled | 账号被禁用,联系管理员。 |
| 404 | task_not_found | 任务不存在、不属于当前用户,或已超过 24 小时保留期。 |
| 402 | insufficient_balance | 账户余额不足。成功出图才扣费,本次未扣费;联系管理员充值后重试。details 里有当前可用余额与预计费用。 |
| 429 | concurrency_limit_exceeded | 并发超限。按 Retry-After 退避,详见下方并发说明。 |
| 502 | all_providers_failed | 所有平台均失败。响应 details.attempts 里有逐平台原因。 |
| 502 | moderation_blocked | 内容审核未通过。修改提示词 / 参考图,不要原样重试。 |
| 503 | no_api_keys | 服务端未配置任何上游 Key,联系管理员。 |
| 503 | all_keys_cooling | 上游 Key 全部处于冷却中,稍后重试。 |
| 504 | upstream_timeout | 上游超时。为避免重复计费,网关默认不自动跨平台重试。 |
并发限制
每个账号有独立并发上限,由管理员分配,账户页只读展示。同一时刻超过上限的请求会被拒绝:
HTTP/1.1 429 Too Many Requests
Retry-After: 1
{
"error": {
"message": "并发超限:上限 2 个请求,当前正在处理 2 个,请稍后重试",
"type": "rate_limit_error",
"code": "concurrency_limit_exceeded",
"details": { "concurrency_limit": 2, "in_flight": 2 }
}
}
- 成功响应会带
X-Concurrency-Limit与X-Concurrency-Active两个响应头,可用于自适应限流。 - 异步任务的并发名额从提交开始占用,任务结束后释放;轮询不占名额。
- 管理员把并发设为
0相当于暂停该账号调用。
余额与扣费
每个账号有一个余额(人民币,元),由管理员在控制台设置或追加。余额为 0 时不再接受新请求。计费严格绑定「出图成功」:
| 阶段 | 余额变化 | 说明 |
|---|---|---|
| 提交请求 | 冻结(不扣) | 按本次请求预计命中路由的价格冻结,防止并发把余额刷成负数;冻结额只存在内存里。 |
| 参数 / 平台 / 余额校验失败 | 不变 | 400 / 402 / 429 都不会扣费,冻结额立即释放。 |
| 上游调用失败 | 不变 | 502 / 503 / 504 或内容审核失败都不扣费。 |
| 出图成功(含异步任务成功) | 扣除实际金额 | 按最终命中的平台与档位的调用价扣费,异步任务在任务 succeeded 时才扣;failed 不扣。 |
调用价按「模型 × 档位」固定配置,在后台 /admin/pricing(「价格配置」)里维护,默认 1K ¥0.12 / 2K ¥0.20 / 4K ¥0.28,三个模型一致。同一个模型档位无论落到 Grsai、沧元还是聚星尘,扣费金额都相同;平台成本价只用于路由排序和后台对账,不参与对外计价。改动即时生效,只影响之后的请求。成本价只在管理后台(平台路由、调用日志、余额流水)显示,接口响应、账户页和用户端流水中都只出现调用价。
扣费金额与扣费后余额会同时出现在三个地方:
- 同步响应:
relay.billing.charged_cny、relay.billing.balance_before、relay.billing.balance_after,以及响应头X-Charged-Cny/X-Balance-Cny。 - 异步任务:任务完成后的
relay.billing(轮询结果里可见)。 - 账户页「调用记录」:每次调用的时间、模型、档位、尺寸、扣费金额、扣费后余额、耗时与错误原因,失败记录显示为「不扣费」。
GET /api/me → { "balance": { "balance_cny": 9.85, "held_cny": 0, "available_cny": 9.85 } }
GET /api/me/logs → { "total": 12, "summary": { "charged_cny": 0.18, "price_cny": 0.18 }, "entries": [...] }
HTTP/1.1 402 Payment Required
{
"error": {
"message": "余额不足:可用 ¥0.0000,本次调用预计 ¥0.1200,请联系管理员充值",
"type": "billing_error",
"code": "insufficient_balance",
"details": { "balance_cny": 0, "held_cny": 0, "available_cny": 0, "required_cny": 0.12 }
}
}
模型与计费
你只需要使用统一模型名。后台会根据参数、平台顺序和平台标价自动选择实际通道与档位,优先调用满足条件的低价路由。
| 统一模型 | 语义 | 典型用途 |
|---|---|---|
gpt-image-2.6 | gpt-image 2.6 入口,默认 1K 底价档。档位由 resolution 决定(1K / 2K / 4K),画幅由 size 决定;quality 为 medium 及以上、带 complexity、参考图超过 9 张或像素超出底价档时,内部自动切换到高质量档。支持 png / jpeg / webp / gif / svg | 所有 gpt-image 出图:草稿、批量、海报、大幅面、GIF / SVG |
gpt-image-2.5 | 参数、档位与升级规则与 gpt-image-2.6 完全一致,共用同一套 resolution / size / quality;只在 Grsai / 沧元 / 聚星尘 三家渠道内路由,不会调用 2.6。区别:只输出 png / jpeg / webp,不支持 GIF / SVG,也不支持 mask / 局部重绘(传了返回 400) | 不需要 GIF / SVG 的常规出图、改图、批量任务 |
gpt-image-2.0 | 参数、档位、升级规则与 2.5 完全一致(向上兼容同一套 resolution / size / quality),同样只在 Grsai / 沧元 / 聚星尘 三家渠道内路由,不会调用 2.5 / 2.6。同样只输出 png / jpeg / webp,不支持 GIF / SVG / mask / complexity。对外价格与 2.5 / 2.6 相同(按档位计价)。gpt-image-2 是它的上游模型名,可作为等价别名传入 | 成本敏感的常规出图、改图、批量任务 |
对外调用价(后台可配)
| 统一模型 | 1K | 2K | 4K |
|---|---|---|---|
gpt-image-2.6 | ¥0.12 | ¥0.20 | ¥0.28 |
gpt-image-2.5 | ¥0.12 | ¥0.20 | ¥0.28 |
gpt-image-2.0 | ¥0.12 | ¥0.20 | ¥0.28 |
/admin/pricing)里改,或调用 PATCH /admin/api/pricing;平台成本价仍按各自平台路由计算,只用于排序与对账。quality 触发的底价档 → 高质量档切换不改变对外价格,只影响实际命中的上游模型与成本。gpt-image-2.6-flare / gpt-image-2.5-flare / gpt-image-2.0-flare / -flare-1k|2k|4k / -vip 这些模型名:1K / 2K / 4K 和高质量档都通过参数表达。旧的写法会返回 400,并按提示改用 model=gpt-image-2.0|2.5|2.6 + resolution + size。想看内部到底用了哪个模型,读 relay.upstream_model 与 relay.upgrade_reasons 即可。gpt-image-2.5 只会在 Grsai / 沧元 / 聚星尘 的 2.5 路由里选,不会因为 2.6 或 2.0 更便宜、或 2.5 暂时不可用就改调其它版本;gpt-image-2.0 与 gpt-image-2.6 同理。当某个族的平台全部关闭、没有 Key 或在冷却时,接口返回 400(没有可用平台)或 503,不会拿另一个模型顶上。响应里的 model 始终等于请求的模型,relay.upstream_model 只会是同族的内部档位模型。调用价以 relay.price_cny 返回,取自后台价格表(模型 × 档位:默认 1K ¥0.12 / 2K ¥0.20 / 4K ¥0.28);出图成功时这个金额会从账户余额扣除,并写进 relay.billing 与响应头 X-Charged-Cny。调用失败(参数错误、鉴权失败、余额不足、上游限流)不产生图片,也不扣余额。
gpt-image-2.6、gpt-image-2.5 或 gpt-image-2.0 单独关掉(例如只关聚星尘的 2.0),其它模型不受影响。被关掉的平台不会出现在该模型的候选里,请求会按顺序落到下一个可用平台;如果所有平台的该模型都关了,接口返回 400(没有可用平台),拒绝原因里会写明「该平台已关闭 gpt-image-2.x」,不会偷换成另一个模型。quality 越高、尺寸越大、参考图越多,越可能被路由到高质量档,成本相应上升。内部模型切换规则
- 默认(不传
resolution且size为1:1/auto):1K 底价档,优先调用平台真正的底价模型。 resolution=2K/resolution=4K,或像素落进 2K / 4K 区间:自动改用支持该档的高质量模型。quality=medium|high|xhigh|max、带complexity、参考图超过 9 张:自动改用高质量档,档位仍由resolution决定。quality=low|auto或不传:等价,不触发升级。- 切换只影响上游模型选择,响应里的
model始终等于你请求的gpt-image-2.0/gpt-image-2.5/gpt-image-2.6;三个版本不会互相顶替。
调用限制
prompt上限 32000 字符;n固定为 1。- 参考图最多 16 张,必须是公网
http(s)URL;不接受 base64、data URI、本地路径、multipart 上传。 - 单张参考图建议控制在 50MB 内;抓取超时或重定向失败会返回上游错误。
- 请求体上限默认 2MB(
server.maxBodyBytes)。 - 画布:宽高为 16 的倍数,最长边 ≤ 3840,总像素 655360–8294400,长宽比 ≤ 3:1。
- GIF 帧数上限因通道而异(部分为 16 帧),SVG 仅部分通道支持;
gpt-image-2.5/gpt-image-2.0完全不支持 GIF / SVG。不支持的组合会被自动过滤到其他平台,2.5 / 2.0 则直接返回400。 - 同步请求受
server.requestTimeoutMs限制(默认 600 秒)。网关/反向代理的读超时应大于该值。
常见问题
生图和改图要调两个接口吗?
不需要。统一用 POST /v1/images/generations,请求里带 images(参考图 URL)就是改图,不带就是文生图。后台自动选择上游的生图或编辑接口。
API Key 会过期吗?
不会。API Key 长期有效,和网页登录会话有效期无关。只有重置 Key、账号被禁用或删除时才会失效。
为什么返回的尺寸和请求的不完全一样?
统一接口按最终命中的平台与档位重新计算画布;个别上游只保证比例、不保证精确像素。需要精确尺寸时,请下载后按实际宽高缩放。
gpt-image-2.6 怎么生成 2K / 4K?为什么没有 flare 模型了?
model 固定传 gpt-image-2.6,档位用 resolution:"resolution": "2K" 或 "4K",画幅另用 size(如 "size": "1:1")。后台会按档位自动匹配支持 2K / 4K 的上游模型,不需要也不接受 gpt-image-2.6-flare-2k 这类模型名(会返回 400)。不传 resolution 时默认 1K。
gpt-image-2.5 和 2.6 有什么区别?
入参、档位、质量升级规则、文生图 / 图生图行为完全一致,resolution / size / quality 写法也一样。唯一区别是 gpt-image-2.5 只输出 png / jpeg / webp:传 output_format=gif|svg 会返回 400,传 mask_url 也会返回 400。需要 GIF / SVG 或蒙版时请改用 gpt-image-2.6。两个版本是独立模型族,价格再低也不会互相替换。
gpt-image-2.0 和 2.5 有什么区别?
入参、档位、质量升级规则、文生图 / 图生图行为完全一致,resolution / size / quality 写法也一样;gpt-image-2 是它的等价别名。区别只在渠道与价格:2.0 走同一批 Grsai / 沧元 / 聚星尘 通道,报价更低(1K 底价 ¥0.01 起),同样只输出 png / jpeg / webp,不支持 GIF / SVG / mask / complexity。三个版本是独立模型族,价格再低也不会互相替换。
为什么 size 不再接受 1K / 2K / 4K?
因为档位和画幅必须能分别表达。size="2K" 实际是「2K + 1:1」,无法表示「2K + 16:9」;现在 resolution 管档位、size 管画幅,任意组合都可表达。旧写法会返回 400,提示改用 resolution。
什么时候该用异步?
预计耗时超过 30 秒、部署在 Serverless/短超时网关、或需要在移动端展示进度时,建议用 async: true + 轮询。
轮询多久一次?任务能保留多久?
建议 2 秒起步,逐步退避到 5–10 秒。任务保留 24 小时,过期返回 404 task_not_found。
怎么固定只调用某一家平台?
传 platform:"cangyuan" / "grsai" / "juxchen"(也接受「沧元 / Grsai / 聚星尘」),不传或传 auto 就是自动路由。指定后本次请求只在该平台找路由,即使别家更便宜也不会改道;该平台关闭、没有对应模型或 Key 全在冷却时直接返回错误。
429 了怎么办?
这是账号并发达到上限,不是上游限流。按 Retry-After 等待后重试;持续出现说明需要联系管理员提高并发。
调用失败了会扣钱吗?异步任务呢?
不会。只有拿到结果图片(同步请求返回 URL / b64,异步任务变为 succeeded)才按「模型 × 档位」价格表扣费。参数错误、余额不足、并发超限、上游失败、内容审核失败都记为 0 元;异步任务在提交时只冻结预计费用,出图失败会把冻结额原路释放,余额一分不动。每次调用的扣费金额都能在账户页「调用记录」里核对。