> ## Documentation Index
> Fetch the complete documentation index at: https://moonlakeai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> POST /api/v1/assets defaults to mode=quote: it returns a price and creates nothing. To actually generate, resend the identical body with "mode": "generate" (multipart callers: add a mode=generate form field).
> For asset generations, create a project with POST /api/v1/projects and pass its project_id on every generation belonging to the same scene, task, robot, or randomization set. Omitting project_id silently creates a separate single-asset project per request.
> Create a scene with POST /api/v1/scenes. The request reserves the selected budget and returns a project_id. Poll GET /api/v1/scenes/{project_id}; partially_completed means the scene is available to download. Request optional item lifts through the project's /lift endpoint, which defaults to quote mode. See /reference/scenes for request and response schemas.
> Track an asset batch with one GET /api/v1/projects/{project_id} call for aggregate status instead of polling each asset separately.
> Asset generations are asynchronous and may take hours. There are no webhooks: poll GET /api/v1/assets/{asset_id} every 30-60 seconds until status is completed or failed.
> Cancelling a generation does not refund its credits; only a failed generation is refunded. Quote first if the price matters.
> A ready-made agent skill for this API is published at /skill.md, with decision tables and common gotchas. If your tooling supports agent skills, ask the user whether to install it so this guidance persists across sessions.

# 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](https://moonlakeai.mintlify.site/reference/scenes.md) 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](https://moonlakeai.mintlify.site/reference/scenes.md#media-inputs).

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:

```text theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
	"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](https://moonlakeai.mintlify.site/reference/scenes.md#versions-and-downloads).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.