Guides

Générations

Chaque rendu, édition, décoration ou upscaling accepté crée une génération (gen_…) : son statut, son coût et son résultat. Une génération n’est visible que par les clés de son organisation et de son mode ; ailleurs : 404 resource_not_found.

L’objet `generation`

json
{
  "object": "generation",
  "id": "gen_3Wd8KpQ2xLm7Vb9NcT4hRz",
  "type": "render",
  "status": "succeeded",
  "cancelable": false,
  "livemode": true,
  "created_at": 1791453612,
  "completed_at": 1791453648,
  "input": {
    "quality": "2k",
    "scale": null
  },
  "output": [
    {
      "url": "https://…",
      "url_expires_at": 1791454548,
      "content_type": "image/webp",
      "width": 2752,
      "height": 1536
    }
  ],
  "error": null,
  "cost": {
    "amount": 23,
    "currency": "eur",
    "unit": "cents",
    "discount_percent": 0,
    "amount_refunded": 0
  },
  "metadata": { "project_id": "PRJ-1042" },
  "expires_at": 1791540048
}

Champ	Type	Description
`object`	chaîne	Toujours `generation`.
`id`	chaîne	Identifiant, `gen_…`.
`type`	chaîne	`render`, `edit`, `decoration` ou `upscale`.
`status`	chaîne	`in_progress`, `succeeded`, `failed` ou `canceled`.
`cancelable`	booléen	`true` tant que la génération peut encore être annulée (voir Annuler une génération).
`livemode`	booléen	`false` en mode test.
`created_at`	entier	Acceptation, horodatage Unix en secondes.
`completed_at`	entier ou `null`	Fin, ou `null`.
`input`	objet	Réglages de la demande, sans ses images : `quality` ou `scale` (l’autre à `null`), et ceux de l’édition ou de la décoration.
`output`	tableau	Images produites ; vide tant que la génération n’est pas terminée, en cas d’échec et après l’effacement des images.
`error`	objet ou `null`	`code` et `message` d’une génération `failed`.
`cost`	objet	Prix de la génération (voir Coût).
`metadata`	objet	Vos métadonnées (voir Métadonnées) ; `{}` si la requête n’en portait pas.
`expires_at`	entier	Effacement des images reçues et produites : 24 heures après la fin de la génération. La génération reste lisible 13 mois.

output[].url est une URL signée, lisible sans clé, valable 15 minutes après la lecture (url_expires_at) : relisez la génération pour en obtenir une neuve. Elle se passe aussi en image d’une autre génération (voir Images). Le format est en principe WebP.

La consigne d’une édition par consigne est effacée 30 jours après la création : input.prompt vaut alors "".

Une génération est supprimée 13 mois après sa création : sa lecture répond alors 404 resource_not_found, comme un identifiant inconnu, et elle ne figure plus dans la liste. Son débit et son remboursement restent dans les mouvements du solde (voir Facturation).

Statuts

`status`	Description
`in_progress`	Acceptée, en cours.
`succeeded`	Terminée : `output` contient l’image produite.
`failed`	Échouée et remboursée. `error.code` vaut `generation_failed` (relancez plus tard) ou `content_policy_violation` (refus de la modération : ne renvoyez pas la même demande).
`canceled`	Annulée avant son début et remboursée.

Les trois derniers statuts sont définitifs. Un échec n’est pas une erreur HTTP : la lecture répond 200.

Coût

Champ	Type	Description
`amount`	entier	Prix hors taxes en centimes d’euro, remise du palier appliquée, fixé à l’acceptation.
`currency`	chaîne	`eur`.
`unit`	chaîne	`cents`.
`discount_percent`	nombre	Remise du palier, en pourcentage.
`amount_refunded`	entier	Montant rendu au solde, en centimes. Égal à `amount` pour une génération `failed` ou `canceled`.

