Asset API

The Gizmo public API supports assets only: generate individual 3D assets, manage your asset library, and download exports for your simulator. You only need job and asset IDs. To create or export a full scene, use the browser editor. Scene operations are not part of the public API. Base URL: https://api.gizmo.antimlabs.com/v1

Authentication

Create a key in Settings → API Keys and send it with every request:

Authorization: Bearer gzm_k1_YOUR_KEY

Generate and download an asset

1. Start generation

curl --fail-with-body -X POST "https://api.gizmo.antimlabs.com/v1/assets" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A wooden cabinet with three sliding drawers"}'

The response is 202 Accepted. Save the job_id. Example fields:

{
  "ok": true,
  "job_id": "job_x9y8z7w6",
  "status": "queued",
  "estimated_seconds": 1050,
  "estimate_note": "Approximate duration; actual generation time varies with the request and service load."
}

Input	Type	Description
`prompt`	string, required	Describe the asset, dimensions, appearance, and any moving parts. Must not be empty.
`reference_image_urls`	string[], optional	Up to 8 publicly accessible HTTP(S) image URLs. Existing URL requests remain supported.
`reference_images`	object[], optional	Uploaded `image_id` or public `url`, plus an optional `view`. Maximum 8 images across both reference fields.
`reference_intent`	object, optional	Reconstruction intent and original user constraints. Input images remain authoritative by default.
`persist`	boolean, optional	Defaults to `true`. Keep it enabled to retrieve and export the saved asset later. If `false`, use the job result; a saved export is not guaranteed.

For generation from a reference image:

{
  "prompt": "Recreate this cabinet, including the three sliding drawers",
  "reference_image_urls": ["https://example.com/cabinet.jpg"]
}

Replace the example URL with a publicly accessible image. Generation time varies; estimated_seconds is advisory, not a deadline.

Upload local files and supply multiple views

Upload local files as multipart/form-data; you do not need to host images yourself. Use the repeated field name files. Let your HTTP client set the multipart boundary (do not manually set a JSON Content-Type for this request).

curl --fail-with-body "https://api.gizmo.antimlabs.com/v1/images" \
  -H "Authorization: Bearer $GIZMO_API_KEY" \
  -F "files=@./front.jpg" \
  -F "files=@./back.png"

The 201 Created response contains images in upload order. Each item has id, content_type, size_bytes, width, height, and sha256. Save the returned IDs:

{
  "prompt": "Recreate this object with working moving parts",
  "reference_images": [
    {"image_id": "IMAGE_ID_FROM_UPLOAD_1", "view": "front"},
    {"image_id": "IMAGE_ID_FROM_UPLOAD_2", "view": "back"},
    {"url": "https://example.com/object-top.jpg", "view": "top"}
  ]
}

Send that JSON to POST /v1/assets. Replace the placeholder IDs with real upload IDs. Each reference has exactly one of image_id or url. Accepted view labels are front, back, left, right, top, bottom, perspective, and detail. Labels are optional user descriptions, not calibrated camera poses. You can supply several details or perspectives. With both reference fields present, legacy reference_image_urls come first, followed by reference_images in order. Limits: 8 files per upload; 8 references per generation; 20 MiB and 40 million pixels per file; 80 MiB of file content per upload batch. Supported formats are non-animated PNG, JPEG, and WebP. Invalid files are rejected before the batch is stored. Original bytes are retained without a mandatory crop or concept redraw; model-specific resized copies can be derived separately. Uploads with identical bytes reuse the same ID within your account. Image IDs are private and cannot be used by another account. Uploads currently remain stored without automatic expiry. GET /v1/images/{id} reads metadata. GET /v1/images/{id}/content downloads the exact original bytes. Queued jobs resolve fresh access URLs when they run, so an upload ID does not expire while a job is waiting. External URLs must remain accessible when the worker runs; use uploads if you need a durable reference. Multiple supplied images use the Blender authoring path because the static mesh backend accepts only a single image. All original views and labels are retained. reference_intent.requested_views is a separate advanced option for generated hypotheses; it is not how you attach observed views and is empty by default.

Retry generation safely

Give each intended generation a unique Idempotency-Key (1–128 ASCII letters, digits, dots, underscores, colons or hyphens):

curl --fail-with-body "https://api.gizmo.antimlabs.com/v1/assets" \
  -H "Authorization: Bearer $GIZMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cabinet-order-2026-001" \
  -d '{"prompt":"A wooden cabinet with three sliding drawers"}'

