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

> Televerser et traiter des videos de vehicules a 360 degres pour des inspections immersives

## Vue d'ensemble

L'API Video 360 vous permet de televerser des videos 360 de vehicules, d'extraire automatiquement des images et de generer des vues 360 interactives pour une meilleure experience client. Ideale pour presenter l'exterieur, l'interieur et des inspections detaillees.

## Fonctionnalites cles

<CardGroup cols={2}>
  <Card title="Televersement video" icon="upload">
    Televerser des videos 360 jusqu'a 100 Mo par fichier
  </Card>

  <Card title="Extraction d'images" icon="images">
    Extraction automatique d'images a des intervalles optimaux
  </Card>

  <Card title="Multiples cotes" icon="car-side">
    Prise en charge des vues OUTSIDE, INSIDE et OPEN (coffre/capot)
  </Card>

  <Card title="Stockage cloud" icon="cloud">
    Stockage S3 securise avec acces via URL signee
  </Card>
</CardGroup>

## Formats video pris en charge

L'API accepte les formats suivants :

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

## Endpoints

### Televerser une video 360

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

Televerser un fichier video 360 vers S3 et declencher l'extraction d'images.

**Type de contenu :** `multipart/form-data`

**Parametres de formulaire :**

<ParamField body="video" type="file" required>
  Fichier video (max 100 Mo)
</ParamField>

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

**Reponse :**

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

**Champs de reponse :**

<ResponseField name="jobId" type="string">
  Identifiant unique pour suivre le traitement
</ResponseField>

<ResponseField name="key" type="string">
  Cle d'objet S3 pour la video televersee
</ResponseField>

<ResponseField name="url" type="string">
  URL publique de la video televersee
</ResponseField>

<ResponseField name="originalName" type="string">
  Nom de fichier d'origine
</ResponseField>

<ResponseField name="size" type="number">
  Taille du fichier en octets
</ResponseField>

<ResponseField name="mimetype" type="string">
  Type MIME du fichier
</ResponseField>

**Exemple de requete :**

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

***

### Recuperer les images traitees

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

Recuperer les images extraites d'une video 360 traitee avec des URLs signees.

**Parametres de requete :**

<ParamField query="jobId" type="string" required>
  ID du job issu du televersement video
</ParamField>

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

**Reponse :**

```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
  }
}
```

**Champs de reponse :**

<ResponseField name="frames" type="array">
  Tableau d'URLs signees des images (valides 1 heure)
</ResponseField>

<ResponseField name="frameCount" type="number">
  Nombre total d'images extraites
</ResponseField>

<Info>
  Les URLs des images sont signees et expirent apres 1 heure. Regenerer les URLs en rappelant cet endpoint.
</Info>

***

### Recuperer les masques d'images

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

Recuperer les masques d'images traites (utilises pour les overlays de detection IA) avec des URLs signees.

**Parametres de requete :**

<ParamField query="carId" type="string" required>
  UUID du vehicule
</ParamField>

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

**Reponse :**

