> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# API für 360-Grad-Video

> 360-Grad-Fahrzeugvideos hochladen und für immersive Inspektionen verarbeiten

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

<CardGroup cols={2}>
  <Card title="Video-Upload" icon="upload">
    360-Grad-Videos bis 100MB pro Datei hochladen
  </Card>

  <Card title="Frame-Extraktion" icon="images">
    Automatische Frame-Extraktion in optimalen Intervallen
  </Card>

  <Card title="Mehrere Seiten" icon="car-side">
    Unterstützung für OUTSIDE, INSIDE und OPEN (Kofferraum/Motorhaube)
  </Card>

  <Card title="Cloud-Speicher" icon="cloud">
    Sicherer S3-Speicher mit Zugriff per signierter URL
  </Card>
</CardGroup>

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

<ParamField path="POST" type="endpoint">
  /360/upload
</ParamField>

Lädt eine 360-Grad-Videodatei nach S3 hoch und startet die Frame-Extraktion.

**Content Type:** `multipart/form-data`

**Form-Parameter:**

<ParamField body="video" type="file" required>
  Videodatei (max 100MB)
</ParamField>

<ParamField body="side" type="enum" required>
  Fahrzeugseite: `OUTSIDE`, `INSIDE`, `OPEN`
</ParamField>

**Antwort:**

```json theme={null}
{
  "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:**

<ResponseField name="jobId" type="string">
  Eindeutige Job-ID zur Verfolgung des Verarbeitungsstatus
</ResponseField>

<ResponseField name="key" type="string">
  S3-Objektschlüssel für das hochgeladene Video
</ResponseField>

<ResponseField name="url" type="string">
  Öffentliche URL des hochgeladenen Videos
</ResponseField>

<ResponseField name="originalName" type="string">
  Originaler Dateiname
</ResponseField>

<ResponseField name="size" type="number">
  Dateigröße in Bytes
</ResponseField>

<ResponseField name="mimetype" type="string">
  MIME-Typ der Datei
</ResponseField>

**Beispielanfrage:**

```bash theme={null}
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

<ParamField path="GET" type="endpoint">
  /360/frames
</ParamField>

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

**Query-Parameter:**

<ParamField query="jobId" type="string" required>
  Job-ID aus dem Video-Upload
</ParamField>

<ParamField query="side" type="enum" required>
  Fahrzeugseite: `OUTSIDE`, `INSIDE`, `OPEN`
</ParamField>

**Antwort:**

```json theme={null}
{
  "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:**

<ResponseField name="frames" type="array">
  Array signierter URLs für Frame-Bilder (1 Stunde gültig)
</ResponseField>

<ResponseField name="frameCount" type="number">
  Gesamtzahl der extrahierten Frames
</ResponseField>

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

***

### Masken-Frames abrufen

<ParamField path="GET" type="endpoint">
  /360/mask-frames
</ParamField>

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

**Query-Parameter:**

<ParamField query="carId" type="string" required>
  Fahrzeug-UUID
</ParamField>

<ParamField query="side" type="enum" required>
  Fahrzeugseite: `OUTSIDE`, `INSIDE`, `OPEN`
</ParamField>

**Antwort:**

```json theme={null}
{
  "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
  }
}
```

<Info>
  Masken-Frames zeigen KI-erkanntes Schadens-Overlay auf den Fahrzeugbildern.
</Info>

***

### 360-Daten bereinigen

<ParamField path="POST" type="endpoint">
  /360/cleanup
</ParamField>

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:**

```json theme={null}
{
  "carId": "car_550e8400-e29b-41d4-a716",
  "side": "OUTSIDE",
  "removeProcessed": true
}
```

<ParamField body="carId" type="string" required>
  Fahrzeug-UUID
</ParamField>

<ParamField body="side" type="enum" required>
  Fahrzeugseite: `OUTSIDE`, `INSIDE`, `OPEN`
</ParamField>

<ParamField body="removeProcessed" type="boolean">
  Entfernt auch verarbeitete Frames (Standard: true)
</ParamField>

**Antwort:**

```json theme={null}
{
  "success": true,
  "message": "360 data cleaned up successfully",
  "data": {
    "filesDeleted": 73,
    "rawVideoDeleted": true,
    "framesDeleted": true,
    "masksDeleted": true
  }
}
```

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

***

## 360-Video-Workflow

```mermaid theme={null}
graph TD
    A[Record 360 Video] --> B[Upload Video]
    B --> C[Video Stored in S3]
    C --> D[Processing Job Created]
    D --> E[Frame Extraction]
    E --> F[Store Frames in S3]
    F --> G[AI Damage Detection]
    G --> H[Generate Mask Frames]
    H --> I[Frames Ready]
    I --> J[Display 360 Viewer]
    J --> K{Need to Update?}
    K -->|Yes| L[Cleanup Old Data]
    L --> A
    K -->|No| M[Keep Displaying]

    style B fill:#282F75
    style I fill:#4360B1
    style J fill:#28a745
```

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

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

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

```bash theme={null}
# 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

```javascript theme={null}
// 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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Bei guter Beleuchtung aufnehmen">
    Tageslicht oder gut ausgeleuchteter Showroom liefern die besten Ergebnisse. Schatten und Blendung vermeiden.
  </Accordion>

  <Accordion title="Konstante Geschwindigkeit halten">
    Gehen Sie gleichmäßig um das Fahrzeug. Zu schnell erzeugt unscharfe Frames.
  </Accordion>

  <Accordion title="Kamera waagerecht halten">
    Konstante Höhe und Winkel sorgen für professionelle Ergebnisse.
  </Accordion>

  <Accordion title="Fahrzeug vorher reinigen">
    Entfernen Sie Schmutz und Unordnung für die beste Präsentation.
  </Accordion>

  <Accordion title="Dateigröße vor Upload prüfen">
    Große Videos komprimieren, ohne die Qualität zu stark zu reduzieren, um unter 100MB zu bleiben.
  </Accordion>

  <Accordion title="Alle drei Seiten hochladen">
    Vollständige OUTSIDE-, INSIDE- und OPEN-Ansichten bieten umfassende Abdeckung.
  </Accordion>

  <Accordion title="Regelmäßig alte Daten bereinigen">
    Nutzen Sie den Cleanup-Endpunkt, um Speicher zu verwalten und veraltete Videos zu entfernen.
  </Accordion>
</AccordionGroup>

## Integration mit der Vehicles API

Die 360-Video-API integriert sich nahtlos mit der Vehicles API:

```javascript theme={null}
// 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;
}
```

## Verwandte Ressourcen

<CardGroup cols={2}>
  <Card title="Fahrzeuge-API" icon="car" href="/de/api-reference/vehicles/overview">
    Fahrzeugbestand und Inserate verwalten
  </Card>

  <Card title="API für visuelle Inspektion" icon="camera" href="/de/api-reference/inspection/visual-inspection">
    KI-gestützte Schadenserkennung
  </Card>

  <Card title="Media Best Practices" icon="images" href="/de/guides/media-best-practices">
    Leitlinien für Fahrzeugfotos und -videos
  </Card>

  <Card title="Speicherverwaltung" icon="database" href="/de/guides/storage-management">
    Medien-Speicherkosten optimieren
  </Card>
</CardGroup>