API de video 360 - Steer Autos Documentation

Resumen

La API de video 360 permite subir videos 360 de vehiculos, extraer frames automaticamente y generar vistas 360 interactivas. Ideal para mostrar exteriores, interiores y detalles.

Funcionalidades clave

Carga de video

Sube videos 360 hasta 100MB por archivo

Extraccion de frames

Extraccion automatica en intervalos optimos

Multiples lados

Soporte para vistas OUTSIDE, INSIDE y OPEN (baul/capo)

Almacenamiento en la nube

S3 seguro con URLs firmadas

Formatos de video soportados

La API acepta:

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

Endpoints

Subir video 360

POST

endpoint

/360/upload

Sube un video 360 a S3 y dispara extraccion de frames. Content Type: multipart/form-data Form Parameters:

video

file

requerido

Archivo de video (max 100MB)

side

enum

requerido

Lado del vehiculo: 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"
    }
  }
}

Campos de respuesta:

jobId

string

Identificador unico del job para seguimiento

key

string

Key en S3 del video subido

url

string

URL publica del video

originalName

string

Nombre original del archivo

size

number

Tamano del archivo en bytes

mimetype

string

Tipo MIME del archivo

Ejemplo de 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"

Obtener frames procesados

GET

endpoint

/360/frames

Obtiene frames extraidos con URLs firmadas. Query Parameters:

jobId

string

requerido

Job ID del upload

side

enum

requerido

Lado del vehiculo: 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
  }
}

Campos de respuesta:

frames

array

Arreglo de URLs firmadas (validas por 1 hora)

frameCount

number

Total de frames extraidos

Las URLs expiran en 1 hora. Genera nuevas URLs llamando este endpoint otra vez.

Obtener mask frames

GET

endpoint

/360/mask-frames

Obtiene mask frames (usados para overlays de deteccion IA) con URLs firmadas. Query Parameters:

carId

string

requerido

Vehicle UUID

side

enum

requerido

Lado del vehiculo: 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
  }
}

Los mask frames muestran danos detectados por IA sobre las imagenes.

Limpiar datos 360

POST

endpoint

/360/cleanup

Elimina videos 360 y frames de un vehiculo y lado especifico. Request Body:

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

carId

string

requerido

Vehicle UUID

side

enum

requerido

Lado del vehiculo: OUTSIDE, INSIDE, OPEN

removeProcessed

boolean

Eliminar frames procesados (default: true)

Response:

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

Esta operacion elimina datos permanentemente. No se puede deshacer.

Flujo de video 360

Lados del vehiculo explicados

OUTSIDE

Vista exterior completa:

Los cuatro lados del vehiculo
Llantas y ruedas
Condicion exterior
Calidad de pintura
Danos en carroceria

Best Practice: Camina alrededor en circulo completo, manteniendo altura consistente.

INSIDE

Vista interior completa:

Tablero y controles
Asientos delanteros y traseros
Consola central
Condicion interior
Todas las funciones de cabina

Best Practice: Graba desde el asiento del conductor y luego el lado pasajero.

OPEN

Compartimientos abiertos:

Baul
Compartimiento del motor
Inspeccion bajo el capot
Compartimientos de almacenamiento

Best Practice: Posiciona la camara para mostrar profundidad y componentes.

Consideraciones de tamano de archivo

Calidad	Resolucion	Duracion	Tamano aprox.	Recomendado
Standard	1080p	30-60s	20-40 MB	✅ Si
High	2K	30-60s	40-70 MB	✅ Si
Ultra	4K	30-60s	70-100 MB	⚠️ Limite
Too Large	4K+	60s+	100+ MB	❌ Excede

Archivos mayores a 100MB seran rechazados. Comprime si es necesario sin perder calidad.

Detalles de extraccion de frames

Extraccion automatica

Frame Rate: 5 frames por segundo (configurable)
Total Frames: ~60-120 frames por video
Formato: JPEG (calidad optimizada)
Resolucion: Mantiene resolucion de origen
Tiempo de proceso: 1-3 minutos

Convencion de nombres

Los frames se nombran secuencialmente:

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

Casos de uso

Ejemplo 1: Carga completa de vehiculo

# 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"

Ejemplo 2: Obtener y mostrar 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
  });
}

Ejemplo 3: Gestion de almacenamiento

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

Codigos de error

Code	Status	Description
`FILE_TOO_LARGE`	413	Video excede limite de 100MB
`INVALID_FILE_TYPE`	400	Formato no soportado
`MISSING_VIDEO_FILE`	400	No se proporciono video
`INVALID_SIDE`	400	Lado de vehiculo invalido
`JOB_NOT_FOUND`	404	Job ID no encontrado
`FRAMES_NOT_READY`	404	Frames aun no procesados
`UPLOAD_FAILED`	500	Error al subir a S3
`PROCESSING_FAILED`	500	Error al extraer frames

Mejores practicas

Graba con buena iluminacion

Luz natural o showroom bien iluminado. Evita sombras y reflejos.

Mantén velocidad constante

Camina a paso constante. Muy rapido crea frames borrosos.

Mantén la camara nivelada

Altura y angulo consistentes para resultados profesionales.

Limpia el vehiculo primero

Quita polvo, suciedad y objetos para mejor presentacion.

Revisa tamano antes de subir

Comprime si es necesario para estar bajo 100MB.

Sube los tres lados

OUTSIDE, INSIDE y OPEN dan cobertura completa.

Limpia datos antiguos regularmente

Usa cleanup para controlar costos y remover videos antiguos.

Integracion con API de vehiculos

La API de video 360 se integra con 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;
}

Recursos relacionados

API de vehiculos

Gestiona inventario y listados

API de inspeccion visual

Deteccion de danos con IA

Mejores practicas de media

Guia para fotos y video

Gestion de almacenamiento

Optimiza costos de almacenamiento

Documentacion de la API

​Resumen

​Funcionalidades clave

Carga de video

Extraccion de frames

Multiples lados

Almacenamiento en la nube

​Formatos de video soportados

​Endpoints

​Subir video 360

​Obtener frames procesados

​Obtener mask frames

​Limpiar datos 360

​Flujo de video 360

​Lados del vehiculo explicados

​OUTSIDE

​INSIDE

​OPEN

​Consideraciones de tamano de archivo

​Detalles de extraccion de frames

​Extraccion automatica

​Convencion de nombres

​Casos de uso

​Ejemplo 1: Carga completa de vehiculo

​Ejemplo 2: Obtener y mostrar frames

​Ejemplo 3: Gestion de almacenamiento

​Codigos de error

​Mejores practicas

​Integracion con API de vehiculos

​Recursos relacionados

API de vehiculos

API de inspeccion visual

Mejores practicas de media

Gestion de almacenamiento

Resumen

Funcionalidades clave

Formatos de video soportados

Endpoints

Subir video 360

Obtener frames procesados

Obtener mask frames

Limpiar datos 360

Flujo de video 360

Lados del vehiculo explicados

OUTSIDE

INSIDE

OPEN

Consideraciones de tamano de archivo

Detalles de extraccion de frames

Extraccion automatica

Convencion de nombres

Casos de uso

Ejemplo 1: Carga completa de vehiculo

Ejemplo 2: Obtener y mostrar frames

Ejemplo 3: Gestion de almacenamiento

Codigos de error

Mejores practicas

Integracion con API de vehiculos

Recursos relacionados