```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>
  Les masques montrent les zones de dommages detectes par l'IA superposees aux images du vehicule.
</Info>

***

### Nettoyer les donnees 360

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

Supprimer les donnees 360 et les images pour un vehicule et un cote. Utilise pour gerer le stockage et supprimer le contenu obsolete.

**Corps de requete :**

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

<ParamField body="carId" type="string" required>
  UUID du vehicule
</ParamField>

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

<ParamField body="removeProcessed" type="boolean">
  Supprimer aussi les images traitees (defaut : true)
</ParamField>

**Reponse :**

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

<Warning>
  Cette operation supprime definitivement les videos et les images. Cette action est irreversible.
</Warning>

***

## Workflow video 360

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

## Cotes du vehicule

### OUTSIDE

Vue 360 complete de l'exterieur :

* Les quatre cotes du vehicule
* Roues et pneus
* Etat exterieur
* Qualite de peinture
* Dommages ou bosses

**Bonne pratique :** Marcher autour du vehicule en cercle complet, en gardant une hauteur constante.

### INSIDE

Vue 360 complete de l'interieur :

* Tableau de bord et commandes
* Sieges avant et arriere
* Console centrale
* Etat interieur
* Toutes les fonctionnalites de l'habitacle

**Bonne pratique :** Filmer depuis le siege conducteur, puis cote passager pour une couverture complete.

### OPEN

Compartiments ouverts et stockage :

* Coffre
* Compartiment moteur
* Inspection sous capot
* Compartiments de rangement

**Bonne pratique :** Positionner la camera pour montrer toute la profondeur et les elements visibles.

## Considerations de taille de fichier

| Qualite       | Resolution | Duree  | Taille approx. | Recommande      |
| ------------- | ---------- | ------ | -------------- | --------------- |
| **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 |

<Warning>
  Les fichiers de plus de 100 Mo seront refuses. Compresser les videos si necessaire tout en conservant la qualite.
</Warning>

## Details d'extraction d'images

### Extraction automatique

* **Frame Rate:** 5 images par seconde (configurable)
* **Total Frames:** \~60-120 images par video
* **Format:** Images JPEG (qualite optimisee)
* **Resolution:** Conserve la resolution d'origine
* **Temps de traitement:** 1-3 minutes en general

### Convention de nommage des images

Les images sont nommees de facon sequentielle :

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

## Cas d'usage

### Exemple 1 : Televerser un vehicule complet

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

### Exemple 2 : Recuperer et afficher des images

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

### Exemple 3 : Gestion du stockage

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

## Codes d'erreur

| Code                 | Statut | Description                          |
| -------------------- | ------ | ------------------------------------ |
| `FILE_TOO_LARGE`     | 413    | La video depasse la limite de 100 Mo |
| `INVALID_FILE_TYPE`  | 400    | Format video non pris en charge      |
| `MISSING_VIDEO_FILE` | 400    | Aucun fichier video fourni           |
| `INVALID_SIDE`       | 400    | Cote du vehicule invalide            |
| `JOB_NOT_FOUND`      | 404    | ID de job introuvable                |
| `FRAMES_NOT_READY`   | 404    | Les images ne sont pas encore pretes |
| `UPLOAD_FAILED`      | 500    | Erreur de televersement S3           |
| `PROCESSING_FAILED`  | 500    | Echec de l'extraction d'images       |

## Bonnes pratiques

<AccordionGroup>
  <Accordion title="Filmer avec un bon eclairage">
    La lumiere naturelle ou un showroom bien eclaire donne les meilleurs resultats. Evitez les ombres et les reflets.
  </Accordion>

  <Accordion title="Garder une vitesse constante">
    Marchez a un rythme regulier autour du vehicule. Trop vite cree des images floues.
  </Accordion>

  <Accordion title="Garder la camera a niveau">
    Conservez une hauteur et un angle constants pour un rendu professionnel.
  </Accordion>

  <Accordion title="Nettoyer le vehicule avant">
    Retirez la salete, les debris et le desordre pour la meilleure presentation.
  </Accordion>

  <Accordion title="Verifier la taille du fichier avant televersement">
    Compressez les grandes videos tout en conservant la qualite pour rester sous 100 Mo.
  </Accordion>

  <Accordion title="Televerser les trois cotes">
    Les vues OUTSIDE, INSIDE et OPEN offrent une couverture complete.
  </Accordion>

  <Accordion title="Nettoyer regulierement les anciennes donnees">
    Utilisez l'endpoint de nettoyage pour gerer les couts de stockage et supprimer les videos obsoletes.
  </Accordion>
</AccordionGroup>

## Integration avec l'API Vehicles

L'API Video 360 s'integre parfaitement a l'API Vehicles :

```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;
}
```

## Ressources associees

<CardGroup cols={2}>
  <Card title="API Vehicules" icon="car" href="/fr/api-reference/vehicles/overview">
    Gerer l'inventaire et les annonces de vehicules
  </Card>

  <Card title="API d'inspection visuelle" icon="camera" href="/fr/api-reference/inspection/visual-inspection">
    Detection de dommages pilotee par IA
  </Card>

  <Card title="Bonnes pratiques media" icon="images" href="/fr/guides/media-best-practices">
    Conseils pour la photo et la video automobile
  </Card>

  <Card title="Gestion du stockage" icon="database" href="/fr/guides/storage-management">
    Optimiser les couts de stockage media
  </Card>
</CardGroup>