Digital twins: rebuild a robot episode as a MuJoCo scene

A twin is one episode of a robotics dataset rebuilt as an interactable simulation. Kite reconstructs the room from the episode’s camera, builds the objects the robot handles with their real size and physics, checks every stage by measurement, and delivers the scene as a single archive you open in MuJoCo.

Private beta. Twins are enabled per account. A call from an account that isn’t enabled returns 403 with code twins_not_enabled. Ask your Kite contact to turn them on.

You give Kite one thing: the dataset. A twin takes about 100 minutes, so the API is asynchronous — create it, then poll it or get a webhook when it’s done.

Check a dataset first

POST /v1/twins/validate runs every check a create runs — the dataset exists and has camera video, which camera will seed the room — and tells you how long a twin typically takes. It creates nothing and costs nothing.

curl https://api.kiteml.com/v1/twins/validate \
  -H "Authorization: Bearer $KITE_API_KEY" \
  -H "Kite-Version: 2026-09-27" \
  -H "Content-Type: application/json" \
  -d '{"source": {"type": "huggingface", "repo_id": "lerobot/svla_so101_pickplace"}}'

{
  "object": "twin_validation",
  "ok": true,
  "source": { "type": "huggingface", "repo_id": "lerobot/svla_so101_pickplace" },
  "cameras": ["observation.images.side", "observation.images.up"],
  "scene_camera": "observation.images.side",
  "wrist_camera": null,
  "episodes": 50,
  "fps": 30,
  "format": "v3.0",
  "estimate": { "duration_s": 5910 }
}

If something is wrong, the error names it and the field to fix. For example, a camera that doesn’t exist lists the ones that do:

{
  "error": {
    "type": "invalid_request_error",
    "code": "camera_not_found",
    "message": "no camera matches 'top'",
    "param": "camera",
    "details": { "cameras": ["observation.images.side", "observation.images.up"] }
  }
}

Create a twin

curl https://api.kiteml.com/v1/twins \
  -H "Authorization: Bearer $KITE_API_KEY" \
  -H "Kite-Version: 2026-09-27" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"source": {"type": "huggingface", "repo_id": "lerobot/svla_so101_pickplace"}}'

The response is the twin, queued, with 202 Accepted:

{
  "id": "twin_01M3GKYV1Z7A0YV4851EGGQYPP",
  "object": "twin",
  "status": "queued",
  "progress": 0.0,
  "source": { "type": "huggingface", "repo_id": "lerobot/svla_so101_pickplace" },
  "camera": { "scene": "observation.images.side", "wrist": null, "available": ["observation.images.side", "observation.images.up"] },
  "download": null,
  "created_at": "2026-09-27T05:03:45.347344Z"
}

The dataset is checked before anything starts, so a twin that can’t work is refused at create, for free, with the same errors as validate.

Request body

Field	Type	Description
`source`	object	Required. `{"type": "huggingface", "repo_id": "..."}` — the same shape as an augmentation’s source. A `huggingface.co` URL works as `repo_id` too.
`name`	string	A short name for the twin.
`task`	string	Which objects to build: the ones the robot handles. Defaults to a general manipulation brief.
`prompt`	string	How to describe the room to the reconstructor.
`camera`	string	A substring of the camera that should seed the room. Validate lists the choices.
`wrist_camera`	string	A substring of the wrist camera to use for close-ups.
`ceiling_m`	number	Floor-to-ceiling height of the real room — the scale anchor. Default `2.9`.
`webhook_metadata`	object	Echoed on the twin and on its webhook events.

Idempotency

Send an Idempotency-Key header with every create. A retry with the same key and body returns the same twin — even while the first request is still being processed — so a dropped connection never builds two twins. Reusing a key with a different body returns 409 idempotency_key_reused. One twin builds at a time per account; a second create returns 429 concurrency_limit_exceeded with a Retry-After header.

Track progress

Retrieve the twin with GET /v1/twins/:id. Poll every 30 seconds or so, or register a webhook for twin.completed, twin.failed, and twin.canceled and skip polling.

{
  "id": "twin_01M3GKYV1Z7A0YV4851EGGQYPP",
  "object": "twin",
  "status": "processing",
  "stage": "decompose",
  "progress": 0.281,
  "eta_seconds": 4250,
  "status_message": "decompose: 7 min in, typically 17 min",
  "stages": [
    { "stage": "ingest", "ok": true, "attempts": 1, "seconds": 12.2, "measurement": "10 probe frames, keyframe t002.png, 0 wrist frames" },
    { "stage": "environment", "ok": true, "attempts": 1, "seconds": 423.7, "measurement": "completed panorama 4608x2304, aspect 2.00" }
  ]
}

A twin moves through queued → processing → succeeded. failed and canceled are the other final states, and canceling sits between a cancel and the build actually stopping. Each finished stage reports what it measured about its own output — ingest, environment, decompose, label, author, refine, assemble, dynamics, and publish.

Download the scene

Once the twin has succeeded, download describes the whole scene as one .tar.gz:

"download": {
  "url": "https://storage.googleapis.com/…/twin_01M3GKYV1Z7A0YV4851EGGQYPP.tar.gz?X-Goog-Algorithm=GOOG4-RSA-SHA256&…",
  "requires_auth": false,
  "expires_at": "2026-09-27T18:17:29Z",
  "filename": "twin_01M3GKYV1Z7A0YV4851EGGQYPP.tar.gz",
  "bytes": 126249063,
  "sha256": "6a6f2debbbf17cbd…",
  "scene": "twin_01M3GKYV1Z7A0YV4851EGGQYPP/scene.xml"
}

url is a signed link straight to the archive. Fetch it without your API key, check the checksum, and extract:

curl -fL "$DOWNLOAD_URL" -o twin.tar.gz
shasum -a 256 twin.tar.gz          # compare with download.sha256
tar xzf twin.tar.gz                # twin_01M3GKYV…/scene.xml and assets/

The folder holds scene.xml — load it with mujoco.MjModel.from_xml_path(...) — and assets/: meshes, textures, and the room as a Gaussian splat. The link expires after an hour; retrieve the twin again for a fresh one. GET /v1/twins/:id/archive does the same in one call: it redirects to a fresh link (curl -L). To see what’s in the archive without downloading it, list its files:

curl "https://api.kiteml.com/v1/twins/twin_01M3GKYV1Z7A0YV4851EGGQYPP/files?limit=2" \
  -H "Authorization: Bearer $KITE_API_KEY"

{
  "object": "list",
  "data": [
    { "object": "twin_file", "path": "assets/background.obj", "bytes": 39594932, "sha256": "03129cb58e32…" },
    { "object": "twin_file", "path": "assets/background_h.obj", "bytes": 72696, "sha256": "ba50d1736800…" }
  ],
  "has_more": true,
  "next_cursor": "assets/background_h.obj"
}

Without writing HTTP

The Kite CLI and Python SDK wrap the whole flow — create, wait, download, verify, and extract:

kite twin create lerobot/svla_so101_pickplace --wait --out ./twins

from kite_sdk import Kite

twin = Kite().twins.create("lerobot/svla_so101_pickplace")
path = twin.wait(on_update=print).download()     # absolute path to <twin id>/scene.xml

Both put twins in the folder you give, else in $KITE_TWINS_DIR, else in ./twins, and report absolute paths. Agents get the same flow as the MCP tools kite_twin_validate, kite_twin_create, and kite_twin_status, whose next field is the exact download command.

Cancel and resume

POST /v1/twins/:id/cancel stops a twin that’s building. It’s canceling for a few seconds, until the build has stopped, then canceled. A failed twin whose error.resumable is true, or a canceled twin, can continue with POST /v1/twins/:id/resume. Every stage it finished is kept, so only the rest runs again.

Errors

Status	Code	Meaning
`400`	`dataset_not_found`	The dataset doesn’t exist, or isn’t public
`400`	`dataset_gated`	The dataset is gated — accept its terms on Hugging Face, or use a public dataset
`400`	`dataset_has_no_video`	The dataset has no camera video to rebuild the room from
`400`	`camera_not_found`	No camera matches `camera`; `details.cameras` lists the real ones
`400`	`no_suitable_camera`	Every camera is a wrist camera; the room needs one that sees the scene
`403`	`twins_not_enabled`	Twins aren’t enabled for this account yet
`409`	`twin_not_ready`	Files or the archive requested before the twin succeeded
`409`	`not_cancelable` / `already_running`	Cancel on a finished twin, or resume on one still building
`429`	`concurrency_limit_exceeded`	A twin is already building on this account — honor `Retry-After`
`429`	`capacity_exceeded`	Kite’s builders are full — honor `Retry-After`

A twin that stops part-way reports status: "failed" with error.code of interrupted, or stage_failed when a stage’s own check didn’t pass. Both are resumable.

The twin object

Field	Type	Description
`id`	string	`twin_` followed by a time-ordered id
`status`	string	`queued`, `processing`, `canceling`, `succeeded`, `failed`, or `canceled`
`progress`	number	`0` to `1`, estimated within the running stage
`stage`	string or null	The stage running now
`eta_seconds`	integer or null	While building: time left, from the stages’ typical durations
`error`	object or null	When `failed`: `code`, `message`, `stage`, `resumable`
`source`	object	The dataset the episode came from
`camera`	object or null	The camera that seeds the room, and every camera the dataset has
`config`	object	The build options you gave at create
`stages`	array	Every finished stage: `stage`, `ok`, `attempts`, `seconds`, `measurement`
`download`	object or null	Once `succeeded`: `url`, `requires_auth`, `expires_at`, `filename`, `bytes`, `sha256`, `scene`
`webhook_metadata`	object or null	Whatever you passed at create
`created_at`	string	ISO 8601, UTC

Get started

Platform API

Digital twins: rebuild a robot episode as a MuJoCo scene

Check a dataset first

Create a twin

Request body

Idempotency

Track progress

Download the scene

Without writing HTTP

Cancel and resume

Errors

The twin object

​Check a dataset first

​Create a twin

​Request body

​Idempotency

​Track progress

​Download the scene

​Without writing HTTP

​Cancel and resume

​Errors

​The twin object

Check a dataset first

Create a twin

Request body

Idempotency

Track progress

Download the scene

Without writing HTTP

Cancel and resume

Errors

The twin object