SamuSynth Logo Vid2Scene Beta
API Documentation
Overview Getting Started Authentication API Endpoints

API Endpoints

Complete reference for all vid2scene API endpoints.

🏢 Enterprise API

All endpoints require Enterprise subscription and API key authentication. You can only access your own jobs.

Jobs

Manage your video processing jobs.

GET List Jobs

GET /api/v1/jobs/

Retrieve a list of your video processing jobs.

Example Request
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     "https://vid2scene.com/api/v1/jobs/"
Example Response
[
  {
    "job_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "My awesome video"
  },
  {
    "job_id": "987fcdeb-51a2-43d1-b789-123456789abc",
    "title": "Another video scene"
  }
]
📋 Lightweight Response

The list endpoint returns only job ID and title for faster performance. Use the GET /api/v1/jobs/{job_id}/ endpoint to get detailed information about a specific job.

GET Get Job Status

GET /api/v1/jobs/{job_id}/

Get the current processing status and progress of a job. This endpoint returns detailed information about the job including its current status, progress, and configuration.

Status Values

The status field can have the following values:

  • 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.

Example Response
{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "My awesome video",
  "status": "Generating 3D scene",
  "percent_complete": 75,
  "uploaded_at": "2024-01-15T10:30:00Z",
  "public": false,
  "reconstruction_method": "glomap",
  "training_max_num_gaussians": 30000,
  "training_num_steps": 7000,
  "remove_background": false,
  "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"
  }
}

PATCH Update Job

PATCH /api/v1/jobs/{job_id}/

Update job properties like title, public status, or camera data.

Request Body
Field Type Description
title string Job title
public boolean Whether the job is publicly visible
camera_data object Camera configuration data
Example Request
curl -X PATCH \
     -H "Authorization: Api-Key YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"title": "Updated title", "public": true}' \
     "https://vid2scene.com/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/"

DELETE Delete Job

DELETE /api/v1/jobs/{job_id}/

Delete a job and all associated files. This action cannot be undone.

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

GET Get Download URL (Redirect)

GET /api/v1/jobs/{job_id}/download/{file_type}/

Returns a 302 redirect to a secure, time-limited download URL for the specified file type. URLs expire in 15 minutes.

Path Parameters
Parameter Type Description
job_id UUID The unique identifier of the job
file_type string File type to download: ply or spz
Example Request
# Follow redirects to download the file
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 --fail --show-error
Response

Returns a 302 Found redirect to the secure download URL. The file will be downloaded directly from cloud storage.

💡 Usage: Use -L to follow redirects and -o to save the file. No additional authentication required for the redirected URL.

GET Get Preview Image (Redirect)

GET /api/v1/jobs/{job_id}/preview/

Returns a 302 redirect to a secure, time-limited URL for the preview image. URLs expire in 15 minutes.

Example Request
curl -H "Authorization: Api-Key YOUR_API_KEY" \
     -L "https://vid2scene.com/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/preview/" \
     -o preview.jpg --fail --show-error
💡 Tip: Use -L to follow redirects and -o to save the image to a file.

Upload

Upload videos for processing.

POST Generate Upload URL

POST /api/v1/generate-upload-url/

Generate a secure upload URL for video files. This returns a time-limited URL that you can use to upload your video directly to our storage.

Request Body
Field Type Required Description
file_extension string Yes File extension only (e.g., mp4, mov)
Example Request
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/"
Example Response
{
  "url": "https://storage.blob.core.windows.net/container/videos/uuid.mp4?sv=...",
  "blob_name": "videos/uuid.mp4"
}

POST Create Processing Job

POST /api/v1/submit-job/

Create and start a new video processing job after uploading your video file.

Request Body
Field Type Required Description
blob_name string Yes Blob name from upload response
title string No Job title (defaults to filename)
public boolean No Make job publicly visible (default: false)
reconstruction_method string No Processing method (default: "glomap")
training_max_num_gaussians integer No Maximum number of Gaussians for training (default: 1000000)
training_num_steps integer No Number of training steps (default: 25000)
apriltag_size_mm float No Physical size of AprilTag in millimeters (1-1000mm). Measured from inner white square. When provided, enables automatic scale calibration using AprilTags. Only supports tagStandard41h12 family. AprilTags will only be detected if this parameter is included.
remove_background boolean No Remove background from images before processing (default: false)
camera_type string No Default camera control mode for the viewer. Options: "orbital" or "drone". If not specified, viewer starts in drone mode.
📐 AprilTag Scale Calibration

Automatically set your 3D reconstruction to real-world scale by placing AprilTags (tagStandard41h12 family) in your scene. Provide the tag's physical size in millimeters to enable this feature. Download tags here.

Example Request
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", "remove_background": false}' \
     "https://vid2scene.com/api/v1/submit-job/"
Example Request with Orbital Camera Controls
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", "camera_type": "orbital"}' \
     "https://vid2scene.com/api/v1/submit-job/"
Example Request with AprilTag Calibration
curl -X POST \
     -H "Authorization: Api-Key YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"blob_name": "videos/uuid.mp4", "title": "My Room", "apriltag_size_mm": 95.6}' \
     "https://vid2scene.com/api/v1/submit-job/"
Example Response
{
  "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": 30000,
  "training_num_steps": 7000,
  "remove_background": false
}

Error Responses

All error responses include an error message and appropriate HTTP status code.

Status Code Description Example Response
400 Bad Request {"error": "Invalid file format"}
401 Unauthorized {"error": "Invalid API key"}
403 Forbidden {"error": "Insufficient permissions"}
404 Not Found {"error": "Job not found"}
429 Rate Limited {"error": "Rate limit exceeded"}
500 Server Error {"error": "Internal server error"}