Retry a lost response with the same key and same JSON body. Once accepted, retries return the original job, with Idempotency-Replayed: true. A different body with the same key returns 409 idempotency_key_reused. Concurrent or interrupted acceptance returns 409 request_in_progress with Retry-After: 5; retry the same key. If that persists, contact support with X-Request-ID rather than creating a new key and risking a duplicate job. Keys are scoped to your account and API deployment, and currently retained without automatic expiry. Recorded 4xx responses are replayed too; after correcting such a request, use a new key. Requests without a key create a new job each time. The 202 response includes Location: /v1/jobs/{id} and Retry-After: 30.

2. Wait for the result

curl --fail-with-body "https://api.gizmo.antimlabs.com/v1/jobs/job_x9y8z7w6?include_result=true" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY"

Poll every 30–60 seconds until job.status is succeeded, failed, or cancelled. While the job is queued or running, result is null. On success, the result includes the generated asset:

{
  "ok": true,
  "job": {
    "id": "job_x9y8z7w6",
    "status": "succeeded",
    "mode": "asset",
    "error": null
  },
  "result": {
    "asset": {
      "id": "ASSET_ID",
      "name": "Drawer Cabinet"
    }
  }
}

These examples show the fields needed for this workflow; responses can include additional metadata. Use result.asset.id as the asset ID. Job timestamps are Unix milliseconds. If the job fails, inspect job.error; do not attempt an export until generation succeeds.

3. Download the export

curl --fail-with-body -X POST \
  "https://api.gizmo.antimlabs.com/v1/assets/ASSET_ID/export?format=mjcf" \
  -H "Authorization: Bearer gzm_k1_YOUR_KEY" \
  -o asset.zip

Replace ASSET_ID with result.asset.id. The required format is a query parameter. There is no request body. The response contains the file bytes, not JSON or a download URL.

Format	Download	Content type
`mjcf`	`.zip`	`application/zip`
`usd`	`.zip`	`application/zip`
`usdz`	`.usdz`	`model/vnd.usdz+zip`
`sdf`	`.zip`	`application/zip`

Use -o asset.usdz when requesting format=usdz. Content-Disposition supplies a suggested filename. X-Export-File-Count and X-Export-Warnings provide export metadata. GLB export is available in the editor.

Endpoints

Method	Path	Output
`POST`	`/v1/images`	`201` with private image IDs and metadata
`GET`	`/v1/images/{id}`	Image metadata
`GET`	`/v1/images/{id}/content`	Original image bytes
`POST`	`/v1/assets`	`202` with a generation `job_id`
`GET`	`/v1/assets`	A page of your asset library in `assets`, with `has_more` and `next_cursor`
`GET`	`/v1/assets/{id}`	Asset metadata in `asset`; add `?include_record=true` for the full record
`POST`	`/v1/assets/{id}/export?format=mjcf`	Binary export file
`DELETE`	`/v1/assets/{id}`	`{ "ok": true, "deleted": "id" }`
`GET`	`/v1/jobs/{id}`	Job status; add `?include_result=true` for the completed result
`GET`	`/v1/jobs/{id}/events`	Server-Sent Events
`POST`	`/v1/jobs/{id}/cancel`	Cancellation outcome in `cancelled`
`GET`	`/v1/catalog`	Premade asset catalog; supports `search`, `category`, `limit`, and `offset`
`GET`	`/v1/catalog/categories`	Category names in `categories`
`GET`	`/v1/catalog/{slug}`	Catalog item detail in `item`
`GET`	`/v1/whoami`	Identity and scopes in `user`
`GET`	`/v1/usage`	Per-key usage in `keys` and `total_requests`

Browse your library

GET /v1/assets?limit=20 returns assets newest first. limit defaults to 20 and accepts 1–100. Large records can produce a shorter page. When has_more is true, send the returned next_cursor as the next request’s cursor query parameter. Continue until has_more is false; an empty page alone does not mean you reached the end.

Completion notifications

Generation continues on the server when your client disconnects. Save the job_id to check the result later; you do not need to keep sending requests to keep generation running. Choose either polling every 30–60 seconds or one SSE connection for progress and completion. The API does not provide webhooks or a guaranteed completion email. Any account email notifications are supplementary; use the job status or SSE done event to drive your integration.

Streaming progress

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

