Getting Started

Quick guide to get up and running with the vid2scene API.

🎯 What You'll Learn

How to get and use API keys
How to upload and process videos
How to monitor job progress
How to download results

Step 1: Get Your API Key

First, you'll need an API key to authenticate your requests.

Log in and go to your profile page
Scroll to the "API Keys" section
Enter a name like "My First API Key"
Click "Generate API Key"
Copy the key (you'll only see it once!)

Important: Store your API key securely. Never commit it to version control or share it publicly.

Step 2: Upload a Video

The vid2scene API uses a two-step upload process for security and reliability:

2.1 Generate Upload URL

First, get a secure upload URL for your video. Send only the file extension:

curl -X POST \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_extension": "mp4"}' \
  https://vid2scene.com/api/v1/generate-upload-url/

This returns:

{
  "url": "https://storage.blob.core.windows.net/container/videos/uuid.mp4?sv=...",
  "blob_name": "videos/uuid.mp4"
}

2.2 Upload Your Video

Use the upload URL to upload your video file:

curl -X PUT \
  -H "x-ms-blob-type: BlockBlob" \
  --data-binary @my_video.mp4 \
  "SAS_URL_FROM_PREVIOUS_STEP"

Step 3: Create Processing Job

After uploading, create and start a processing job:

curl -X POST \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blob_name": "videos/uuid.mp4",
    "title": "My Awesome Video",
    "public": false,
    "reconstruction_method": "glomap"
  }' \
  https://vid2scene.com/api/v1/submit-job/

This returns the job details:

{
  "success": true,
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "My Awesome Video",
  "status": "Queued",
  "uploaded_at": "2024-01-15T10:30:00Z",
  "public": false,
  "reconstruction_method": "glomap",
  "training_max_num_gaussians": 300000,
  "training_num_steps": 10000,
  "camera_data": {
    "position": {"x": 0.0, "y": 0.0, "z": 5.0},
    "lookAt": {"x": 0.0, "y": 0.0, "z": 0.0},
    "up": {"x": 0.0, "y": 1.0, "z": 0.0},
    "cameraType": "orbital"
  }
}

Step 4: Monitor Progress

Check the status of your job:

curl -H "Authorization: Api-Key YOUR_API_KEY" \
  https://vid2scene.com/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/

This returns the full job details including status:

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "My Awesome Video",
  "status": "Queued - position: 3",
  "percent_complete": null,
  "uploaded_at": "2024-01-15T10:30:00Z",
  "public": false,
  "reconstruction_method": "glomap",
  "training_max_num_gaussians": 300000,
  "training_num_steps": 10000,
  "has_ply": false,
  "has_spz": false,
  "camera_data": {
    "position": {"x": 0.0, "y": 0.0, "z": 5.0},
    "lookAt": {"x": 0.0, "y": 0.0, "z": 0.0},
    "up": {"x": 0.0, "y": 1.0, "z": 0.0},
    "cameraType": "orbital"
  }
}

Job status can be:

Queued - Waiting to start processing
Queued - position: X - Waiting in queue at position X
Processing video - Currently processing the video
Generating 3D scene - Creating the 3D reconstruction
Finished - Completed successfully
Failed - Processing failed
Not found - Job not found in queue

The percent_complete field shows progress during 3D scene generation (0-100), or null if not yet started.

Step 5: Get Results

Once processing is complete, you can:

5.1 Download Files

Download specific file types (PLY or SPZ) - these endpoints return 302 redirects:

# Download PLY file (follow redirect)
curl -H "Authorization: Api-Key YOUR_API_KEY" \
  -L "https://vid2scene.com/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/download/ply/" \
  -o scene.ply

# Download SPZ file (follow redirect)
curl -H "Authorization: Api-Key YOUR_API_KEY" \
  -L "https://vid2scene.com/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/download/spz/" \
  -o scene.spz

5.2 Get Preview Image

Fetch a short-lived preview image URL (returns a 302 redirect to the image):

