Referensi API

Skema lengkap untuk REST API publik. Tersedia pada paket Pro dan Max. Terbitkan kunci di /account/api.

Lebih suka Postman? Unduh koleksi v2.1 kami — tempelkan kunci gimg_… Anda ke variabel apiKey.

Auth

Semua endpoint menerima token Bearer di header Authorization. Token selalu diawali gimg_.

Authorization: Bearer gimg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate limit

600 permintaan / jam / kunci, maksimum 5 in flight. Setiap respons menyertakan:

X-RateLimit-Limit — tetap 600
X-RateLimit-Remaining — panggilan tersisa di window saat ini
X-RateLimit-Reset — epoch seconds saat window di-reset
Retry-After — detik hingga panggilan berikutnya yang diperbolehkan (hanya pada 429)

Idempotency

Sertakan Idempotency-Key pada permintaan POST. Mengirim kunci yang sama dua kali akan mengembalikan baris generation yang sudah ada alih-alih menagih kredit ganda.

POST/api/v1/generate

Kirim generation text-to-image ATAU image-edit. Mengembalikan generationId secara langsung; poll /api/v1/generations/:id untuk hasilnya.

Body

promptstring ≤ 4000 charswajib
Deskripsi bahasa alami. Terminologi fotografer (kamera, lensa, pencahayaan) membantu.
type"text2img" | "edit"
Default ke 'text2img'. 'edit' membutuhkan inputImageKeys.
size"1024x1024" | "1024x1536" | "1536x1024"
Rasio aspek. Default 1024x1024.
quality"low" | "medium" | "high"
Default ke medium. high = HD 2K. low adalah Fast (1cr).
n1–4
Jumlah variasi. Default 1.
inputImageKeysstring[] (max 4)
Key R2 yang dikembalikan oleh /api/v1/upload. Wajib ketika type=edit.

Responses

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
Body tidak valid. Error menyertakan pesan validasi Zod.
401 Unauthorizedjson
Bearer key hilang atau tidak valid.
402 Payment Requiredjson
Kredit tidak mencukupi atau batas compute bulanan tercapai.
403 Forbiddenjson
Paket Pro/Max diperlukan.
422 Unprocessablejson
Prompt diblokir oleh kebijakan konten.
429 Too Many Requestsjson
Rate limit tercapai. Lihat Retry-After.

POST/api/v1/upload

Dapatkan presigned URL R2 PUT untuk mengunggah gambar input. Dua langkah: ini mengembalikan URL, Anda PUT byte langsung ke URL tersebut.

Body

filenamestring ≤ 200wajib
Nama tampilan; tidak digunakan untuk penyimpanan.
contentType"image/png" | "image/jpeg" | "image/webp"wajib
Harus persis salah satu dari ketiga ini.
sizenumber (bytes ≤ 10 MB)wajib
Ukuran file yang akan Anda PUT. Digunakan untuk validasi.

Response (200)

urlstring
Presigned PUT URL, kedaluwarsa dalam 5 menit.
keystring
Key R2 — sertakan ini di inputImageKeys saat memanggil /api/v1/generate.

GET/api/v1/generations/:id

Poll status sebuah generation. Mengembalikan state saat ini secara langsung.

Response (200)

idstring
Generation id.
status"queued" | "running" | "succeeded" | "failed" | "blocked"
'blocked' = moderasi konten menolak input atau output (kredit dikembalikan).
typestring
text2img | edit | upscale | …
outputsArray<{ png, webp, width, height }>
Diisi ketika status=succeeded. URL bersifat publik, immutable, dan di-cache oleh CDN.
errorstring | null
Diisi ketika status=failed atau status=blocked.
costCreditsnumber
Kredit yang ditagih (dikembalikan jika blocked atau failed).
createdAt / completedAtISO 8601
Timestamps.

Webhook keluar

Lewati polling: daftarkan endpoint HTTPS untuk menerima event generation.succeeded dan generation.failed saat terjadi. Kelola melalui /api/account/webhooks.

Daftar

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 event

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

Verifikasi signature

// 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 detik per percobaan. Kami mencoba ulang respons non-2xx hingga 3 kali dengan exponential backoff (30 detik → 2 menit → 10 menit). Setelah 8 kegagalan berturut-turut antar percobaan, webhook dinonaktifkan otomatis — aktifkan kembali dari /account/webhooks.