Progress events include a sequence number. Reconnect with ?after=LAST_SEQUENCE to receive later events. Progress event types can vary; ignore types your client does not recognize. ping is a keepalive. done includes the terminal status and job_id, and closes the stream. Fetch the job with include_result=true to retrieve the asset after success.

Errors and limits

Check the HTTP status before reading JSON or saving export bytes. Errors on documented public endpoints use this shape:

{
  "detail": {
    "error": {
      "code": "asset_not_found",
      "message": "Asset ASSET_ID not found",
      "status": 404
    }
  }
}

Request validation errors return 422 with detail.error.code: "validation_error" and an additional fields array inside detail.error, identifying field locations and messages. Responses include an X-Request-ID for support. Errors from an upstream proxy may have a different body; always check HTTP status first.

Status	Meaning
`401`	Missing, invalid, or revoked API key
`402`	Insufficient generation credits
`404`	Asset, job, or image not found for your account
`409`	Conflicting request or idempotency key; inspect the error code
`413`	Image or upload batch exceeds its size limit
`415`	Unsupported or invalid image content
`422`	Invalid prompt, image URL, export format, or another request field
`429`	Rate limit exceeded; retry after the supplied reset time
`500` / `503`	Generation setup, export, or service failure

Rate-limited API-key responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds). Honor Retry-After on 429 and use exponential backoff with jitter for transient failures. Retry generation with its original idempotency key. Generation uses your account’s credits. See the OpenAPI specification for request schemas and the interactive reference to try requests.

Reference fidelity

Uploaded product photos are preserved for reconstruction by default. For an object inside a scene, the planner keeps the selected original photos and binds them to that object’s name. It does not generate a replacement product shot first. The optional reference_intent request field selects reconstruct, extract, modify, or design. Use modify for requested changes to the pictured object, or design when asking for a new design inspired by the inputs. Your prompt remains the user instruction. Additional generated views are optional hypotheses, not measurements of unseen surfaces.

Python: local files and URL references

import os
import uuid
import httpx

with httpx.Client(
    base_url="https://api.gizmo.antimlabs.com/v1/",
    headers={"Authorization": f"Bearer {os.environ['GIZMO_API_KEY']}"},
    timeout=120,
) as client:
    with open("front.jpg", "rb") as front, open("back.png", "rb") as back:
        upload = client.post("images", files=[
            ("files", ("front.jpg", front, "image/jpeg")),
            ("files", ("back.png", back, "image/png")),
        ])
    upload.raise_for_status()
    images = upload.json()["images"]
    # Save the key before sending; reuse it if this POST needs to be retried.
    key = str(uuid.uuid4())
    response = client.post("assets", headers={"Idempotency-Key": key}, json={
        "prompt": "Recreate this object with working joints",
        "reference_images": [
            {"image_id": images[0]["id"], "view": "front"},
            {"image_id": images[1]["id"], "view": "back"},
            {"url": "https://example.com/object-top.jpg", "view": "top"},
        ],
    })
    response.raise_for_status()
    print(response.json()["job_id"])

For URL-only generation, omit the upload and use reference_image_urls or reference_images: [{"url": "https://your-host/your-image.jpg", "view": "front"}]. Replace all example URLs with accessible images. API keys belong on your server, not in browser bundles. SSE responses include event IDs; resume using Last-Event-ID or ?after=SEQUENCE. Polling and SSE are supported; webhook delivery is not currently implemented. Reference URLs must serve image bytes directly. Redirect responses are not followed; use the final image URL or upload the local file with POST /v1/images.

Getting started

Concepts

API

Help

Authentication

Generate and download an asset

1. Start generation

Upload local files and supply multiple views

Retry generation safely

2. Wait for the result

3. Download the export

Endpoints

Browse your library

Completion notifications

Streaming progress

Errors and limits

Reference fidelity

Python: local files and URL references

​Authentication

​Generate and download an asset

​1. Start generation

​Upload local files and supply multiple views

​Retry generation safely

​2. Wait for the result

​3. Download the export

​Endpoints

​Browse your library

​Completion notifications

​Streaming progress

​Errors and limits

​Reference fidelity

​Python: local files and URL references

Authentication

Generate and download an asset

1. Start generation

Upload local files and supply multiple views

Retry generation safely

2. Wait for the result

3. Download the export

Endpoints

Browse your library

Completion notifications

Streaming progress

Errors and limits

Reference fidelity

Python: local files and URL references