---
title: "ring-video-create"
description: "MCP tool — scripted media pipeline, firstFramePrompt auto-still, I2V, thumbnails, remaster"
locale: "en"
---
# `ring-video-create`

Generate a short video from a text prompt. **Scripted media path:** pass **`firstFramePrompt`** to auto-generate a still (ImageConductor), then I2V with **grok-imagine-video-1.5** @ 480p. Optional **`thumbnail`** text overlays on the first frame.

Author **`scripted-video-generation-request-*.json`** (see [Scripted media pipeline](/docs/development/scripted-media-pipeline.md)) or pass **`firstFramePrompt`** + compiled **`DIALOGUE:`** prompt directly. No manual `imageUrl` wrangling required.

  
- **[Scripted media pipeline](/docs/development/scripted-media-pipeline.md)** — Request JSON schema, CLI, director lens.

  
- **[Generative videos](/docs/development/generative-videos.md)** — Full VideoConductor reference, CLI, truth lens.

  
- **[ring-image-create](/docs/mcp/ring-image-create.md)** — Standalone still generation (invoked via firstFramePrompt).

## Quality modes & cost

| `qualityMode` | Model | Resolution | ~$/sec | Notes |
|---------------|--------|------------|--------|-------|
| **`draft`** (default) | `grok-imagine-video` | 480p | $0.05 | T2V — no `imageUrl` |
| **`draft_i2v`** | `grok-imagine-video-1.5` | **480p** | **$0.08** | **I2V + prompt** — needs `imageUrl` |
| **`production`** | `grok-imagine-video` | 720p | $0.05 | T2V remaster |
| **`production_i2v`** | `grok-imagine-video-1.5` | 720p | $0.14 | I2V remaster |

**Auto:** `draft` + `imageUrl` → `draft_i2v` without passing `draft_i2v` explicitly.

## Parameters

| Parameter | Required | Type | Notes |
|-----------|----------|------|-------|
| `prompt` | **Yes** | string | Scene, ACTION, **DIALOGUE:** lines |
| `imageUrl` | For 1.5 | string | Pre-generated frame — skips `firstFramePrompt` |
| `firstFramePrompt` | For scripted I2V | string | Auto-generates still when `imageUrl` absent |
| `imageProvider` | No | `xai` \| `google` | First-frame provider (default xai) |
| `imageModel` | No | string | Override image model |
| `imageResolution` | No | `1k` \| `2k` | First-frame resolution (default 2k) |
| `clipId` | No | string | Clip id for manifest / DB audit |
| `pipelineRequestId` | No | string | Parent request file id |
| `thumbnail` | No | object | `{ enabled, template, overlays[] }` — text on first frame |
| `qualityMode` | No | enum | `draft`, `draft_i2v`, `production`, `production_i2v` |
| `remaster` | No | boolean | 720p re-gen **or** edit when `sourceVideoUrl` set |
| `sourceVideoUrl` | No | string | Manifest/CDN MP4 → `POST /v1/videos/edits` |
| `remasterFromVideoUrl` | No | string | Alias for `sourceVideoUrl` |
| `duration` | No | number | 1–15 seconds (default 6) |
| `aspectRatio` | No | string | e.g. `16:9`, `9:16` |
| `resolution` | No | `480p` \| `720p` \| `1080p` | Override preset |
| `model` | No | string | Override xAI model slug |
| `remasterFromRequestId` | No | string | Audit link to draft job |
| `persistToFilebase` | No | boolean | Default true |

## Examples

**Scripted scene (auto first frame + thumbnail):**

```
ring-video-create prompt "DIALOGUE: Man says: \"Ringize your HOA.\"" firstFramePrompt "Cinematic still, guy and girl at SF nightclub bar, neon lights" qualityMode draft duration 12 clipId 03_opener thumbnail '{"enabled":true,"overlays":[{"text":"Your HOA on Ring","role":"title","position":"bottom"}]}'
```

**Pre-generated imageUrl (skip first frame):**

```
ring-video-create prompt "DIALOGUE: …" imageUrl https://cdn.../still.jpg qualityMode draft duration 12
```

**Remaster from manifest URL (edit):**

```
ring-video-create prompt "Sharpen scene; clearer lip movement for same dialogue" remaster true sourceVideoUrl https://vidgen.x.ai/.../draft.mp4 remasterFromRequestId 
```

**720p re-generate (no source URL):**

```
ring-video-create prompt "…same locked prompt…" remaster true imageUrl https://cdn.../still.jpg qualityMode production_i2v duration 12
```

## Response shape

Success includes `firstFrame`, `thumbnail`, `clipId`, `pipelineRequestId`, and `generationKind`: `generate` | `edit`.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Vague dialogue | Use **1.5 I2V** + `imageUrl` + explicit **DIALOGUE:** in prompt |
| `requires imageUrl` | 1.5 is I2V-only — generate still first |
| `does not support text-to-video` | Use `grok-imagine-video` for T2V montages |
| Edit remaster same resolution | Edit inherits source res (capped 720p) — use re-gen for true 720p upscale |
| Timeout | Raise `VIDEO_GEN_POLL_TIMEOUT_MS` |

## Related docs

- [xAI video generation](https://docs.x.ai/developers/model-capabilities/video/generation)
- [xAI video editing](https://docs.x.ai/developers/model-capabilities/video/editing)
- [AIML grok-imagine-video-1.5-preview](https://docs.aimlapi.com/api-references/video-models/xai/grok-imagine-video-1.5-preview)