> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldlens.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Text to 3D Simulation

> Create immersive 3D simulations from natural language descriptions

## 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

<CodeGroup>
  ```bash API Key theme={null}
  curl -X POST "https://api.vects.ai/api/v1/simulations/" \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```bash Token theme={null}
  curl -X POST "https://api.vects.ai/api/v1/simulations/" \
    -H "Authorization: Token YOUR_AUTH_TOKEN" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

## Request Body

<ParamField body="prompt" type="string" required>
  Natural language description of the simulation you want to create. Be specific about the environment, actors, and scenarios you envision.
</ParamField>

<ParamField body="webhook_url" type="string">
  Optional webhook URL to receive notifications when the simulation is complete. Must be a valid HTTPS URL.
</ParamField>

<ParamField body="settings" type="object">
  Optional simulation settings to customize the generation process.

  <Expandable title="settings properties">
    <ParamField body="settings.max_agents" type="integer" default="100">
      Maximum number of agents to include in the simulation (1-1000)
    </ParamField>

    <ParamField body="settings.simulation_duration" type="integer" default="300">
      Simulation duration in seconds (60-3600)
    </ParamField>

    <ParamField body="settings.environment_type" type="string" default="urban">
      Type of environment: `urban`, `rural`, `indoor`, `mixed`
    </ParamField>

    <ParamField body="settings.weather_conditions" type="string" default="clear">
      Weather conditions: `clear`, `rain`, `snow`, `fog`, `storm`
    </ParamField>
  </Expandable>
</ParamField>

## Example Requests

<CodeGroup>
  ```bash Basic Simulation theme={null}
  curl -X POST "https://api.vects.ai/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"
    }'
  ```

  ```bash Advanced Simulation theme={null}
  curl -X POST "https://api.vects.ai/api/v1/simulations/" \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Simulate an emergency evacuation scenario in a shopping mall with multiple exits, crowds of people, and emergency vehicles arriving",
      "webhook_url": "https://your-app.com/webhooks/simulation-complete",
      "settings": {
        "max_agents": 500,
        "simulation_duration": 600,
        "environment_type": "indoor",
        "weather_conditions": "clear"
      }
    }'
  ```

  ```bash Disaster Scenario theme={null}
  curl -X POST "https://api.vects.ai/api/v1/simulations/" \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Model a flood evacuation in a coastal town with rising water levels, emergency responders, and residents moving to higher ground",
      "settings": {
        "max_agents": 300,
        "simulation_duration": 900,
        "environment_type": "mixed",
        "weather_conditions": "storm"
      }
    }'
  ```
</CodeGroup>

## Response

<ResponseField name="simulation_id" type="string">
  Unique identifier for the created simulation ("id")
</ResponseField>

<ResponseField name="slug" type="string">
  URL-friendly slug for the simulation, useful in web UIs
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the simulation: `queued`, `processing`, `completed`, `failed`
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the simulation was created
</ResponseField>

<ResponseField name="status_url" type="string">
  Absolute URL to poll build status
</ResponseField>

<ResponseField name="result_url" type="string">
  Absolute URL to fetch completed simulation data (null until `status == completed`)
</ResponseField>

## Example Response

```json theme={null}
{
  "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

<ResponseField name="201" type="Created">
  Simulation successfully queued for processing
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Invalid request parameters or malformed prompt
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Invalid or missing API key
</ResponseField>

<ResponseField name="429" type="Too Many Requests">
  Rate limit exceeded
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error during simulation creation
</ResponseField>

## Error Response

```json theme={null}
{
  "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

```json theme={null}
{
  "event": "simulation.started",
  "simulation_id": "sim_abc123def456",
  "timestamp": "2024-01-15T10:30:30Z"
}
```

### Simulation Completed

```json theme={null}
{
  "event": "simulation.completed",
  "simulation_id": "sim_abc123def456",
  "timestamp": "2024-01-15T10:35:15Z",
  "result_url": "https://api.vects.ai/api/v1/simulations/sim_abc123def456/"
}
```

### Simulation Failed

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

## Next Steps

* Check simulation status using the [Status API](/api-reference/simulation/status)
* Retrieve completed results with the [Results API](/api-reference/simulation/results)
* Learn about [Risk Analysis](/api-reference/risk/route-analysis) for safety assessments