API für 360-Grad-Video

Überblick

Die 360-Grad-Video-API ermöglicht das Hochladen von 360-Grad-Fahrzeugvideos, die automatische Extraktion von Frames und die Generierung interaktiver 360-Ansichten für ein besseres Kundenerlebnis. Ideal für Außenansichten, Innenräume und detaillierte Inspektionen.

Hauptfunktionen

Video-Upload

360-Grad-Videos bis 100MB pro Datei hochladen

Frame-Extraktion

Automatische Frame-Extraktion in optimalen Intervallen

Mehrere Seiten

Unterstützung für OUTSIDE, INSIDE und OPEN (Kofferraum/Motorhaube)

Cloud-Speicher

Sicherer S3-Speicher mit Zugriff per signierter URL

Unterstützte Videoformate

Die API akzeptiert folgende Videoformate:

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

Endpunkte

360-Video hochladen

POST

endpoint

/360/upload

Lädt eine 360-Grad-Videodatei nach S3 hoch und startet die Frame-Extraktion. Content Type: multipart/form-data Form-Parameter:

video

file

erforderlich

Videodatei (max 100MB)

side

enum

erforderlich

Fahrzeugseite: OUTSIDE, INSIDE, OPEN

Antwort:

{
  "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"
    }
  }
}

Antwortfelder:

jobId

string

Eindeutige Job-ID zur Verfolgung des Verarbeitungsstatus

key

string

S3-Objektschlüssel für das hochgeladene Video

url

string

Öffentliche URL des hochgeladenen Videos

originalName

string

Originaler Dateiname

size

number

Dateigröße in Bytes

mimetype

string

MIME-Typ der Datei

Beispielanfrage:

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

Verarbeitete Frames abrufen

GET

endpoint

/360/frames

Ruft extrahierte Frames aus einem verarbeiteten 360-Video mit signierten URLs ab. Query-Parameter:

jobId

string

erforderlich

Job-ID aus dem Video-Upload

side

enum

erforderlich

Fahrzeugseite: OUTSIDE, INSIDE, OPEN

Antwort:

{
  "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
  }
}

Antwortfelder:

frames

array

Array signierter URLs für Frame-Bilder (1 Stunde gültig)

frameCount

number

Gesamtzahl der extrahierten Frames

Frame-URLs sind signiert und nach 1 Stunde abgelaufen. Neue URLs erhalten Sie durch erneuten Aufruf dieses Endpunkts.

Masken-Frames abrufen

GET

endpoint

/360/mask-frames

Ruft verarbeitete Masken-Frames (für KI-Overlay) mit signierten URLs ab. Query-Parameter:

carId

string

erforderlich

Fahrzeug-UUID

side

enum

erforderlich

Fahrzeugseite: OUTSIDE, INSIDE, OPEN

Antwort:

{
  "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
  }
}

Masken-Frames zeigen KI-erkanntes Schadens-Overlay auf den Fahrzeugbildern.

360-Daten bereinigen

POST

endpoint

/360/cleanup

Löscht 360-Video-Daten und Frames für ein bestimmtes Fahrzeug und eine Seite. Wird genutzt, um Speicher zu verwalten und veraltete Inhalte zu entfernen. Anfrage-Body:

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

carId

string

erforderlich

Fahrzeug-UUID

side

enum

erforderlich

Fahrzeugseite: OUTSIDE, INSIDE, OPEN

removeProcessed

boolean

Entfernt auch verarbeitete Frames (Standard: true)

Antwort:

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

Dieser Vorgang löscht Video- und Frame-Daten dauerhaft. Diese Aktion kann nicht rückgängig gemacht werden.

360-Video-Workflow

Fahrzeugseiten erklärt

OUTSIDE

Komplette Außenansicht in 360 Grad:

Alle vier Seiten des Fahrzeugs
Räder und Reifen
Außenzustand
Lackqualität
Karosserieschäden oder Dellen

Best Practice: Gehen Sie in einem vollständigen Kreis um das Fahrzeug, mit konstanter Höhe der Kamera.

INSIDE

Komplette Innenraumansicht in 360 Grad:

Dashboard und Bedienelemente
Vordersitze und Rücksitze
Mittelkonsole
Innenraumzustand
Alle Kabinen-Features

Best Practice: Zuerst vom Fahrersitz, dann von der Beifahrerseite für vollständige Abdeckung aufnehmen.

OPEN

Geöffnete Bereiche und Stauraum:

Kofferraum/Heckklappe
Motorraum
Inspektion unter der Haube
Staufächer

Best Practice: Kamera so positionieren, dass volle Tiefe und alle sichtbaren Komponenten erfasst sind.

Dateigröße

Qualität	Auflösung	Dauer	Ca. Größe	Empfohlen
Standard	1080p	30-60s	20-40 MB	✅ Ja
Hoch	2K	30-60s	40-70 MB	✅ Ja
Ultra	4K	30-60s	70-100 MB	⚠️ Max-Limit
Zu groß	4K+	60s+	100+ MB	❌ Überschreitet Limit

Dateien über 100MB werden abgelehnt. Komprimieren Sie Videos bei Bedarf und halten Sie die Qualität.

Frame-Extraktion – Details

Automatische Extraktion

