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

# Introdução

> Aprenda a adicionar legendas estilizadas a vídeos verticais.

# Visão Geral

Com a API Mirage, você pode transcrever automaticamente o áudio do seu vídeo e renderizar legendas animadas diretamente no vídeo. Escolha entre uma variedade de modelos de legenda para combinar com sua marca ou visão criativa.

## Pré-requisitos

Crie uma chave de API no [painel da plataforma](https://platform.mirage.app/).

## 1) Escolha um Modelo de Legenda

Adicionar legendas a vídeos requer um modelo de legenda. Explore todos os modelos disponíveis na [galeria de modelos de legenda](/help/docs/pt/api/video-caption-templates) ou obtenha-os [programaticamente](https://help.mirage.app/api-reference/video-captions/list-caption-templates).

**Modelo de Exemplo: 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 do Modelo de Legenda**

```
ctpl_DxflLOnuKkb198FNdI9E
```

## 2) Adicionar Legendas a um Vídeo

Envie seu vídeo junto com um ID de modelo de legenda. Você pode fazer upload de um arquivo de vídeo diretamente ou referenciar um ID de vídeo existente de uma geração anterior.

<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 use um ID de vídeo existente em vez de fazer upload:
  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 use um ID de vídeo existente em vez de fazer upload:
  // 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>

**Resposta (exemplo)**

```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) Verificar Status do Job

Verifique periodicamente até que o status seja `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>

**Valores de status**

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

## 4) Baixar o Vídeo

Quando o status for `COMPLETE`, baixe seu vídeo legendado.

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

## Requisitos de vídeo

* **Proporção:** 9:16 (vertical/retrato)
* **Tamanho máximo:** 50 MB
* **Duração máxima:** 5 minutos
* **Formatos:** MP4, MOV

## Referência da API

* [**Adicionar Legendas**](https://help.mirage.app/api-reference/video-captions/add-captions)
* [**Listar Modelos de Legenda**](https://help.mirage.app/api-reference/video-captions/list-caption-templates)
* [**Recuperar Modelo de Legenda**](https://help.mirage.app/api-reference/video-captions/retrieve-caption-template)
* [**Recuperar Vídeo**](https://help.mirage.app/api-reference/videos/retrieve-video)
* [**Recuperar Conteúdo do Vídeo**](https://help.mirage.app/api-reference/videos/retrieve-video-content)