Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
VideoConductor is Ring Platform's async generative video layer — the video counterpart to ImageConductor. It polls xAI Grok Imagine Video, optionally uploads MP4s to ring-filebase, and records an audit row in PostgreSQL generated_videos.
Use Founder / Developer tabs in the docs sidebar to filter this page. Founders see operator workflows and cost control; developers see facade APIs, MCP payloads, and storage.
Operators and agents call ring-video-create (MCP) or VideoConductor from server code. Default draft mode uses grok-imagine-video @ 480p (~$0.05/second) for cheap text-to-video iteration. Set remaster: true for 720p finals, or pass sourceVideoUrl for scene-preserving edit/remaster via xAI's video edits API. First-frame stills compose through ImageConductor.
| Capability | Detail |
|---|---|
| Text-to-video (T2V) | grok-imagine-video — montages, UI demos, vague dialogue |
| Image-to-video (I2V) | grok-imagine-video-1.5 — requires imageUrl; prompt drives motion |
| Draft iteration | 480p presets — minimize cost while scripting scenes |
| Production remaster | 720p re-generate or edit pass on an existing MP4 URL |
| First-frame automation | firstFramePrompt → ImageConductor when imageUrl is absent |
| Thumbnail overlays | Optional thumbnail spec via lib/media/thumbnail |
| Persistence | ring-filebase CDN URL + generated_videos JSONB ledger |
| Pipeline audit | clipId, pipelineRequestId, refCode, actorId |
SSOT: lib/video/video-presets.json. Passing imageUrl on a draft request auto-upgrades to draft_i2v.
qualityMode | Model | Resolution | ~$/sec | Needs imageUrl |
|---|---|---|---|---|
draft (default) | grok-imagine-video | 480p | $0.05 | No (T2V) |
draft_i2v | grok-imagine-video-1.5 | 480p | $0.08 | Yes |
production | grok-imagine-video | 720p | $0.05 | No |
production_i2v |
grok-imagine-video-1.5 is not text-only T2V — it needs a starting frame (imageUrl or firstFramePrompt). For word-perfect spoken lines, burn VO in post or treat DIALOGUE: blocks as best-effort guidance.
Product/NFT gallery field; video studio polish is backlog there (GENERATIVE_CREDIT_VIDEO).
CLI examples, model pricing table, legacy generate script.
Shared xAI block and first-frame generation.
Conductor pattern for wallet money paths.
| Date | Milestone |
|---|---|
| 2026-06-09 | ImageConductor — generated_images ledger, ring-image-create MCP |
| 2026-06-18 | VideoConductor v1 — draft/production T2V, ring-video-create MCP, manifest v2 |
| 2026-06-18 | I2V modes — draft_i2v / production_i2v, firstFramePrompt, sourceVideoUrl edit remaster |
| 2026-06-19 | Migration 018 — generated_videos on dev + prod |
| 2026-07-12 | Dual-audience docs — Founder ops journey vs Developer API/storage |
VideoConductor is Ring Platform's async generative video layer — the video counterpart to ImageConductor. It polls xAI Grok Imagine Video, optionally uploads MP4s to ring-filebase, and records an audit row in PostgreSQL generated_videos.
Use Founder / Developer tabs in the docs sidebar to filter this page. Founders see operator workflows and cost control; developers see facade APIs, MCP payloads, and storage.
Operators and agents call ring-video-create (MCP) or VideoConductor from server code. Default draft mode uses grok-imagine-video @ 480p (~$0.05/second) for cheap text-to-video iteration. Set remaster: true for 720p finals, or pass sourceVideoUrl for scene-preserving edit/remaster via xAI's video edits API. First-frame stills compose through ImageConductor.
| Capability | Detail |
|---|---|
| Text-to-video (T2V) | grok-imagine-video — montages, UI demos, vague dialogue |
| Image-to-video (I2V) | grok-imagine-video-1.5 — requires imageUrl; prompt drives motion |
| Draft iteration | 480p presets — minimize cost while scripting scenes |
| Production remaster | 720p re-generate or edit pass on an existing MP4 URL |
| First-frame automation | firstFramePrompt → ImageConductor when imageUrl is absent |
| Thumbnail overlays | Optional thumbnail spec via lib/media/thumbnail |
| Persistence | ring-filebase CDN URL + generated_videos JSONB ledger |
| Pipeline audit | clipId, pipelineRequestId, refCode, actorId |
SSOT: lib/video/video-presets.json. Passing imageUrl on a draft request auto-upgrades to draft_i2v.
qualityMode | Model | Resolution | ~$/sec | Needs imageUrl |
|---|---|---|---|---|
draft (default) | grok-imagine-video | 480p | $0.05 | No (T2V) |
draft_i2v | grok-imagine-video-1.5 | 480p | $0.08 | Yes |
production | grok-imagine-video | 720p | $0.05 | No |
production_i2v |
grok-imagine-video-1.5 is not text-only T2V — it needs a starting frame (imageUrl or firstFramePrompt). For word-perfect spoken lines, burn VO in post or treat DIALOGUE: blocks as best-effort guidance.
Product/NFT gallery field; video studio polish is backlog there (GENERATIVE_CREDIT_VIDEO).
CLI examples, model pricing table, legacy generate script.
Shared xAI block and first-frame generation.
Conductor pattern for wallet money paths.
| Date | Milestone |
|---|---|
| 2026-06-09 | ImageConductor — generated_images ledger, ring-image-create MCP |
| 2026-06-18 | VideoConductor v1 — draft/production T2V, ring-video-create MCP, manifest v2 |
| 2026-06-18 | I2V modes — draft_i2v / production_i2v, firstFramePrompt, sourceVideoUrl edit remaster |
| 2026-06-19 | Migration 018 — generated_videos on dev + prod |
| 2026-07-12 | Dual-audience docs — Founder ops journey vs Developer API/storage |
VideoConductor is Ring Platform's async generative video layer — the video counterpart to ImageConductor. It polls xAI Grok Imagine Video, optionally uploads MP4s to ring-filebase, and records an audit row in PostgreSQL generated_videos.
Use Founder / Developer tabs in the docs sidebar to filter this page. Founders see operator workflows and cost control; developers see facade APIs, MCP payloads, and storage.
Operators and agents call ring-video-create (MCP) or VideoConductor from server code. Default draft mode uses grok-imagine-video @ 480p (~$0.05/second) for cheap text-to-video iteration. Set remaster: true for 720p finals, or pass sourceVideoUrl for scene-preserving edit/remaster via xAI's video edits API. First-frame stills compose through ImageConductor.
| Capability | Detail |
|---|---|
| Text-to-video (T2V) | grok-imagine-video — montages, UI demos, vague dialogue |
| Image-to-video (I2V) | grok-imagine-video-1.5 — requires imageUrl; prompt drives motion |
| Draft iteration | 480p presets — minimize cost while scripting scenes |
| Production remaster | 720p re-generate or edit pass on an existing MP4 URL |
| First-frame automation | firstFramePrompt → ImageConductor when imageUrl is absent |
| Thumbnail overlays | Optional thumbnail spec via lib/media/thumbnail |
| Persistence | ring-filebase CDN URL + generated_videos JSONB ledger |
| Pipeline audit | clipId, pipelineRequestId, refCode, actorId |
SSOT: lib/video/video-presets.json. Passing imageUrl on a draft request auto-upgrades to draft_i2v.
qualityMode | Model | Resolution | ~$/sec | Needs imageUrl |
|---|---|---|---|---|
draft (default) | grok-imagine-video | 480p | $0.05 | No (T2V) |
draft_i2v | grok-imagine-video-1.5 | 480p | $0.08 | Yes |
production | grok-imagine-video | 720p | $0.05 | No |
production_i2v |
grok-imagine-video-1.5 is not text-only T2V — it needs a starting frame (imageUrl or firstFramePrompt). For word-perfect spoken lines, burn VO in post or treat DIALOGUE: blocks as best-effort guidance.
Product/NFT gallery field; video studio polish is backlog there (GENERATIVE_CREDIT_VIDEO).
CLI examples, model pricing table, legacy generate script.
Shared xAI block and first-frame generation.
Conductor pattern for wallet money paths.
| Date | Milestone |
|---|---|
| 2026-06-09 | ImageConductor — generated_images ledger, ring-image-create MCP |
| 2026-06-18 | VideoConductor v1 — draft/production T2V, ring-video-create MCP, manifest v2 |
| 2026-06-18 | I2V modes — draft_i2v / production_i2v, firstFramePrompt, sourceVideoUrl edit remaster |
| 2026-06-19 | Migration 018 — generated_videos on dev + prod |
| 2026-07-12 | Dual-audience docs — Founder ops journey vs Developer API/storage |
grok-imagine-video-1.5| 720p |
| $0.14 |
| Yes |
Same conductor pattern for money paths (top-up, desk, custodial send).
| Surface | Entry | Auth |
|---|---|---|
| MCP | ring-video-create → POST /api/mcp/v1/videos/generate | RING_MCP_ACCESS_KEY bearer |
| Scripted CLI | node scripts/ring-viral-video/run-scripted-video.mjs <request.json> | Local XAI_API_KEY + gateway token |
| Server code | VideoConductor.generate / .remaster / .editFromSource | App runtime |
| Input | Behavior |
|---|---|
remaster: true only | Re-generate at 720p |
remaster: true + sourceVideoUrl | POST /v1/videos/edits — scene-preserving edit |
Draft every scene @ 480p
Use qualityMode: draft (or draft_i2v with a still) until framing and motion are acceptable. Manifest CLI upserts by id::qualityMode — partial runs never wipe prior clips.
Remaster winners @ 720p
Call with remaster: true on approved clips, or pass sourceVideoUrl from the draft manifest for an edit pass that preserves composition.
Persist to ring-filebase
Leave persistToFilebase at default true so operators get permanent CDN URLs instead of expiring xAI temporary links.
Treat draft spend as the learning budget. Only remaster clips that survive review — that is the main lever on xAI video cost.
lib/video/providers/xai.provider.ts| Request schema | lib/media/schemas.ts → generateVideoBodySchema |
| MCP route | app/api/mcp/v1/videos/generate/route.ts |
| Scripted media | lib/media/* — prompt compiler, thumbnail renderer |
| Truth lens | AI-LEGIOX/legiox-truth-lens/xai-grok-imagine-video-specialist.nodus.json |
| Field | Required | Notes |
|---|---|---|
prompt | Yes | Motion, ACTION, DIALOGUE blocks |
qualityMode | No | draft (default), draft_i2v, production, production_i2v |
imageUrl | For 1.5 I2V | Auto-upgrades draft → draft_i2v |
firstFramePrompt | No | Triggers ImageConductor when imageUrl absent |
thumbnail | No | ThumbnailSpec — overlays on first frame |
sourceVideoUrl | For edit remaster | Prior clip url from manifest or CDN |
remaster | No | true → VideoConductor.remaster() |
remasterFromRequestId | No | Audit link to draft xAI job |
persistToFilebase | No | Default true |
clipId / pipelineRequestId | No | Multi-clip campaign tracking |
purpose / refCode | No | Storage path + referral attribution |
actorId is set server-side from the MCP guard — never trust client-supplied actor ids on the gateway.
Apply migration data/migrations/018_generative_media_conductor_schema.sql (idempotent).
| Table | Role |
|---|---|
generated_videos | One row per persisted clip — JSONB data holds GeneratedVideoRecord |
generated_images | First-frame stills from ImageConductor (separate ledger) |
Indexed JSONB paths: actorId, provider, purpose, refCode, clipId, pipelineRequestId, qualityMode, requestId, generationKind, remasterFromRequestId.
BackendSelector routes generated_videos and generated_images to PostgreSQL. Missing table: upload still succeeds; persist logs a warning until migration 018 is applied.
From env.local.template — reuse XAI_API_KEY from ImageConductor:
Never commit XAI_API_KEY or RING_MCP_ACCESS_KEY. MCP routes are bearer-gated via withMcpGuard.
| Field | Description |
|---|---|
video.url | Permanent CDN URL (when persisted) or temporary xAI URL |
video.temporaryUrl | Original xAI download link (expires) |
video.requestId | xAI job id — audit and remaster chains |
video.recordId | generated_videos row id |
firstFrame | ImageConductor asset when firstFramePrompt was used |
thumbnail | Rendered thumbnail when thumbnail.enabled |
estimatedCostUsd | duration × preset rate estimate |
qualityMode / resolution | Effective preset after auto-upgrade |
Moderation failures return success: false when xAI sets respect_moderation: false.
MDX widget reference for authoring.
grok-imagine-video-1.5| 720p |
| $0.14 |
| Yes |
Same conductor pattern for money paths (top-up, desk, custodial send).
| Surface | Entry | Auth |
|---|---|---|
| MCP | ring-video-create → POST /api/mcp/v1/videos/generate | RING_MCP_ACCESS_KEY bearer |
| Scripted CLI | node scripts/ring-viral-video/run-scripted-video.mjs <request.json> | Local XAI_API_KEY + gateway token |
| Server code | VideoConductor.generate / .remaster / .editFromSource | App runtime |
| Input | Behavior |
|---|---|
remaster: true only | Re-generate at 720p |
remaster: true + sourceVideoUrl | POST /v1/videos/edits — scene-preserving edit |
Draft every scene @ 480p
Use qualityMode: draft (or draft_i2v with a still) until framing and motion are acceptable. Manifest CLI upserts by id::qualityMode — partial runs never wipe prior clips.
Remaster winners @ 720p
Call with remaster: true on approved clips, or pass sourceVideoUrl from the draft manifest for an edit pass that preserves composition.
Persist to ring-filebase
Leave persistToFilebase at default true so operators get permanent CDN URLs instead of expiring xAI temporary links.
Treat draft spend as the learning budget. Only remaster clips that survive review — that is the main lever on xAI video cost.
lib/video/providers/xai.provider.ts| Request schema | lib/media/schemas.ts → generateVideoBodySchema |
| MCP route | app/api/mcp/v1/videos/generate/route.ts |
| Scripted media | lib/media/* — prompt compiler, thumbnail renderer |
| Truth lens | AI-LEGIOX/legiox-truth-lens/xai-grok-imagine-video-specialist.nodus.json |
| Field | Required | Notes |
|---|---|---|
prompt | Yes | Motion, ACTION, DIALOGUE blocks |
qualityMode | No | draft (default), draft_i2v, production, production_i2v |
imageUrl | For 1.5 I2V | Auto-upgrades draft → draft_i2v |
firstFramePrompt | No | Triggers ImageConductor when imageUrl absent |
thumbnail | No | ThumbnailSpec — overlays on first frame |
sourceVideoUrl | For edit remaster | Prior clip url from manifest or CDN |
remaster | No | true → VideoConductor.remaster() |
remasterFromRequestId | No | Audit link to draft xAI job |
persistToFilebase | No | Default true |
clipId / pipelineRequestId | No | Multi-clip campaign tracking |
purpose / refCode | No | Storage path + referral attribution |
actorId is set server-side from the MCP guard — never trust client-supplied actor ids on the gateway.
Apply migration data/migrations/018_generative_media_conductor_schema.sql (idempotent).
| Table | Role |
|---|---|
generated_videos | One row per persisted clip — JSONB data holds GeneratedVideoRecord |
generated_images | First-frame stills from ImageConductor (separate ledger) |
Indexed JSONB paths: actorId, provider, purpose, refCode, clipId, pipelineRequestId, qualityMode, requestId, generationKind, remasterFromRequestId.
BackendSelector routes generated_videos and generated_images to PostgreSQL. Missing table: upload still succeeds; persist logs a warning until migration 018 is applied.
From env.local.template — reuse XAI_API_KEY from ImageConductor:
Never commit XAI_API_KEY or RING_MCP_ACCESS_KEY. MCP routes are bearer-gated via withMcpGuard.
| Field | Description |
|---|---|
video.url | Permanent CDN URL (when persisted) or temporary xAI URL |
video.temporaryUrl | Original xAI download link (expires) |
video.requestId | xAI job id — audit and remaster chains |
video.recordId | generated_videos row id |
firstFrame | ImageConductor asset when firstFramePrompt was used |
thumbnail | Rendered thumbnail when thumbnail.enabled |
estimatedCostUsd | duration × preset rate estimate |
qualityMode / resolution | Effective preset after auto-upgrade |
Moderation failures return success: false when xAI sets respect_moderation: false.
MDX widget reference for authoring.
grok-imagine-video-1.5| 720p |
| $0.14 |
| Yes |
Same conductor pattern for money paths (top-up, desk, custodial send).
| Surface | Entry | Auth |
|---|---|---|
| MCP | ring-video-create → POST /api/mcp/v1/videos/generate | RING_MCP_ACCESS_KEY bearer |
| Scripted CLI | node scripts/ring-viral-video/run-scripted-video.mjs <request.json> | Local XAI_API_KEY + gateway token |
| Server code | VideoConductor.generate / .remaster / .editFromSource | App runtime |
| Input | Behavior |
|---|---|
remaster: true only | Re-generate at 720p |
remaster: true + sourceVideoUrl | POST /v1/videos/edits — scene-preserving edit |
Draft every scene @ 480p
Use qualityMode: draft (or draft_i2v with a still) until framing and motion are acceptable. Manifest CLI upserts by id::qualityMode — partial runs never wipe prior clips.
Remaster winners @ 720p
Call with remaster: true on approved clips, or pass sourceVideoUrl from the draft manifest for an edit pass that preserves composition.
Persist to ring-filebase
Leave persistToFilebase at default true so operators get permanent CDN URLs instead of expiring xAI temporary links.
Treat draft spend as the learning budget. Only remaster clips that survive review — that is the main lever on xAI video cost.
lib/video/providers/xai.provider.ts| Request schema | lib/media/schemas.ts → generateVideoBodySchema |
| MCP route | app/api/mcp/v1/videos/generate/route.ts |
| Scripted media | lib/media/* — prompt compiler, thumbnail renderer |
| Truth lens | AI-LEGIOX/legiox-truth-lens/xai-grok-imagine-video-specialist.nodus.json |
| Field | Required | Notes |
|---|---|---|
prompt | Yes | Motion, ACTION, DIALOGUE blocks |
qualityMode | No | draft (default), draft_i2v, production, production_i2v |
imageUrl | For 1.5 I2V | Auto-upgrades draft → draft_i2v |
firstFramePrompt | No | Triggers ImageConductor when imageUrl absent |
thumbnail | No | ThumbnailSpec — overlays on first frame |
sourceVideoUrl | For edit remaster | Prior clip url from manifest or CDN |
remaster | No | true → VideoConductor.remaster() |
remasterFromRequestId | No | Audit link to draft xAI job |
persistToFilebase | No | Default true |
clipId / pipelineRequestId | No | Multi-clip campaign tracking |
purpose / refCode | No | Storage path + referral attribution |
actorId is set server-side from the MCP guard — never trust client-supplied actor ids on the gateway.
Apply migration data/migrations/018_generative_media_conductor_schema.sql (idempotent).
| Table | Role |
|---|---|
generated_videos | One row per persisted clip — JSONB data holds GeneratedVideoRecord |
generated_images | First-frame stills from ImageConductor (separate ledger) |
Indexed JSONB paths: actorId, provider, purpose, refCode, clipId, pipelineRequestId, qualityMode, requestId, generationKind, remasterFromRequestId.
BackendSelector routes generated_videos and generated_images to PostgreSQL. Missing table: upload still succeeds; persist logs a warning until migration 018 is applied.
From env.local.template — reuse XAI_API_KEY from ImageConductor:
Never commit XAI_API_KEY or RING_MCP_ACCESS_KEY. MCP routes are bearer-gated via withMcpGuard.
| Field | Description |
|---|---|
video.url | Permanent CDN URL (when persisted) or temporary xAI URL |
video.temporaryUrl | Original xAI download link (expires) |
video.requestId | xAI job id — audit and remaster chains |
video.recordId | generated_videos row id |
firstFrame | ImageConductor asset when firstFramePrompt was used |
thumbnail | Rendered thumbnail when thumbnail.enabled |
estimatedCostUsd | duration × preset rate estimate |
qualityMode / resolution | Effective preset after auto-upgrade |
Moderation failures return success: false when xAI sets respect_moderation: false.
MDX widget reference for authoring.