---
title: "VideoConductor"
description: "Оркестрація генеративного відео Ring Platform — xAI Grok Imagine Video, режими чернетки/продакшену, перші кадри через ImageConductor, збереження в ring-filebase та MCP ring-video-create"
locale: "uk"
---
# VideoConductor

**VideoConductor** — це асинхронний шар генеративного відео Ring Platform — відеоаналог [ImageConductor](/docs/development/generative-images.md). Він опитує xAI Grok Imagine Video, за потреби завантажує MP4 у **ring-filebase** та записує рядок аудиту в PostgreSQL `generated_videos`.

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

Оператори й агенти викликають **`ring-video-create`** (MCP) або `VideoConductor` із серверного коду. Типовий режим **`draft`** використовує **`grok-imagine-video` @ 480p** (~**$0.05/second**) для дешевої ітерації text-to-video. Встановіть **`remaster: true`** для фіналів **720p** або передайте `sourceVideoUrl` для монтажу/remaster зі збереженням сцени через API редагування відео xAI. Статичні зображення першого кадру створюються через **ImageConductor**.

## Що робить VideoConductor

| Можливість | Деталі |
|------------|--------|
| **Text-to-video (T2V)** | `grok-imagine-video` — монтажі, демо UI, нечіткі діалоги |
| **Image-to-video (I2V)** | `grok-imagine-video-1.5` — потребує `imageUrl`; prompt керує рухом |
| **Ітерація чернетки** | Пресети 480p — мінімізують витрати під час сценарної роботи |
| **Продакшен-remaster** | Повторна генерація 720p або редагування наявного MP4 URL |
| **Автоматизація першого кадру** | `firstFramePrompt` → ImageConductor, коли `imageUrl` відсутній |
| **Накладки мініатюри** | Необов’язкова специфікація `thumbnail` через `lib/media/thumbnail` |
| **Збереження** | CDN URL ring-filebase + JSONB-реєстр `generated_videos` |
| **Аудит pipeline** | `clipId`, `pipelineRequestId`, `refCode`, `actorId` |

## Режими якості

SSOT: `lib/video/video-presets.json`. Передавання `imageUrl` у запиті `draft` автоматично підвищує режим до **`draft_i2v`**.

| `qualityMode` | Модель | Роздільність | ~$/sec | Потрібен `imageUrl` |
|---------------|--------|------------|--------|------------------|
| **`draft`** (типовий) | `grok-imagine-video` | 480p | $0.05 | Ні (T2V) |
| **`draft_i2v`** | `grok-imagine-video-1.5` | 480p | $0.08 | Так |
| **`production`** | `grok-imagine-video` | 720p | $0.05 | Ні |
| **`production_i2v`** | `grok-imagine-video-1.5` | 720p | $0.14 | Так |

**`grok-imagine-video-1.5` — не T2V лише з тексту**: йому потрібен початковий кадр (`imageUrl` або `firstFramePrompt`). Для дослівних реплік записуйте VO на постпродакшені або сприймайте блоки `DIALOGUE:` як рекомендації без гарантії.

### For founders

## Шлях оператора

```mermaid
flowchart LR
  Draft["Draft @ 480p"]
  Review["Operator review"]
  Remaster["Remaster @ 720p"]
  CDN["ring-filebase CDN"]
  Draft --> Review --> Remaster --> CDN
```

  
- **[MCP ring-video-create](/docs/mcp/ring-video-create.md)** — Інструмент із Bearer-захистом для агентів і ops — створюйте чернеткові кліпи без дотику до серверного коду.

  
- **[Viral video CLI](/docs/development/generative-videos.md)** — Кампанії з кількома кліпами на основі маніфесту з upsert-ами draft → remaster.

  
- **[ImageConductor](/docs/development/generative-images.md)** — Статичні зображення першого кадру та спільні облікові дані xAI для I2V-сцен.

  
- **[WalletConductor](/docs/features/wallet-conductor.md)** — Та сама модель conductor для грошових шляхів (поповнення, desk, кастодіальне відправлення).

### Поверхні

| Поверхня | Вхід | Auth |
|---------|--------|------|
| **MCP** | `ring-video-create` → `POST /api/mcp/v1/videos/generate` | Bearer `RING_MCP_ACCESS_KEY` |
| **Сценарний CLI** | `node scripts/ring-viral-video/run-scripted-video.mjs ` | Локальний `XAI_API_KEY` + gateway token |
| **Серверний код** | `VideoConductor.generate` / `.remaster` / `.editFromSource` | Runtime застосунку |

### Стратегії remaster

| Вхід | Поведінка |
|-------|----------|
| `remaster: true` лише | Повторна генерація в **720p** |
| `remaster: true` + **`sourceVideoUrl`** | **`POST /v1/videos/edits`** — редагування зі збереженням сцени |

### Процес контролю витрат

**Створюйте кожну сцену в 480p**

Використовуйте `qualityMode: draft` (або `draft_i2v` зі статичним кадром), доки композиція й рух не стануть прийнятними. CLI маніфестів робить upsert за `id::qualityMode` — часткові запуски ніколи не стирають попередні кліпи.

