Gizmo API Reference

Programmatic access to AI-powered 3D simulation authoring. Generate physics-ready scenes and articulated assets from natural language — export to USD (Isaac Sim) and MJCF (MuJoCo).

Base URLhttps://api.gizmo.antimlabs.com

Quickstart5 min

Generate your first 3D scene in four steps — from API key to physics-ready geometry.

Create an API key

Go to Settings → API Keys and create a key. Copy the gzm_k1_... token.

Generate a scene

curl -X POST "https://api.gizmo.antimlabs.com/v1/scenes" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A modern robotics lab with two workbenches"}'

Returns 202 with a job_id — generation runs asynchronously (2-5 min).

Poll for completion

curl "https://api.gizmo.antimlabs.com/v1/jobs/job_a1b2c3d4" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY"

# → {"ok": true, "job": {"status": "succeeded", ...}}

Or stream real-time progress via GET /v1/jobs/{id}/events (SSE).

Retrieve the result

curl "https://api.gizmo.antimlabs.com/v1/scenes/jh72k3m4n5p6q7r8?include_graph=true" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY"

# → Full scene with 3D geometry, joints, materials, physics

The scene graph contains everything needed for USD/MJCF export.

Single asset generation

Need just one 3D asset instead of a full scene? Use the asset endpoint (30-90s):

curl -X POST "https://api.gizmo.antimlabs.com/v1/assets" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A 6-DOF robotic arm with gripper end-effector", "asset_pipeline": "cad"}'

Authentication

All API requests require a Bearer token. Create keys in Settings → API Keys.

Authorization: Bearer gzm_k1_a1b2c3d4e5f6...

Rate Limiting

Per-key sliding window. Headers on every response:

X-RateLimit-Limit

Requests/min allowed

X-RateLimit-Remaining

Requests left

X-RateLimit-Reset

Window reset (unix)

Errors

All errors return a consistent JSON structure:

{"error": {"code": "scene_not_found", "message": "Scene not found", "status": 404}}

401invalid_api_key

404*_not_found

429rate_limit_exceeded

503*_not_configured

Async Generation

POST endpoints return 202 with a job_id. Then:

1. POST /v1/scenes → get job_id

2. GET /v1/jobs/{id} → poll status

3. GET /v1/jobs/{id}/events → SSE stream

Scenes(7 endpoints)

GET/v1/scenes

List scenes

Retrieve all scenes belonging to the authenticated user, ordered by creation date (newest first).

{
  "ok": true,
  "scenes": [
    {
      "id": "jh72k3m4n5p6q7r8",
      "name": "Robot Kitchen Environment",
      "pipeline_status": "completed",
      "pipeline_prompt": "A modern kitchen with island",
      "created_at": 1717800000000,
      "updated_at": 1717800060000
    }
  ]
}

GET/v1/scenes/{scene_id}

Get scene detail

Retrieve a single scene by ID, optionally including the full scene graph (3D geometry, joints, materials) from S3.

Query Parameters

include_graphbooleanInclude the full scene graph JSON from S3

{
  "ok": true,
  "scene": {
    "id": "jh72k3m4n5p6q7r8",
    "name": "Robot Kitchen",
    "pipeline_status": "completed",
    "pipeline_stages": [...],
    "duration_ms": 145000,
    "scene_graph": { ... }
  }
}

POST/v1/scenes202

Generate a scene

Start async scene generation from a text prompt. Returns immediately with a job_id. Poll progress via GET /v1/jobs/{job_id} or stream real-time events via GET /v1/jobs/{job_id}/events. Typical generation: 2-5 minutes.

Request Body

promptstringrequiredNatural language description of the scene

modelstringOverride the default LLM model

asset_pipeline"auto" | "gizmo" | "cad"Geometry pipeline (default: auto)

reference_image_urlsstring[]Up to 3 http(s) image URLs — a room photo grounds the structure build

persistbooleanSave to library (default: true)

{
  "ok": true,
  "scene_id": "jh72k3m4n5p6q7r8",
  "job_id": "job_a1b2c3d4",
  "status": "queued"
}

PATCH/v1/scenes/{scene_id}

Update scene metadata

Update a scene's name or description. Does not trigger regeneration.

Request Body

namestringNew scene name

descriptionstringNew description

{ "ok": true, "scene_id": "jh72k3m4n5p6q7r8" }

DELETE/v1/scenes/{scene_id}

Delete scene

Permanently delete a scene and its associated data.

{ "ok": true, "deleted": "jh72k3m4n5p6q7r8" }

POST/v1/scenes/{scene_id}/edit202

Edit a scene

Apply a natural language edit to an existing scene. Returns a job_id — poll or stream for progress.

Request Body

promptstringrequiredEdit instruction

modelstringOverride the default LLM model

{
  "ok": true,
  "scene_id": "jh72k3m4n5p6q7r8",
  "job_id": "job_e5f6g7h8",
  "status": "queued"
}

GET/v1/scenes/{scene_id}/status

Scene pipeline status

Get detailed pipeline execution status — stages completed, errors, timing.

{
  "ok": true,
  "scene_id": "jh72k3m4n5p6q7r8",
  "pipeline_status": "running",
  "pipeline_stages": [
    { "name": "asset_generation", "status": "complete" },
    { "name": "floorplan", "status": "running" }
  ],
  "duration_ms": 45000
}

Assets(4 endpoints)

GET/v1/assets

List assets

Retrieve all assets belonging to the authenticated user. Optionally filter by scene.

Query Parameters

scene_idstringFilter by scene ID

{
  "ok": true,
  "assets": [
    {
      "id": "ast_x9y8z7w6",
      "name": "Articulated Drawer Unit",
      "status": "completed",
      "scene_id": "jh72k3m4n5p6q7r8",
      "prompt": "A wooden 3-drawer filing cabinet"
    }
  ]
}

