---
title: "Generative Gallery"
description: "Upload or AI-generate galleries for NFT, store products, and File Cabinet — credit-billed Ghost-write + ImageConductor, cabinet sibling saves, RingFileBase derivatives"
locale: "en"
---
# Generative Gallery

Generative Gallery is Ring Platform’s **shared media field** for NFT create, multi-vendor product forms, and File Cabinet detail-panel Image/Video chat. Operators **upload** images or **generate** ImageConductor variations, enrich prompts with **Ghost-write** (TextConductor + web search), and keep history in a **hidden tool chat** (`genmedia:…`) that never clutters Messages.

> **Info**
> Use **Founder** / **Developer** tabs in the docs sidebar to filter this page. Founders see operator value and surfaces; developers see modules, billing, and verified paths.

## Where it ships

| Surface | Role |
|---------|------|
| NFT create wizard | Collection cover + mint media via `GenerativeMediaField` (`scope: 'nft'`) |
| Vendor / admin product form | Product image gallery (`scope: 'product'`); Agent Knowledge Research is a separate WebConductor path — see [Store](/docs/features/store.md) |
| File Cabinet detail panel | **Image chat** / **Video chat** → `GenerativeMediaEditorFsModal` (`scope: 'cabinet'`); sibling save under source parent |
| Product detail gallery | Prefers `derivatives.thumb` / `webpUrl` for strip; lightbox uses original |
| News cards / hero / OG | `pickImageSrc` → card / hero / og; blur LQIP when present |
| Avatar | `avatarThumb` (sync_thumb) preferred over `photoURL` original |
| Chat image bubbles | `MessageAttachment.derivatives.thumb` preferred over original URL |
| NFT mint + listings | Off-chain Metaplex JSON (`image`, optional `animation_url`, `properties.files`) |

SSOT module: `features/generative-media/`. Scopes: `nft` \| `product` \| `cabinet` \| `editor`.

### For founders

## Why this matters for your clone

- **One field, several desks** — store catalog photos, member NFT art, and cabinet enhance/enlive share one generative UX.
- **Credit-first spend** — Ghost-write and image generation debit platform credits through WalletConductor before the turn runs.
- **Clean inbox** — generation history lives in a hidden product-tool conversation (`generative_gallery` / `genmedia:`).
- **Research vs Generate** — Store **Research** (WebConductor) harvests citation-backed web photos into File Cabinet `…/alt`; Generative Gallery creates or enhances pixels. Gallery attach from research stays **Use in gallery** (explicit).
- **Cabinet siblings** — enhance/enlive saves next to the source file as `{name}-enhanced-…` or `{name}-enlive-…` so originals stay intact.

  
- **[NFT Marketplace](/docs/features/nft-market.md)** — Member create/mint/list — Generative Gallery is the media path.

  
- **[Multi-Vendor Store](/docs/features/store.md)** — Product forms + Agent Knowledge Research (WebConductor) + Use in gallery.

  
- **[File Cabinet](/docs/features/file-cabinet.md)** — Detail-panel Image/Video chat entry and sibling save.

  
- **[WalletConductor](/docs/features/wallet-conductor.md)** — `spendCredits` powers generative billing today.

### Operator checklist

- Ensure ImageConductor / TextConductor providers are configured.
- Fund **platform credits** (`GENERATIVE_CREDIT_*` optional overrides).
- Prefer **`ring_filebase`** so uploads return a full `derivatives` map.
- Train vendors: Upload \| Generate on the product form; Research for web harvest; cabinet Image chat for polish.
- On NFT listings, verify showcase thumbs/animation when creators attach multi-item galleries.

### Typical journeys

```mermaid
flowchart LR
  Field[GenerativeMediaField]
  Cab[Cabinet detail panel]
  Field --> Upload[Upload tab]
  Field --> Gen[Generate tab]
  Cab --> Chat[Image / Video chat]
  Chat --> Modal[GenerativeMediaEditorFsModal]
  Modal --> Sib[Sibling under parentId]
  Upload --> Strip[Gallery strip]
  Gen --> Ghost[Ghost-write optional]
  Ghost --> IC[ImageConductor]
  IC --> Strip
  Strip --> Store[Product / NFT]
```

### For developers

## Architecture

Credit-first generative turns run through server actions → `features/generative-media/service.ts` → ImageConductor / TextConductor, with optional WebP derive and FCM/in-app notify when generation completes in the background.

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

