OpenImage Open API · v1

把生图能力接入你的应用。

同样的扣费规则、同样的三次重试、同样保存到 OSS 的稳定地址 — 现在通过 HTTP 直接调用。创建密钥、给它一个积分上限和过期时间，开箱即用。

Quick Start · 快速开始

登录账号，前往开发者中心创建密钥。
把密钥写到 Authorization: Bearer <your-key> 头中。
调用 POST /openapi/v1/images/generations 即可生成图片。
同步模式下，接口会等待生成完成（最多 4 分钟）后返回 OSS 图片地址。

curl -X POST "/openapi/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cat astronaut floating in space, cinematic",
    "model": "gpt-image-2",
    "aspectRatio": "1:1"
  }'

const res = await fetch("/openapi/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A cat astronaut floating in space",
    model: "gpt-image-2",
    aspectRatio: "1:1"
  })
});
const data = await res.json();
console.log(data.imageUrls);

import requests

resp = requests.post(
    "/openapi/v1/images/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "prompt": "A cat astronaut floating in space",
        "model": "gpt-image-2",
        "aspectRatio": "1:1",
    },
)
print(resp.json()["imageUrls"])

Authentication · 鉴权

所有 /openapi/v1/* 接口都需要密钥。支持三种传递方式（按优先级）：

HTTP Header（推荐）：Authorization: Bearer oi-xxxxxxx
专用头：X-API-Key: oi-xxxxxxx
查询参数：?api_key=oi-xxxxxxx（仅供调试，会被日志/CDN 记录，不建议生产使用）

密钥等同于账户的提款凭证，不要提交到公开仓库或前端代码。建议：每个使用场景单独创建密钥，并设置积分上限。

Models & Pricing · 模型与计费

每次生成的扣费 = 所选模型的「基础积分 / 张」。参考图数量与画幅比例均不再产生附加费用。任务失败会自动退款。

gpt-image-2-official（GPT Image 2 · 官key） 是支持高清档位的模型，经 OpenAI 官方 Key 直连，通过 quality（推荐）或 size 指定输出规格，提供 1K / 2K / 4K 三档 × 9 种画幅比例 = 27 个固定尺寸；档位之间价格不同，详见各档位 creditCost。

nano-banana-2 / nano-banana-pro 同样支持 quality（1k/2k/4k，默认 1k）+ 9 种画幅比例，交互与官key 一致；上游为 RC Images API，按档位独立计费。

gpt-image-2（标准）、nano-banana、nano-banana-2-lite 固定 1K 出图，无需传 quality。gpt-image-2-vip（PRO） 现为标准画幅渠道：支持 9 种画幅比例，按 2K 规格出图，不再展示 4K UI，无需传 size / quality。

模型 ID	名称	基础积分 / 张
gpt-image-2	GPT Image 2 · 标准（默认）	5
gpt-image-2-vip	GPT Image 2 · PRO	8
gpt-image-2-official	GPT Image 2 · 官key	36
grok-imagine	Grok Imagine	10
nano-banana	Nano Banana	17
nano-banana-2	Nano Banana 2	15
nano-banana-pro	Nano Banana Pro	22
nano-banana-2-lite	Nano Banana 2 Lite	6

List Models · 列出模型

GET/openapi/v1/models

返回当前可用的模型清单和单价（以积分计）。无副作用，不扣费，可用于在你的 UI 里做模型下拉/选择列表。

响应字段

字段	类型	说明
success	boolean	请求是否成功。
models	object[]	模型数组，按推荐顺序排列。
models[].id	string	模型 ID，传给生图接口的 `model` 字段。
models[].label	string	面向用户的展示名（含中文标签）。
models[].baseCost	number	该模型基础积分 / 张。参考图与画幅比例不再额外计费。
models[].default	boolean	是否为默认模型；不传 `model` 时使用此项。

响应示例

{
  "success": true,
  "models": [
    { "id": "gpt-image-2", "label": "GPT Image 2 · 标准", "baseCost": 10, "default": true },
    { "id": "gpt-image-2-vip", "label": "GPT Image 2 · PRO", "baseCost": 33, "default": false },
    { "id": "gpt-image-2-official", "label": "GPT Image 2 · 官key", "baseCost": 33, "default": false },
    { "id": "nano-banana-pro", "label": "Nano Banana Pro", "baseCost": 45, "default": false }
  ]
}

Account · 查询额度

GET/openapi/v1/account

查询当前密钥的额度使用情况，以及密钥所属账户的整体积分余额。无副作用，不扣费，适合调用前先看看够不够。

响应字段

字段	类型	说明
success	boolean	请求是否成功。
apiKey.prefix	string	密钥可见前缀（如 `oi-aB3kZ9...`），完整密钥永不回显。
apiKey.creditLimit	number / null	密钥配置的积分上限；`null` 表示不设上限（仅受账户余额限制）。
apiKey.creditUsed	number	该密钥累计已消耗积分（含失败已退款的部分会回退）。
apiKey.creditRemaining	number	密钥剩余可用额度 = `creditLimit - creditUsed`，不设上限时不返回此字段。
credit.balance	number	账户总积分余额（含赠送积分）。
credit.giftBalance	number	其中赠送积分余额，消耗时优先扣此项。
credit.totalConsumed	number	账户累计已消耗积分（历史，不含退款回退后的差额）。

响应示例

{
  "success": true,
  "apiKey": {
    "prefix": "oi-aB3kZ9...",
    "creditLimit": 5000,
    "creditUsed": 1280,
    "creditRemaining": 3720
  },
  "credit": {
    "balance": 8420,
    "giftBalance": 230,
    "totalConsumed": 1580
  }
}

Generate Image · 生成图片

POST/openapi/v1/images/generations

提交一次生图请求。默认同步模式会阻塞直到生成完成（含 3 次自动重试），并直接返回保存到 OSS 的稳定图片 URL。如不希望阻塞，可设 async: true 立刻拿到 taskId，再轮询 /images/{taskId}。

接口支持两种 Content-Type：application/json（仅 URL 参考图）与 multipart/form-data（可直接上传本地图片作为参考图）。两种形式的字段名一致，仅本地文件需要走 multipart。

请求字段

字段类型说明

prompt必填 string 画面描述（支持中英文），最多 2000 字符。

model选填 string 模型 ID，见 List Models。默认 gpt-image-2。

aspectRatio选填 string 画幅比例。普通模型（含 gpt-image-2 / gpt-image-2-vip · PRO / Nano Banana 系列）支持 auto / 1:1 / 3:4 / 4:3 / 16:9 / 9:16，所有比例同价，默认 auto。
官key（gpt-image-2-official）专属：扩展为 9 种比例 —— 1:1 / 4:3 / 3:2 / 16:9 / 21:9 / 3:4 / 2:3 / 9:16 / 9:21，与 quality 组合可选 27 个像素尺寸。官key 不支持 auto，未传时按 16:9 处理。

quality选填 string 清晰度档位，可选值 1k / 2k / 4k。对以下模型生效：gpt-image-2-official（官key，默认 2k）、nano-banana-2 / nano-banana-pro（默认 1k）。1K / 2K / 4K 按档位独立计费。
推荐使用 quality + aspectRatio 组合传参。

size选填

string

直接指定像素尺寸（官key 与分档 Banana 生效；其它模型忽略）。优先级高于 quality + aspectRatio；同时传时以 size 为准。
合法取值为下表 27 条之一，其它值会返回 400：

	1:1	3:2	2:3	4:3	3:4	16:9	9:16	21:9	9:21
1K	1024x1024	1536x1024	1024x1536	1360x1024	1024x1360	1824x1024	1024x1824	2384x1024	1024x2384
2K	2048x2048	2048x1360	1360x2048	2048x1536	1536x2048	2048x1152	1152x2048	2048x880	880x2048
4K	2880x2880	3520x2336	2336x3520	3312x2480	2480x3312	3840x2160	2160x3840	3840x1648	1648x3840

不传 size 也不传 quality 时默认 2k + 16:9（即 2048x1152）。

negativePrompt选填 string 反向提示词（不希望出现的元素），最多 500 字符。

referenceUrls选填 string[] 参考图 URL 数组，最多 6 张。需为公开可访问的 HTTP(S) 地址。可与 referenceFiles 同时存在，最终合并。

referenceFiles选填 file[] 仅 multipart。本地参考图文件，重复传字段名 referenceFiles 即可上传多张；服务端会上传到 OSS 并自动拼接到 referenceUrls。单张 ≤ 20MB，image/* 任意类型。参考图不再额外扣费。

async选填 boolean 是否异步：true 立即返回任务 ID 不等待，需自行轮询；false（默认）阻塞至完成。

waitMs选填 number 同步模式下最大等待毫秒数，默认 180000（3 分钟），最大 360000（6 分钟）。官key 4K 生成耗时较长，建议显式抬到 360000。超时不算失败，可继续轮询拿结果。

请求示例 · multipart 直传本地参考图

curl -X POST "/openapi/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "prompt=把这张人像改成赛博朋克风格" \
  -F "model=gpt-image-2" \
  -F "aspectRatio=1:1" \
  -F "referenceFiles=@./portrait.png" \
  -F "referenceFiles=@./style.jpg"

请求示例 · 官key 模型生成 4K 横版图

curl -X POST "/openapi/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic landscape, golden hour, ultra detailed",
    "model": "gpt-image-2-official",
    "aspectRatio": "16:9",
    "quality": "4k",
    "async": true
  }'

响应字段

同步与异步返回的字段结构一致，区别只是返回时刻 status 是否已经是终态。详细字段说明见 Get Task 章节，常用字段速览：

字段	类型	说明
success	boolean	请求是否被成功受理。注意：`true` 仅代表受理成功，是否生图成功要看 `status`。
taskId	string	本次任务的唯一 ID，可用于轮询和补单。
status	string	`queued`（排队）/ `running`（生成中）/ `succeeded`（成功）/ `failed`（失败）。
imageUrl	string / null	主图 URL（即 `imageUrls[0]`），未完成或失败时为 `null`。
imageUrls	string[]	所有结果图的 OSS 稳定地址。同步成功时至少 1 张。
model	string	实际使用的模型 ID。
size	string / null	实际生成图的像素尺寸（如 `2048x2048`、`3840x2160`），仅官key（`gpt-image-2-official`）模型返回；其他模型为 `null`。
prompt / aspectRatio / negativePrompt / referenceUrls	—	原样回显请求参数，方便对账与日志。
progressText	string	面向人的进度文案，如 "正在请求绘图模型" / "第 2 次尝试…"。
errorMessage	string / null	失败原因（如 "请求过于频繁，请稍后再试"），仅 `failed` 时有值。
creditsCharged	number	本次实际扣除的积分。
creditsRefunded	boolean	是否已自动退款。三次重试都失败 → `true`；命中内容安全策略被拒（如涉黄、暴力等）属于有效调用，`false`，不退款。
createdAt / updatedAt	datetime	任务创建时间 / 最近一次状态更新时间（ISO-8601）。

响应示例 · 同步成功

{
  "success": true,
  "taskId": "f8d3e91a06d34c5fb4d2c1e9a7b08c2d",
  "status": "succeeded",
  "model": "gpt-image-2",
  "prompt": "A cat astronaut floating in space, cinematic",
  "aspectRatio": "1:1",
  "imageUrl": "https://pic-es.oss-cn-shanghai.aliyuncs.com/image-draw/result-f8d3e91a-1.png",
  "imageUrls": ["https://pic-es.oss-cn-shanghai.aliyuncs.com/image-draw/result-f8d3e91a-1.png"],
  "creditsCharged": 10,
  "creditsRefunded": false,
  "progressText": "生成完成",
  "createdAt": "2026-05-20T10:23:18.000+08:00",
  "updatedAt": "2026-05-20T10:23:42.000+08:00"
}

响应示例 · 异步受理

{
  "success": true,
  "taskId": "f8d3e91a...",
  "status": "queued",
  "creditsCharged": 10,
  "imageUrls": [],
  "progressText": "已加入生成队列"
}

✓

三次自动重试：上游接口超时、限流或返回空，服务自动重试，全部失败再退款。你不用自己实现重试逻辑。
例外：提示词或参考图被上游内容安全策略拒绝时（涉黄、暴力等），不会重试也不退款，errorMessage 会明确提示「内容违规」。请在客户端做基础的提示词审查。

Get Task · 查询任务

GET/openapi/v1/images/{taskId}

查询任务状态、进度和最终图片地址。同步模式下返回的 taskId 也可以用来重查、补单。任务在 Redis 保留 14 天，过期返回 404。

路径参数

参数	位置	说明
taskId必填	path	提交生图时返回的任务 ID（32 位 hex）。仅可查看属于当前密钥提交的任务。

请求示例

curl "/openapi/v1/images/f8d3e91a06d34c5fb4d2c1e9a7b08c2d" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应字段

字段	类型	说明
success	boolean	是否成功取到任务（任务不存在 → 404 + `success: false`）。
taskId	string	任务 ID。
status	string	`queued`（排队中）/ `running`（生成中）/ `succeeded`（成功）/ `failed`（失败）。
imageUrl	string	主图 URL（即 `imageUrls[0]`），仅 `succeeded` 时有值；失败或进行中为 `null`。
imageUrls	string[]	所有结果图的 OSS 稳定地址数组。
model	string	本次使用的模型 ID。
size	string / null	实际生成图的像素尺寸（如 `2048x2048`、`3840x2160`），仅官key（`gpt-image-2-official`）模型返回。
prompt	string	提交时的画面描述。
aspectRatio	string	画幅比例。
negativePrompt	string	反向提示词（可空）。
referenceUrls	string[]	参考图 URL 列表。
progressText	string	面向人的进度文案，如 "正在请求绘图模型" / "第 2 次尝试 · 上次未成功，正在重试…"。
errorMessage	string	失败时的错误描述（如限流、上游超时等），其他状态为 `null`。
createdAt	datetime	任务创建时间（ISO-8601）。
updatedAt	datetime	最近一次状态更新时间。
creditsCharged	number	本次扣除的积分。
creditsRefunded	boolean	是否已自动退款（三次重试都失败时为 `true`；命中内容安全策略被拒不退款，`false`）。

响应示例 · 成功

{
  "success": true,
  "taskId": "f8d3e91a06d34c5fb4d2c1e9a7b08c2d",
  "status": "succeeded",
  "model": "gpt-image-2",
  "prompt": "A cat astronaut floating in space",
  "aspectRatio": "1:1",
  "negativePrompt": null,
  "referenceUrls": [],
  "imageUrl": "https://pic-es.oss-cn-shanghai.aliyuncs.com/image-draw/result-f8d3e91a-1.png",
  "imageUrls": [
    "https://pic-es.oss-cn-shanghai.aliyuncs.com/image-draw/result-f8d3e91a-1.png"
  ],
  "progressText": "生成完成",
  "errorMessage": null,
  "createdAt": "2026-05-20T10:23:18.000+08:00",
  "updatedAt": "2026-05-20T10:23:42.000+08:00",
  "creditsCharged": 10,
  "creditsRefunded": false
}

响应示例 · 进行中

{
  "success": true,
  "taskId": "f8d3e91a...",
  "status": "running",
  "progressText": "正在请求绘图模型",
  "imageUrl": null,
  "imageUrls": [],
  "errorMessage": null,
  "creditsCharged": 10,
  "creditsRefunded": false
}

响应示例 · 失败已退款

{
  "success": true,
  "taskId": "f8d3e91a...",
  "status": "failed",
  "progressText": "生成失败",
  "errorMessage": "模型多次未返回图像，请尝试调整提示词",
  "imageUrl": null,
  "imageUrls": [],
  "creditsCharged": 10,
  "creditsRefunded": true
}

异步轮询建议：建议每 5 秒查一次，直到 status 变为 succeeded 或 failed。或者直接用同步模式（async 不传），服务端帮你阻塞至完成，单次请求即可拿到最终结果。

Error Codes · 错误码

所有错误响应的结构一致：HTTP 非 2xx + JSON body 包含 success: false、code（机器可读的错误标识）、message（面向人的错误描述）。部分错误会附加上下文字段（如 required、balance）方便你做提示。

统一错误响应结构

{
  "success": false,
  "code": "insufficient_credits",    // 机器可读的错误码
  "message": "积分不足：当前 5，需要 10",  // 用户友好提示
  "required": 10,                        // 部分错误会附加额外字段
  "balance": 5
}

错误码表

code	HTTP	含义
missing_api_key	401	请求未携带密钥（Authorization / X-API-Key / api_key 全为空）。
invalid_api_key	401	密钥不存在、已删除或已过期。检查是否复制完整。
user_disabled	401	密钥所属用户被管理员禁用。
unauthorized	401	未识别到密钥上下文（一般不会出现，除非鉴权拦截被绕过）。
insufficient_credits	402	账户积分不足。响应附带 `required`（需要积分）和 `balance`（当前余额）。
api_key_limit_exceeded	402	密钥配置的积分上限已用尽。响应附带 `required` / `creditLimit` / `creditUsed`。
invalid_request	400	参数非法（如 `prompt` 为空、上传文件超限）。`message` 中说明原因。
not_found	404	任务不存在或不属于当前密钥。
generation_failed	502	三次重试后仍失败，已自动退款。响应附带 `task` 字段含完整任务详情。
endpoint_removed	410	该接口已下线（如旧的 `/images/upload`），`message` 中给出替代方案。
server_error	500	未分类的服务端错误，详见 `message`。

Playground · 在线调试

填好密钥和提示词，直接在页面里发起一次真实调用 — 同样会扣积分。

Try it now · 发起一次真实请求

密钥仅在浏览器本地存储，不会上传服务器。同步模式最长等 4 分钟。

API Key 来自开发者中心。本浏览器记住，刷新仍可用。

Prompt

Model

Aspect Ratio

参考图 URL（每行一条，可空）

尚未发起请求

把 生图能力 接入你的应用。

Quick Start · 快速开始

Authentication · 鉴权

Models & Pricing · 模型与计费

List Models · 列出模型

响应字段

响应示例

Account · 查询额度

响应字段

响应示例

Generate Image · 生成图片

请求字段

请求示例 · multipart 直传本地参考图

请求示例 · 官key 模型生成 4K 横版图

响应字段

响应示例 · 同步成功

响应示例 · 异步受理

Get Task · 查询任务

路径参数

请求示例

响应字段

响应示例 · 成功

响应示例 · 进行中

响应示例 · 失败已退款

Error Codes · 错误码

统一错误响应结构

错误码表

Playground · 在线调试

Try it now · 发起一次真实请求

把生图能力接入你的应用。