---
title: "Generative Gallery"
description: "Завантаження або генерація галерей за допомогою ШІ для NFT, товарів магазину та File Cabinet — кредитне Ghost-write + ImageConductor, збереження сусідніх файлів у кабінеті, похідні RingFileBase"
locale: "uk"
---
# Generative Gallery

Generative Gallery — це **спільне медіаполе** Ring Platform для створення NFT, форм товарів мультивендорного магазину та Image/Video chat на панелі деталей File Cabinet. Оператори **завантажують** зображення або **генерують** варіанти через ImageConductor, збагачують промпти за допомогою **Ghost-write** (TextConductor + вебпошук), а історію зберігають у **прихованому tool chat** (`genmedia:…`), який не захаращує Messages.

> **Info**
> Використовуйте вкладки **Founder** / **Developer** на бічній панелі документації, щоб відфільтрувати цю сторінку. Засновники бачать операторську цінність і поверхні; розробники — модулі, білінг і перевірені шляхи.

## Де це працює

| Поверхня | Роль |
|---------|------|
| Майстер створення NFT | Обкладинка колекції + mint-медіа через `GenerativeMediaField` (`scope: 'nft'`) |
| Форма товару продавця / адміністратора | Галерея зображень товару (`scope: 'product'`); Agent Knowledge Research — окремий шлях WebConductor, див. [Store](/docs/features/store.md) |
| Панель деталей File Cabinet | **Image chat** / **Video chat** → `GenerativeMediaEditorFsModal` (`scope: 'cabinet'`); збереження поруч із джерелом |
| Галерея деталей товару | Для смужки надає перевагу `derivatives.thumb` / `webpUrl`; lightbox використовує оригінал |
| Картки новин / hero / OG | `pickImageSrc` → card / hero / og; за наявності — розмитий LQIP |
| Аватар | `avatarThumb` (sync_thumb) має перевагу над оригіналом `photoURL` |
| Бульбашки зображень у чаті | `MessageAttachment.derivatives.thumb` має перевагу над оригінальним URL |
| Mint NFT + лістинги | Off-chain Metaplex JSON (`image`, необов’язковий `animation_url`, `properties.files`) |

SSOT-модуль: `features/generative-media/`. Області: `nft` \| `product` \| `cabinet` \| `editor`.

### For founders

## Чому це важливо для вашого клону

- **Одне поле — кілька робочих столів** — фотографії каталогу, NFT-арт учасника та enhance/enlive у кабінеті використовують один generative UX.
- **Витрати спершу з кредитів** — Ghost-write і генерація зображень списують кредити платформи через WalletConductor до запуску ходу.
- **Чиста скринька** — історія генерації живе у прихованій розмові product-tool (`generative_gallery` / `genmedia:`).
- **Research проти Generate** — Store **Research** (WebConductor) збирає вебфото з цитатами у File Cabinet `…/alt`; Generative Gallery створює або покращує пікселі. Додавання до галереї з research залишається явною дією **Use in gallery**.
- **Сусідні файли кабінету** — enhance/enlive зберігає результат поруч із джерелом як `{name}-enhanced-…` або `{name}-enlive-…`, тому оригінали залишаються недоторканими.

  
- **[NFT Marketplace](/docs/features/nft-market.md)** — Створення/mint/list для member — Generative Gallery є медіашляхом.

  
- **[Multi-Vendor Store](/docs/features/store.md)** — Форми товарів + Agent Knowledge Research (WebConductor) + Use in gallery.

  
- **[File Cabinet](/docs/features/file-cabinet.md)** — Вхід до Image/Video chat із панелі деталей і збереження поруч із джерелом.

  
- **[WalletConductor](/docs/features/wallet-conductor.md)** — Сьогодні generative billing працює через `spendCredits`.

### Чекліст оператора

- Переконайтеся, що провайдери ImageConductor / TextConductor налаштовані.
- Поповніть **кредити платформи** (необов’язкові перевизначення `GENERATIVE_CREDIT_*`).
- Віддавайте перевагу **`ring_filebase`**, щоб завантаження повертали повну карту `derivatives`.
- Навчіть продавців: Upload \| Generate у формі товару; Research для вебзбору; Image chat кабінету для полірування.
- Для лістингів NFT перевіряйте showcase thumbnails/animation, коли автори додають галереї з кількох елементів.

### Типові шляхи

```mermaid
flowchart LR
  Field[GenerativeMediaField]
  Cab[Панель деталей кабінету]
  Field --> Upload[Вкладка Upload]
  Field --> Gen[Вкладка Generate]
  Cab --> Chat[Image / Video chat]
  Chat --> Modal[GenerativeMediaEditorFsModal]
  Modal --> Sib[Сусідній файл під parentId]
  Upload --> Strip[Смужка галереї]
  Gen --> Ghost[Необов’язковий Ghost-write]
  Ghost --> IC[ImageConductor]
  IC --> Strip
  Strip --> Store[Product / NFT]
```

### For developers

## Архітектура

Generative turns із кредитами спершу проходять через server actions → `features/generative-media/service.ts` → ImageConductor / TextConductor, із необов’язковим створенням WebP і FCM/in-app сповіщенням після завершення фонової генерації.

