360-Degree Video API - Steer Autos Documentation

Overview

The 360-Degree Video API enables you to upload 360-degree videos of vehicles, automatically extract frames, and generate interactive 360-degree views for enhanced customer experiences. Perfect for showcasing vehicle exteriors, interiors, and detailed inspections.

Key Features

Video Upload

Upload 360-degree videos up to 100MB per file

Frame Extraction

Automatic frame extraction at optimal intervals

Multiple Sides

Support for OUTSIDE, INSIDE, and OPEN (trunk/hood) views

Cloud Storage

Secure S3 storage with signed URL access

Supported Video Formats

The API accepts the following video formats:

MP4 (.mp4) - Recommended
AVI (.avi)
MOV (.mov)
WMV (.wmv)
FLV (.flv)
WebM (.webm)
MKV (.mkv)
QuickTime (.mov, .qt)

Endpoints

Upload 360 Video

POST

endpoint

/360/upload

Upload a 360-degree video file to S3 and trigger frame extraction. Content Type: multipart/form-data Form Parameters:

video

file

required

Video file (max 100MB)

side

enum

required

Vehicle side: OUTSIDE, INSIDE, OPEN

Response:

{
  "success": true,
  "message": "360 video uploaded successfully",
  "data": {
    "message": "Video uploaded and processing started",
    "jobId": "job_550e8400-e29b-41d4-a716",
    "video": {
      "key": "360/videos/job_550e8400/OUTSIDE/video.mp4",
      "url": "https://s3.amazonaws.com/bucket/360/videos/job_550e8400/OUTSIDE/video.mp4",
      "originalName": "exterior_360.mp4",
      "size": 45678901,
      "mimetype": "video/mp4",
      "jobId": "job_550e8400-e29b-41d4-a716"
    }
  }
}

Response Fields:

jobId

string

Unique job identifier for tracking processing status

key

string

S3 object key for the uploaded video

url

string

Public URL of the uploaded video

originalName

string

Original filename

size

number

File size in bytes

mimetype

string

MIME type of the file

Example Request:

curl -X POST "https://api.steerai.autos/v1/360/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "video=@exterior_360.mp4" \
  -F "side=OUTSIDE"

Get Processed Frames

GET

endpoint

/360/frames

Retrieve extracted frames from a processed 360 video with signed URLs. Query Parameters:

jobId

string

required

Job ID from video upload

side

enum

required

Vehicle side: OUTSIDE, INSIDE, OPEN

Response:

{
  "success": true,
  "message": "Frames retrieved successfully",
  "data": {
    "message": "360 frames found",
    "jobId": "job_550e8400-e29b-41d4-a716",
    "side": "OUTSIDE",
    "frames": [
      "https://s3.amazonaws.com/bucket/360/frames/job_550e8400/OUTSIDE/frame_001.jpg?X-Amz-Signature=...",
      "https://s3.amazonaws.com/bucket/360/frames/job_550e8400/OUTSIDE/frame_002.jpg?X-Amz-Signature=...",
      "https://s3.amazonaws.com/bucket/360/frames/job_550e8400/OUTSIDE/frame_003.jpg?X-Amz-Signature=..."
    ],
    "frameCount": 72
  }
}

Response Fields:

frames

array

Array of signed URLs for frame images (valid for 1 hour)

frameCount

number

Total number of extracted frames

Frame URLs are signed and expire after 1 hour. Generate new URLs by calling this endpoint again.

Get Mask Frames

GET

endpoint

/360/mask-frames

Retrieve processed mask frames (used for AI detection overlays) with signed URLs. Query Parameters:

carId

string

required

Vehicle UUID

side

enum

required

Vehicle side: OUTSIDE, INSIDE, OPEN

Response:

{
  "success": true,
  "message": "Mask frames retrieved successfully",
  "data": {
    "message": "360 mask frames found",
    "carId": "car_550e8400-e29b-41d4-a716",
    "side": "OUTSIDE",
    "frames": [
      "https://s3.amazonaws.com/bucket/360/masks/car_550e8400/OUTSIDE/mask_001.png?X-Amz-Signature=...",
      "https://s3.amazonaws.com/bucket/360/masks/car_550e8400/OUTSIDE/mask_002.png?X-Amz-Signature=..."
    ],
    "frameCount": 72
  }
}

