Skip to main content
A scene is a named simulation environment that aggregates one or more assets at defined positions and orientations. Use scenes to compose a full robot workcell, warehouse layout, or lab environment — then export the entire scene as a single file for your target simulator.
Early Access: The Scenes API is in alpha. Endpoint behaviour and response shapes may change. You will be notified of breaking changes at the email address associated with your API key.
Assets must have status: "ready" before they can be added to a scene. See the Assets API for generation and polling details.

​
Create a Scene

​
name
string
required
A human-readable name for the scene. Example: "Warehouse Workcell Alpha".
​
description
string
An optional description of the scene’s purpose or configuration.
curl --request POST \
  --url https://api.gizmo.antimlabs.com/v1/scenes \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Warehouse Workcell Alpha",
    "description": "Assembly cell with a 6-DOF arm and conveyor belt for pick-and-place testing."
  }'
POST /scenes — Response
​
id
string
Unique identifier for the scene. Use this in all subsequent scene operations.
​
name
string
The name provided at creation.
​
description
string
The description provided at creation, or null if omitted.
​
created_at
string
ISO 8601 timestamp of scene creation.
​
assets
array
Array of placed assets in the scene. Empty on creation.
Example Response
{
  "id": "scn_03kz1b5m4q0h9s",
  "name": "Warehouse Workcell Alpha",
  "description": "Assembly cell with a 6-DOF arm and conveyor belt for pick-and-place testing.",
  "created_at": "2024-11-12T10:15:00Z",
  "assets": []
}

​
Get Scene Details

Retrieve a scene and its full list of placed assets, including each asset’s position and rotation in the scene coordinate frame.

​
Path Parameters

​
id
string
required
The unique identifier of the scene.
curl --request GET \
  --url https://api.gizmo.antimlabs.com/v1/scenes/scn_03kz1b5m4q0h9s \
  --header "Authorization: Bearer YOUR_API_KEY"
GET /scenes/{id} — Response
​
id
string
Unique scene identifier.
​
name
string
Scene name.
​
description
string
Scene description.
​
assets
array
Array of placed-asset objects. Each entry includes:
Example Response
{
  "id": "scn_03kz1b5m4q0h9s",
  "name": "Warehouse Workcell Alpha",
  "description": "Assembly cell with a 6-DOF arm and conveyor belt for pick-and-place testing.",
  "assets": [
    {
      "asset_id": "ast_01hx9z3k2n8f7q",
      "name": "Industrial Arm v1",
      "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
      "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }
    }
  ]
}

​
List Scenes

Return a paginated list of all scenes associated with your API key.

​
Query Parameters

​
limit
integer
Maximum number of scenes to return. Defaults to 20. Maximum is 100.
​
offset
integer
Number of scenes to skip. Defaults to 0.
curl --request GET \
  --url "https://api.gizmo.antimlabs.com/v1/scenes?limit=10&offset=0" \
  --header "Authorization: Bearer YOUR_API_KEY"
GET /scenes — Response
​
scenes
array
Array of scene summary objects, each with id, name, description, and created_at.
​
total
integer
Total number of scenes in your account.
​
limit
integer
The limit applied to this response.
​
offset
integer
The offset applied to this response.
Example Response
{
  "scenes": [
    {
      "id": "scn_03kz1b5m4q0h9s",
      "name": "Warehouse Workcell Alpha",
      "description": "Assembly cell with a 6-DOF arm and conveyor belt for pick-and-place testing.",
      "created_at": "2024-11-12T10:15:00Z"
    },
    {
      "id": "scn_04lz2c6n5r1i0t",
      "name": "Lab Inspection Cell",
      "description": "Inspection station with a mounted camera arm and turntable.",
      "created_at": "2024-11-13T08:30:00Z"
    }
  ],
  "total": 2,
  "limit": 10,
  "offset": 0
}

​
Add an Asset to a Scene

Place a ready asset into a scene at a specified position and orientation. You can add the same asset multiple times at different poses (e.g. two identical gripper arms mounted on opposite sides of a workcell).

​
Path Parameters

​
id
string
required
The unique identifier of the scene.

​
Body Parameters

​
asset_id
string
required
The ID of the asset to add. The asset must have status: "ready".
​
position
object
Position of the asset in scene-space. Defaults to the origin {x: 0, y: 0, z: 0} if omitted.
​
rotation
object
Orientation of the asset expressed as a unit quaternion. Defaults to identity {x: 0, y: 0, z: 0, w: 1} (no rotation) if omitted.
curl --request POST \
  --url https://api.gizmo.antimlabs.com/v1/scenes/scn_03kz1b5m4q0h9s/assets \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "asset_id": "ast_01hx9z3k2n8f7q",
    "position": { "x": 1.2, "y": 0.0, "z": 0.75 },
    "rotation": { "x": 0.0, "y": 0.0, "z": 0.707, "w": 0.707 }
  }'
POST /scenes/{id}/assets — Response Returns the full updated scene object, including the newly placed asset appended to the assets array.
Example Response
{
  "id": "scn_03kz1b5m4q0h9s",
  "name": "Warehouse Workcell Alpha",
  "description": "Assembly cell with a 6-DOF arm and conveyor belt for pick-and-place testing.",
  "assets": [
    {
      "asset_id": "ast_01hx9z3k2n8f7q",
      "name": "Industrial Arm v1",
      "position": { "x": 1.2, "y": 0.0, "z": 0.75 },
      "rotation": { "x": 0.0, "y": 0.0, "z": 0.707, "w": 0.707 }
    }
  ]
}
Quaternion {x: 0, y: 0, z: 0.707, w: 0.707} represents a 90° rotation about the Z axis. Use a quaternion calculator or a library like scipy.spatial.transform.Rotation to compute the values you need.

​
Export a Scene

Export the entire scene — all placed assets combined — as a single simulator-ready file. This is the recommended way to load a complete environment into Isaac Sim or MuJoCo, as it preserves all relative transforms between assets.

​
Path Parameters

​
id
string
required
The unique identifier of the scene to export.

​
Body Parameters

​
format
string
required
The export format. Supported scene export formats:
ValueDescription
isaac_sim_usdUSD stage containing all scene assets, for NVIDIA Isaac Sim
mujoco_mjcfSingle MJCF XML file with all assets included as bodies, for MuJoCo
curl --request POST \
  --url https://api.gizmo.antimlabs.com/v1/scenes/scn_03kz1b5m4q0h9s/export \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "format": "isaac_sim_usd"
  }'
POST /scenes/{id}/export — Response
​
download_url
string
A pre-signed URL to download the exported scene file. Time-limited — download promptly.
​
expires_at
string
ISO 8601 timestamp indicating when the download_url expires.
Example Response
{
  "download_url": "https://cdn.gizmo.antimlabs.com/exports/scn_03kz1b5m4q0h9s/isaac_sim_usd/workcell_alpha.usd?token=eyJhbGc...",
  "expires_at": "2024-11-12T11:15:00Z"
}
Scene export bundles all constituent assets into a single file. Every asset in the scene must have status: "ready" — if any asset is still pending or processing, the export request will return a 400 Bad Request error.
Export URLs are time-limited (typically 1 hour). Download and store the file locally before the URL expires. Re-request the export if needed.