# Baixar mídia

Fonte: https://apiwpp.com/docs/api/midia/baixar-midia
Seção: Mídia
Atualizado em: 2026-09-28

`GET /media/{connectionId}/{fileName}`

Baixa um arquivo de mídia recebido (imagem, vídeo, áudio, documento ou figurinha) pela URL assinada que o webhook [message.incoming](https://apiwpp.com/docs/webhooks/message-incoming) traz em `data.media.url`. Não leva chave de API: a própria URL é a credencial, válida até `data.media.expiresAt`. Use a URL exatamente como recebida; sem assinatura, expirada ou alterada, ela responde `404`, igual a um arquivo que não existe. Sem chave de API: a URL assinada é a credencial.

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `connectionId` | `string · uuid` | sim | Identificador da conexão (o número) que recebeu a mídia, como vem na URL assinada. |
| `fileName` | `string` | sim | Nome com que a apiwpp guardou o arquivo: o id da mensagem mais a extensão (`3EB0C767D26A8A0F2B41.jpg`). É o mesmo valor de `data.media.fileName`, não o nome original do documento. |

## Parâmetros de consulta

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `exp` | `string` | não | Momento de expiração da URL, em segundos unix. A partir dele, a URL responde `404`. Na prática é obrigatório: sem ele, a resposta é `404`. |
| `sig` | `string` | não | A assinatura da URL: HMAC-SHA256 em base64url (43 caracteres) sobre `connectionId/fileName/exp`. Na prática é obrigatório: sem ele, ou com qualquer parte da URL alterada, a resposta é `404`. |

## Exemplo de requisição

### cURL

```bash
curl "https://api.apiwpp.com/media/$CONNECTION_ID/$FILE_NAME?exp=1790812800&sig=m2Yk7rWq0p9ZcV3xN8aHf1LdJ6uBtE4sQyGo5iRnKwA" \
  -o arquivo
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/media/${connectionId}/${fileName}?exp=1790812800&sig=m2Yk7rWq0p9ZcV3xN8aHf1LdJ6uBtE4sQyGo5iRnKwA`)
const file = Buffer.from(await res.arrayBuffer())
```

### PHP

```php
$response = Http::get("https://api.apiwpp.com/media/{$connectionId}/{$fileName}", [
        'exp' => '1790812800',
        'sig' => 'm2Yk7rWq0p9ZcV3xN8aHf1LdJ6uBtE4sQyGo5iRnKwA',
    ]);
```

### Python

```python
import requests

response = requests.get(
    f"https://api.apiwpp.com/media/{connection_id}/{file_name}",
    params={
        "exp": "1790812800",
        "sig": "m2Yk7rWq0p9ZcV3xN8aHf1LdJ6uBtE4sQyGo5iRnKwA",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | O arquivo, com o `Content-Type` da extensão do nome (`image/jpeg`, `video/mp4`, `audio/ogg`, `application/pdf`…; `application/octet-stream` para as demais), `Content-Length` e `Cache-Control` que permite guardá-lo até a URL expirar (no máximo 1 hora). |
| 400 | `FST_ERR_VALIDATION` | Os parâmetros não seguem o formato da operação (por exemplo, `connectionId` que não é um UUID). A assinatura é conferida antes dessa validação, então uma URL sem assinatura válida responde `404`, nunca `400`; com a URL exatamente como a apiwpp entregou, este status não acontece. |
| 404 |  | A URL não tem assinatura, expirou, foi alterada em qualquer parte ou o arquivo não existe mais (apagado depois do prazo): todos esses casos respondem igual, com o corpo `{"error": "Media not found"}`. Não há como renovar a URL; a mídia só pode ser baixada enquanto o link do evento for válido. |
| 429 |  | Requisições demais deste IP de origem (por padrão, 600 por minuto): espere os segundos de `Retry-After`. Veja [Limites](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |

### 200 OK

O corpo é o próprio arquivo.

## Detalhes

**Não monte a URL.** Os parâmetros `exp` e `sig` são gerados pela apiwpp quando o evento é enviado: `sig` é um HMAC-SHA256 (em base64url) sobre `connectionId/fileName/exp`, com uma chave que só o gateway conhece. Faça `GET` na URL de `data.media.url` como ela veio, com o mesmo host. Nos exemplos ao lado, os parâmetros aparecem separados só para mostrar o formato.

**Sem credencial.** A rota é pública e não lê o cabeçalho `Authorization` nem `X-Api-Key`: com ou sem chave, a resposta é a mesma. Por isso, quem tiver a URL baixa o arquivo até ela expirar. Trate o link como um segredo: não o registre em log nem o repasse.

**Validade.** Por padrão, a URL vale 24 horas a partir do envio do evento, e o arquivo é apagado 24 horas depois de recebido, qualquer que seja a validade da URL. Baixe o arquivo quando o evento chegar em vez de guardar o link. Não há como pedir uma URL nova: depois de expirada, a mídia não pode mais ser baixada pela API.

**A resposta.** O corpo é o próprio arquivo, com `Content-Type` pela extensão do nome: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `video/mp4`, `video/quicktime`, `audio/ogg`, `audio/mpeg`, `audio/mp4`, `application/pdf`, `application/msword` ou o tipo do `.docx`; qualquer outra extensão (inclusive `.bin`) vem como `application/octet-stream`. `Content-Length` traz o tamanho, e `Cache-Control: private, max-age=<segundos>` deixa o navegador guardar o arquivo por até 1 hora, nunca além da expiração da URL.

**Direto no navegador.** A resposta traz `Cross-Origin-Resource-Policy: cross-origin`, então a URL pode ser usada num `<img>`, num `<video>` ou num frame de PDF de outro domínio enquanto for válida.

Guia: [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura).
