# API: Mídia do Vault e uploads assinados

_API · Leitura de 5 min · Atualizado 2026-10-22 · https://lanachat.ai/guides/pt/api-vault/_

O **Vault** armazena fotos, vídeos e notas de voz de uma criadora, organizados em pastas. Cada item é **Free**, **Teaser** ou **Paid** com um preço em Stars. Os arquivos nunca passam pela API: você solicita uma **URL de upload assinada**, envia o arquivo para lá e depois confirma.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/media` | Listar mídia (`creator_id=` obrigatório, `folder_id=`, `type=photo,video,voice`, `access=free,teaser,paid`) | `can_setup` | Planned |
| POST | `/media/uploads` | Obter uma URL assinada para enviar um arquivo (válida por 15 minutos) | `can_setup` | Planned |
| POST | `/media/uploads/{upload_id}/complete` | Confirmar o upload; a mídia é criada e processada | `can_setup` | Planned |
| GET | `/media/{id}` | Uma mídia, sua prévia e onde é usada | `can_setup` | Planned |
| PATCH | `/media/{id}` | Alterar descrição, acesso, preço ou pasta | `can_setup` | Planned |
| DELETE | `/media/{id}` | Excluir (recusado se um passo do script estiver usando) | `can_setup` | Planned |
| GET | `/media/folders` | Pastas do Vault de uma criadora | `can_setup` | Planned |
| POST | `/media/folders` | Criar uma pasta | `can_setup` | Planned |
| PATCH | `/media/folders/{id}` | Renomear ou mover uma pasta | `can_setup` | Planned |
| DELETE | `/media/folders/{id}` | Excluir uma pasta vazia | `can_setup` | Planned |

## O objeto mídia

```json
{
  "id": "med_5521",
  "creator_id": "cr_lea",
  "type": "photo",
  "status": "ready",
  "folder_id": "vf_3",
  "access": "paid",
  "stars": 300,
  "description": "Beach, golden hour, white bikini",
  "preview_url": "https://cdn.lanachat.ai/w/7Hq2/cr_lea/med_5521/preview.jpg",
  "created_at": "2026-10-06T14:21:40Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Começa com `med_` |
| `creator_id` | string | De quem é o Vault |
| `type` | string | `photo`, `video` ou `voice` |
| `status` | string | `processing`, `ready` ou `failed` (com motivo) |
| `folder_id` | string ou null | Pasta do Vault |
| `access` | string | `free`, `teaser` ou `paid` |
| `stars` | number ou null | Preço em Stars, obrigatório se `access` for `paid` (1 a 100.000) |
| `description` | string ou null | Ajuda a AI a escolher a mídia certa; nunca mostrado para o fã |
| `preview_url` | string ou null | Uma prévia, quando a mídia estiver `ready` |
| `created_at` | string | ISO 8601, UTC |

## Mídia

### Listar mídia

`GET /media` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sim | A criadora |
| `folder_id` | string | Não | Apenas essa pasta |
| `type` | string | Não | `photo`, `video` ou `voice`; vários separados por vírgulas |
| `access` | string | Não | `free`, `teaser` ou `paid`; vários separados por vírgulas |
| `limit`, `cursor` | number, string | Não | [Paginação](https://lanachat.ai/guides/pt/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/media?creator_id=cr_lea&type=photo&access=paid" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "med_5522", "creator_id": "cr_lea", "type": "photo", "status": "ready", "folder_id": "vf_3", "access": "paid", "stars": 250, "description": "Mirror, black dress", "preview_url": "https://cdn.lanachat.ai/w/7Hq2/cr_lea/med_5522/preview.jpg", "created_at": "2026-10-06T14:25:10Z" },
    { "id": "med_5521", "creator_id": "cr_lea", "type": "photo", "status": "ready", "folder_id": "vf_3", "access": "paid", "stars": 300, "description": "Beach, golden hour, white bikini", "preview_url": "https://cdn.lanachat.ai/w/7Hq2/cr_lea/med_5521/preview.jpg", "created_at": "2026-10-06T14:21:40Z" }
  ],
  "next_cursor": null
}
```

Sem `creator_id` a API responde `400`.

### Enviar um arquivo

Três chamadas: pede uma URL assinada, envia o arquivo para lá, confirma.

**Passo 1.** `POST /media/uploads` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sim | Para qual Vault será enviado |
| `file_name` | string | Sim | Nome do arquivo, ex: `beach-01.jpg` |
| `content_type` | string | Sim | Exemplo: `image/jpeg` ou `video/mp4` |
| `size_bytes` | number | Sim | Tamanho do arquivo, até 2 GB |
| `folder_id` | string | Não | Pasta do Vault onde será colocado |

```bash
curl -X POST https://api.lanachat.ai/v1/media/uploads \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"creator_id": "cr_lea", "file_name": "beach-01.jpg", "content_type": "image/jpeg", "size_bytes": 2483201, "folder_id": "vf_3"}'
```

```json
{
  "upload_id": "up_7781",
  "url": "https://uploads.lanachat.ai/w/7Hq2/up_7781?X-Signature=…&X-Expires=1759760100",
  "method": "PUT",
  "headers": { "Content-Type": "image/jpeg" },
  "expires_at": "2026-10-06T14:35:00Z"
}
```

A URL é válida por 15 minutos.

**Passo 2.** Envie o arquivo com `PUT` para `url`, usando exatamente os `headers` fornecidos (sem cabeçalho `Authorization`).

```bash
curl -X PUT "https://uploads.lanachat.ai/w/7Hq2/up_7781?X-Signature=…&X-Expires=1759760100" \
  -H "Content-Type: image/jpeg" --data-binary @beach-01.jpg
