API Access

The Gizmo API lets you generate articulated assets and complete scenes from text prompts, manage your library, browse the premade catalog, and export to USD, USDZ, MJCF, or SDF — all without the editor UI. Base URL: https://api.gizmo.antimlabs.com/v1

Authentication

All endpoints require an API key via the Authorization header:

Authorization: Bearer gzm_k1_YOUR_KEY

Create API keys in Settings → API Keys. Each key has configurable rate limits and scopes.

Quick Start

1. Verify your key

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

2. 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"}'

This returns 202 Accepted with a job_id — poll with GET /v1/jobs/{job_id} or stream real-time progress via SSE at GET /v1/jobs/{job_id}/events.

3. Export to a simulator

curl -X POST "https://api.gizmo.antimlabs.com/v1/scenes/{scene_id}/export" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "mjcf"}' \
  -o scene.zip

Endpoint Groups

Scenes

Method	Path	Description
`GET`	`/v1/scenes`	List all scenes
`GET`	`/v1/scenes/{id}`	Get scene detail (optionally with full scene graph)
`POST`	`/v1/scenes`	Generate a new scene from a prompt
`PATCH`	`/v1/scenes/{id}`	Update scene metadata (name, description)
`DELETE`	`/v1/scenes/{id}`	Delete a scene
`POST`	`/v1/scenes/{id}/edit`	Apply a natural language edit to a scene
`GET`	`/v1/scenes/{id}/status`	Get pipeline execution status
`POST`	`/v1/scenes/{id}/export`	Export to MJCF, USD, USDZ, or SDF (returns ZIP)

Assets

Method	Path	Description
`GET`	`/v1/assets`	List all assets (filter by scene)
`GET`	`/v1/assets/{id}`	Get asset detail (optionally with full record)
`POST`	`/v1/assets`	Generate a single asset from a prompt
`POST`	`/v1/assets/{id}/export`	Export a single asset to MJCF, USD, USDZ, or SDF (returns ZIP)
`DELETE`	`/v1/assets/{id}`	Delete an asset

POST /v1/assets attaches generated assets to a scene. If scene_id is omitted, the API tries to create or use a default scene. If it cannot, it returns 400 no_scene. To generate a standalone environment instead, use POST /v1/scenes.

Both POST /v1/scenes and POST /v1/assets accept an optional asset_pipeline field (auto, gizmo, or cad). auto picks the best pipeline for the prompt; gizmo uses editable parametric primitives; cad uses B-Rep solids via build123d for precision mechanical parts.

Jobs

Method	Path	Description
`GET`	`/v1/jobs/{id}`	Poll job status
`GET`	`/v1/jobs/{id}/events`	Stream real-time progress (SSE)
`POST`	`/v1/jobs/{id}/cancel`	Cancel a running job

Catalog

Method	Path	Description
`GET`	`/v1/catalog`	Search and browse premade assets
`GET`	`/v1/catalog/categories`	List all catalog categories
`GET`	`/v1/catalog/{slug}`	Get catalog item detail with download paths

Account

Method	Path	Description
`GET`	`/v1/whoami`	Verify API key and check scopes
`GET`	`/v1/usage`	Get usage stats for all your keys

Async Generation

Scene and asset generation is asynchronous. POST endpoints return 202 Accepted with a job_id. Use the Jobs endpoints to track progress:

Polling: GET /v1/jobs/{id} returns status (queued → running → succeeded | failed | cancelled)
Streaming: GET /v1/jobs/{id}/events provides real-time Server-Sent Events with stage transitions, asset completions, and errors

SSE Event Types

Event	Description
`stage_start`	A pipeline stage has begun
`stage_complete`	A pipeline stage has finished
`asset_ready`	An individual asset is complete
`error`	An error occurred
`ping`	Keep-alive (every 15s)
`done`	Job reached terminal state

Rate Limiting

Every response includes rate limit headers:

X-RateLimit-Limit — requests allowed per minute
X-RateLimit-Remaining — requests remaining in current window
X-RateLimit-Reset — Unix timestamp when the window resets

Error Format

All errors follow a consistent structure:

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

Common error codes: authentication_required (401), insufficient_credits (402), scene_not_found (404), rate_limit_exceeded (429).

OpenAPI Specification

The full OpenAPI 3.1 spec is available at:

GET https://api.gizmo.antimlabs.com/v1/openapi.json

Use it to generate client SDKs or import into tools like Postman.

Getting started

Concepts

API

Help

Authentication

Quick Start

1. Verify your key

2. Generate a scene

3. Export to a simulator

Endpoint Groups

Scenes

Assets

Jobs

Catalog

Account

Async Generation

SSE Event Types

Rate Limiting

Error Format

OpenAPI Specification

​Authentication

​Quick Start

​1. Verify your key

​2. Generate a scene

​3. Export to a simulator

​Endpoint Groups

​Scenes

​Assets

​Jobs

​Catalog

​Account

​Async Generation

​SSE Event Types

​Rate Limiting

​Error Format

​OpenAPI Specification

Authentication

Quick Start

1. Verify your key

2. Generate a scene

3. Export to a simulator

Endpoint Groups

Scenes

Assets

Jobs

Catalog

Account

Async Generation

SSE Event Types

Rate Limiting

Error Format

OpenAPI Specification