Reconstruct a complete scene

Scene reconstruction uses a Team key and a scene-enabled Team execution release. Personal keys are not supported. An unsupported release returns 409 scene_reconstruction_unavailable before generation starts. The fixed-price scene API is available for Antim and PI production Teams. Use a production Team key with the production base URL below. The Scenes API reference lists request fields and response schemas.

export GIZMO_API_BASE="https://api.gizmo.antimlabs.com"
# Set GIZMO_API_KEY securely in your server environment.

Submit with references directly

Send the prompt and reference in one POST /v1/scenes request. No separate image-upload call is required. For a remote image, use "reference_images": [{"url": "https://example.com/workbench.jpg"}]. For a local image, attach a base64 data URL in data_url:

import base64
import os
import uuid
from pathlib import Path
import requests

base = os.environ["GIZMO_API_BASE"]
headers = {"Authorization": "Bearer " + os.environ["GIZMO_API_KEY"],
           "Idempotency-Key": str(uuid.uuid4())}
body = {
    "prompt": "Reconstruct this wooden workbench as one asset, with a plain floor and wall.",
    "reference_images": [{"data_url": "data:image/jpeg;base64," +
        base64.b64encode(Path("workbench.jpg").read_bytes()).decode()}],
    "max_asset_definitions": 1,
    "max_instances": 1,
    "max_cost_cents": 1300,
}
# Persist headers["Idempotency-Key"] and body before sending, for safe retries.
response = requests.post(base + "/v1/scenes", headers=headers, json=body, timeout=120)
response.raise_for_status()
print(response.json())

Choose exactly one of url, data_url, or an existing image_id per reference. Inline PNG, JPEG and WebP images support up to 20 MiB decoded per image and 40 million pixels. Optional view labels use the same values as asset references. Existing uploaded IDs remain supported for compatibility. Omit references for text-to-scene generation. Asset-only reference_image_urls and reference_intent are not scene request fields. This caps a one-asset scene at **

13** at a

5 Team asset price plus $8 scene assembly. Choose a new idempotency key for each intentional new generation. Your integration generates and persists the Idempotency-Key; end users do not need to enter or manage it. It is required, must be 1–128 characters, and accepts letters, digits, ., _, :, and -. A UUID is suitable. After a timeout or lost response, retry with the same key and identical request to recover the same job and scene. The response sets Idempotency-Replayed: true for a replay. Changed requests with that key return 409 idempotency_conflict. Do not create a new key just because a job is still running. The 202 Accepted response contains both identifiers:

{"ok": true, "job_id": "job_EXAMPLE", "scene_id": "SCENE_ID", "status": "queued"}

The Team API uses the same scene-generation orchestration as the normal scene flow. After inventory planning and price checks, canonical asset generation runs alongside structure building and layout planning. Final placement uses the completed structure and available generated assets. Failed assets are counted as excluded; the pipeline can continue with available assets. Canonical designs can also be authored in parallel, subject to the Team release’s worker concurrency. A large scene can take considerably longer than a single asset. max_asset_definitions defaults to 50 (range 1–100), and max_instances defaults to 100 (range 1–500). A plan above either limit stops before modeling rather than silently omitting objects. Prompts are limited to 20,000 characters and references to three images. Models and worker configuration come from the Team’s pinned release, not caller overrides.

Price and spending limits

For the fixed-price scene release: Scene price = delivered unique canonical assets × the Team’s asset price + $8 assembly. The assembly fee defaults to 800 cents; use the accepted job’s scene_pricing for the exact Team configuration. At

5 per asset, a table and one chair design placed four times cost **

18**: two canonical assets ×

5 +

8. Repeated instances do not incur additional asset charges. Major visual variants are separate designs. The asset price and assembly fee are frozen when the job is accepted. Provider calls, parallel workers, and internal modeling iterations do not add metered charges to a fixed-price scene. The final charge uses delivered definitions, excluding failed ones, and settles once the accepted release’s required outputs are published. New releases require Blender, GLB, USD and source outputs. A delivered partial or candidate_delivered result is still billable; incomplete validation does not make a delivered scene free. Failed and cancelled jobs cost $0, including when a recovery archive is available. Teams with company billing use the Team credit account. max_cost_cents is an optional ceiling, not a charge or an asset count:

Omit it or send null to use the server-configured ceiling.
Send an integer from 1 through 1000000 to set a per-request ceiling in cents.
Send "unlimited" to remove the total cost cap on a release that supports it.

