Skip to main content
POST
https://api.worldlens.co
/
api
/
v1
/
simulations
Text to 3D Simulation
curl --request POST \
  --url https://api.worldlens.co/api/v1/simulations/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "webhook_url": "<string>",
  "settings": {
    "settings.max_agents": 123,
    "settings.simulation_duration": 123,
    "settings.environment_type": "<string>",
    "settings.weather_conditions": "<string>"
  }
}
'
{
  "201": {},
  "400": {},
  "401": {},
  "429": {},
  "500": {},
  "simulation_id": "<string>",
  "slug": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "status_url": "<string>",
  "result_url": "<string>"
}

​
Overview

The Text to 3D Simulation API transforms natural language prompts into fully interactive 3D simulations. This endpoint leverages advanced AI to interpret your description and generate a complete simulation environment with actors, terrain, and dynamic elements.

​
Authentication

curl -X POST "https://api.worldlens.co/api/v1/simulations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Request Body

​
prompt
string
required
Natural language description of the simulation you want to create. Be specific about the environment, actors, and scenarios you envision.
​
webhook_url
string
Optional webhook URL to receive notifications when the simulation is complete. Must be a valid HTTPS URL.
​
settings
object
Optional simulation settings to customize the generation process.

​
Example Requests

curl -X POST "https://api.worldlens.co/api/v1/simulations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a busy downtown intersection with pedestrians crossing, cars waiting at traffic lights, and a food truck on the corner"
  }'

​
Response

​
simulation_id
string
Unique identifier for the created simulation (“id”)
​
slug
string
URL-friendly slug for the simulation, useful in web UIs
​
status
string
Current status of the simulation: queued, processing, completed, failed
​
created_at
string
ISO 8601 timestamp when the simulation was created
​
status_url
string
Absolute URL to poll build status
​
result_url
string
Absolute URL to fetch completed simulation data (null until status == completed)

​
Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "busy-downtown-intersection",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00Z",
  "status_url": "/api/v1/simulations/123e4567-e89b-12d3-a456-426614174000/status/",
  "result_url": "/api/v1/simulations/123e4567-e89b-12d3-a456-426614174000/"
}

​
Status Codes

​
201
Created
Simulation successfully queued for processing
​
400
Bad Request
Invalid request parameters or malformed prompt
​
401
Unauthorized
Invalid or missing API key
​
429
Too Many Requests
Rate limit exceeded
​
500
Internal Server Error
Server error during simulation creation

​
Error Response

{
  "error": "Invalid prompt: Prompt must be at least 10 characters long",
  "code": "INVALID_PROMPT",
  "details": {
    "field": "prompt",
    "min_length": 10,
    "provided_length": 5
  }
}

​
Webhook Notifications

If you provide a webhook_url, you’ll receive POST notifications at key simulation milestones:

​
Simulation Started

{
  "event": "simulation.started",
  "simulation_id": "sim_abc123def456",
  "timestamp": "2024-01-15T10:30:30Z"
}

​
Simulation Completed

{
  "event": "simulation.completed",
  "simulation_id": "sim_abc123def456",
  "timestamp": "2024-01-15T10:35:15Z",
  "result_url": "https://api.worldlens.co/api/v1/simulations/sim_abc123def456/"
}

​
Simulation Failed

{
  "event": "simulation.failed",
  "simulation_id": "sim_abc123def456",
  "timestamp": "2024-01-15T10:32:45Z",
  "error": "Failed to generate terrain from prompt"
}

​
Next Steps