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

> Crie um vídeo humano expressivo de curta duração a partir de uma imagem estática e uma faixa de áudio.

# Visão Geral

O Mirage Video é um modelo de vídeo desenvolvido especialmente para realismo humano. A partir de uma única imagem e um clipe de áudio, o Mirage pode criar vídeos expressivos e realistas que capturam movimentos faciais sutis, emoções e sincronização de fala com notável fidelidade.

Treinado em diversas imagens humanas, o Mirage entende como os rostos se movem, como as vozes moldam as expressões e como os pequenos detalhes fazem as pessoas parecerem reais na tela.

A API Mirage Video expõe essa capacidade para desenvolvedores por meio de endpoints simples:

* Criar vídeo — Inicie uma nova geração de vídeo a partir de um par de imagem e áudio.
* Recuperar vídeo — Recupere o estado atual de um job de geração de vídeo e acompanhe seu progresso.
* Recuperar conteúdo do vídeo — Obtenha o MP4 final quando o job estiver concluído.
* Listar vídeos — Acesse suas gerações de vídeo recentes.

## Pré-requisitos

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

## 1) Criar um vídeo

Forneça uma imagem de retrato (JPEG/PNG) e áudio de fala (WAV/MP3).

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

  url = "https://api.mirage.app/v1/videos"
  headers = {
      "x-api-key": "<api-key>"
  }
  files = {
      "image_reference": open("portrait.jpg", "rb"),
      "audio_reference": open("voice.mp3", "rb")
  }
  data = {
      "model": "mirage-video-1-latest"
  }

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

  ```typescript TypeScript theme={"system"}
  const formData = new FormData();
  formData.append("model", "mirage-video-1-latest");
  formData.append("image_reference", await fs.readFile("portrait.jpg"));
  formData.append("audio_reference", await fs.readFile("voice.mp3"));

  const response = await fetch("https://api.mirage.app/v1/videos", {
    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 \
    --header 'Content-Type: multipart/form-data' \
    --header 'x-api-key: <api-key>' \
    --form model=mirage-video-1-latest \
    --form image_reference=@portrait.jpg \
    --form audio_reference=@voice.mp3
  ```
</CodeGroup>

**Resposta (exemplo)**

```json theme={"system"}
{
  "id": "video_abc123def456",
  "object": "video",
  "completed_at": 1730822520,
  "created_at": 1730822400,
  "model": "mirage-video-1-latest",
  "progress": 100,
  "status": "COMPLETE",
  "error": null
}
```

## 2) 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)
  ```

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

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

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

## 3) Baixar o vídeo (seguir redirecionamento)

Quando o status de um vídeo for `COMPLETE`, ele estará disponível para download. O endpoint `content` retorna um redirecionamento HTTP para o URL final do vídeo.

<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("output.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>

Seu vídeo gerado agora está salvo como `output.mp4`.

## Dicas para melhores resultados

* Use um retrato claro, de frente, com boa iluminação e um único sujeito. Certifique-se de que o rosto esteja visível, a boca aberta e o sujeito orientado em um enquadramento próximo a médio para garantir alinhamento natural com a voz.
* Evite imagens com bocas fechadas ou várias pessoas no quadro.
* Use áudio expressivo e realista. Os resultados tendem a ser piores se o áudio for visivelmente "gerado por IA".

## Referência da API

* [**Criar vídeo**](https://help.mirage.app/api-reference/videos/create-video)
* [**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)
* [**Listar Vídeos**](https://help.mirage.app/api-reference/videos/list-videos)