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

# Premiers pas

> Apprenez à ajouter des sous-titres stylisés aux vidéos verticales.

# Aperçu

Avec l'API Mirage, vous pouvez transcrire automatiquement l'audio de votre vidéo et afficher de magnifiques sous-titres animés directement sur la vidéo. Choisissez parmi une variété de modèles de sous-titres pour correspondre à votre marque ou vision créative.

## Prérequis

Créez une clé API dans le [tableau de bord de la plateforme](https://platform.mirage.app/).

## 1) Choisir un modèle de sous-titres

L'ajout de sous-titres aux vidéos nécessite un modèle de sous-titres. Parcourez tous les modèles disponibles dans la [galerie de modèles de sous-titres](/help/docs/fr/api/video-caption-templates) ou récupérez-les [par programmation](https://help.mirage.app/api-reference/video-captions/list-caption-templates).

**Modèle d'exemple : Heat**

<div onMouseEnter={(e) => e.currentTarget.querySelector('video').play()} onMouseLeave={(e) => { const v = e.currentTarget.querySelector('video'); v.pause(); v.currentTime = 0.3; }} style={{maxWidth: '300px'}}>
  <video loop muted playsInline preload="auto" src="https://captions-cdn.xyz/studio-assets/captions-style-previews/0021BB09-AEA4-4B3B-8E93-4FBFD63FB5D0.mp4#t=0.3" />
</div>

**ID du modèle de sous-titres**

```
ctpl_DxflLOnuKkb198FNdI9E
```

## 2) Ajouter des sous-titres à une vidéo

Envoyez votre vidéo avec un ID de modèle de sous-titres. Vous pouvez télécharger un fichier vidéo directement ou référencer un ID de vidéo existant d'une génération précédente.

<CodeGroup>
  ```python Python theme={"system"}
  import requests

  url = "https://api.mirage.app/v1/videos/captions"
  headers = {
      "x-api-key": "<api-key>"
  }
  files = {
      "video": open("input.mp4", "rb")
  }
  data = {
      "caption_template_id": "ctpl_DxflLOnuKkb198FNdI9E"
  }

  # Ou utilisez un ID de vidéo existant au lieu de télécharger :
  data = {
      "caption_template_id": "ctpl_DxflLOnuKkb198FNdI9E",
      "video_id": "video_abc123def456"
  }

  response = requests.post(url, headers=headers, files=files, data=data)
  print(response.json())
  ```

  ```typescript TypeScript theme={"system"}
  const formData = new FormData();
  formData.append("caption_template_id", "ctpl_DxflLOnuKkb198FNdI9E");
  formData.append("video", await fs.readFile("input.mp4"));

  // Ou utilisez un ID de vidéo existant au lieu de télécharger :
  // formData.append("video_id", "video_abc123def456");

  const response = await fetch("https://api.mirage.app/v1/videos/captions", {
    method: "POST",
    headers: {
      "x-api-key": "<api-key>"
    },
    body: formData
  });

  const data = await response.json();
  console.log(data);
  ```

  ```bash cURL theme={"system"}
  curl --request POST \
    --url https://api.mirage.app/v1/videos/captions \
    --header 'Content-Type: multipart/form-data' \
    --header 'x-api-key: <api-key>' \
    --form caption_template_id=ctpl_DxflLOnuKkb198FNdI9E \
    --form video=@input.mp4
  ```
</CodeGroup>

**Réponse (exemple)**

```json theme={"system"}
{
  "id": "video_cap789xyz",
  "object": "video",
  "status": "PROCESSING",
  "created_at": 1730822600,
  "progress": 0,
  "source_video_id": null,
  "caption_template_id": "ctpl_DxflLOnuKkb198FNdI9E"
}
```

## 3) Vérifier le statut du job

Interrogez jusqu'à ce que le statut devienne `COMPLETE`.

<CodeGroup>
  ```python Python theme={"system"}
  import requests

  url = f"https://api.mirage.app/v1/videos/{video_id}"
  headers = {
      "x-api-key": "<api-key>"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```typescript TypeScript theme={"system"}
  const response = await fetch(`https://api.mirage.app/v1/videos/${videoId}`, {
    method: "GET",
    headers: {
      "x-api-key": "<api-key>"
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```bash cURL theme={"system"}
  curl --request GET \
    --url https://api.mirage.app/v1/videos/{video_id} \
    --header 'x-api-key: <api-key>'
  ```
</CodeGroup>

**Valeurs de statut**

* `QUEUED`
* `PROCESSING`
* `COMPLETE`
* `FAILED`
* `CANCELLED`

## 4) Télécharger la vidéo

Une fois le statut `COMPLETE`, téléchargez votre vidéo sous-titrée.

<CodeGroup>
  ```python Python theme={"system"}
  import requests

  url = f"https://api.mirage.app/v1/videos/{video_id}/content"
  headers = {
      "x-api-key": "<api-key>"
  }

  response = requests.get(url, headers=headers, allow_redirects=True)

  with open("captioned.mp4", "wb") as f:
      f.write(response.content)
  ```

  ```typescript TypeScript theme={"system"}
  const response = await fetch(`https://api.mirage.app/v1/videos/${videoId}/content`, {
    method: "GET",
    headers: {
      "x-api-key": "<api-key>"
    },
    redirect: "follow"
  });
  ```

  ```bash cURL theme={"system"}
  curl --request GET \
    --url https://api.mirage.app/v1/videos/{video_id}/content \
    --header 'x-api-key: <api-key>' \
    --location \
    --output output.mp4
  ```
</CodeGroup>

## Exigences vidéo

* **Format :** 9:16 (vertical/portrait)
* **Taille maximale :** 50 Mo
* **Durée maximale :** 5 minutes
* **Formats :** MP4, MOV

## Référence API

* [**Ajouter des sous-titres**](https://help.mirage.app/api-reference/video-captions/add-captions)
* [**Lister les modèles de sous-titres**](https://help.mirage.app/api-reference/video-captions/list-caption-templates)
* [**Récupérer un modèle de sous-titres**](https://help.mirage.app/api-reference/video-captions/retrieve-caption-template)
* [**Récupérer une vidéo**](https://help.mirage.app/api-reference/videos/retrieve-video)
* [**Récupérer le contenu vidéo**](https://help.mirage.app/api-reference/videos/retrieve-video-content)