Scenes and surfaces

What a scene is

A scene is a room, or an outdoor space, that your products render into. It has a picture, a name, a setting (indoor or outdoor) and, once it is ready, the surfaces found in it. One scene can take any number of renders, so a handful of good scenes can show a whole catalog.

{
  "id": 812,
  "name": "Library",
  "origin": "upload",
  "setting": "indoor",
  "status": "ready",
  "image_url": "https://…",
  "surfaces": [
    {
      "id": "wall_1",
      "name": "Back wall",
      "type": "wall"
    },
    {
      "id": "floor_1",
      "name": "Floor",
      "type": "floor"
    },
    {
      "id": "sofa_1",
      "name": "Sofa",
      "type": "furniture"
    },
    {
      "id": "scene_lighting",
      "name": "Scene lighting",
      "type": "lighting"
    }
  ],
  "created_at": "2026-10-21T14:02:40.000Z"
}

Where scenes come from

All of them are listed by List all scenes and can be rendered into the same way. Adding a scene costs no credits; it counts only toward your workspace’s image storage. A workspace can add up to 500 scenes a day through the API.

Scene statuses

A new scene starts as analyzing and always ends ready or failed. Poll Retrieve a scene to follow it. A scene that failed could not be read this time, so add it again in a few minutes; one that is ready with only scene_lighting had no surfaces found, so add the room again with a clearer picture.

Surfaces

Surfaces are the parts of the picture a render can change: walls, floors, ceilings, counters, cabinets, furniture, light fittings and, outdoors, the ground. Each has:

• id: what you pass as surface_id to render onto it. It is meaningful only within its own scene.
• name: a readable label, such as “Back wall” or “Sofa”.
• type: the kind of surface, which decides what can go on it. See Which products fit which surfaces.

Surfaces are listed in your workspace’s preferred order. When a render leaves out surface_id, the first surface in that list the product fits is used, so the order matters.

Scene lighting

Every ready scene also lists scene_lighting, the room’s light as a whole. It is not an object in the picture, so no analysis finds it; it is there so lighting products, such as bulbs, have something to relight. It always comes last, so a light fitting found in the picture is chosen first.

Indoor and outdoor scenes

A scene is indoor unless you add it as outdoor. You choose the setting; it is never guessed from the picture. It decides how the scene is read and which products suit it. See Render outdoor scenes.

Choose good scenes

• Pick rooms that suit the product: a living room for a sofa fabric, a kitchen for a countertop, a patio for pavers.
• Use sharp, evenly lit pictures, with the surfaces you want to render onto in clear view and not hidden behind furniture.
• Reuse scenes. Rendering every finish of a product into the same rooms gives shoppers a fair comparison, and your catalog a consistent look.