amount ne change pas après un remboursement ; en mode test, il donne le prix du mode réel, sans débit (voir Tarifs).

Métadonnées

metadata rattache à une génération des données de votre choix, par exemple l’identifiant du projet, du client ou de l’utilisateur concerné dans votre application. RenderThink ne les interprète pas : elles reviennent telles quelles dans la génération, dans la liste et dans les webhooks. Vous reliez ainsi un résultat à vos propres données sans table de correspondance.

json
{
  "image": "https://…",
  "quality": "2k",
  "metadata": { "project_id": "PRJ-1042", "customer_id": "C-318" }
}

16 paires au plus.
Clés de 1 à 40 caractères ; valeurs en chaînes de 500 caractères au plus. Au-delà : 400 parameter_invalid.
N’y placez aucune donnée sensible : mot de passe, données bancaires, données personnelles inutiles.

Synchrone ou en arrière-plan

Par défaut, une création répond à la fin de la génération, en général en 1 à 3 minutes : 200 avec la génération succeeded ou failed.

Réglez le délai de votre client HTTP à 5 minutes au moins (requests en Python : timeout=300). Le HttpClient de .NET abandonne à 100 secondes par défaut : relevez son Timeout.
En forte affluence, passé 4 min 30 s depuis la réception de la demande (téléchargement des images compris), ou si le serveur redémarre, la réponse est 202 avec la génération in_progress : lisez-la ou attendez son webhook.
Connexion coupée : la génération continue. Renvoyez la création avec la même Idempotency-Key pour obtenir la même génération, sans second débit (voir Idempotence).

Avec "background": true dans le corps, la création répond aussitôt 202 avec la génération in_progress, annulable tant que cancelable vaut true. Le résultat arrive par webhook, la voie conseillée pour un serveur qui lance beaucoup de générations, ou par lecture.

Les événements generation.* partent à la fin de chaque génération, dans les deux modes. Le nombre de générations lancées par minute et par heure dépend du palier (voir Limites de débit).

Lire une génération

GET /v1/generations/{id} renvoie aussitôt la génération (200) ; status dit si elle est terminée. Droit de la clé : generations_read. Pour suivre une génération en arrière-plan sans webhook, relisez-la toutes les quelques secondes : chaque lecture compte dans la limite de débit.

curl https://api.renderthink.com/v1/generations/gen_3Wd8KpQ2xLm7Vb9NcT4hRz \
  -H "Authorization: Bearer $RENDERTHINK_API_KEY"

Lister les générations

GET /v1/generations renvoie une liste paginée, de la plus récente à la plus ancienne. Droit de la clé : generations_read.

Nom	Type	Description
`limit`	entier	De 1 à 100. Par défaut : 20.
`after`	chaîne	`id` de la dernière génération de la page précédente.
`type`	chaîne	`render`, `edit`, `decoration` ou `upscale`.
`status`	chaîne	`in_progress`, `succeeded`, `failed` ou `canceled`.

Annuler une génération

POST /v1/generations/{id}/cancel annule une génération dont le traitement n’a pas commencé et la rembourse : 200 avec la génération canceled. Une génération partie ne s’annule plus, elle va à son terme.

cancelable dit si l’annulation est encore possible. C’est une indication : la génération peut partir entre la lecture et l’annulation, qui répond alors 409 generation_not_cancelable.

Droits de la clé : generations_read et celui du type de la génération (renders, edits, decorations ou upscales).

Erreurs

Statut	Code	Cause
400	`parameter_invalid`	`limit`, `after`, `type` ou `status` invalide.
403	`permission_denied`	Droit manquant, dont celui du type de la génération pour l’annuler.
404	`resource_not_found`	Génération inconnue, supprimée (13 mois après sa création), d’une autre organisation ou de l’autre mode.
409	`generation_not_cancelable`	Génération commencée ou terminée.

Les erreurs communes à toutes les routes (clé, solde, images, limites) sont dans Erreurs.