GPT-Image Relay

docs

快速开始

GPT-Image 图像生图聚合平台的统一接口,覆盖 GPT-Image 2.6 / 2.5 / 2.0 三款模型。文生图和参考图改图使用同一个端点,传了参考图就自动走改图链路。

Base URL
https://your-host
鉴权方式
Authorization: Bearer sk-relay-...
请求格式
application/json(不接受 multipart)
响应格式
application/json,图片默认返回线上 URL
curl · 文生图
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": "橘猫在窗台,午后阳光,胶片质感",
    "size": "1:1"
  }'
curl · 参考图改图(同一个接口)
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 · 指定平台
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 泄露时请立刻到 我的账户 重置,并更新调用方配置。
不要把 Key 写进前端代码、公开仓库或截图。服务端到服务端调用时请放在环境变量里。

接口总览

接口说明是否计费
POST/v1/images/generations生图 + 改图统一入口;带 images 即改图成功出图才计费
GET/v1/images/tasks/{id}轮询异步任务状态与结果否
GET/v1/models可用统一模型列表否
GET/health服务健康状态否
/v1/images/edits 作为旧版别名仍然可用,但新接入请统一使用 /v1/images/generations。两者行为一致:是否改图由请求里有没有参考图决定。

发起生图 / 改图

POST/v1/images/generationsapplication/json

同步模式会一直等到图片生成完成(通常 10–120 秒,复杂任务更久),直接返回结果;异步模式立即返回任务 ID,再轮询结果。两种模式请求参数完全一致。

请求参数

参数类型 / 默认说明
promptstring · 必填提示词,中英文均可,上限 32000 字符。
modelstring · gpt-image-2.6gpt-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 指定,后台自动匹配对应上游模型。三个模型族互不顶替:点名哪个就只调用哪个。
platformstring · auto指定平台:auto(默认,按价格 / 平台顺序自动选)或 cangyuan / grsai / juxchen(也接受中文名「沧元 / Grsai / 聚星尘」)。指定后只调用该平台,不再跨平台兜底;该平台无法处理本次请求时返回 400。别名:provider、platform_id。
resolutionstring · 1K分辨率档位:1K / 2K / 4K,与画幅完全独立。1K + 1:1(1024×1024)和 2K + 1:1(2048×2048)是两次不同的生成。别名:tier、image_resolution。其他值返回 400。
sizestring · auto画幅:比例(下表 15 个,如 1:1、16:9、1:3)、像素(1024x1024,宽高须为 16 的倍数)或 auto。不支持 1K / 2K / 4K 写法(返回 400,提示改用 resolution)。只传 resolution 时按 1:1 展开。
qualitystring · autoauto / low / medium / high / xhigh / max。low 与 auto、不传完全等价,都按底价档处理;medium 及以上会自动切换到高质量模型档(调用方不用改 model)。
imagesstring[] · 无参考图 URL 数组,最多 16 张。传了它就是改图。字段别名:image、image_url、image_urls、reference_image、reference_images、ref_images。只接受公网 http(s)。
mask_urlstring · 无局部重绘蒙版 URL(透明区域为重绘区)。必须同时提供参考图;仅部分通道支持。gpt-image-2.5 / gpt-image-2.0 不支持 mask(返回 400)。
output_formatstring · pngpng / jpeg / webp / gif / svg。GIF / SVG 仅 gpt-image-2.6 支持;gpt-image-2.5 / gpt-image-2.0 传 GIF / SVG 会返回 400。
backgroundstring · autoauto / opaque / transparent。透明背景只支持 png / webp。
complexitystring · 无none / low / medium / high / xhigh / max。控制生成前的规划投入;传入后会自动切到高质量模型档,且仅部分通道支持。gpt-image-2.5 / gpt-image-2.0 不支持该参数(返回 400)。
response_formatstring · urlurl 或 b64_json。异步任务只支持 url。
asyncboolean · false设为 true 时立即返回 202 与任务 ID;也可以改用请求头 Prefer: respond-async。
nnumber · 1固定为 1,传其他值返回 400。需要多张请并发调用。
frame_countnumber · 上游默认仅 gif:2–64。部分通道实际上限为 16,超出会被路由过滤。
frame_duration_msnumber · 上游默认仅 gif:20–2000 毫秒。
output_compressionnumber · 无仅 jpeg / webp,0–100。

档位与画幅(两个独立参数)

resolution 只决定「多清晰」,size 只决定「什么形状」。两者组合后才能确定画布:

请求档位实际画布命中通道(示例)
不传 resolution 与 size1K1024×1024底价档
"resolution":"1K","size":"1:1"1K1024×1024底价档
"resolution":"2K","size":"1:1"2K2048×2048高质量档 2K
"resolution":"4K","size":"1:1"4K2880×2880高质量档 4K
"resolution":"2K","size":"16:9"2K2048×1152高质量档 2K
"resolution":"4K","size":"16:9"4K3840×2160高质量档 4K
"size":"2048x1152"(未传 resolution)2K2048×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 决定。

画布表(比例 × 档位)

比例1K2K4K
1:11024×10242048×20482880×2880
16:91280×7202048×11523840×2160
9:16720×12801152×20482160×3840
4:31152×8642304×17283264×2448
3:4864×11521728×23042448×3264
3:21536×10242048×13603504×2336
2:31024×15361360×20482336×3504
5:41120×8962240×17923200×2560
4:5896×11201792×22402560×3200
21:91456×6242912×12483840×1648
9:21624×14561248×29121648×3840
2:11536×7683072×15363840×1920
1:2768×15361536×30721920×3840
1:3688×20481024×3072*1280×3840
3:12048×6883072×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 / GrsaiGrsaigpt-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 元数据:

200 OK
{
  "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].urlstring结果图片线上地址;response_format=b64_json 时为 data[0].b64_json。
relay.platformstring实际调用的上游平台:grsai / cangyuan / juxchen。
relay.platform_requestedstring请求里的 platform 归一后的值;未指定时为 auto。
relay.platform_pinnedboolean是否被请求钉死在某个平台(true 表示没有跨平台路由)。
relay.platform_modestringauto(网关自动选)或 pinned(按请求指定平台调用)。
relay.upstream_modelstring该平台实际调用的上游模型名(内部切换结果)。1K 底价档通常是 gpt-image-2.6;2K / 4K 或高质量档会是 gpt-image-2.6-flare / gpt-image-2.6-flare-2k 等。
relay.model_upgradedboolean是否因为参数(尺寸 / quality / complexity / 参考图数量)从底价档切到了高质量档。
relay.upgrade_reasonsstring[]触发切换的具体参数,例如 ["resolution=2K"] 或 ["size=2048x2048(2K,超过底价档上限)"]。空数组表示按底价档执行。
relay.tierstring实际档位 1K / 2K / 4K。
relay.resolutionstring | null调用方显式传入的 resolution;为空表示未指定,档位由像素或默认 1K 推导。
relay.sizestring实际生效画布(宽x高)。后台按最终命中的通道与档位展开,可能与请求像素略有差异。
relay.price_cnynumber本次调用价:从账户余额实际扣除的金额,取自后台「价格配置」里的模型 × 档位价格表,与走哪家平台、平台成本多少无关。平台成本价不对外返回,只在管理后台与后台日志里可见。
relay.request_idstring请求 ID;异步任务里与任务 ID 相同,可在后台日志中检索。
relay.adjustmentsarray上游不支持、已被剥离或改写的参数明细:{ param, action, from, to, reason }。action 为 dropped(丢弃)或 replaced(改写成 to)。为空数组表示请求参数全部原样生效。
relay.dropped_paramsstring[]被丢弃的参数名,等价于 adjustments 中 action=dropped 的 param 列表。响应头 X-Relay-Adjusted 也会列出全部被调整的参数名(逗号分隔)。
relay.elapsed_msnumber端到端耗时(毫秒)。

异步任务与轮询

生成通常需要几十秒,网关、Serverless 或移动端容易在等待中超时。此时用异步模式:提交后立即拿到任务 ID,再用轮询接口取结果。异步和同步走同一条生成链路,计价、路由和结果完全一致。

提交异步任务

两种等价写法:请求体加 "async": true,或请求头加 Prefer: respond-async。

提交 · 返回 202
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
  }'
202 Accepted
{
  "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 可查全部。

轮询结果

GET/v1/images/tasks/{id}Authorization 必带

任务进行中返回 200,响应头带 Retry-After: 2。推荐间隔 2 秒起步,逐次退避到 5–10 秒,最长轮询 10 分钟。

status含义后续动作
queued已入队,等待执行继续轮询
processing已发往上游,正在生成继续轮询
succeeded成功,data 与 relay 就绪取图,停止轮询
failed失败,error 给出原因按错误码决定重试或修改参数
成功 · 200
{
  "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
  }
}
失败 · 200(任务状态为 failed)
{
  "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": {}
  }
}
HTTPcode说明 / 建议
400invalid_request参数不合法(prompt 为空、size 越界、n≠1、参考图不是 URL、未知平台、指定平台无法处理该请求等)。按 message 修正后重试。
400payload_too_large请求体超过上限。参考图请用 URL,不要内联 base64。
401missing_api_key没有携带 Authorization 头。
401invalid_api_keyKey 不存在或已被重置。到账户页复制最新 Key。
403user_disabled账号被禁用,联系管理员。
404task_not_found任务不存在、不属于当前用户,或已超过 24 小时保留期。
402insufficient_balance账户余额不足。成功出图才扣费,本次未扣费;联系管理员充值后重试。details 里有当前可用余额与预计费用。
429concurrency_limit_exceeded并发超限。按 Retry-After 退避,详见下方并发说明。
502all_providers_failed所有平台均失败。响应 details.attempts 里有逐平台原因。
502moderation_blocked内容审核未通过。修改提示词 / 参考图,不要原样重试。
503no_api_keys服务端未配置任何上游 Key,联系管理员。
503all_keys_cooling上游 Key 全部处于冷却中,稍后重试。
504upstream_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 }
  }
}
余额是账号级预付费额度,与并发上限、API Key 相互独立。充值、退款、调整余额都在管理后台的「用户」页完成;用户端只读展示余额、可用余额(冻结中的部分不计入)和每次调用的扣费明细。

模型与计费

你只需要使用统一模型名。后台会根据参数、平台顺序和平台标价自动选择实际通道与档位,优先调用满足条件的低价路由。

统一模型语义典型用途
gpt-image-2.6gpt-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 是它的上游模型名,可作为等价别名传入成本敏感的常规出图、改图、批量任务

对外调用价(后台可配)

统一模型1K2K4K
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 元;异步任务在提交时只冻结预计费用,出图失败会把冻结额原路释放,余额一分不动。每次调用的扣费金额都能在账户页「调用记录」里核对。

GPT-Image Relay · 统一接口文档 · 最后更新 2026-11-17