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

# Subir Media

> Sube archivos a Meta CDN y obtén un media_id para usar en mensajes

Sube imágenes, videos, audios o documentos directamente a Meta CDN.

## Casos de Uso

* **Archivos grandes**: Videos o documentos que excedan los límites del proxy automático
* **Reutilización**: Enviar el mismo archivo a múltiples destinatarios sin re-subirlo
* **Control**: Subir archivos de forma asíncrona antes de enviar mensajes

<Note>
  El `media_id` expira después de aproximadamente 30 días en Meta CDN.
</Note>

***

## Headers Requeridos

| Header          | Valor                   |
| --------------- | ----------------------- |
| `Authorization` | `Bearer wha_TU_API_KEY` |
| `Content-Type`  | `multipart/form-data`   |

<Warning>
  No uses `application/json`. Este endpoint requiere `multipart/form-data` porque envía archivos binarios.
</Warning>

***

## Parámetros del Body

<ParamField body="file" type="binary" required>
  El archivo binario a subir. Debe enviarse como multipart/form-data.
</ParamField>

<ParamField body="type" type="string" required>
  Tipo de media: `image`, `video`, `audio`, `document`, `sticker`
</ParamField>

***

## Límites de Tamaño

| Tipo       | Formatos                | Tamaño Máximo |
| ---------- | ----------------------- | ------------- |
| `image`    | JPEG, PNG, WebP         | 5 MB          |
| `video`    | MP4, 3GPP               | 16 MB         |
| `audio`    | AAC, MP3, OGG, AMR      | 16 MB         |
| `document` | PDF, DOC, XLS, PPT, TXT | 100 MB        |
| `sticker`  | WebP                    | 500 KB        |

***

## Ejemplo con cURL

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/media/v1 \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -F "file=@/ruta/a/imagen.jpg" \
    -F "type=image"
  ```

  ```javascript Node.js theme={null}
  const FormData = require('form-data');
  const fs = require('fs');

  const formData = new FormData();
  formData.append('file', fs.createReadStream('./imagen.jpg'));
  formData.append('type', 'image');

  const response = await fetch('https://api.whaapy.com/media/v1', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wha_TU_API_KEY'
    },
    body: formData
  });

  const data = await response.json();
  console.log('Media ID:', data.media_id);
  ```

  ```python Python theme={null}
  import requests

  with open('imagen.jpg', 'rb') as f:
      response = requests.post(
          'https://api.whaapy.com/media/v1',
          headers={'Authorization': 'Bearer wha_TU_API_KEY'},
          files={'file': f},
          data={'type': 'image'}
      )

  print('Media ID:', response.json()['media_id'])
  ```
</RequestExample>

***

## Respuesta Exitosa

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "media_id": "123456789012345",
    "mime_type": "image/jpeg",
    "file_size": 1048576,
    "type": "image"
  }
  ```
</ResponseExample>

***

## Flujo Completo

### Paso 1: Subir el archivo

```bash theme={null}
curl -X POST https://api.whaapy.com/media/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -F "file=@video.mp4" \
  -F "type=video"
```

Respuesta:

```json theme={null}
{
  "media_id": "123456789012345",
  "mime_type": "video/mp4",
  "file_size": 15728640,
  "type": "video"
}
```

### Paso 2: Enviar mensaje con el media\_id

```bash theme={null}
curl -X POST https://api.whaapy.com/messages/v1 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5215512345678",
    "type": "video",
    "video": {
      "id": "123456789012345",
      "caption": "Mira este video"
    }
  }'
```

<Tip>
  Puedes usar el mismo `media_id` para enviar el archivo a múltiples destinatarios. El ID es válido por 30 días.
</Tip>

***

## Cuándo usar este endpoint

| Escenario                      | Recomendación                             |
| ------------------------------ | ----------------------------------------- |
| Imagen pequeña con URL pública | Usa `image.link` directamente             |
| Video de cualquier tamaño      | Usa `/media/v1`                           |
| Documento grande               | Usa `/media/v1`                           |
| Enviar a múltiples personas    | Usa `/media/v1` y reutiliza el `media_id` |
| URL privada o protegida        | Usa `/media/v1`                           |

<Info>
  Para imágenes que excedan 5MB por URL, Whaapy las comprime automáticamente. No necesitas usar este endpoint solo por el tamaño.
</Info>

***

## Errores Comunes

### Tipo de archivo no permitido

```json theme={null}
{
  "error": "Tipo de archivo no permitido",
  "message": "Para video, los formatos permitidos son: video/mp4, video/3gpp"
}
```

### Archivo demasiado grande

```json theme={null}
{
  "error": "Archivo demasiado grande",
  "message": "El tamaño máximo para video es 16MB"
}
```

### WhatsApp no configurado

```json theme={null}
{
  "error": "WhatsApp no configurado",
  "message": "No se encontró configuración de WhatsApp activa para este negocio"
}
```

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Enviar Media" icon="image" href="/api-reference/messages/send-media">
    Usa el media\_id para enviar imágenes, videos o documentos
  </Card>

  <Card title="Enviar Mensajes" icon="message" href="/api-reference/messages/send">
    Envía mensajes de texto simples
  </Card>
</CardGroup>