Text to 3D Simulation

curl --request POST \
  --url https://api.vects.ai/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>"
  }
}
'

import requests

url = "https://api.vects.ai/api/v1/simulations/"

payload = {
    "prompt": "<string>",
    "webhook_url": "<string>",
    "settings": {
        "settings.max_agents": 123,
        "settings.simulation_duration": 123,
        "settings.environment_type": "<string>",
        "settings.weather_conditions": "<string>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    webhook_url: '<string>',
    settings: {
      'settings.max_agents': 123,
      'settings.simulation_duration': 123,
      'settings.environment_type': '<string>',
      'settings.weather_conditions': '<string>'
    }
  })
};

fetch('https://api.vects.ai/api/v1/simulations/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vects.ai/api/v1/simulations/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'webhook_url' => '<string>',
    'settings' => [
        'settings.max_agents' => 123,
        'settings.simulation_duration' => 123,
        'settings.environment_type' => '<string>',
        'settings.weather_conditions' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vects.ai/api/v1/simulations/"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"settings\": {\n    \"settings.max_agents\": 123,\n    \"settings.simulation_duration\": 123,\n    \"settings.environment_type\": \"<string>\",\n    \"settings.weather_conditions\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vects.ai/api/v1/simulations/")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"settings\": {\n    \"settings.max_agents\": 123,\n    \"settings.simulation_duration\": 123,\n    \"settings.environment_type\": \"<string>\",\n    \"settings.weather_conditions\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vects.ai/api/v1/simulations/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"settings\": {\n    \"settings.max_agents\": 123,\n    \"settings.simulation_duration\": 123,\n    \"settings.environment_type\": \"<string>\",\n    \"settings.weather_conditions\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "201": {},
  "400": {},
  "401": {},
  "429": {},
  "500": {},
  "simulation_id": "<string>",
  "slug": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "status_url": "<string>",
  "result_url": "<string>"
}

POST

api

simulations

Text to 3D Simulation

curl --request POST \
  --url https://api.vects.ai/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>"
  }
}
'

import requests

url = "https://api.vects.ai/api/v1/simulations/"

payload = {
    "prompt": "<string>",
    "webhook_url": "<string>",
    "settings": {
        "settings.max_agents": 123,
        "settings.simulation_duration": 123,
        "settings.environment_type": "<string>",
        "settings.weather_conditions": "<string>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    webhook_url: '<string>',
    settings: {
      'settings.max_agents': 123,
      'settings.simulation_duration': 123,
      'settings.environment_type': '<string>',
      'settings.weather_conditions': '<string>'
    }
  })
};

fetch('https://api.vects.ai/api/v1/simulations/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vects.ai/api/v1/simulations/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'webhook_url' => '<string>',
    'settings' => [
        'settings.max_agents' => 123,
        'settings.simulation_duration' => 123,
        'settings.environment_type' => '<string>',
        'settings.weather_conditions' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vects.ai/api/v1/simulations/"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"settings\": {\n    \"settings.max_agents\": 123,\n    \"settings.simulation_duration\": 123,\n    \"settings.environment_type\": \"<string>\",\n    \"settings.weather_conditions\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vects.ai/api/v1/simulations/")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"settings\": {\n    \"settings.max_agents\": 123,\n    \"settings.simulation_duration\": 123,\n    \"settings.environment_type\": \"<string>\",\n    \"settings.weather_conditions\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vects.ai/api/v1/simulations/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"settings\": {\n    \"settings.max_agents\": 123,\n    \"settings.simulation_duration\": 123,\n    \"settings.environment_type\": \"<string>\",\n    \"settings.weather_conditions\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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.vects.ai/api/v1/simulations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json"

curl -X POST "https://api.vects.ai/api/v1/simulations/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json"

Request Body

string

required

Natural language description of the simulation you want to create. Be specific about the environment, actors, and scenarios you envision.

string

Optional webhook URL to receive notifications when the simulation is complete. Must be a valid HTTPS URL.

object

Optional simulation settings to customize the generation process.

Show settings properties

integer

default:"100"

Maximum number of agents to include in the simulation (1-1000)

integer

default:"300"

Simulation duration in seconds (60-3600)

string

default:"urban"

Type of environment: urban, rural, indoor, mixed

string

default:"clear"

Weather conditions: clear, rain, snow, fog, storm

Example Requests

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"
  }'

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"
    }
  }'

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"
    }
  }'

Response

string

Unique identifier for the created simulation (“id”)

string

URL-friendly slug for the simulation, useful in web UIs

string

Current status of the simulation: queued, processing, completed, failed

string

ISO 8601 timestamp when the simulation was created

string

Absolute URL to poll build status

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

Created

Simulation successfully queued for processing

Bad Request

Invalid request parameters or malformed prompt

Unauthorized

Invalid or missing API key

Too Many Requests

Rate limit exceeded

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.vects.ai/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

Check simulation status using the Status API
Retrieve completed results with the Results API
Learn about Risk Analysis for safety assessments

Simulation Risk Analysis

Simulation APIs

Urban Mobility MARL

Risk Assessment

Text to 3D Simulation

Overview

Authentication

Request Body

Example Requests

Response

Example Response

Status Codes

Error Response

Webhook Notifications

Simulation Started

Simulation Completed

Simulation Failed

Next Steps

​Overview

​Authentication

​Request Body

​Example Requests

​Response

​Example Response

​Status Codes

​Error Response

​Webhook Notifications

​Simulation Started

​Simulation Completed

​Simulation Failed

​Next Steps

Overview

Authentication

Request Body

Example Requests

Response

Example Response

Status Codes

Error Response

Webhook Notifications

Simulation Started

Simulation Completed

Simulation Failed

Next Steps