Référence de l'API

Schéma complet de l'API REST publique. Disponible sur les plans Pro et Max. Émettez une clé sur /account/api.

Vous préférez Postman ? Téléchargez notre collection v2.1 — collez votre clé gimg_… dans la variable apiKey.

Authentification

Tous les endpoints attendent un jeton Bearer dans l'en-tête Authorization. Les jetons commencent toujours par gimg_.

Authorization: Bearer gimg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Limites de débit

600 requêtes / heure / clé, 5 maximum en simultané. Chaque réponse inclut :

X-RateLimit-Limit — fixé à 600
X-RateLimit-Remaining — appels restants dans la fenêtre courante
X-RateLimit-Reset — secondes epoch auxquelles la fenêtre se réinitialise
Retry-After — secondes avant le prochain appel autorisé (uniquement sur 429)

Idempotence

Passez Idempotency-Key sur les requêtes POST. Renvoyer la même clé deux fois retourne la génération existante au lieu de débiter les crédits deux fois.

POST/api/v1/generate

Soumet une génération texte-vers-image OU une édition d'image. Renvoie immédiatement un generationId ; interrogez /api/v1/generations/:id pour obtenir le résultat.

Corps

promptstring ≤ 4000 charsrequis
Description en langage naturel. Le vocabulaire de photographe (boîtier, objectif, éclairage) aide.
type"text2img" | "edit"
Vaut 'text2img' par défaut. 'edit' nécessite inputImageKeys.
size"1024x1024" | "1024x1536" | "1536x1024"
Format. Vaut 1024x1024 par défaut.
quality"low" | "medium" | "high"
Vaut medium par défaut. high = HD 2K. low correspond à Fast (1 cr).
n1–4
Nombre de variantes. Vaut 1 par défaut.
inputImageKeysstring[] (max 4)
Clés R2 renvoyées par /api/v1/upload. Requis quand type=edit.

Réponses

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
Corps invalide. L'erreur inclut un message de validation Zod.
401 Unauthorizedjson
Clé Bearer manquante ou invalide.
402 Payment Requiredjson
Crédits insuffisants ou plafond mensuel de calcul atteint.
403 Forbiddenjson
Plan Pro/Max requis.
422 Unprocessablejson
Prompt bloqué par la politique de contenu.
429 Too Many Requestsjson
Limite de débit atteinte. Voir Retry-After.

POST/api/v1/upload

Récupère une URL PUT R2 présignée pour importer une image d'entrée. En deux étapes : ceci renvoie l'URL, puis vous y envoyez les octets directement en PUT.

Corps

filenamestring ≤ 200requis
Nom d'affichage ; non utilisé pour le stockage.
contentType"image/png" | "image/jpeg" | "image/webp"requis
Doit valoir exactement l'une de ces trois valeurs.
sizenumber (bytes ≤ 10 MB)requis
Taille du fichier que vous comptez envoyer en PUT. Sert à la validation.

Réponse (200)

urlstring
URL PUT présignée, expire dans 5 minutes.
keystring
Clé R2 — passez-la dans inputImageKeys lors de l'appel à /api/v1/generate.

GET/api/v1/generations/:id

Interroge l'état d'une génération. Renvoie immédiatement l'état courant.

Réponse (200)

idstring
L'identifiant de la génération.
status"queued" | "running" | "succeeded" | "failed" | "blocked"
'blocked' = la modération de contenu a rejeté l'entrée ou la sortie (crédits remboursés).
typestring
text2img | edit | upscale | …
outputsArray<{ png, webp, width, height }>
Renseigné quand status=succeeded. Les URL sont publiques, immuables, mises en cache CDN.
errorstring | null
Renseigné quand status=failed ou status=blocked.
costCreditsnumber
Crédits débités (remboursés en cas de blocage ou d'échec).
createdAt / completedAtISO 8601
Horodatages.

Webhooks sortants

Évitez le polling : enregistrez des endpoints HTTPS pour recevoir les événements generation.succeeded et generation.failed au moment où ils se produisent. Gestion via /api/account/webhooks.

Enregistrer

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

Charge utile de l'événement

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

Vérifier la 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"])
);

Délai d'expiration : 5 s par tentative. Nous réessayons les réponses non-2xx jusqu'à 3 fois avec un backoff exponentiel (30 s → 2 m → 10 m). Après 8 échecs consécutifs sur l'ensemble des tentatives, le webhook est désactivé automatiquement — réactivez-le depuis /account/webhooks.