API 文件

公開 REST API 的完整 schema。僅 Pro 與 Max 方案可用。請至 /account/api 申請金鑰。

想用 Postman?下載 v2.1 collection,把你的 gimg_… 金鑰貼到 apiKey 變數即可。

驗證

所有 endpoint 都需要在 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 取得結果。

Body

promptstring ≤ 4000 chars必填
自然語言描述。使用攝影術語(相機、鏡頭、光線)會更有幫助。
type"text2img" | "edit"
預設為 'text2img'。'edit' 模式下需搭配 inputImageKeys。
size"1024x1024" | "1024x1536" | "1536x1024"
畫幅。預設 1024x1024。
quality"low" | "medium" | "high"
預設 medium。high = HD 2K。low 為 Fast(1 點數)。
n1–4
變化張數。預設 1。
inputImageKeysstring[] (max 4)
由 /api/v1/upload 回傳的 R2 key。type=edit 時必填。

Response

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
Body 無效。錯誤訊息中包含 Zod 驗證提示。
401 Unauthorizedjson
Bearer 金鑰缺失或無效。
402 Payment Requiredjson
點數不足或已達月運算上限。
403 Forbiddenjson
需 Pro 或 Max 方案。
422 Unprocessablejson
提示詞被內容政策擋下。
429 Too Many Requestsjson
已觸發速率限制。請參考 Retry-After。

POST/api/v1/upload

取得用於上傳輸入圖片的預簽 R2 PUT URL。分兩步:此 endpoint 回傳 URL,你直接 PUT 位元組到該 URL。

Body

filenamestring ≤ 200必填
顯示用名稱,不會用於儲存。
contentType"image/png" | "image/jpeg" | "image/webp"必填
必須是這三種其中之一。
sizenumber (bytes ≤ 10 MB)必填
你打算 PUT 的檔案大小,用於驗證。

Response (200)

urlstring
預簽的 PUT URL,5 分鐘後過期。
keystring
R2 key,呼叫 /api/v1/generate 時傳入 inputImageKeys。

GET/api/v1/generations/:id

輪詢生成狀態。立即回傳目前狀態。

Response (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 次(30 秒 → 2 分鐘 → 10 分鐘)。連續 8 次失敗後,Webhook 會被自動停用,請至 /account/webhooks 重新啟用。