GET/v1/assets/{asset_id}

Get asset detail

Retrieve a single asset by ID. Use include_record=true to get geometry, joints, and materials.

Query Parameters

include_recordbooleanInclude the full asset record from S3

{
  "ok": true,
  "asset": {
    "id": "ast_x9y8z7w6",
    "name": "Articulated Drawer Unit",
    "status": "completed",
    "record": { "primitives": [...], "joints": [...] }
  }
}

POST/v1/assets202

Generate an asset

Generate a single 3D asset from a text prompt. Includes geometry, joints, materials, and physics. Returns a job_id. Typical: 30-90 seconds.

Request Body

promptstringrequiredNatural language description

scene_idstringTarget scene (auto-created if omitted)

asset_pipeline"auto" | "gizmo" | "cad"Geometry pipeline

reference_image_urlsstring[]Up to 3 http(s) image URLs grounding geometry/texture. Build method (prim-based ~20 min vs mesh scan ~3 min) is picked automatically per prompt

{
  "ok": true,
  "scene_id": "jh72k3m4n5p6q7r8",
  "job_id": "job_x9y8z7w6",
  "status": "queued"
}

DELETE/v1/assets/{asset_id}

Delete asset

Permanently delete an asset.

{ "ok": true, "deleted": "ast_x9y8z7w6" }

Jobs(3 endpoints)

GET/v1/jobs/{job_id}

Get job status

Poll the current status of a generation job. Status values: queued → running → succeeded | failed | cancelled.

Query Parameters

include_resultbooleanInclude the full result payload once complete

{
  "ok": true,
  "job": {
    "id": "job_a1b2c3d4",
    "status": "running",
    "mode": "scene",
    "scene_id": "jh72k3m4n5p6q7r8",
    "created_at": 1717800000,
    "started_at": 1717800001,
    "completed_at": null
  },
  "result": null
}

GET/v1/jobs/{job_id}/events

Job event stream (SSE)

Real-time Server-Sent Events stream. Events include stage transitions, asset completion, errors. Closes when job completes. Use 'after' param to resume.

Query Parameters

afterintegerResume from sequence number (for reconnection)

event: stage_start
data: {"stage": "asset_generation", "sequence": 1}

event: stage_complete
data: {"stage": "asset_generation", "sequence": 5}

event: done
data: {"ok": true, "status": "succeeded", "job_id": "job_a1b2c3d4"}

POST/v1/jobs/{job_id}/cancel

Cancel a job

Request cancellation of a running job. No-op if already completed.

{ "ok": true, "cancelled": true, "job_id": "job_a1b2c3d4" }

Catalog(3 endpoints)

GET/v1/catalog

Browse premade catalog

Search and browse the premade asset library. Supports full-text search, category filtering, and pagination.

Query Parameters

searchstringSearch term

categorystringFilter by category

limitintegerResults per page (1-200, default 50)

offsetintegerPagination offset

{
  "ok": true,
  "items": [
    {
      "slug": "modern-office-chair",
      "name": "Modern Office Chair",
      "category": "furniture",
      "tags": ["chair", "office", "swivel"],
      "mesh_count": 12,
      "extent_m": 0.85
    }
  ],
  "total": 3071,
  "offset": 0,
  "limit": 50
}

GET/v1/catalog/categories

Catalog categories

Get all available categories in the premade catalog.

{
  "ok": true,
  "categories": ["appliances", "electronics", "furniture", "industrial", "lighting", "storage"]
}

GET/v1/catalog/{slug}

Catalog item detail

Get full details including GLB/USDZ download paths.

{
  "ok": true,
  "item": {
    "slug": "modern-office-chair",
    "name": "Modern Office Chair",
    "category": "furniture",
    "tags": ["chair", "office", "swivel"],
    "mesh_count": 12,
    "extent_m": 0.85,
    "glb_path": "premade/furniture/modern-office-chair.glb",
    "usdz_path": "premade/furniture/modern-office-chair.usdz"
  }
}

Account(2 endpoints)

GET/v1/whoami

Current user info

Verify your API key and check scopes.

{
  "ok": true,
  "user": {
    "kind": "api_key",
    "storage_user_id": "user_abc123",
    "convex_user_id": "jh72k3m4n5p6q7r8",
    "email": "dev@example.com",
    "name": "Jane Developer",
    "scopes": ["generate:asset", "generate:scene", "read:scenes"]
  }
}

GET/v1/usage

API key usage stats

Request counts, last used timestamps, and rate limit info for all your keys.

{
  "ok": true,
  "total_requests": 1847,
  "keys": [
    {
      "id": "key_abc123",
      "name": "Production Key",
      "status": "active",
      "request_count": 1502,
      "last_used_at": 1717800000000,
      "rate_limit_rpm": 100
    }
  ]
}

Gizmo API Reference

Quickstart5 min

Create an API key

Generate a scene

Poll for completion

Retrieve the result

Single asset generation

Authentication

Rate Limiting

Errors

Async Generation

Scenes(7 endpoints)

List scenes

Get scene detail

Query Parameters

Generate a scene

Request Body

Update scene metadata

Request Body

Delete scene

Edit a scene

Request Body

Scene pipeline status

Assets(4 endpoints)

List assets

Query Parameters

Get asset detail

Query Parameters

Generate an asset

Request Body

Delete asset

Jobs(3 endpoints)

Get job status

Query Parameters

Job event stream (SSE)

Query Parameters

Cancel a job

Catalog(3 endpoints)

Browse premade catalog

Query Parameters

Catalog categories

Catalog item detail

Account(2 endpoints)

Current user info

API key usage stats

GIZMO