```

**Passo 3.** `POST /media/uploads/{upload_id}/complete` · `can_setup`

```bash
curl -X POST https://api.lanachat.ai/v1/media/uploads/up_7781/complete \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{
  "id": "med_5521",
  "creator_id": "cr_lea",
  "type": "photo",
  "status": "processing",
  "folder_id": "vf_3",
  "access": "paid",
  "stars": null,
  "description": null,
  "preview_url": null,
  "created_at": "2026-10-06T14:21:40Z"
}
```

O `status` muda de `processing` para `ready` (prévias e cópia para Telegram são feitas) ou `failed` com um motivo. Um webhook `media.ready` avisa quando, veja [Webhooks](https://lanachat.ai/guides/pt/api-webhooks/). Aceitos: JPEG, PNG, HEIC, MP4, MOV, OGG e M4A, até 2 GB.

### Obter uma mídia

`GET /media/{id}` · `can_setup`

```bash
curl https://api.lanachat.ai/v1/media/med_5521 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

A resposta é o objeto mídia, com sua prévia e onde é usada. Um id desconhecido responde `404`.

### Preço e descrição

`PATCH /media/{id}` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `access` | string | Não | `free`, `teaser` ou `paid` |
| `stars` | number | Quando `access` for `paid` | 1 a 100.000 |
| `description` | string | Não | O que mostra, para a AI |
| `folder_id` | string ou null | Não | Mover para outra pasta |

```bash
curl -X PATCH https://api.lanachat.ai/v1/media/med_5521 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"access": "paid", "stars": 300, "description": "Beach, golden hour, white bikini"}'
```

A resposta é a mídia atualizada. `stars` é obrigatório se `access` for `paid` (1 a 100.000), senão a API responde `400`. A descrição ajuda a AI a escolher a mídia certa; nunca é mostrada para o fã.

### Excluir uma mídia

`DELETE /media/{id}` · `can_setup`

```bash
curl -X DELETE https://api.lanachat.ai/v1/media/med_5521 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Uma mídia que um passo do script ainda usa é recusada (`409`): remova-a do [script](https://lanachat.ai/guides/pt/api-scripts/) primeiro.

## Pastas

### Listar pastas

`GET /media/folders` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sim | De quem é o Vault |

```bash
curl "https://api.lanachat.ai/v1/media/folders?creator_id=cr_lea" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

### Criar uma pasta

`POST /media/folders` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sim | De quem é o Vault |
| `name` | string | Sim | Nome da pasta |

```bash
curl -X POST https://api.lanachat.ai/v1/media/folders \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"creator_id": "cr_lea", "name": "Beach"}'
```

### Renomear ou mover uma pasta

`PATCH /media/folders/{id}` · `can_setup`

```bash
curl -X PATCH https://api.lanachat.ai/v1/media/folders/vf_3 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Beach, summer"}'
```

### Excluir uma pasta

`DELETE /media/folders/{id}` · `can_setup`

```bash
curl -X DELETE https://api.lanachat.ai/v1/media/folders/vf_3 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Só uma pasta vazia pode ser excluída; caso contrário a API responde `409`.

## Artigos relacionados

- [API LanaChat: início rápido, autenticação e erros](https://lanachat.ai/guides/pt/api-overview/)
- [Vault: enviar mídia, prévias e pastas](https://lanachat.ai/guides/pt/vault/)
- [API: scripts, etapas e pastas](https://lanachat.ai/guides/pt/api-scripts/)