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

# Erste Schritte

> Erfahren Sie, wie Sie stilisierte Untertitel zu vertikalen Videos hinzufügen.

# Übersicht

Mit der Mirage API können Sie das Audio Ihres Videos automatisch transkribieren und schön animierte Untertitel direkt auf das Video rendern. Wählen Sie aus einer Vielzahl von Untertitelvorlagen, die zu Ihrer Marke oder kreativen Vision passen.

## Voraussetzungen

Erstellen Sie einen API-Schlüssel im [Plattform-Dashboard](https://platform.mirage.app/).

## 1) Untertitelvorlage auswählen

Um Untertitel zu Videos hinzuzufügen, ist eine Untertitelvorlage erforderlich. Durchsuchen Sie alle verfügbaren Vorlagen in der [Untertitelvorlagen-Galerie](/help/docs/de/api/video-caption-templates) oder rufen Sie sie [programmgesteuert](https://help.mirage.app/api-reference/video-captions/list-caption-templates) ab.

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

**Untertitelvorlage-ID**

```
ctpl_DxflLOnuKkb198FNdI9E
```

## 2) Untertitel zum Video hinzufügen

Senden Sie Ihr Video zusammen mit einer Untertitelvorlage-ID. Sie können eine Videodatei direkt hochladen oder auf eine vorhandene Video-ID aus einer früheren Generierung verweisen.

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

  # Oder verwende eine vorhandene Video-ID statt eines Uploads:
  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"));

  // Oder verwende eine vorhandene Video-ID statt eines Uploads:
  // 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>

**Antwort (Beispiel)**

```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) Job-Status prüfen

Abfragen, bis der Status `COMPLETE` ist.

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

**Statuswerte**

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

## 4) Video herunterladen

Wenn der Status `COMPLETE` ist, laden Sie Ihr untertiteltes Video herunter.

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

## Videoanforderungen

* **Seitenverhältnis:** 9:16 (vertikal/Hochformat)
* **Maximale Dateigröße:** 50 MB
* **Maximale Dauer:** 5 Minuten
* **Formate:** MP4, MOV

## API-Referenz

* [**Untertitel hinzufügen**](https://help.mirage.app/api-reference/video-captions/add-captions)
* [**Untertitelvorlagen auflisten**](https://help.mirage.app/api-reference/video-captions/list-caption-templates)
* [**Untertitelvorlage abrufen**](https://help.mirage.app/api-reference/video-captions/retrieve-caption-template)
* [**Video abrufen**](https://help.mirage.app/api-reference/videos/retrieve-video)
* [**Videoinhalt abrufen**](https://help.mirage.app/api-reference/videos/retrieve-video-content)