search
ChangelogFeedbackOpen Studio

Quick Start

Get the Model API running with your embedded Vectary project in 5 minutes.

hashtag
Prerequisites

1

hashtag
Step 1: Get your Project ID

  • Open your project in Vectary Studio

  • Click Share in the top right corner

  • Copy the Project ID from the embed URL:

https://app.vectary.com/p/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                          └──────────── Project ID ────────────┘

2

hashtag
Step 2: Add the embed to your page

Create an HTML file with an iframe pointing to your project:

<!DOCTYPE html>
<html>
<head>
  <title>Vectary API Demo</title>
</head>
<body>
  <iframe 
    id="vectary-embed"
    src="https://app.vectary.com/p/YOUR_PROJECT_ID"
    width="800" 
    height="600"
    frameborder="0"
  ></iframe>
</body>
</html>

Replace YOUR_PROJECT_ID with the ID from Step 1

3

hashtag
Step 3: Initialize the API

Add this script after the iframe:

<script type="module">
  import { VctrModelApi } from "https://app.vectary.com/studio-lite/scripts/api.js";

  // Create API instance with the iframe's DOM id
  const api = new VctrModelApi("vectary-embed");
  
  // Wait for initialization
  await api.init();
  
  console.log("API ready!");
</script>

Open your browser's console - you should see "API ready!" once the model loads.

4

hashtag
Step 4: Make your first API call

The API provides many methods to control the scene (see the full list in the API Reference). Here's a simple example to get you started:

<script type="module">
  import { VctrModelApi } from "https://app.vectary.com/studio-lite/scripts/api.js";

  const api = new VctrModelApi("vectary-embed");
  await api.init();

  // Get all objects in the scene
  const objects = await api.getObjects();
  console.log("Scene objects:", objects);
</script>

hashtag
Complete example

Here's a full working example that lists all objects in the scene:

<!DOCTYPE html>
<html>
<head>
  <title>Vectary API Demo</title>
  <style>
    body { font-family: sans-serif; padding: 20px; }
    iframe { border: 1px solid #ccc; }
    pre { background: #f5f5f5; padding: 15px; overflow: auto; }
  </style>
</head>
<body>
  <h1>My 3D Configurator</h1>
  
  <iframe 
    id="vectary-embed"
    src="https://app.vectary.com/p/YOUR_PROJECT_ID"
    width="800" 
    height="600"
    frameborder="0"
  ></iframe>

  <h2>Scene Objects</h2>
  <pre id="output">Loading...</pre>

  <script type="module">
    import { VctrModelApi } from "https://app.vectary.com/studio-lite/scripts/api.js";

    const api = new VctrModelApi("vectary-embed");
    await api.init();

    const objects = await api.getObjects();
    document.getElementById("output").textContent = JSON.stringify(objects, null, 2);
  </script>
</body>
</html>

hashtag
Key points

Point
Details

One API instance per iframe

If you have multiple embeds, create a separate VctrModelApi for each

All methods are async

Always use await or .then() - methods return Promises

Initialize before calling methods

Wait for api.init() to complete before making other calls

Error handling

Errors reject the Promise with { status: "error", error?: string }

hashtag
Troubleshooting

API not initializing?

  • Check that the iframe id matches the string passed to VctrModelApi()

  • Ensure the project is published and accessible

  • Verify your workspace has a Business plan

Methods returning empty results?

  • Make sure init() has completed before calling other methods

  • Check the browser console for error messages

CORS errors?

  • The API script must be loaded from app.vectary.com, not copied locally

hashtag
Next steps

PreviousModel APINextCore Concepts

Last updated