Guides

Editing

POST /v1/edits modifies an existing image. In prompt mode, a written instruction describes the change, on the whole image or on one area. In mask mode, a color mask designates areas, and one layer per color states what to do in each.

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": "Replace the grey sofa with a sage green velvet sofa.",
    "quality": "2k"
  }'

Parameters

Name	Type	Description
`image`	string	Required. `https://` URL or file in `multipart/form-data` (see Images).
`mode`	string	Required. `prompt` or `mask`.
`quality`	string	Required. Output resolution: `1k`, `2k`, `4k` or `8k` (see Resolutions).
`prompt`	string	Required in `prompt` mode, refused in `mask` mode. The instruction, from 1 to 1,000 characters.
`mask`	string	Required in `mask` mode, optional in `prompt` mode. PNG mask, by URL or as a file.
`layers`	array	Required in `mask` mode, refused in `prompt` mode. 1 to 3 layers, one per painted color.
`metadata`	object	Free-form key-value pairs attached to the generation and returned with it (see Metadata).
`background`	boolean	`true`: the request responds as soon as the generation is accepted, and the result arrives by webhook or by retrieval (see Generations).

Key permission: edits.

Edit by instruction

The instruction can be written in any language, without translation. Its length is counted in Unicode characters: an accented letter counts as one character.
Line breaks and tabs are allowed. An empty instruction, other control characters and invisible characters (zero width, writing direction) are refused.
Without mask, the instruction applies to the whole image. With a mask painted in a single palette color, only that area changes, shadows and reflections included.

Rules that take precedence over the instruction

The architecture (walls, ceiling, floor, openings, beams, stairs) only changes if the instruction explicitly targets it.
The framing, the light and the rest of the scene are kept: the image is never cropped, rotated, mirrored or extended.
No text is added (letter, number, logo, brand, signature, watermark), even on request; text already present is kept.

An instruction that is partly unfeasible is applied only for its feasible part, or not at all (image unchanged). The generation still succeeds (succeeded).

Moderation and retention

In live mode, the instruction goes through moderation before any charge; test mode does not moderate it. An instruction accepted in test mode can therefore be refused in live mode (422 content_policy_violation).

The instruction, accepted or refused, is kept for 30 days then erased: input.prompt is then "".

Writing an instruction

Request a single modification per call. To chain several, pass the output[0].url of the previous edit in image.
Name the object and its position, then describe a concrete result: “the grey sofa left of the window, in sage green velvet” rather than “warmer”.
With a mask, there is no need to describe the position. Nor is there any need to restate the rules above: they always apply.

Edit by mask

The mask is a PNG image at the dimensions of the image to edit, which you can draw with any graphics library. Each area is painted in a palette color; the rest is transparent.

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

Palette: #FF0000 (red), #CCFF00 (chartreuse), #00FF66 (emerald), #0066FF (azure), #CC00FF (violet).

Mask

PNG format, within the limits of input images.
Same proportions as the image (turned upright according to its EXIF orientation), within 1%. A mask of another size is brought to the image's size, without smoothing.
At least 512 pixels on its long side, or the image's size if the image is smaller; below that, the mask is refused.
A pixel is painted if it is at least 50% opaque and within 48 of a palette color on each channel (red, green, blue).
The same color can cover several areas. A color that covers less than 0.01% of the pixels counts as not painted.
Each layer must match a painted color, and each painted color a layer.

Layers

Name	Type	Description
`mask_color`	string	Required. Color of the area, taken from the palette. Two layers cannot share the same one.
`action`	string	Required. `modify` (material or color), `remove` (removal), `add` (adding `element`) or `replace` (replacing with `element`).
`material`	string	With `modify`: `id` of a material from `GET /v1/edit-materials`. Incompatible with `color`.
`color`	string	With `modify`: new color, as `#RRGGBB`. Incompatible with `material`.
`finish`	string	With `color` only: `default` (finish of the original surface, default), `solid_glossy`, `solid_matte`, `wood`, `stone`, `metal`, `fabric` or `concrete`.
`element`	string	Required with `add` and `replace`. Image of the object, JPEG, PNG or WebP, by URL or as a file.

modify and add only change the pixels of the area: paint it exactly.
remove and replace process the designated object in full, shadows and reflections included, even outside the area: covering it approximately is enough.
A layer only holds the fields of its action; an extra field is refused.

Response

The API returns the ended generation, of type edit, with the 200 status; with background: true, it returns the generation in progress, with the 202 status. The output image is in output[0].url. The input field returns the settings, without the images: colors in uppercase, and finish set to default for a color sent without a finish.

Errors

Status	Code	Cause
400	`parameter_invalid`	Field missing, unknown or extra, color outside the palette or repeated, non-compliant instruction; `param` names the field.
400	`mask_invalid`	Mask unreadable or not a PNG.
400	`mask_dimensions_mismatch`	Mask proportions differ from the image's, or its long side is under 512 pixels (or the image's, if smaller).
400	`mask_colors_mismatch`	Layer color not painted (`param` names the layer) or painted color without a layer (`param` is `mask`). In `prompt` mode: a mask that does not hold exactly one painted color.
404	`resource_not_found`	Material unknown or withdrawn from the catalog.
422	`content_policy_violation`	Instruction refused by moderation. Do not resend it as is.
503	`service_unavailable`	Moderation temporarily unavailable. Resend the same request after the `Retry-After` delay (30 seconds).
503	`mode_unavailable`	Editing temporarily unavailable, or unavailable at the requested resolution.

Input image errors are described in Input images, and errors shared by every route (key, permissions, balance, limits) in Errors.