Guides

Input images

The image fields of creation requests accept an https:// URL or the file itself, sent in a multipart/form-data request. They are the image field of a render, an edit, a decoration or an upscaling, and the mask and layers[].element fields of an edit. The route's permission is enough: no other is required.

Form	Sending
URL	JSON body: `"image": "https://developers.renderthink.com/assets/scenes/sejour-charpente-export.webp"`
File	`multipart/form-data` body: a file part named after the field (`image`, `mask`, `layers[0].element`)

Base64 images (data URIs) are not accepted.

Send a file

In a multipart/form-data request, each image is a file part named after its field; the other parameters are text fields, with layers, metadata and categories as JSON in a text field.

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

A mask edit sends the image, the mask and a layer's element as files, and the layers as JSON:

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

A request can mix both forms: a file for the image and a URL in the mask text field, for example. A JSON body (Content-Type: application/json) only accepts URLs.

Rules

Rule	Value
Formats	JPEG, PNG or WebP. The format is recognized from the file content, not from its extension or declared type.
Size	10 MB at most per image, file or URL.
Dimensions	8,192 pixels at most per side, and 36 million pixels at most in total.
Request body	In `multipart/form-data`, up to five files (image, mask, one element per layer) and 64 KB of text fields; in JSON, 64 KB.
URL	`https://` only, on port 443, 2,048 characters at most. Private or local addresses are refused.
Download	5 redirects at most, never from `https` to `http`. Downloading all the URLs of a request must take 30 seconds at most.

Before the generation, the API turns the image upright according to its EXIF orientation and strips its metadata (EXIF, XMP, IPTC).

Chain generations

The output[0].url of a succeeded generation can be used as the image of the next generation: upscaling a render, editing a decoration… This signed URL expires after 15 minutes (url_expires_at). After that, retrieve the generation again to get a new URL, as long as the output image is kept.

Retention

Received images and output image: kept for 24 hours after the generation ends (succeeded, failed or canceled), until the expires_at deadline, then deleted. output then becomes empty.
Received images: never returned by the API; input only holds the settings. The images of a refused request are deleted immediately.

Errors

Status	Code	Cause
400	`parameter_invalid`	Value that is neither an `https://` URL nor a file of the request; base64 image; file sent under another field name, or twice.
400	`image_url_unreachable`	Download failed: unreachable or private address, error response, timeout, expired URL.
400	`image_unreadable`	Unreadable image.
400	`image_dimensions_invalid`	Image of more than 8,192 pixels per side or 36 million pixels; for upscaling, see Upscaling.
413	`image_too_large`	Image over 10 MB.
413	`request_too_large`	JSON body over 64 KB; in `multipart/form-data`, over 64 KB of text fields or a body beyond five 10 MB images.
415	`unsupported_image_type`	Not JPEG, PNG or WebP; URL that does not return an image.
503	`overloaded`	Received images not analyzed in time (heavy load): resend the request after the `Retry-After` delay, nothing is charged.

param names the refused field: image, mask or layers[0].element. Errors shared by every route (key, permissions, balance, limits) are in Errors.