API 文档

公开 REST API 的完整 schema。仅 Pro 与 Max 方案可用。前往 /account/api 创建密钥。

想用 Postman?下载 v2.1 集合,把你的 gimg_… 密钥粘进 apiKey 变量即可。

鉴权

所有接口都需要在 Authorization 请求头中携带 Bearer token。token 始终以 gimg_ 开头。

Authorization: Bearer gimg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

速率限制

每个密钥每小时 600 次请求,并发上限为 5。每个响应都包含:

X-RateLimit-Limit — 固定为 600
X-RateLimit-Remaining — 当前窗口剩余可调用次数
X-RateLimit-Reset — 窗口重置时间(epoch 秒)
Retry-After — 距离下次允许调用的秒数(仅在 429 时返回)

幂等性

在 POST 请求上传 Idempotency-Key。同一个 key 第二次请求会返回已有的生成记录,而不会重复扣费。

POST/api/v1/generate

提交一次文生图或图像编辑任务。立即返回 generationId,调用 /api/v1/generations/:id 轮询结果。

请求体

promptstring ≤ 4000 chars必填
自然语言描述。使用摄影术语(相机、镜头、灯光)效果更好。
type"text2img" | "edit"
默认 'text2img'。'edit' 模式下必须传 inputImageKeys。
size"1024x1024" | "1024x1536" | "1536x1024"
画幅比例。默认 1024x1024。
quality"low" | "medium" | "high"
默认 medium。high = 高清 2K。low 为 Fast 模式(1cr)。
n1–4
生成变体数量。默认 1。
inputImageKeysstring[] (max 4)
由 /api/v1/upload 返回的 R2 key。type=edit 时必填。

响应

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
请求体不合法。错误信息中包含 Zod 校验提示。
401 Unauthorizedjson
Bearer key 缺失或不合法。
402 Payment Requiredjson
积分不足或已达月度算力上限。
403 Forbiddenjson
需要 Pro 或 Max 方案。
422 Unprocessablejson
提示词被内容政策拦截。
429 Too Many Requestsjson
已触发速率限制。请参考 Retry-After。

POST/api/v1/upload

获取 R2 的预签名 PUT URL,用于上传输入图。两步流程:此接口返回 URL,你直接 PUT 字节到这个 URL。

请求体

filenamestring ≤ 200必填
显示用文件名,不用于存储。
contentType"image/png" | "image/jpeg" | "image/webp"必填
必须是这三种之一。
sizenumber (bytes ≤ 10 MB)必填
你打算 PUT 上传的文件大小,用于校验。

响应(200)

urlstring
预签名 PUT URL,5 分钟后过期。
keystring
R2 key,调用 /api/v1/generate 时把它传入 inputImageKeys。

GET/api/v1/generations/:id

轮询某次生成任务的状态。立即返回当前状态。

响应(200)

idstring
本次生成任务的 id。
status"queued" | "running" | "succeeded" | "failed" | "blocked"
'blocked' = 内容审核拒绝了输入或输出(积分已退还)。
typestring
text2img | edit | upscale | …
outputsArray<{ png, webp, width, height }>
在 status=succeeded 时填充。URL 是公开、不可变、CDN 缓存的。
errorstring | null
在 status=failed 或 status=blocked 时填充。
costCreditsnumber
扣除的积分数(被 blocked 或 failed 时退还)。
createdAt / completedAtISO 8601
时间戳。

出站 webhook

省去轮询:注册一个 HTTPS endpoint,实时接收 generation.succeeded 与 generation.failed 事件。在 /api/account/webhooks 进行管理。

注册

curl -X POST https://gptimage2.plus/api/account/webhooks \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/gptimg",
    "events": ["generation.succeeded", "generation.failed"],
    "label": "Production app"
  }'
# → { "id": "...", "secret": "whsec_..." }   ← copy this, shown ONCE

事件 payload

POST https://your-app.com/hooks/gptimg
X-Gptimg-Event: generation.succeeded
X-Gptimg-Signature: <hex sha256 hmac of body>
X-Gptimg-Delivery: <uuid for dedup>
Content-Type: application/json

{
  "event": "generation.succeeded",
  "data": {
    "generationId": "...",
    "type": "text2img",
    "status": "succeeded",
    "outputs": [{ "png": "...", "webp": "...", "width": 1024, "height": 1024 }],
    "createdAt": "2026-04-26T01:23:45.000Z",
    "completedAt": "2026-04-26T01:23:50.000Z"
  }
}

校验签名

// Node example
import crypto from "crypto";
const expected = crypto
  .createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-gptimg-signature"])
);

超时:每次 5 秒。非 2xx 响应会按指数退避重试 3 次(30s → 2m → 10m)。连续 8 次失败后,webhook 会被自动停用,在 /account/webhooks 重新启用。