curl -I -H "Authorization: Api-Key YOUR_API_KEY" \
  https://vid2scene.com/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/preview/

Complete Python Example

Here's a complete example in Python:

import requests
import time
import os

# Your API key
API_KEY = "your-api-key-here"
BASE_URL = "https://vid2scene.com/api/v1"
headers = {"Authorization": f"Api-Key {API_KEY}"}

# Step 1: Generate upload URL
video_file = "my_video.mp4"
file_extension = os.path.splitext(video_file)[1].lstrip('.')

upload_response = requests.post(
    f"{BASE_URL}/generate-upload-url/",
    headers={**headers, "Content-Type": "application/json"},
    json={"file_extension": file_extension}
)
upload_response.raise_for_status()
upload_data = upload_response.json()

# Step 2: Upload video
with open(video_file, 'rb') as f:
    upload_result = requests.put(
        upload_data["url"],
        headers={"x-ms-blob-type": "BlockBlob"},
        data=f
    )
    upload_result.raise_for_status()

# Step 3: Create job
job_response = requests.post(
    f"{BASE_URL}/submit-job/",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "blob_name": upload_data["blob_name"],
        "title": "My Python Upload",
        "public": False,
        "reconstruction_method": "glomap"
    }
)
job_response.raise_for_status()
job_data = job_response.json()
job_id = job_data["job_id"]

print(f"Job created: {job_id}")

# Step 4: Monitor progress
while True:
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}/",
        headers=headers
    )
    status_response.raise_for_status()
    status_data = status_response.json()

    pc = status_data.get('percent_complete')
    pc_str = f" ({pc}%)" if pc is not None else ""
    print(f"Status: {status_data['status']}{pc_str}")

    if status_data["status"] == "Finished":
        print("Processing complete!")
        break
    if status_data["status"] == "Failed":
        print("Processing failed!")
        break

    time.sleep(30)  # Check every 30 seconds

# Step 5: Get results
if status_data["status"] == "Finished":
    # Download PLY file (follows redirect automatically)
    try:
        ply_response = requests.get(
            f"{BASE_URL}/jobs/{job_id}/download/ply/",
            headers=headers,
            stream=True
        )
        if ply_response.status_code == 200:
            with open(f"{job_id}_scene.ply", 'wb') as f:
                for chunk in ply_response.iter_content(chunk_size=8192):
                    if chunk:
                        f.write(chunk)
            print(f"PLY file downloaded: {job_id}_scene.ply")
        else:
            print("PLY not available for this job")
    except requests.exceptions.RequestException:
        print("Error downloading PLY file")

    # Download SPZ file (follows redirect automatically)
    try:
        spz_response = requests.get(
            f"{BASE_URL}/jobs/{job_id}/download/spz/",
            headers=headers,
            stream=True
        )
        if spz_response.status_code == 200:
            with open(f"{job_id}_scene.spz", 'wb') as f:
                for chunk in spz_response.iter_content(chunk_size=8192):
                    if chunk:
                        f.write(chunk)
            print(f"SPZ file downloaded: {job_id}_scene.spz")
        else:
            print("SPZ not available for this job")
    except requests.exceptions.RequestException:
        print("Error downloading SPZ file")

    # Get preview image (302 redirect)
    preview_head = requests.head(
        f"{BASE_URL}/jobs/{job_id}/preview/",
        headers=headers,
        allow_redirects=False
    )
    if preview_head.status_code == 302:
        print(f"Preview image URL: {preview_head.headers.get('Location')}")

Best Practices

Video Quality: Use high-quality videos with good lighting for best results
Camera Movement: Smooth camera movements work better than shaky footage
Scene Content: Scenes with distinct features and textures process better
Duration: 2 to 3 minute videos typically produce the best results
Rate Limiting: Respect rate limits to avoid getting blocked
Error Handling: Always check response status codes and handle errors gracefully

Next Steps

Read the Authentication Guide for security best practices
Explore all API Endpoints for advanced features

API Documentation