Guides

Édition

POST /v1/edits modifie une image existante. En mode prompt, une consigne écrite décrit la modification, sur toute l’image ou sur une zone. En mode mask, un masque de couleurs désigne des zones, et un calque par couleur indique quoi y faire.

curl https://api.renderthink.com/v1/edits \
  -H "Authorization: Bearer $RENDERTHINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://developers.renderthink.com/assets/scenes/sejour-charpente-rendu.webp",
    "mode": "prompt",
    "prompt": "Remplacer le canapé gris par un canapé en velours vert sauge.",
    "quality": "2k"
  }'

Paramètres

Nom	Type	Description
`image`	chaîne	Obligatoire. URL `https://` ou fichier en `multipart/form-data` (voir Images).
`mode`	chaîne	Obligatoire. `prompt` ou `mask`.
`quality`	chaîne	Obligatoire. Résolution de sortie : `1k`, `2k`, `4k` ou `8k` (voir Résolutions).
`prompt`	chaîne	Obligatoire en mode `prompt`, refusé en mode `mask`. La consigne, de 1 à 1 000 caractères.
`mask`	chaîne	Obligatoire en mode `mask`, facultatif en mode `prompt`. Masque PNG, par URL ou en fichier.
`layers`	tableau	Obligatoire en mode `mask`, refusé en mode `prompt`. De 1 à 3 calques, un par couleur peinte.
`metadata`	objet	Paires clé-valeur libres, rattachées à la génération et renvoyées avec elle (voir Métadonnées).
`background`	booléen	`true` : la requête répond dès l’acceptation, et le résultat arrive par webhook ou par lecture (voir Générations).

Droit de la clé : edits.

Édition par consigne

La consigne s’écrit dans n’importe quelle langue, sans traduction. Sa longueur se compte en caractères Unicode : une lettre accentuée compte pour un caractère.
Les sauts de ligne et les tabulations sont permis. Une consigne vide, les autres caractères de contrôle et les caractères invisibles (largeur nulle, sens d’écriture) sont refusés.
Sans mask, la consigne s’applique à toute l’image. Avec un mask peint d’une seule couleur de la palette, seule cette zone change, ombres et reflets compris.

Règles qui priment sur la consigne

L’architecture (murs, plafond, sol, ouvertures, poutres, escaliers) ne change que si la consigne la vise explicitement.
Le cadrage, la lumière et le reste de la scène sont conservés : l’image n’est jamais recadrée, pivotée, retournée ni prolongée.
Aucun texte n’est ajouté (lettre, chiffre, logo, marque, signature, filigrane), même sur demande ; un texte déjà présent est conservé.

Une consigne en partie irréalisable n’est appliquée que pour sa partie réalisable, voire pas du tout (image inchangée). La génération aboutit tout de même (succeeded).

Modération et conservation

En mode réel, la consigne passe par une modération avant tout débit ; le mode test ne la modère pas. Une consigne acceptée en test peut donc être refusée en mode réel (422 content_policy_violation).

La consigne, acceptée ou refusée, est conservée 30 jours puis effacée : input.prompt vaut alors "".

Rédaction d’une consigne

Demandez une seule modification par appel. Pour en enchaîner plusieurs, passez l’output[0].url de l’édition précédente dans image.
Nommez l’objet et sa position, puis décrivez un résultat concret : « le canapé gris à gauche de la fenêtre, en velours vert sauge » plutôt que « plus chaleureux ».
Avec un masque, inutile de décrire la position. Inutile aussi de rappeler les règles ci-dessus : elles s’appliquent toujours.

Édition par masque

Le masque est une image PNG aux dimensions de l’image à éditer, que vous pouvez dessiner avec n’importe quelle bibliothèque graphique. Chaque zone y est peinte d’une couleur de la palette ; le reste est transparent.

