Reconstruct a scene

Define the scene scope, choose a budget, and retrieve reconstruction and optional item-lift results.

Scene reconstruction turns images or a video into a scene with individually modeled items. Submit your references and describe the region to model, then use the returned project ID to track progress and download the scene.

Use your Moonlake API key for authentication. Set MOONLAKE_API_BASE_URL to the API base URL for your account, including /api/v1. See the scene API reference for request and response schemas.

Choose a budget

Set config.budget_credits for appearance and geometry reconstruction. This budget does not cover physics or articulation. Optional item lifts are quoted and purchased separately.

Use these ranges as starting points for the region you want modeled:

Scene scope	Typical coverage	Suggested credits
Small, localized scene	A tabletop, desk, or single workstation captured in a few reference images	50–250
Medium scene	A room section or work area captured in a short video or a larger set of overlapping images	250–600
Large scene	A larger environment or several connected areas captured in a longer video	600–1000

Choose within each range based on the number of distinct objects, their geometric detail, and the area you want reconstructed. A long video of one object may need less work than a short video of a densely furnished room. Video inputs must still fit the media limits.

These ranges are starting points, not quality guarantees. Choose a budget that reflects the scope and detail you need. Include additional references when important surfaces or measurements are missing.

Define the region to model

When the scope is ambiguous, state exactly which region or area belongs in the reconstruction. Identify its physical boundaries and the distant, background, or non-focal areas to exclude. Do not rely on camera framing alone to communicate which visible objects matter.

Include the intended use, the most important items, and any known dimensions with units. Call out features that must be preserved, such as a box cavity, shelf spacing, or a curved profile. Distinguish measured dimensions from estimates. Describe appearance and geometry requirements separately from any later physics or articulation work.

For example, set input.prompt to:

Reconstruct the foreground workstation, bounded by the desk edges,
the adjacent wall, and the floor beneath the chair. Include the desk,
chair, monitor, and objects on the desktop. Exclude the distant room,
the doorway beyond the workstation, and background furniture.

Prioritize the desk and chair proportions, the monitor placement,
and the visible desktop objects. Preserve the desk's open leg space
and the chair's curved back. The measured desk width is 1.4 meters;
other dimensions are unknown. Match the visible materials and colors.

Name the items that matter most to your task and describe the detail each needs. Include walls, fixtures, and other structures explicitly when they belong in the requested region. State whether people or animals should be included.

Prepare useful references

Use one image, overlapping views of the same scene, or one video. Do not combine images and video in a request. For multiple views, include angles that reveal object placement, important profiles, and occluded features. Avoid unrelated images that describe different environments.

A single image leaves hidden surfaces and absolute scale uncertain. Provide additional views and known dimensions when those details matter to your task.

Submit the reconstruction

Send multipart form data for local files. Each attached reference names its matching file field. This shell example uses a local image and a new idempotency key:

curl --request POST "$MOONLAKE_API_BASE_URL/scenes" \
	--header "Authorization: Bearer $MOONLAKE_API_KEY" \
	--header 'Idempotency-Key: workstation-reconstruction-001' \
	--form 'input={"input_type":"single_image","prompt":"Reconstruct only the foreground workstation, its chair, desktop objects, adjacent wall, and nearby floor. Exclude the distant room and background furniture.","references":[{"source":"attached","name":"reference_0"}]}' \
	--form 'config={"budget_credits":100}' \
	--form 'reference_0=@workstation.png'

The API returns 202 with a project_id and reserves the scene credits. Save that ID for polling, downloads, cancellation, and optional lifts. Scene creation creates its own project; do not create or pass a separate project ID.

If a request times out, retry the same payload with the same idempotency key. If an error response includes a project ID, poll that project before submitting anything new.

Track and download the scene

Poll the project, for example every 30–60 seconds:

curl "$MOONLAKE_API_BASE_URL/scenes/PROJECT_ID" \
	--header "Authorization: Bearer $MOONLAKE_API_KEY"

Use status to determine the outcome and phase for progress display. A downloadable scene result is partially_completed: the scene is available, and optional item lifts remain possible. You do not need to request a lift to download the scene.

Read result.artifacts for the scene and item downloads. The published formats are Blender, GLB, USDZ, and ZIP bundles. The initial result represents appearance and geometry reconstruction; it does not certify physics or articulation. Review the output against your intended use and references.

Quote and lift selected items

Retrieve the catalog with GET /api/v1/scenes/PROJECT_ID/items. Select the returned item_id values and give each item its own enhancement prompt. The default lift mode returns an itemized quote without starting generation:

{
	"mode": "quote",
	"items": [
		{
			"item_id": "tabletop/pill_organizer",
			"prompt": "Complete this pill organizer for simulation, with independently opening lids and appropriate joint limits and collision geometry."
		}
	]
}

Send this body to POST /api/v1/scenes/PROJECT_ID/lift. Replace the example item ID with one from your catalog. To proceed, send mode: "generate" and a new Idempotency-Key. Generation evaluates the price again; a quote is not a price lock. Accepted lift prices appear in the project’s pricing field.

Continue polling the same project. You can request lifts for different items while other lifts are in progress. Wait until an active item finishes before requesting another lift for that item. Completed lifts become available in a new scene version. Earlier versions remain downloadable through the version endpoints.