# API: Медіа Vault та підписані завантаження

_API · Читання 5 хв · Оновлено 2026-10-22 · https://lanachat.ai/guides/uk/api-vault/_

**Vault** зберігає фото, відео та голосові нотатки авторки, відсортовані по папках. Кожен елемент є **Free**, **Teaser** або **Paid** з ціною в Stars. Файли ніколи не проходять через API: ви запитуєте **підписаний URL для завантаження**, відправляєте файл туди, а потім підтверджуєте.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/media` | Список медіа (`creator_id=` обов’язковий, `folder_id=`, `type=photo,video,voice`, `access=free,teaser,paid`) | `can_setup` | Planned |
| POST | `/media/uploads` | Отримати підписаний URL для завантаження одного файлу (дійсний 15 хвилин) | `can_setup` | Planned |
| POST | `/media/uploads/{upload_id}/complete` | Підтвердити завантаження; медіа створюється та обробляється | `can_setup` | Planned |
| GET | `/media/{id}` | Одне медіа, його прев’ю та де воно використовується | `can_setup` | Planned |
| PATCH | `/media/{id}` | Змінити опис, доступ, ціну або папку | `can_setup` | Planned |
| DELETE | `/media/{id}` | Видалити (відмовлено, якщо крок скрипта його використовує) | `can_setup` | Planned |
| GET | `/media/folders` | Папки Vault авторки | `can_setup` | Planned |
| POST | `/media/folders` | Створити папку | `can_setup` | Planned |
| PATCH | `/media/folders/{id}` | Перейменувати або перемістити папку | `can_setup` | Planned |
| DELETE | `/media/folders/{id}` | Видалити порожню папку | `can_setup` | Planned |

## Об’єкт медіа

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

| Поле | Тип | Опис |
|---|---|---|
| `id` | string | Починається з `med_` |
| `creator_id` | string | Чий Vault |
| `type` | string | `photo`, `video` або `voice` |
| `status` | string | `processing`, `ready` або `failed` (з причиною) |
| `folder_id` | string або null | Папка Vault |
| `access` | string | `free`, `teaser` або `paid` |
| `stars` | number або null | Ціна в Stars, обов’язково при `access` = `paid` (від 1 до 100000) |
| `description` | string або null | Допомагає AI вибрати потрібне медіа; ніколи не показується фанам |
| `preview_url` | string або null | Прев’ю, коли медіа `ready` |
| `created_at` | string | ISO 8601, UTC |

## Медіа

### Список медіа

`GET /media` · `can_setup`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `creator_id` | string | Так | Авторка |
| `folder_id` | string | Ні | Тільки ця папка |
| `type` | string | Ні | `photo`, `video` або `voice`; кілька через кому |
| `access` | string | Ні | `free`, `teaser` або `paid`; кілька через кому |
| `limit`, `cursor` | number, string | Ні | [Пагінація](https://lanachat.ai/guides/uk/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
}
```

Без `creator_id` API відповідає `400`.

### Завантаження файлу

Три виклики: запитати підписаний URL, відправити файл туди, підтвердити.

**Крок 1.** `POST /media/uploads` · `can_setup`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `creator_id` | string | Так | Чий Vault приймає файл |
| `file_name` | string | Так | Ім’я файлу, наприклад `beach-01.jpg` |
| `content_type` | string | Так | Наприклад `image/jpeg` або `video/mp4` |
| `size_bytes` | number | Так | Розмір файлу, до 2 ГБ |
| `folder_id` | string | Ні | Папка Vault для розміщення |

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

URL дійсний 15 хвилин.

**Крок 2.** Відправте файл з `PUT` на `url`, з точно заданими `headers` (без заголовка `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
```

**Крок 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"
}
```

`status` змінюється з `processing` на `ready` (створюються прев’ю та копія для Telegram) або `failed` з причиною. Вебхук `media.ready` повідомляє про готовність, див. [Webhooks](https://lanachat.ai/guides/uk/api-webhooks/). Підтримуються формати: JPEG, PNG, HEIC, MP4, MOV, OGG та M4A, до 2 ГБ.

### Отримати медіа

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

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

Відповідь, об’єкт медіа з прев’ю та інформацією про використання. Невідомий id відповідає `404`.

### Встановити ціну та опис

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

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `access` | string | Ні | `free`, `teaser` або `paid` |
| `stars` | number | При `access` = `paid` | Від 1 до 100000 |
| `description` | string | Ні | Що показує, для AI |
| `folder_id` | string або null | Ні | Перемістити в іншу папку |

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

Відповідь, оновлене медіа. `stars` обов’язковий при `access` = `paid` (від 1 до 100000), інакше API відповідає `400`. Опис допомагає AI вибрати потрібне медіа; ніколи не показується фанам.

### Видалити медіа

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

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

Медіа, яке ще використовується в кроці скрипта, не видаляється (`409`): спочатку видаліть його зі [скрипта](https://lanachat.ai/guides/uk/api-scripts/).

## Папки

### Список папок

`GET /media/folders` · `can_setup`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `creator_id` | string | Так | Чий Vault |

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

### Створити папку

`POST /media/folders` · `can_setup`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `creator_id` | string | Так | Чий Vault |
| `name` | string | Так | Назва папки |

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

### Перейменувати або перемістити папку

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

### Видалити папку

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

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

Видалити можна лише порожню папку; інакше API відповідає `409`.

## Пов’язані статті

- [LanaChat API: швидкий старт, автентифікація та помилки](https://lanachat.ai/guides/uk/api-overview/)
- [Vault: завантаження медіа, прев’ю та папок](https://lanachat.ai/guides/uk/vault/)
- [API: скрипти, кроки та папки](https://lanachat.ai/guides/uk/api-scripts/)