API-Referenz

Vollständiges Schema für die öffentliche REST-API. Verfügbar in den Plänen Pro und Max. Schlüssel ausstellen unter /account/api.

Lieber Postman? Lade unsere v2.1-Collection herunter — füge deinen gimg_…-Schlüssel in die Variable apiKey ein.

Auth

Alle Endpoints erwarten ein Bearer-Token im Authorization-Header. Tokens beginnen immer mit gimg_.

Authorization: Bearer gimg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate-Limits

600 Anfragen / Stunde / Schlüssel, max. 5 parallel. Jede Antwort enthält:

X-RateLimit-Limit — fest auf 600
X-RateLimit-Remaining — verbleibende Aufrufe im aktuellen Fenster
X-RateLimit-Reset — Epoch-Sekunden, wann das Fenster zurückgesetzt wird
Retry-After — Sekunden bis zum nächsten erlaubten Aufruf (nur bei 429)

Idempotenz

Schick einen Idempotency-Key bei POST-Anfragen mit. Derselbe Key gibt zweimal die bestehende Generation zurück, statt Credits doppelt abzubuchen.

POST/api/v1/generate

Sendet eine Text-zu-Bild- ODER Bildbearbeitungs-Generation. Antwortet sofort mit einer generationId; frag /api/v1/generations/:id für das Ergebnis ab.

Body

promptstring ≤ 4000 charsPflicht
Beschreibung in natürlicher Sprache. Fotografen-Vokabular (Kamera, Objektiv, Licht) hilft.
type"text2img" | "edit"
Standard ist 'text2img'. 'edit' erfordert inputImageKeys.
size"1024x1024" | "1024x1536" | "1536x1024"
Seitenverhältnis. Standard ist 1024x1024.
quality"low" | "medium" | "high"
Standard ist medium. high = HD 2K. low ist Fast (1cr).
n1–4
Anzahl der Varianten. Standard ist 1.
inputImageKeysstring[] (max 4)
R2-Keys aus /api/v1/upload. Pflicht, wenn type=edit.

Antworten

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
Ungültiger Body. Der Fehler enthält eine Zod-Validierungsmeldung.
401 Unauthorizedjson
Bearer-Schlüssel fehlt oder ist ungültig.
402 Payment Requiredjson
Nicht genug Credits oder monatliches Compute-Limit erreicht.
403 Forbiddenjson
Pro- oder Max-Plan erforderlich.
422 Unprocessablejson
Prompt durch Inhaltsrichtlinie blockiert.
429 Too Many Requestsjson
Rate-Limit erreicht. Siehe Retry-After.

POST/api/v1/upload

Liefert eine vorsignierte R2-PUT-URL zum Hochladen eines Eingabebildes. Zwei Schritte: hier die URL bekommen, dann Bytes direkt per PUT hochladen.

Body

filenamestring ≤ 200Pflicht
Anzeigename; nicht für die Speicherung verwendet.
contentType"image/png" | "image/jpeg" | "image/webp"Pflicht
Muss exakt einer dieser drei sein.
sizenumber (bytes ≤ 10 MB)Pflicht
Dateigröße, die du per PUT senden willst. Wird zur Validierung genutzt.

Antwort (200)

urlstring
Vorsignierte PUT-URL, läuft nach 5 Minuten ab.
keystring
R2-Key — gib ihn beim Aufruf von /api/v1/generate als inputImageKeys mit.

GET/api/v1/generations/:id

Status einer Generation abfragen. Antwortet sofort mit dem aktuellen Stand.

Antwort (200)

idstring
Die ID der Generation.
status"queued" | "running" | "succeeded" | "failed" | "blocked"
'blocked' = Inhalts-Moderation hat Eingabe oder Ausgabe abgelehnt (Credits werden erstattet).
typestring
text2img | edit | upscale | …
outputsArray<{ png, webp, width, height }>
Befüllt, wenn status=succeeded. URLs sind öffentlich, unveränderlich, CDN-gecacht.
errorstring | null
Befüllt, wenn status=failed oder status=blocked.
costCreditsnumber
Berechnete Credits (erstattet bei blocked oder failed).
createdAt / completedAtISO 8601
Zeitstempel.

Outbound-Webhooks

Spar dir das Pollen: Registriere HTTPS-Endpoints, um generation.succeeded- und generation.failed-Events live zu empfangen. Verwaltung über /api/account/webhooks.

Registrieren

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

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

Signatur prüfen

// 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 s pro Versuch. Nicht-2xx-Antworten werden bis zu 3-mal mit exponentiellem Backoff wiederholt (30 s → 2 m → 10 m). Nach 8 aufeinanderfolgenden Fehlversuchen wird der Webhook automatisch deaktiviert — wieder aktivieren unter /account/webhooks.