### Cabinet entry path (Phase G — shipped)

| Step | Detail |
|------|--------|
| UI trigger | `file-cabinet-detail-panel.tsx` — **Image chat** / **Video chat** on image files when `canGenerate` |
| Desktop host | `file-cabinet-desktop.tsx` opens `GenerativeMediaEditorFsModal` with `scope="cabinet"` |
| Save action | `saveGeneratedMediaToDesktopAction` in `app/_actions/file-cabinet.ts` |
| Naming | `{base}-enhanced-{ts}.{ext}` for images; `{base}-enlive-{ts}.{ext}` for video (`base` from source filename) |
| Parent | `parentId: genSourceNode.parentId` — sibling of the source, not a new root dump |
| Pipeline | `cabinet.genmedia.sibling_save` in `scripts/PIPELINES.md` |

### Modules

| Path | Role |
|------|------|
| `features/generative-media/types.ts` | `GalleryItem`, scopes `nft` \| `product` \| `cabinet` \| `editor`, `buildGenMediaChatKey` → `genmedia:scope:entity:page:field` |
| `features/generative-media/billing.ts` | Credit-first `WalletConductor.spendCredits` + `generative_usage` ledger |
| `features/generative-media/service.ts` | Hidden tool chat, upload, Ghost-write, ImageConductor / video turns |
| `features/generative-media/nft-metadata.ts` | Metaplex JSON + upload helpers |
| `features/generative-media/parse-product-images.ts` | FormData URL gallery for vendor/admin |
| `features/generative-media/components/generative-media-field.tsx` | Upload \| Generate tabs SSOT widget |
| `features/generative-media/components/generative-media-editor-fs-modal.tsx` | Fullscreen history + Ghost-write + Use this image |
| `app/_actions/generative-media.ts` | `listGenMediaMessagesAction`, `runGenMediaImageAction`, `runGhostWriteAction`, … |
| `lib/file/media-asset.ts` | `pickImageSrc` / `pickGalleryDisplayUrl` display SSOT |
| `features/chat/services/conversation-service.ts` | `isHiddenToolConversation` |

### Auth gates (verified)

**Session required** — all generative-media server actions call `auth()`; unauthenticated → `Unauthorized`.

**NFT scope needs member+** — `requireMember = true` when `scope === 'nft'`.

**Product / cabinet scopes** — signed-in actor (vendor/admin form or cabinet owner path).

### Billing (credit-first)

| Action | Env key | Default credits |
|--------|---------|-----------------|
| Ghost-write | `GENERATIVE_CREDIT_GHOST_WRITE` | `5` |
| Image gen | `GENERATIVE_CREDIT_IMAGE` | `15` |
| Video gen (priced; studio polish TBD) | `GENERATIVE_CREDIT_VIDEO` | `50` |

Flow: soft-idempotent on `referenceId` in `generative_usage` → balance check → `WalletConductor.spendCredits` → ledger row.

### Conversation channel reuse

| Field | Value |
|-------|--------|
| `type` | `'product'` |
| `metadata.kind` | `'generative_gallery'` |
| `metadata.hiddenFromInbox` | `true` |
| `metadata.productId` / `subject` | `genmedia:{scope}:{entity}:{page}:{field}` |

Store product-agent chats also use `type: 'product'` with a real catalog `productId` and **no** tool `kind` — they remain **visible** in Messages.

## Related documentation

  
- [features/messaging](/docs/features/messaging.md) — Depends-on: Conversation.type vs metadata.kind — tool chats reuse the product channel.

  
- [features/nft-market](/docs/features/nft-market.md) — Same-workflow: Generative Gallery on member create/mint/list.

  
- [features/store](/docs/features/store.md) — Same-workflow: product gallery field plus WebConductor Agent Knowledge Research.

  
- [features/file-cabinet](/docs/features/file-cabinet.md) — Next-step: detail-panel Image/Video chat and sibling save under parentId.

  
- [features/wallet-conductor](/docs/features/wallet-conductor.md) — Depends-on: credit spend used by generative billing.

  
- [integrations/ring-filebase](/docs/integrations/ring-filebase.md) — Depends-on: object storage + fileId_v_* derivative ladders.

  
- [development/generative-images](/docs/development/generative-images.md) — Deep-dive: lower-level ImageConductor / storage notes.