Guides

Images d’entrée

Les champs d’image des requêtes de création acceptent une URL https:// ou le fichier lui-même, envoyé dans une requête multipart/form-data. Ce sont le champ image d’un rendu, d’une édition, d’une décoration ou d’un upscaling, et les champs mask et layers[].element d’une édition. Le droit de la route suffit : aucun autre n’est requis.

Forme	Envoi
URL	Corps JSON : `"image": "https://developers.renderthink.com/assets/scenes/sejour-charpente-export.webp"`
Fichier	Corps `multipart/form-data` : une partie fichier nommée comme le champ (`image`, `mask`, `layers[0].element`)

Les images en base64 (data URI) ne sont pas acceptées.

Envoyer un fichier

Dans une requête multipart/form-data, chaque image est une partie fichier au nom de son champ ; les autres paramètres sont des champs texte, et layers, metadata et categories du JSON dans un champ texte.

curl https://api.renderthink.com/v1/renders \
  -H "Authorization: Bearer $RENDERTHINK_API_KEY" \
  -F image=@salon.jpg \
  -F quality=2k

Une édition par masque envoie l’image, le masque et l’élément d’un calque en fichiers, et les calques en JSON :

bash
curl https://api.renderthink.com/v1/edits \
  -H "Authorization: Bearer $RENDERTHINK_API_KEY" \
  -F image=@salon.jpg \
  -F mask=@masque.png \
  -F 'layers[0].element=@fauteuil.png' \
  -F mode=mask \
  -F quality=2k \
  --form-string 'layers=[{"mask_color": "#FF0000", "action": "add"}]'

Une même requête peut mêler les deux formes : un fichier pour l’image et une URL dans le champ texte mask, par exemple. Un corps JSON (Content-Type: application/json) n’accepte que des URL.

Règles

Règle	Valeur
Formats	JPEG, PNG ou WebP. Le format est reconnu d’après le contenu du fichier, et non d’après son extension ou le type annoncé.
Taille	10 Mo au plus par image, fichier ou URL.
Dimensions	8 192 pixels au plus par côté, et 36 millions de pixels au plus au total.
Corps de requête	En `multipart/form-data`, jusqu’à cinq fichiers (image, masque, un élément par calque) et 64 Ko de champs texte ; en JSON, 64 Ko.
URL	`https://` uniquement, sur le port 443, 2 048 caractères au plus. Les adresses privées ou locales sont refusées.
Téléchargement	5 redirections au plus, jamais de `https` vers `http`. Le téléchargement de toutes les URL d’une requête doit tenir en 30 secondes.

Avant la génération, l’API redresse l’image selon son orientation EXIF et retire ses métadonnées (EXIF, XMP, IPTC).

Enchaîner des générations

L’URL output[0].url d’une génération succeeded peut servir d’image à la génération suivante : upscaling d’un rendu, édition d’une décoration… Cette URL signée expire après 15 minutes (url_expires_at). Passé ce délai, lisez de nouveau la génération pour obtenir une nouvelle URL, tant que l’image produite est conservée.

Conservation

Images reçues et image produite : conservées 24 heures après la fin de la génération (succeeded, failed ou canceled), jusqu’à l’échéance expires_at, puis effacées. output devient alors vide.
Images reçues : jamais renvoyées par l’API ; input ne contient que les réglages. Les images d’une requête refusée sont effacées immédiatement.

Erreurs

Statut	Code	Cause
400	`parameter_invalid`	Valeur qui n’est ni une URL `https://` ni un fichier de la requête ; image en base64 ; fichier envoyé sous un autre nom de champ, ou deux fois.
400	`image_url_unreachable`	Téléchargement impossible : adresse injoignable ou privée, réponse en erreur, délai dépassé, URL expirée.
400	`image_unreadable`	Image illisible.
400	`image_dimensions_invalid`	Image de plus de 8 192 pixels de côté ou de 36 millions de pixels ; pour l’upscaling, voir Upscaling.
413	`image_too_large`	Image de plus de 10 Mo.
413	`request_too_large`	Corps JSON de plus de 64 Ko ; en `multipart/form-data`, plus de 64 Ko de champs texte ou un corps au-delà de cinq images de 10 Mo.
415	`unsupported_image_type`	Ni JPEG, ni PNG, ni WebP ; URL qui ne renvoie pas une image.
503	`overloaded`	Images reçues non analysées à temps (forte affluence) : renvoyez la requête après le délai de `Retry-After`, rien n’est débité.

param nomme le champ refusé : image, mask ou layers[0].element. Les erreurs communes à toutes les routes (clé, droits, solde, limites) sont dans Erreurs.