Generation API

Connect asset and environment generation to your scripts and training workflows. Read the examples here, then sign in to create an API key.

Create an API key Connect through MCP

On this page

Your first API request.

Generate USD content from your own scripts. Replace YOUR_API_KEY and YOUR_ORG_SLUG with your key and the organisation it will use.

Connect your workflow

Base URL: https://robotics-api.imagine.io
Authentication: Authorization: Bearer YOUR_API_KEY
Credit balance: Generation requests use your organisation’s credits, just like the website.
Keep your key private: Call the API from your server or scripts. Keep keys out of browser code and source control.

The examples use a Unix shell with curl and uuidgen. Create a new request ID for each new job. To retry job creation, reuse the same ID, organisation and body.

Generate an asset

export API_BASE_URL='https://robotics-api.imagine.io'
export SIMGENERATOR_API_KEY='YOUR_API_KEY'
export SIMGENERATOR_ORG='YOUR_ORG_SLUG'

# Create once per new output. Reuse this value when retrying.
export REQUEST_ID="$(uuidgen)"

curl --fail-with-body "$API_BASE_URL/simready-gen/api/jobs/" \
  -H "Authorization: Bearer $SIMGENERATOR_API_KEY" \
  -H "X-Org: $SIMGENERATOR_ORG" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_ID" \
  --data '{
  "run_name": "warehouse-storage-cabinet",
  "mode": "generate",
  "text": "A metal warehouse storage cabinet with two hinged doors."
}'

Asset generation costs 200 credits. The response includes a job id. Use its returned status to follow progress and any review steps.

Plan an environment

export API_BASE_URL='https://robotics-api.imagine.io'
export SIMGENERATOR_API_KEY='YOUR_API_KEY'
export SIMGENERATOR_ORG='YOUR_ORG_SLUG'

# Create once per new output. Reuse this value when retrying.
export REQUEST_ID="$(uuidgen)"

curl --fail-with-body "$API_BASE_URL/simready-gen/api/jobs/" \
  -H "Authorization: Bearer $SIMGENERATOR_API_KEY" \
  -H "X-Org: $SIMGENERATOR_ORG" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_ID" \
  --data '{
  "run_name": "warehouse-picking-area",
  "mode": "generate",
  "text": "A warehouse picking area with shelving, storage totes and clear robot navigation paths.",
  "assetType": "scene",
  "selection": "review"
}'

The response includes a job id. This example requests a plan for review. When it reaches AWAITING_SELECTION, choose the assets and approve the build below. The build price depends on the parts you keep.

Check progress and download the package

Use the returned job ID. Poll approximately once every 60 seconds. If the status is AWAITING_SELECTION, review and approve the selection before the build can continue. Stop polling on SUCCESS, FAILURE or CANCELED.

Check job status

export JOB_ID='123' # Replace with the id returned when creating the job.

curl --fail-with-body "$API_BASE_URL/simready-gen/api/jobs/$JOB_ID/" \
  -H "Authorization: Bearer $SIMGENERATOR_API_KEY" \
  -H "X-Org: $SIMGENERATOR_ORG"

On SUCCESS, request the download information. This endpoint returns JSON with a temporary url and its expiry, rather than the ZIP itself. If it expires, request a fresh URL.

Download the generated package

curl --fail-with-body "$API_BASE_URL/simready-gen/api/jobs/$JOB_ID/download/" \
  -H "Authorization: Bearer $SIMGENERATOR_API_KEY" \
  -H "X-Org: $SIMGENERATOR_ORG"

# Use the url from the JSON response. Do not send your API key to it.
curl --fail --location 'SIGNED_URL_FROM_RESPONSE' --output generation.zip

Review and approve an environment build

Set JOB_ID to the ID returned by the planning request. Once its status is AWAITING_SELECTION, read the selection:

Read the planned assets and price

curl --fail-with-body "$API_BASE_URL/simready-gen/api/jobs/$JOB_ID/selection/" \
  -H "Authorization: Bearer $SIMGENERATOR_API_KEY" \
  -H "X-Org: $SIMGENERATOR_ORG"

The response includes candidates, part_price.credits, your organisation’s balance, the recorded planning charge and expires_at. Keep at least one asset. Locked architecture is always included. Calculate the build total from the part_count of all locked groups plus the assets you keep, multiplied by part_price.credits. Count each group once; its placements do not multiply the price. This total excludes the earlier planning charge.

Save the following as selection-approval.json. Replace the asset ID placeholder with the candidate IDs you want to keep, and replace 0 with the calculated build total. Confirm the price and available balance before sending:

Selection approval body

{
  "kind": "selection",
  "action": "approve",
  "keep_assets": [
    "ASSET_ID_FROM_SELECTION"
  ],
  "expected_credits": 0
}

Optionally add articulated as a list of kept candidate IDs marked articulable: true. Omit it to build every eligible kept asset with articulation, or use an empty list to build them all static.

Approve and start the build

# First save and review selection-approval.json, using the example below.
curl --fail-with-body "$API_BASE_URL/simready-gen/api/jobs/$JOB_ID/decision/" \
  -H "Authorization: Bearer $SIMGENERATOR_API_KEY" \
  -H "X-Org: $SIMGENERATOR_ORG" \
  -H "Content-Type: application/json" \
  --data @selection-approval.json

A successful 202 response confirms the approval and charge. Resume polling the same job. If the request times out, check its status and selection before retrying. On 409 quote_changed, fetch the selection again and review the new total. On 402, add credits before approving. Do not approve an expired plan or a selection with no available part price.

For unattended builds, create the environment with "selection": "auto" instead. This builds every planned asset and charges the parts automatically after planning, without waiting for your approval.

Add a reference image

Upload a PNG, JPEG or WebP image under 10 MB. Add the returned ID to your generation body as "reference": "RETURNED_REFERENCE_ID". Use the same organisation for both requests.

Upload a reference image

curl --fail-with-body "$API_BASE_URL/simready-gen/api/references/" \
  -H "Authorization: Bearer $SIMGENERATOR_API_KEY" \
  -H "X-Org: $SIMGENERATOR_ORG" \
  -F "image=@./reference.png"

Send the upload ID, not a local image path or URL, in the generation request.

Request fields and organisation context

run_name: A readable label for your generation.
mode: Use generate to create a new output.
text: Describe the asset or environment, up to 2,000 characters.
assetType: Use scene for an environment. Omit it for an asset.
selection: For environments, use review to choose assets and approve the build, or auto to build and charge for all planned assets automatically.
reference: Optional ID returned by the reference-image upload endpoint.

Use the same X-Org slug for uploads, planning, selection, approval, polling and package requests. Keys pinned to an organisation remain limited to that organisation.

Endpoints and common responses

POST /simready-gen/api/jobs/Create an asset generation or environment plan.

GET /simready-gen/api/jobs/List your generation jobs.

GET /simready-gen/api/jobs/{id}/Read a job’s status and progress.

GET /simready-gen/api/jobs/{id}/selection/Read planned assets, part prices and available credits.

POST /simready-gen/api/jobs/{id}/decision/Approve the selection and start the build.

GET /simready-gen/api/jobs/{id}/download/Get a signed package URL.

POST /simready-gen/api/references/Upload a reference image.

401: Check that the key is valid and the Bearer header is present.
403: Check email verification and access to the selected organisation.
402: Add credits or change your plan before starting another generation or approving a build.
409: Read the response code. The selection may not be ready, its quote may have changed, or a concurrency limit may apply.
503: The service or its pricing is unavailable. Follow the response message and retry later.