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

# Enviar mídia

> Envie um arquivo e obtenha um file_uuid para enviá-lo em uma ação.

Para enviar imagens, vídeo, áudio ou documentos, primeiro você envia o arquivo e
obtém um `file_uuid`, que depois passa a uma ação de envio.

<Steps>
  <Step title="Peça uma URL de upload">
    ```http theme={null}
    POST /files/request-upload
    ```

    Com `{ filename, mime_type, size_bytes }`. Responde `201` com `file_uuid`,
    `upload_url`, `upload_token`, `storage_path` e `expires_at`.
  </Step>

  <Step title="Envie o binário">
    ```http theme={null}
    PUT {upload_url}
    ```

    Envie o arquivo para a `upload_url` que você recebeu, antes que expire
    (`expires_at`).
  </Step>

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

    Com `{ file_uuid }`. Responde `200` com `file_uuid`, `mime_type`,
    `size_bytes`, `download_url` e `expires_at`. A partir daqui o `file_uuid` é
    enviável.
  </Step>
</Steps>

Uma vez confirmado, passe o `file_uuid` a uma ação de envio — como mídia
direta em `send_message`, ou como header de um template:

```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" }]
      }
    }
  ]
}
```

O `header.type` ∈ `image` | `video` | `document` leva `file_uuid` (`document`
aceita um `filename` opcional). Em `send_message` no modo mídia, o `file_uuid` vai
no nível da ação com `body` como legenda opcional (o áudio não admite legenda).

<Tip>
  Se o preflight rejeitar o grupo, a resposta é um `4xx` síncrono e nenhuma
  ação é executada. Ver [Erros](/pt/errors).
</Tip>

## Exemplo executável

O fluxo completo em três chamadas. O `file_uuid` que o passo 3 confirma é o que
você depois passa a uma ação de envio.

**1 · Peça uma URL de upload**

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

  ```json Resposta 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 · Envie o binário** para a `upload_url` antes que expire

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

**3 · Confirme**

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

  ```json Resposta 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>