API Reference

Turn any 3D mesh into simulation-ready physics (MJCF + Domain Randomization profiles) in seconds.

No manual tuning. No parameter guesswork. Physics derived directly from geometry.

Quick Start

POST /api/v1/scene
curl -X POST https://api.enviscale.com/api/v1/scene \
  -H "X-API-Key: es_live_YOUR_KEY" \
  -F "file=@dataset.zip" \
  -F "surface_condition=all" \
  --output dataset_mjcf.zip

Instant Output Stream

Returns a ZIP containing:
- MuJoCo XMLs
- Collision meshes
- Physics report (JSON)

Authentication

All API requests must be explicitly authenticated. Generate a key from your dashboard and inject it as the X-API-Key header.

# HTTP Header
X-API-Key: es_live_9ZDmto...

The Endpoint

The engine exposes a single, powerful compilation pipeline that handles all geometry extraction, visual categorization, and friction matrix calculations mathematically.

fileFileRequired

The primary 3D mesh file or a bundled structural .zip.

companion_filesFile Array

Optional flattened array of .bin files or textures. Only required if NOT utilizing explicit Zip nesting.

surface_conditionString

Surface wear profile filter. Defaults to "all" — options: clean | worn | contaminated

fill_stateString

Fluid volume constraint filter. Defaults to "all" — options: empty | half | full

scene_nameString

Optional name for the output scene. Defaults to the uploaded filename stem.

export_formatString

Output format. Only "mjcf" is currently supported.

Supported Formats

Our engine inherently parses standard structural geometries natively.

.glb
.gltf
.obj
.stl
.ply
.zip

Code Examples

We support simple file uploads alongside complex rendering pipelines natively. Integrate our processing core directly into your Python dataset scripts.

1. Basic Upload

Minimal working example for a single 3D structural file.

import requests

with open("cup.glb", "rb") as f:
    res = requests.post(
        "https://api.enviscale.com/api/v1/scene",
        headers={"X-API-Key": "es_live_..."},
        files={"file": f}
    )
Recommended

2. ZIP Dataset Upload

Bundle your .glb, buffers, and nested textures/ folder directly into a .zip archive. The backend unrolls the archive natively.

import requests

with open("dataset.zip", "rb") as f:
    res = requests.post(
        "https://api.enviscale.com/api/v1/scene",
        headers={"X-API-Key": "es_live_..."},
        files={"file": ("dataset.zip", f, "application/zip")}
    )

3. Advanced: Multipart Companion Files

For power users bypassing local zip compilation. You can programmatically append all buffers onto the POST stream. Note: flatten path references in the tuple structure.

multipart = [
  ("file", ("robot.gltf", open("robot.gltf", "rb"))),
  # Note: 'textures/map.jpg' is flattened to 'map.jpg' automatically
  ("companion_files", ("map.jpg", open("textures/map.jpg", "rb")))
]
requests.post(API_URL, files=multipart)

Response Structure

The API returns the explicit simulation bundle as application/zip stream. Critical computation telemetry is deliberately piped into standard HTTP header channels so your framework does not have to unpack the zip to access reporting details.

Exposed Headers

X-Processing-Time: 3.09s
X-Confidence: 0.94
X-Object-Name: ceramic_mug
X-Profile-Count: 12

Bundle Format (.zip)

  • XML MJCFs (MuJoCo-ready)
  • Physics Bounds JSON
  • Convex Collision Assets

Internal JSON Extrapolation (physics_report.json)

{
  "scene_name": "robot_arm_actuator",
  "object_category": "tool",
  "base_physics": {
    "mass_kg": 2.45,
    "friction_sliding": 0.45,
    "confidence": 0.94
  },
  "profiles": [
    { "profile_name": "clean_empty", "mjcf_file": "scene_clean_empty.xml" }
  ],
  "processing_time_seconds": 3.09
}

Physics Parameters

Adjust friction gradients and internal fluid volume properties dynamically to create DOM randomization configurations mathematically aligned with physical scenarios.

surface_condition

String

Adjusts strictly applied friction and restitution constants based heavily on physical surface wear criteria.

"all""clean""worn""contaminated"

fill_state

String

Commands the backend engine to synthesize internal fluid masses, lowering total Center of Mass matrices for container objects inherently preventing uncalibrated physics interactions during manipulations.

"all""empty""half""full"

Errors & Guarantees

Response Codes

400Invalid mesh, unsupported format, or file too large (>50 MB)
401Missing or invalid API key
403Tier restriction — feature not available on your plan
500Internal processing failure — geometry or pipeline error

Processing Limitations

Processing Speed: 2 - 5 seconds typically
File Boundary: 50 MB / Request
Replication: Completely deterministic outputs for identical uploaded geometries