# API: Media di Vault e upload firmati

_API · 5 min di lettura · Aggiornato 2026-10-22 · https://lanachat.ai/guides/it/api-vault/_

Il **Vault** contiene foto, video e note vocali di una creator, organizzati in cartelle. Ogni elemento è **Free**, **Teaser** o **Paid** con un prezzo in Stars. I file non transitano mai tramite l'API: si richiede un **URL di upload firmato**, si invia il file lì, poi si conferma.

## Endpoints

| Method | Path | Descrizione | Permesso | Stato |
|---|---|---|---|---|
| GET | `/media` | Elenca media (`creator_id=` richiesto, `folder_id=`, `type=photo,video,voice`, `access=free,teaser,paid`) | `can_setup` | Planned |
| POST | `/media/uploads` | Ottieni un URL firmato per caricare un file (valido 15 minuti) | `can_setup` | Planned |
| POST | `/media/uploads/{upload_id}/complete` | Conferma l'upload; il media viene creato e processato | `can_setup` | Planned |
| GET | `/media/{id}` | Un media, la sua anteprima e dove viene usato | `can_setup` | Planned |
| PATCH | `/media/{id}` | Cambia descrizione, accesso, prezzo o cartella | `can_setup` | Planned |
| DELETE | `/media/{id}` | Elimina il media (rifiutato se uno step di uno script lo usa) | `can_setup` | Planned |
| GET | `/media/folders` | Cartelle del Vault di una creator | `can_setup` | Planned |
| POST | `/media/folders` | Crea una cartella | `can_setup` | Planned |
| PATCH | `/media/folders/{id}` | Rinomina o sposta una cartella | `can_setup` | Planned |
| DELETE | `/media/folders/{id}` | Elimina una cartella vuota | `can_setup` | Planned |

## L'oggetto media

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

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | Inizia con `med_` |
| `creator_id` | string | Di chi è il Vault |
| `type` | string | `photo`, `video` o `voice` |
| `status` | string | `processing`, `ready` o `failed` (con motivo) |
| `folder_id` | string o null | Cartella del Vault |
| `access` | string | `free`, `teaser` o `paid` |
| `stars` | number o null | Prezzo in Stars, richiesto se `access` è `paid` (1 a 100.000) |
| `description` | string o null | Aiuta l'AI a scegliere il media giusto; mai mostrata ai fan |
| `preview_url` | string o null | Anteprima, quando il media è `ready` |
| `created_at` | string | ISO 8601, UTC |

## Media

### Elenca media

`GET /media` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | Sì | La creator |
| `folder_id` | string | No | Solo questa cartella |
| `type` | string | No | `photo`, `video` o `voice`; più valori separati da virgola |
| `access` | string | No | `free`, `teaser` o `paid`; più valori separati da virgola |
| `limit`, `cursor` | number, string | No | [Paginazione](https://lanachat.ai/guides/it/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
}
```

Senza `creator_id` l'API risponde con `400`.

### Carica un file

Tre chiamate: richiedi un URL firmato, invia il file lì, conferma.

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | Sì | Il Vault che lo riceve |
| `file_name` | string | Sì | Nome del file, es. `beach-01.jpg` |
| `content_type` | string | Sì | Es. `image/jpeg` o `video/mp4` |
| `size_bytes` | number | Sì | Dimensione file, fino a 2 GB |
| `folder_id` | string | No | Cartella del Vault dove inserirlo |

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

L'URL è valido 15 minuti.

**Step 2.** Invia il file con `PUT` all'`url`, con esattamente gli `headers` indicati (senza header `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
```

**Step 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"
}
```

Lo `status` passa da `processing` a `ready` (anteprime e copia Telegram create) o `failed` con motivo. Un webhook `media.ready` ti avvisa, vedi [Webhooks](https://lanachat.ai/guides/it/api-webhooks/). Formati accettati: JPEG, PNG, HEIC, MP4, MOV, OGG e M4A, fino a 2 GB.

### Ottieni un media

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

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

La risposta è l'oggetto media, con anteprima e dove è usato. Un id sconosciuto risponde `404`.

### Prezzo e descrizione

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `access` | string | No | `free`, `teaser` o `paid` |
| `stars` | number | Se `access` è `paid` | 1 a 100.000 |
| `description` | string | No | Cosa mostra, per l'AI |
| `folder_id` | string o null | No | Spostalo in un'altra cartella |

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

La risposta è il media aggiornato. `stars` è richiesto se `access` è `paid` (1 a 100.000), altrimenti l'API risponde `400`. La descrizione aiuta l'AI a scegliere il media giusto; non è mai mostrata ai fan.

### Elimina un media

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

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

Un media usato da uno step di uno script viene rifiutato (`409`): rimuovilo prima dallo [script](https://lanachat.ai/guides/it/api-scripts/).

## Cartelle

### Elenca cartelle

`GET /media/folders` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | Sì | Di chi è il Vault |

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

### Crea una cartella

`POST /media/folders` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | Sì | Di chi è il Vault |
| `name` | string | Sì | Nome della cartella |

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

### Rinomina o sposta una cartella

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

### Elimina una cartella

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

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

Si può eliminare solo una cartella vuota; altrimenti l'API risponde `409`.

## Articoli correlati

- [API LanaChat: avvio rapido, autenticazione ed errori](https://lanachat.ai/guides/it/api-overview/)
- [Vault: carica media, anteprime e cartelle](https://lanachat.ai/guides/it/vault/)
- [API: script, passaggi e cartelle](https://lanachat.ai/guides/it/api-scripts/)