Create renders

Queues renders: each one a product, or a paint color, on one surface of one scene. It answers 202 Accepted straight away with the renders, queued; they finish in the background. Poll Retrieve a render for each.

Headers

Idempotency-Keystring, up to 255 charactersoptional

Strongly recommended. A retry with the same key and body gets the first answer back instead of a second charge. See Idempotent requests.

Content-Typestringrequired

application/json

Body: one render

Send the render’s fields at the top level of the body:

scene_idintegerrequired

The scene to render into. It must be ready. See Retrieve a scene.

product_idintegeroptional

The product to put in the scene, from List all products. Send this or paint, never both.

paintobjectoptional

A paint color instead of a product. It repaints the scene’s walls, ceiling or cabinet fronts. See Render paint colors.

paint.hexstringrequired

The exact color, as #RRGGBB, such as #4A78B8.

paint.namestring, up to 60 charactersoptional

Your own name or code for the color. It is shown back to you and never changes the render.

surface_idstringoptional

The surface to render onto, from the scene’s surfaces. Leave it out and a product goes on the first surface of the scene it fits; a paint color on the first wall, ceiling or cabinet front.

upscalebooleanoptional

Ask for an upscaled image, at no extra credit. Each render says what became of it in upscale_status. Upscaling is not available yet, so renders complete at full 4K resolution and report unavailable. See Upscaling.

Body: many renders

rendersarray, 1 to 100 itemsrequired

Each item has the fields of one render above: scene_id, then product_id or paint, and optionally surface_id. The same render may not appear twice.

upscalebooleanoptional

Ask for every render in the request to be upscaled.

Response

202 Accepted, with renders, one Render for each render asked for in the order you sent them, and credits_charged. Renders start in that order too.

How it is charged

• Each render is 1 credit. Upscaling adds nothing.
• The whole request is charged at once, or not at all. If any render in it cannot be done, or there are not enough credits for every one, nothing is queued and nothing is charged.
• A render that fails gives its credit back on its own.
• A render cancelled before it starts gives its credit back, unless it was taken before your workspace’s credits last renewed.

Errors

Every message, with its fix, is in Error messages by endpoint.