Frame Rate: 5 Frames pro Sekunde (konfigurierbar)
Total Frames: ~60-120 Frames pro Video
Format: JPEG-Bilder (optimierte Qualität)
Auflösung: Beibehaltung der Quellauflösung
Verarbeitungszeit: 1-3 Minuten typisch

Frame-Benennung

Frames werden fortlaufend benannt:

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

Anwendungsfälle

Beispiel 1: Vollständiger Fahrzeug-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"

Beispiel 2: Frames abrufen und anzeigen

// 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
  });
}

Beispiel 3: Speicherverwaltung

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

Fehlercodes

Code	Status	Beschreibung
`FILE_TOO_LARGE`	413	Video überschreitet 100MB-Limit
`INVALID_FILE_TYPE`	400	Nicht unterstütztes Videoformat
`MISSING_VIDEO_FILE`	400	Keine Videodatei übergeben
`INVALID_SIDE`	400	Ungültige Fahrzeugseite angegeben
`JOB_NOT_FOUND`	404	Verarbeitungsjob-ID nicht gefunden
`FRAMES_NOT_READY`	404	Frames noch nicht verarbeitet
`UPLOAD_FAILED`	500	S3-Upload-Fehler
`PROCESSING_FAILED`	500	Frame-Extraktion fehlgeschlagen

Bewährte Praktiken

Bei guter Beleuchtung aufnehmen

Tageslicht oder gut ausgeleuchteter Showroom liefern die besten Ergebnisse. Schatten und Blendung vermeiden.

Konstante Geschwindigkeit halten

Gehen Sie gleichmäßig um das Fahrzeug. Zu schnell erzeugt unscharfe Frames.

Kamera waagerecht halten

Konstante Höhe und Winkel sorgen für professionelle Ergebnisse.

Fahrzeug vorher reinigen

Entfernen Sie Schmutz und Unordnung für die beste Präsentation.

Dateigröße vor Upload prüfen

Große Videos komprimieren, ohne die Qualität zu stark zu reduzieren, um unter 100MB zu bleiben.

Alle drei Seiten hochladen

Vollständige OUTSIDE-, INSIDE- und OPEN-Ansichten bieten umfassende Abdeckung.

Regelmäßig alte Daten bereinigen

Nutzen Sie den Cleanup-Endpunkt, um Speicher zu verwalten und veraltete Videos zu entfernen.

Integration mit der Vehicles API

Die 360-Video-API integriert sich nahtlos mit der 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;
}

Fahrzeuge-API

Fahrzeugbestand und Inserate verwalten

API für visuelle Inspektion

KI-gestützte Schadenserkennung

Media Best Practices

Leitlinien für Fahrzeugfotos und -videos

Speicherverwaltung

Medien-Speicherkosten optimieren

API-Dokumentation

Überblick

Hauptfunktionen

Video-Upload

Frame-Extraktion

Mehrere Seiten

Cloud-Speicher

Unterstützte Videoformate

Endpunkte

360-Video hochladen

Verarbeitete Frames abrufen

Masken-Frames abrufen

360-Daten bereinigen

360-Video-Workflow

Fahrzeugseiten erklärt

OUTSIDE

INSIDE

OPEN

Dateigröße

Frame-Extraktion – Details

Automatische Extraktion

Frame-Benennung

Anwendungsfälle

Beispiel 1: Vollständiger Fahrzeug-Upload

Beispiel 2: Frames abrufen und anzeigen

Beispiel 3: Speicherverwaltung

Fehlercodes

Bewährte Praktiken

Integration mit der Vehicles API

Verwandte Ressourcen

Fahrzeuge-API

API für visuelle Inspektion

Media Best Practices

Speicherverwaltung

API-Dokumentation

​Überblick

​Hauptfunktionen

Video-Upload

Frame-Extraktion

Mehrere Seiten

Cloud-Speicher

​Unterstützte Videoformate

​Endpunkte

​360-Video hochladen

​Verarbeitete Frames abrufen

​Masken-Frames abrufen

​360-Daten bereinigen

​360-Video-Workflow

​Fahrzeugseiten erklärt

​OUTSIDE

​INSIDE

​OPEN

​Dateigröße

​Frame-Extraktion – Details

​Automatische Extraktion

​Frame-Benennung

​Anwendungsfälle

​Beispiel 1: Vollständiger Fahrzeug-Upload

​Beispiel 2: Frames abrufen und anzeigen

​Beispiel 3: Speicherverwaltung

​Fehlercodes

​Bewährte Praktiken

​Integration mit der Vehicles API

​Verwandte Ressourcen

Fahrzeuge-API

API für visuelle Inspektion

Media Best Practices

Speicherverwaltung

Überblick

Hauptfunktionen

Unterstützte Videoformate

Endpunkte

360-Video hochladen

Verarbeitete Frames abrufen

Masken-Frames abrufen

360-Daten bereinigen

360-Video-Workflow

Fahrzeugseiten erklärt

OUTSIDE

INSIDE

OPEN

Dateigröße

Frame-Extraktion – Details

Automatische Extraktion

Frame-Benennung

Anwendungsfälle

Beispiel 1: Vollständiger Fahrzeug-Upload

Beispiel 2: Frames abrufen und anzeigen

Beispiel 3: Speicherverwaltung

Fehlercodes

Bewährte Praktiken

Integration mit der Vehicles API

Verwandte Ressourcen