Tài liệu API

Schema đầy đủ cho REST API công khai. Có sẵn trên gói Pro và Max. Tạo key tại /account/api.

Thích Postman hơn? Tải bộ collection v2.1 của chúng tôi — dán key gimg_… của bạn vào biến apiKey.

Auth

Tất cả endpoint nhận token Bearer trong header Authorization. Token luôn bắt đầu bằng gimg_.

Authorization: Bearer gimg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Giới hạn truy cập

600 request / giờ / key, tối đa 5 đồng thời. Mọi response đều bao gồm:

X-RateLimit-Limit — cố định ở mức 600
X-RateLimit-Remaining — số lượt còn lại trong cửa sổ hiện tại
X-RateLimit-Reset — epoch seconds khi cửa sổ reset
Retry-After — số giây cho đến khi cuộc gọi tiếp theo được phép (chỉ trên 429)

Idempotency

Truyền Idempotency-Key trong các request POST. Gửi cùng key hai lần sẽ trả về row generation đã có thay vì trừ credit hai lần.

POST/api/v1/generate

Gửi yêu cầu tạo ảnh từ văn bản HOẶC chỉnh sửa ảnh. Trả về ngay lập tức kèm generationId; poll /api/v1/generations/:id để lấy kết quả.

Body

promptstring ≤ 4000 charsbắt buộc
Mô tả bằng ngôn ngữ tự nhiên. Sử dụng thuật ngữ nhiếp ảnh (máy ảnh, ống kính, ánh sáng) sẽ giúp nhiều.
type"text2img" | "edit"
Mặc định là 'text2img'. 'edit' yêu cầu inputImageKeys.
size"1024x1024" | "1024x1536" | "1536x1024"
Tỷ lệ khung hình. Mặc định 1024x1024.
quality"low" | "medium" | "high"
Mặc định medium. high = HD 2K. low là Fast (1cr).
n1–4
Số biến thể. Mặc định 1.
inputImageKeysstring[] (max 4)
Các R2 key trả về từ /api/v1/upload. Bắt buộc khi type=edit.

Responses

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
Body không hợp lệ. Lỗi bao gồm thông điệp xác thực Zod.
401 Unauthorizedjson
Thiếu hoặc Bearer key không hợp lệ.
402 Payment Requiredjson
Không đủ credit hoặc đã chạm giới hạn compute hàng tháng.
403 Forbiddenjson
Yêu cầu gói Pro/Max.
422 Unprocessablejson
Prompt bị chính sách nội dung chặn.
429 Too Many Requestsjson
Đã chạm giới hạn truy cập. Xem Retry-After.

POST/api/v1/upload

Lấy URL PUT presigned của R2 để upload ảnh đầu vào. Hai bước: API trả về URL, bạn PUT bytes trực tiếp lên đó.

Body

filenamestring ≤ 200bắt buộc
Tên hiển thị; không dùng cho lưu trữ.
contentType"image/png" | "image/jpeg" | "image/webp"bắt buộc
Phải là chính xác một trong ba giá trị này.
sizenumber (bytes ≤ 10 MB)bắt buộc
Kích thước file bạn dự định PUT. Dùng để xác thực.

Response (200)

urlstring
URL PUT presigned, hết hạn sau 5 phút.
keystring
R2 key — truyền giá trị này trong inputImageKeys khi gọi /api/v1/generate.

GET/api/v1/generations/:id

Poll trạng thái của một lượt tạo. Trả về ngay lập tức kèm trạng thái hiện tại.

Response (200)

idstring
ID của lượt tạo.
status"queued" | "running" | "succeeded" | "failed" | "blocked"
'blocked' = kiểm duyệt nội dung từ chối input hoặc output (credit được hoàn lại).
typestring
text2img | edit | upscale | …
outputsArray<{ png, webp, width, height }>
Có giá trị khi status=succeeded. URL công khai, bất biến, được CDN cache.
errorstring | null
Có giá trị khi status=failed hoặc status=blocked.
costCreditsnumber
Số credit bị trừ (hoàn lại nếu blocked hoặc failed).
createdAt / completedAtISO 8601
Mốc thời gian.

Outbound webhooks

Bỏ qua bước poll: đăng ký endpoint HTTPS để nhận sự kiện generation.succeeded và generation.failed ngay khi xảy ra. Quản lý qua /api/account/webhooks.

Đăng ký

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 sự kiện

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"
  }
}

Xác thực chữ ký

// 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"])
);

Timeout: 5 giây cho mỗi lần thử. Chúng tôi retry các response không phải 2xx tối đa 3 lần với exponential backoff (30 giây → 2 phút → 10 phút). Sau 8 lần thất bại liên tiếp, webhook sẽ tự động bị tắt — kích hoạt lại từ /account/webhooks.