Build a location precisely from a scene-layout/v2 map and generate its plate.
This is the "exact location building" path: instead of describing the room in prose
(which the model reinterprets — furniture drifts, depths change between shots), it
renders a control image from the map's boxes (each object a colored block at its true
position/size/depth, plus a 1-meter floor grid in true perspective), then asks the
generator to REPLACE each block with its real object in the same camera — so the plate
follows the geometry pixel-wise. Same room from another camera_id is the same space.
scene_layout: a scene-layout/v2 dict — {format, units, room{w,d,h}, objects{...boxes},
cameras{<id>:{pos,look_at,fov_deg,framing?}}, ...}. The camera must carry fov_deg.
camera_id: which camera in scene_layout.cameras to render from.
aspect: PORTRAIT (9:16), LANDSCAPE (16:9) or SQUARE. 9:16 and 16:9 from one camera share
the vertical FOV, so depths are identical across aspects.
style / extra: prepended / appended prose (art style, mood) — geometry comes from the map.
A box may carry `rot: [rx, ry, rz]` (degrees around the world X/Y/Z axes) and `pivot:
[x, y, z]`, applied as p' = Rx·Ry·Rz·(p − pivot) + pivot, pivot defaulting to the box
centre. That is how a POSE is expressed — a raised arm is a box rotated about the
shoulder. Measured live 2026-08-09: moving a hand by 2–20 cm is ignored by the
generator, rotating the arm by 15–60° comes through. Build motion out of angles.
seed / image_inputs: same meaning as in generate_image. For a SEQUENCE of frames of one
character, generate a reference frame first, then pass its mediaId as image_inputs on
every following frame — that is what keeps the face, clothes and colours identical.
A fixed seed alone does not: it only repeats an unchanged control image.
depth: render the guide as a plain greyscale depth map instead of the colour hybrid
(for an external depth-ControlNet). calibration: add frame markers, a back-wall grid
and a 2 m ruler with 10 cm ticks — measured to cut the framing drift roughly fourfold.
background: "dark" (default, unchanged) or "light". Use "light" when the plate must be
on a white background: the generator sometimes copies the guide's own palette into the
result, and a light guide makes that leak land as white rather than as a dark grid.
control_png: return the layout guide itself, base64-encoded. OFF by default because it is
hundreds of thousands of characters of TEXT — one guide can cost more context than the
whole conversation around it. `control_png_kb` always reports its size.
Returns {"urls", "media_ids", "legend", "control_png_kb"} — legend maps block colors to
objects. Add control_png=True to also get the guide itself for inspection/acceptance.