```mermaid
sequenceDiagram
  participant UI as GenerativeMediaField / EditorFsModal
  participant SA as app/_actions/generative-media
  participant Bill as billing.billGenerativeTurn
  participant WC as WalletConductor.spendCredits
  participant Svc as generative-media/service
  participant IC as ImageConductor
  participant Chat as hidden product conversation

  UI->>SA: runGenMediaImageAction
  SA->>Svc: runGenMediaImageTurn
  Svc->>Bill: action image_gen + referenceId
  Bill->>WC: spendCredits
  WC-->>Bill: transactionId
  Bill-->>Svc: ok
  Svc->>Chat: user prompt message
  Svc->>IC: generate n=4 + referenceImages
  IC-->>Svc: image URLs
  Svc->>Chat: ImageConductor attachments
  Svc-->>UI: galleryItems
```

### Шлях входу з кабінету (Phase G — випущено)

| Крок | Деталь |
|------|--------|
| Тригер UI | `file-cabinet-detail-panel.tsx` — **Image chat** / **Video chat** на файлах зображень, коли `canGenerate` |
| Вузол desktop | `file-cabinet-desktop.tsx` відкриває `GenerativeMediaEditorFsModal` зі `scope="cabinet"` |
| Дія збереження | `saveGeneratedMediaToDesktopAction` у `app/_actions/file-cabinet.ts` |
| Іменування | `{base}-enhanced-{ts}.{ext}` для зображень; `{base}-enlive-{ts}.{ext}` для відео (`base` з імені файлу джерела) |
| Батьківський елемент | `parentId: genSourceNode.parentId` — сусідній файл джерела, а не новий кореневий дамп |
| Pipeline | `cabinet.genmedia.sibling_save` у `scripts/PIPELINES.md` |

### Модулі

| Шлях | Роль |
|------|------|
| `features/generative-media/types.ts` | `GalleryItem`, області `nft` \| `product` \| `cabinet` \| `editor`, `buildGenMediaChatKey` → `genmedia:scope:entity:page:field` |
| `features/generative-media/billing.ts` | Credit-first `WalletConductor.spendCredits` + журнал `generative_usage` |
| `features/generative-media/service.ts` | Прихований tool chat, upload, Ghost-write, ходи ImageConductor / video |
| `features/generative-media/nft-metadata.ts` | Metaplex JSON + помічники завантаження |
| `features/generative-media/parse-product-images.ts` | Галерея URL FormData для vendor/admin |
| `features/generative-media/components/generative-media-field.tsx` | Віджет SSOT із вкладками Upload \| Generate |
| `features/generative-media/components/generative-media-editor-fs-modal.tsx` | Повноекранна історія + Ghost-write + Use this image |
| `app/_actions/generative-media.ts` | `listGenMediaMessagesAction`, `runGenMediaImageAction`, `runGhostWriteAction`, … |
| `lib/file/media-asset.ts` | SSOT відображення `pickImageSrc` / `pickGalleryDisplayUrl` |
| `features/chat/services/conversation-service.ts` | `isHiddenToolConversation` |

### Гейти авторизації (перевірено)

**Потрібна сесія** — усі server actions generative-media викликають `auth()`; без автентифікації → `Unauthorized`.

**Область NFT потребує member+** — `requireMember = true`, коли `scope === 'nft'`.

**Області product / cabinet** — автентифікований actor (форма vendor/admin або шлях власника cabinet).

### Білінг (credit-first)

| Дія | Env key | Кредити за замовчуванням |
|--------|---------|-----------------|
| Ghost-write | `GENERATIVE_CREDIT_GHOST_WRITE` | `5` |
| Image gen | `GENERATIVE_CREDIT_IMAGE` | `15` |
| Video gen (ціна є; studio polish TBD) | `GENERATIVE_CREDIT_VIDEO` | `50` |

Потік: м’яка ідемпотентність за `referenceId` у `generative_usage` → перевірка балансу → `WalletConductor.spendCredits` → рядок журналу.

### Повторне використання каналу розмови

| Поле | Значення |
|-------|--------|
| `type` | `'product'` |
| `metadata.kind` | `'generative_gallery'` |
| `metadata.hiddenFromInbox` | `true` |
| `metadata.productId` / `subject` | `genmedia:{scope}:{entity}:{page}:{field}` |

Чати product-agent магазину також використовують `type: 'product'` із реальним `productId` каталогу та **без** tool `kind` — вони залишаються **видимими** у Messages.

## Пов’язана документація

  
- [features/messaging](/docs/features/messaging.md) — Залежність: Conversation.type проти metadata.kind — tool chats повторно використовують product channel.

  
- [features/nft-market](/docs/features/nft-market.md) — Той самий процес: Generative Gallery під час create/mint/list для member.

  
- [features/store](/docs/features/store.md) — Той самий процес: поле галереї товару плюс WebConductor Agent Knowledge Research.

  
- [features/file-cabinet](/docs/features/file-cabinet.md) — Наступний крок: Image/Video chat на панелі деталей і збереження поруч із parentId.

  
- [features/wallet-conductor](/docs/features/wallet-conductor.md) — Залежність: витрачання кредитів для generative billing.

  
- [integrations/ring-filebase](/docs/integrations/ring-filebase.md) — Залежність: об’єктне сховище + драбини похідних fileId_v_*.

  
- [development/generative-images](/docs/development/generative-images.md) — Поглиблення: нотатки про ImageConductor / сховище нижчого рівня.