**Робіть remaster переможців у 720p**

Викликайте з `remaster: true` для схвалених кліпів або передавайте `sourceVideoUrl` із чернеткового маніфесту для редагування зі збереженням композиції.

**Зберігайте в ring-filebase**

Залишайте `persistToFilebase` зі значенням за замовчуванням `true`, щоб оператори отримували постійні CDN URL замість тимчасових посилань xAI, що спливають.

> **Tip**
> Вважайте витрати на чернетки навчальним бюджетом. Робіть remaster лише кліпів, які пройшли перевірку — це головний важіль контролю вартості відео xAI.

### For developers

## Потік від початку до кінця

```mermaid
sequenceDiagram
  participant Surface as MCP / CLI / server
  participant VC as VideoConductor
  participant IC as ImageConductor
  participant xAI as xAI API
  participant FB as ring-filebase
  participant DB as generated_videos

  Surface->>VC: generate(ctx) or remaster(ctx)
  opt firstFramePrompt without imageUrl
    VC->>IC: generate still (16:9)
    IC-->>VC: imageUrl
  end
  VC->>xAI: POST /v1/videos/generations or /edits
  xAI-->>VC: request_id
  loop poll until ready
    VC->>xAI: GET /v1/videos/{request_id}
  end
  xAI-->>VC: temporary MP4 URL
  opt persistToFilebase (default true)
    VC->>FB: upload generated/videos/…
    FB-->>VC: permanent CDN URL
    VC->>DB: createDoc generated_videos
  end
  VC-->>Surface: { success, video, firstFrame, thumbnail }
```

## Публічний API

{`import { VideoConductor } from '@/lib/video/conductor/video-conductor'

const result = await VideoConductor.generate({
  prompt: 'Cinematic product reveal, slow dolly in',
  qualityMode: 'draft',
  duration: 6,
  purpose: 'news-promo',
  actorId: session.user.id,
})

await VideoConductor.generate({
  prompt: 'ACTION: couple laughs. DIALOGUE: Woman says: "Try Ring."',
  firstFramePrompt: 'Nightclub bar, neon magenta, silver ring on finger',
  clipId: '03_sf_nightclub_opener',
  pipelineRequestId: 'campaign-2026-06',
})

await VideoConductor.remaster({
  prompt: 'Improve clarity; same dialogue, clearer lip movement',
  sourceVideoUrl: 'https://vidgen.x.ai/.../draft.mp4',
  remasterFromRequestId: 'prior-draft-request-id',
})`}

### Карта реалізації

| Рівень | Шлях |
|-------|------|
| Types | `lib/video/conductor/types.ts` |
| Фасад | `lib/video/conductor/video-conductor.ts` |
| Presets | `lib/video/video-presets.json` |
| Config | `lib/video/video.config.ts` |
| xAI provider | `lib/video/providers/xai.provider.ts` |
| Схема запиту | `lib/media/schemas.ts` → `generateVideoBodySchema` |
| MCP route | `app/api/mcp/v1/videos/generate/route.ts` |
| Сценарні медіа | `lib/media/*` — компілятор prompt, рендерер thumbnail |
| Truth lens | `AI-LEGIOX/legiox-truth-lens/xai-grok-imagine-video-specialist.nodus.json` |

### Тіло запиту MCP (перевірено)

{`{
  "prompt": "ACTION: man leans in. DIALOGUE: Man says: \\"So your HOA uses Ring?\\"",
  "firstFramePrompt": "Cinematic still, couple at SF nightclub bar, neon magenta, silver ring visible",
  "qualityMode": "draft",
  "duration": 12,
  "clipId": "03_sf_nightclub_ring_opener",
  "pipelineRequestId": "hoa-nightclub-viral-2026-06"
}`}

| Поле | Обов’язкове | Примітки |
|-------|----------|-------|
| `prompt` | Так | Рух, блоки `ACTION`, `DIALOGUE` |
| `qualityMode` | Ні | `draft` (типовий), `draft_i2v`, `production`, `production_i2v` |
| `imageUrl` | Для 1.5 I2V | Автоматично підвищує draft → `draft_i2v` |
| `firstFramePrompt` | Ні | Викликає ImageConductor, коли `imageUrl` відсутній |
| `thumbnail` | Ні | `ThumbnailSpec` — накладки на перший кадр |
| `sourceVideoUrl` | Для edit remaster | `url` попереднього кліпу з маніфесту або CDN |
| `remaster` | Ні | `true` → `VideoConductor.remaster()` |
| `remasterFromRequestId` | Ні | Аудитне посилання на xAI job чернетки |
| `persistToFilebase` | Ні | Типово `true` |
| `clipId` / `pipelineRequestId` | Ні | Відстеження кампаній із кількома кліпами |
| `purpose` / `refCode` | Ні | Шлях сховища + атрибуція referral |

`actorId` встановлюється на сервері через MCP guard — ніколи не довіряйте actor id, переданому клієнтом на gateway.

## База даних і сховище

Застосуйте міграцію **`data/migrations/018_generative_media_conductor_schema.sql`** (ідемпотентна).

{`psql "$DATABASE_URL" -f data/migrations/018_generative_media_conductor_schema.sql`}