json
{
  "image": "https://developers.renderthink.com/assets/scenes/sejour-charpente-rendu.webp",
  "mode": "mask",
  "mask": "https://www.example.com/salon-masque.png",
  "quality": "2k",
  "layers": [
    {
      "mask_color": "#FF0000",
      "action": "modify",
      "material": "mat_4Zq8nV2bXk7pLr9TcW3yHd"
    },
    { "mask_color": "#0066FF", "action": "remove" }
  ]
}

Palette : #FF0000 (rouge), #CCFF00 (chartreuse), #00FF66 (émeraude), #0066FF (azur), #CC00FF (violet).

Masque

Format PNG, dans les limites des images d’entrée.
Mêmes proportions que l’image (redressée selon son orientation EXIF), à 1 % près. Un masque d’une autre taille est ramené à celle de l’image, sans lissage.
Au moins 512 pixels sur son plus grand côté, ou la taille de l’image si elle est plus petite ; en dessous, le masque est refusé.
Un pixel est peint s’il est opaque à 50 % au moins et s’écarte de 48 au plus d’une couleur de la palette sur chaque canal (rouge, vert, bleu).
Une même couleur peut couvrir plusieurs zones. Une couleur qui couvre moins de 0,01 % des pixels compte comme non peinte.
Chaque calque doit correspondre à une couleur peinte, et chaque couleur peinte à un calque.

Calques

Nom	Type	Description
`mask_color`	chaîne	Obligatoire. Couleur de la zone, prise dans la palette. Deux calques ne peuvent pas avoir la même.
`action`	chaîne	Obligatoire. `modify` (matière ou couleur), `remove` (effacement), `add` (ajout de `element`) ou `replace` (remplacement par `element`).
`material`	chaîne	Avec `modify` : `id` d’un matériau de `GET /v1/edit-materials`. Incompatible avec `color`.
`color`	chaîne	Avec `modify` : nouvelle couleur, au format `#RRGGBB`. Incompatible avec `material`.
`finish`	chaîne	Avec `color` uniquement : `default` (finition de la surface d’origine, par défaut), `solid_glossy`, `solid_matte`, `wood`, `stone`, `metal`, `fabric` ou `concrete`.
`element`	chaîne	Obligatoire avec `add` et `replace`. Image de l’objet, JPEG, PNG ou WebP, par URL ou en fichier.

modify et add ne changent que les pixels de la zone : peignez-la exactement.
remove et replace traitent l’objet désigné en entier, ombres et reflets compris, même hors de la zone : il suffit de le couvrir approximativement.
Un calque ne contient que les champs de son action ; un champ superflu est refusé.

Réponse

L’API renvoie la génération terminée, de type edit, avec le statut 200 ; avec background: true, elle renvoie la génération en cours, avec le statut 202. L’image produite est dans output[0].url. Le champ input reprend les réglages, sans les images : couleurs en majuscules, et finish à default pour une color envoyée sans finition.

Erreurs

Statut	Code	Cause
400	`parameter_invalid`	Champ absent, inconnu ou superflu, couleur hors palette ou en double, consigne non conforme ; `param` nomme le champ.
400	`mask_invalid`	Masque illisible ou pas en PNG.
400	`mask_dimensions_mismatch`	Proportions du masque différentes de celles de l’image, ou grand côté sous 512 pixels (sous celui de l’image, si elle est plus petite).
400	`mask_colors_mismatch`	Couleur de calque non peinte (`param` nomme le calque) ou couleur peinte sans calque (`param` vaut `mask`). En mode `prompt` : masque qui ne compte pas exactement une couleur peinte.
404	`resource_not_found`	Matériau inconnu ou retiré du catalogue.
422	`content_policy_violation`	Consigne refusée par la modération. Ne la renvoyez pas telle quelle.
503	`service_unavailable`	Modération momentanément indisponible. Renvoyez la même requête après le délai de `Retry-After` (30 secondes).
503	`mode_unavailable`	Édition momentanément indisponible, ou indisponible dans la résolution demandée.

Les erreurs des images d’entrée sont décrites dans Images d’entrée, et les erreurs communes à toutes les routes (clé, droits, solde, limites) dans Erreurs.