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

# Subir multimedia

> Sube un archivo y obtén un file_uuid para enviarlo en una acción.

Para enviar imágenes, video, audio o documentos, primero subes el archivo y
obtienes un `file_uuid`, que luego pasas a una acción de envío.

<Steps>
  <Step title="Pide una URL de subida">
    ```http theme={null}
    POST /files/request-upload
    ```

    Con `{ filename, mime_type, size_bytes }`. Responde `201` con `file_uuid`,
    `upload_url`, `upload_token`, `storage_path` y `expires_at`.
  </Step>

  <Step title="Sube el binario">
    ```http theme={null}
    PUT {upload_url}
    ```

    Sube el archivo a la `upload_url` que recibiste, antes de que expire
    (`expires_at`).
  </Step>

  <Step title="Confirma">
    ```http theme={null}
    POST /files/confirm
    ```

    Con `{ file_uuid }`. Responde `200` con `file_uuid`, `mime_type`,
    `size_bytes`, `download_url` y `expires_at`. A partir de aquí el `file_uuid`
    es enviable.
  </Step>
</Steps>

Una vez confirmado, pasa el `file_uuid` a una acción de envío — como media
directa en `send_message`, o como header de una plantilla:

```jsonc theme={null}
{
  "conversation": { "phone": "+5215512345678", "channel": "ch_7A9K2M4Q" },
  "actions": [
    {
      "type": "send_message",
      "template": {
        "name": "promo_verano",
        "language": "es_MX",
        "header": {
          "type": "image",
          "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678"
        },
        "body_variables": [{ "index": 1, "value": "Ana" }]
      }
    }
  ]
}
```

El `header.type` ∈ `image` | `video` | `document` lleva `file_uuid` (`document`
acepta un `filename` opcional). En `send_message` modo media, el `file_uuid` va a
nivel de acción con `body` como caption opcional (el audio no admite caption).

<Tip>
  Si el preflight rechaza el grupo, la respuesta es un `4xx` síncrono y ninguna
  acción se ejecuta. Ver [Errores](/es/errors).
</Tip>

## Ejemplo ejecutable

El flujo completo en tres llamadas. El `file_uuid` que confirma el paso 3 es el
que después pasas a una acción de envío.

**1 · Pide la URL de subida**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/files/request-upload" \
    -H "Authorization: Bearer sk_1to1_tu_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "filename": "comprobante.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 48213
    }'
  ```

  ```json Respuesta 201 theme={null}
  {
    "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
    "upload_url": "https://storage.1to1.ai/uploads/7b8a1c2d?token=...",
    "upload_token": "ut_9f8e7d6c5b4a3210",
    "storage_path": "business/uploads/7b8a1c2d.pdf",
    "expires_at": "2026-07-22T15:30:00Z"
  }
  ```
</CodeGroup>

**2 · Sube el binario** a la `upload_url` antes de que expire

```bash theme={null}
curl -X PUT "{upload_url}" \
  -H "Content-Type: application/pdf" \
  --data-binary @comprobante.pdf
```

**3 · Confirma**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/files/confirm" \
    -H "Authorization: Bearer sk_1to1_tu_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678"
    }'
  ```

  ```json Respuesta 200 theme={null}
  {
    "file_uuid": "7b8a1c2d-3e4f-5678-90ab-cdef12345678",
    "mime_type": "application/pdf",
    "size_bytes": 48213,
    "download_url": "https://storage.1to1.ai/download/7b8a1c2d?token=...",
    "expires_at": "2026-07-22T16:30:00Z"
  }
  ```
</CodeGroup>