API: Media di Vault e upload firmati

5 min di letturaAggiornato 22 ott 2026Markdown

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 #

{
  "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

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

{
  "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

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

{
  "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).

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

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

{
  "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. Formati accettati: JPEG, PNG, HEIC, MP4, MOV, OGG e M4A, fino a 2 GB.

Ottieni un media #

GET /media/{id} · can_setup

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

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

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.

Cartelle #

Elenca cartelle #

GET /media/folders · can_setup

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

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

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

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

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.