Mask frames show AI-detected damage areas overlaid on the vehicle images.

Cleanup 360 Data

POST

endpoint

/360/cleanup

Delete 360 video data and frames for a specific vehicle and side. Used to manage storage and remove outdated content. Request Body:

{
  "carId": "car_550e8400-e29b-41d4-a716",
  "side": "OUTSIDE",
  "removeProcessed": true
}

carId

string

required

Vehicle UUID

side

enum

required

Vehicle side: OUTSIDE, INSIDE, OPEN

removeProcessed

boolean

Also remove processed frames (default: true)

Response:

{
  "success": true,
  "message": "360 data cleaned up successfully",
  "data": {
    "filesDeleted": 73,
    "rawVideoDeleted": true,
    "framesDeleted": true,
    "masksDeleted": true
  }
}

This operation permanently deletes video and frame data. This action cannot be undone.

360 Video Workflow

Vehicle Sides Explained

OUTSIDE

Complete exterior 360-degree view showing:

All four sides of the vehicle
Wheels and tires
Exterior condition
Paint quality
Body damage or dents

Best Practice: Walk around the vehicle in a complete circle, keeping the phone/camera at consistent height.

INSIDE

Complete interior 360-degree view showing:

Dashboard and controls
Front and rear seats
Center console
Interior condition
All cabin features

Best Practice: Record from the driver’s seat, then passenger side for full coverage.

OPEN

Open compartments and storage:

Trunk/boot space
Engine bay
Under hood inspection
Storage compartments

Best Practice: Position camera to show full depth and all visible components.

File Size Considerations

Quality	Resolution	Duration	Approx. Size	Recommended
Standard	1080p	30-60s	20-40 MB	✅ Yes
High	2K	30-60s	40-70 MB	✅ Yes
Ultra	4K	30-60s	70-100 MB	⚠️ Max limit
Too Large	4K+	60s+	100+ MB	❌ Exceeds limit

Files larger than 100MB will be rejected. Compress videos if necessary while maintaining quality.

Frame Extraction Details

Automatic Extraction

Frame Rate: 5 frames per second (configurable)
Total Frames: ~60-120 frames per video
Format: JPEG images (optimized quality)
Resolution: Maintains source resolution
Processing Time: 1-3 minutes typical

Frame Naming Convention

Frames are named sequentially:

frame_001.jpg
frame_002.jpg
frame_003.jpg
...
frame_072.jpg

Use Cases

Example 1: Complete Vehicle Upload

# Upload exterior 360 video
curl -X POST "https://api.steerai.autos/v1/360/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "video=@exterior_360.mp4" \
  -F "side=OUTSIDE"

# Upload interior 360 video
curl -X POST "https://api.steerai.autos/v1/360/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "video=@interior_360.mp4" \
  -F "side=INSIDE"

# Upload trunk/engine 360 video
curl -X POST "https://api.steerai.autos/v1/360/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "video=@open_360.mp4" \
  -F "side=OPEN"

Example 2: Retrieve and Display Frames