| Таблиця | Роль |
|-------|------|
| `generated_videos` | Один рядок на збережений кліп — JSONB `data` містить `GeneratedVideoRecord` |
| `generated_images` | Статичні зображення першого кадру від ImageConductor (окремий реєстр) |

Проіндексовані шляхи JSONB: `actorId`, `provider`, `purpose`, `refCode`, `clipId`, `pipelineRequestId`, `qualityMode`, `requestId`, `generationKind`, `remasterFromRequestId`.

```mermaid
flowchart LR
  VC["VideoConductor"]
  FB["ring-filebase\\ngenerated/videos/{purpose}/{qualityMode}/{kind}/"]
  DB[("generated_videos\\nid + data JSONB")]
  VC -->|upload MP4| FB
  VC -->|createDoc| DB
  DB -.->|url, fileId, requestId| FB
```

BackendSelector спрямовує `generated_videos` і `generated_images` до PostgreSQL. Якщо таблиці немає, upload static image все одно завершується успішно; persist записує warning, доки не буде застосовано міграцію 018.

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

```mermaid
flowchart TB
  subgraph surfaces["Surfaces"]
    MCP["ring-video-create MCP"]
    CLI["ring-viral-video CLI"]
    SRV["Server imports"]
  end

  subgraph conductor["VideoConductor"]
    GEN[".generate()"]
    REM[".remaster()"]
    EDT[".editFromSource()"]
  end

  subgraph deps["Dependencies"]
    IC["ImageConductor\\nfirst frame"]
    TH["renderAndUploadThumbnail"]
    XAI["xai.provider\\nstart + poll"]
    FILE["file()\\nupload"]
    DB["db().createDoc\\ngenerated_videos"]
  end

  MCP --> GEN
  MCP --> REM
  CLI --> MCP
  SRV --> GEN
  GEN --> IC
  GEN --> TH
  GEN --> XAI
  REM --> EDT
  REM --> XAI
  XAI --> FILE
  FILE --> DB
```

## Змінні середовища

Із `env.local.template` — **повторно використовуйте `XAI_API_KEY`** з ImageConductor:

{`# Shared xAI credentials (also used by ImageConductor)
XAI_API_KEY=your_key
XAI_API_BASE_URL=https://api.x.ai/v1

# VideoConductor tuning
VIDEO_GEN_STORAGE_PREFIX=generated/videos
VIDEO_GEN_POLL_TIMEOUT_MS=900000
VIDEO_GEN_POLL_INTERVAL_MS=5000
XAI_VIDEO_DEFAULT_DURATION=6
XAI_VIDEO_ASPECT_RATIO=16:9

# MCP gateway (ring-video-create)
# RING_MCP_ACCESS_KEY=dev-only-change-me`}

Ніколи не комітьте `XAI_API_KEY` або `RING_MCP_ACCESS_KEY`. MCP routes захищені Bearer через `withMcpGuard`.

## Форма відповіді

| Поле | Опис |
|-------------|-------------|
| `video.url` | Постійний CDN URL (коли збережено) або тимчасовий URL xAI |
| `video.temporaryUrl` | Оригінальне посилання xAI для завантаження (спливає) |
| `video.requestId` | ID xAI job — аудит і ланцюжки remaster |
| `video.recordId` | ID рядка `generated_videos` |
| `firstFrame` | Ресурс ImageConductor, коли використано `firstFramePrompt` |
| `thumbnail` | Рендерена мініатюра, коли `thumbnail.enabled` |
| `estimatedCostUsd` | Оцінка `duration × preset rate` |
| `qualityMode` / `resolution` | Фактичний preset після автоматичного підвищення |

Помилки модерації повертають `success: false`, коли xAI встановлює `respect_moderation: false`.

## Пов’язане

  
- **[Generative Gallery](/docs/features/generative-media.md)** — Поле продукту/NFT gallery; полірування відеостудії перебуває в беклозі (`GENERATIVE_CREDIT_VIDEO`).

  
- **[Generative videos (developer)](/docs/development/generative-videos.md)** — Приклади CLI, таблиця цін моделей, застарілий generate script.

  
- **[Generative images](/docs/development/generative-images.md)** — Спільний блок xAI і генерація першого кадру.

  
- **[WalletConductor](/docs/features/wallet-conductor.md)** — Модель conductor для грошових шляхів гаманця.

  
- **[Компоненти документації](/docs/development/docs-components.md)** — Довідник MDX-віджетів для авторингу.

## Історія релізів

| Дата | Етап |
|------|-----------|
| 2026-06-09 | **ImageConductor** — реєстр `generated_images`, MCP `ring-image-create` |
| 2026-06-18 | **VideoConductor v1** — T2V draft/production, MCP `ring-video-create`, manifest v2 |
| 2026-06-18 | **Режими I2V** — `draft_i2v` / `production_i2v`, `firstFramePrompt`, edit remaster через `sourceVideoUrl` |
| 2026-06-19 | **Міграція 018** — `generated_videos` на dev + prod |
| 2026-07-12 | **Документація для двох аудиторій** — шлях операцій Founder проти API/сховища Developer |