The effective ceiling is saved as budget_cents; later settings changes and idempotent replays do not replace it. A ceiling below one asset plus assembly is rejected with 422 scene_budget_too_low. After planning, the entire planned price must fit the ceiling before asset generation starts. If it does not, the job fails without generating the assets or charging for the scene. The service does not silently trim the plan to fit. The ceiling is not reserved from the balance upfront, and credit eligibility still applies. Older metered releases and jobs accepted under them retain their original accounting. Check job.scene_pricing: a populated value identifies the fixed-price contract described here. Do not infer fixed pricing for an older job where it is absent or null.

Poll progress and inspect results

curl --fail-with-body \
  -H "Authorization: Bearer $GIZMO_API_KEY" \
  "$GIZMO_API_BASE/v1/jobs/job_EXAMPLE?include_result=true"

curl --fail-with-body \
  -H "Authorization: Bearer $GIZMO_API_KEY" \
  "$GIZMO_API_BASE/v1/scenes/SCENE_ID"

Poll every 30–60 seconds until job.status is succeeded, failed, or cancelled. Use GET /v1/scenes/{scene_id} for the typed scene result, which is null until publication. Inspect job.error if generation fails. The job exposes scene_progress with phase (planning, assets, structure, or placement) and planned/generated/excluded instance counts. The normal job phase also tracks queueing, export, cancellation, and completion. Use the existing job cancellation endpoint if needed; cancelling does not automatically regenerate or retry the scene. A successful job means native outputs were delivered. Inspect the scene result separately:

status: complete, candidate_delivered, or partial.
sceneCommitted: the saved native scene was committed within this job’s artifact package.
assetDefinitions: planned, delivered, and excluded canonical designs. These differ from instance counts and determine the fixed asset charge.
counts: planned, eligible, excluded, accepted, and pending instances.
structure_status: complete or partial.
validationPassed: whether placement checks completed successfully with no excluded instances or unfinished structure.
exports: available files, hashes, sizes, and relative download URLs.

Pending instances can be present in a useful candidate without passing every physical check. Image fidelity is advisory. Delivery does not certify collision-free physics or simulation readiness. Native geometry and source diagnostics are preserved for inspection. For fixed-price jobs, job.scene_pricing exposes asset_price_cents, assembly_fee_cents, and delivered_assets (which can be null before delivery). Read settled_spend_cents for the actual charge and billing_status for settlement progress; a running job’s zero settled spend is not its final price.

Download

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $GIZMO_API_KEY" \
  "$GIZMO_API_BASE/v1/scenes/SCENE_ID/export?format=blend" \
  -o scene.blend

Use format=blend, usd, usdz, glb, or source. Downloads are binary responses protected by the owning Team key, with X-Content-SHA256 and Content-Length. New releases require Blender, GLB, a USD ZIP, and a source ZIP for successful publication. USDZ is an optional conversion; only download formats listed in exports. An unavailable conversion returns 409. Export URLs are relative to the API origin and require POST, including URLs returned in exports; they are not public GET links. Preserve the optional job_id query parameter in returned URLs: it pins the download to that job’s artifacts even after an export recovery publishes a newer delivery for the same scene. You can also pass job_id=JOB_ID explicitly when downloading a specific scene job. format=source downloads native inputs, dependencies, the plan, and diagnostics. It is also available for failed/cancelled jobs when a complete recovery archive was saved. If no archive survived, the API returns 409 checkpoint_unavailable. Downloads never start another generation. The reconstruction is delivered as native files; this endpoint does not import its individual assets into the editable Team library. Use the existing Team key scopes: generate:asset to submit, read:assets to poll, and export:assets to download. These legacy scope names cover scene reconstruction too.

Recover exports without generating again

If conversion failed, or an older scene lacks GLB, call POST /v1/jobs/{job_id}/retry-export with a new saved Idempotency-Key. Use a Team key with generate:asset and export:assets scopes. Poll the returned job ID, then read the original scene ID for the newest successful delivery. The previous delivery stays available while recovery runs. Scene export recovery uses the retained authoring checkpoint and the current compatible Team exporter. It does not generate assets again and costs $0, including recovery from an uncharged failed scene. A complete saved authoring checkpoint is required; this is not a retry of failed modeling. Reuse the same idempotency key after a lost response to avoid redundant export work.

Start here

Generate

Manage results

Operate

Reconstruct a complete scene

Submit with references directly

Price and spending limits

Poll progress and inspect results

Download

Recover exports without generating again

​Submit with references directly

​Price and spending limits

​Poll progress and inspect results

​Download

​Recover exports without generating again

Submit with references directly

Price and spending limits

Poll progress and inspect results

Download

Recover exports without generating again