// Fetch frames after processing
async function get360Frames(jobId, side) {
  const response = await fetch(
    `https://api.steerai.autos/v1/360/frames?jobId=${jobId}&side=${side}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const { data } = await response.json();
  return data.frames;
}

// Display in 360 viewer
async function display360View(jobId) {
  const frames = await get360Frames(jobId, 'OUTSIDE');

  // Initialize 360 viewer library
  const viewer = new Viewer360({
    container: '#viewer-container',
    frames: frames,
    autoRotate: true,
    rotationSpeed: 2
  });
}

Example 3: Storage Management

# Clean up old 360 data
curl -X POST "https://api.steerai.autos/v1/360/cleanup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "carId": "car_550e8400-e29b-41d4-a716",
    "side": "OUTSIDE",
    "removeProcessed": true
  }'

Error Codes

Code	Status	Description
`FILE_TOO_LARGE`	413	Video exceeds 100MB limit
`INVALID_FILE_TYPE`	400	Unsupported video format
`MISSING_VIDEO_FILE`	400	No video file provided
`INVALID_SIDE`	400	Invalid vehicle side specified
`JOB_NOT_FOUND`	404	Processing job ID not found
`FRAMES_NOT_READY`	404	Frames not yet processed
`UPLOAD_FAILED`	500	S3 upload error
`PROCESSING_FAILED`	500	Frame extraction failed

Best Practices

Record in good lighting

Natural daylight or well-lit showroom provides best results. Avoid shadows and glare.

Maintain consistent speed

Walk at a steady pace around the vehicle. Too fast creates blurry frames.

Keep camera level

Maintain consistent height and angle for professional-looking results.

Clean the vehicle first

Remove dirt, debris, and clutter for the best presentation.

Check file size before upload

Compress large videos while maintaining quality to stay under 100MB limit.

Upload all three sides

Complete OUTSIDE, INSIDE, and OPEN views provide comprehensive coverage.

Regularly cleanup old data

Use the cleanup endpoint to manage storage costs and remove outdated videos.

Integration with Vehicles API

The 360 Video API integrates seamlessly with the Vehicles API:

// Complete vehicle listing workflow
async function createVehicleWith360(vehicleData, videoFiles) {
  // Step 1: Create vehicle
  const vehicle = await createVehicle(vehicleData);

  // Step 2: Upload 360 videos
  const outsideJob = await upload360Video(videoFiles.outside, 'OUTSIDE');
  const insideJob = await upload360Video(videoFiles.inside, 'INSIDE');
  const openJob = await upload360Video(videoFiles.open, 'OPEN');

  // Step 3: Wait for processing
  await waitForProcessing([outsideJob.jobId, insideJob.jobId, openJob.jobId]);

  // Step 4: Get frames
  const outsideFrames = await get360Frames(outsideJob.jobId, 'OUTSIDE');
  const insideFrames = await get360Frames(insideJob.jobId, 'INSIDE');
  const openFrames = await get360Frames(openJob.jobId, 'OPEN');

  // Step 5: Update vehicle with frame URLs
  await updateVehicle(vehicle.id, {
    media360: {
      outside: outsideFrames,
      inside: insideFrames,
      open: openFrames
    }
  });

  return vehicle;
}

Vehicles API

Manage vehicle inventory and listings

Visual Inspection API

AI-powered damage detection

Media Best Practices

Guidelines for vehicle photography and video

Storage Management

Optimize media storage costs

API Documentation

​Overview

​Key Features

Video Upload

Frame Extraction

Multiple Sides

Cloud Storage

​Supported Video Formats

​Endpoints

​Upload 360 Video

​Get Processed Frames

​Get Mask Frames

​Cleanup 360 Data

​360 Video Workflow

​Vehicle Sides Explained

​OUTSIDE

​INSIDE

​OPEN

​File Size Considerations

​Frame Extraction Details

​Automatic Extraction

​Frame Naming Convention

​Use Cases

​Example 1: Complete Vehicle Upload

​Example 2: Retrieve and Display Frames

​Example 3: Storage Management

​Error Codes

​Best Practices

​Integration with Vehicles API

​Related Resources

Vehicles API

Visual Inspection API

Media Best Practices

Storage Management

Overview

Key Features

Supported Video Formats

Endpoints

Upload 360 Video

Get Processed Frames

Get Mask Frames

Cleanup 360 Data

360 Video Workflow

Vehicle Sides Explained

OUTSIDE

INSIDE

OPEN

File Size Considerations

Frame Extraction Details

Automatic Extraction

Frame Naming Convention

Use Cases

Example 1: Complete Vehicle Upload

Example 2: Retrieve and Display Frames

Example 3: Storage Management

Error Codes

Best Practices

Integration with Vehicles API

Related Resources