video-generation

视频生成

使用 generate_media 并设置 mode="video" 来生成视频。系统会根据可用的 API 密钥自动选择最佳后端。

快速入门

# Simple text-to-video (auto-selects backend)
generate_media(prompt="A robot walking through a city", mode="video")

# Specify backend and duration
generate_media(prompt="Ocean waves crashing on rocks", mode="video",
               backend_type="google", duration=8)

# With aspect ratio
generate_media(prompt="A timelapse of clouds", mode="video",
               backend_type="grok", aspect_ratio="16:9", duration=10)

后端对比

后端	默认模型	时长范围	默认时长	分辨率	API 密钥
Grok（优先级 1）	grok-imagine-video	1-15s	5s	480p、720p	XAI_API_KEY
Google Veo（优先级 2）	veo-3.1-generate-preview	4-8s	8s	720p、1080p、4K（使用 size）；默认 16:9	GOOGLE_API_KEY
OpenAI Sora（优先级 3）	sora-2	4、8 或 12s（离散值）	4s	标准	OPENAI_API_KEY

关键参数

参数	说明	示例
prompt	视频的文字描述	"A drone flying over mountains"
backend_type	指定特定后端	"grok"、"google"、"openai"
model	覆盖默认模型	"veo-3.1-generate-preview"
duration	视频时长（秒）	8（会限制在后端允许的范围内）
aspect_ratio	视频宽高比	"16:9"、"9:16"、"1:1"
size	分辨率（Grok：480p/720p；Veo：720p/1080p/4k）	"720p"、"1080p"、"4k"
input_images	图生视频的源图像	["starting_frame.jpg"]
video_reference_images	风格/内容参考图像（Veo，最多 3 张）	["ref1.png", "ref2.png"]
negative_prompt	要排除的内容（Veo）	"blurry, low quality"

时长处理

每个后端的时长限制各不相同。generate_media 会自动将请求的时长限制在允许范围内：

• Grok：连续范围 1-15s（限制在边界值内）
• Google Veo：连续范围 4-8s（限制在边界值内），默认宽高比为 16:9
• OpenAI Sora：仅支持离散值（4、8 或 12s）——会调整为最接近的有效值

如果调整了时长，系统会记录一条警告。

图生视频

所有三个视频后端都支持通过 input_images 从现有图像开始生成视频：

generate_media(
    prompt="Animate this scene with gentle movement",
    mode="video",
    input_images=["scene.jpg"],
    duration=5
)

系统会使用 input_images 中的第一张图像；其他图像会被忽略。

生成时间

视频生成明显比图像生成更慢。所有后端都会轮询：

• Grok：SDK 会在内部处理轮询（超时最长 10 分钟）
• Google Veo：自定义轮询，每 20s 一次（最长 10 分钟）
• OpenAI Sora：自定义轮询，每 2s 一次

Veo 3.1：原生音频

Veo 3.1 会根据提示词内容自动生成音频（对白、音效、环境音）。无需额外参数，只需描述声音：

• 对白：在提示词中使用引号（"Hello," she said.）
• 音效：描述声音（tires screeching, engine roaring）
• 环境音：描述氛围（eerie hum resonates through the hallway）

Veo 3.1：扩展限制

使用 continue_from 和 veo_vid_* ID 扩展视频时：

• 分辨率固定为 720p（扩展的 API 要求）
• 仅支持 16:9 和 9:16 宽高比
• 每次扩展最多增加 7 秒（API 限制：最多扩展 20 次，总时长约 141s）
• 生成的视频会保留 2 天，之后过期

制作更长的视频

当前 API 将单段视频的时长上限设为 15 秒（Grok），大多数后端则为 4-8 秒。无法通过一次调用生成连续 30 秒以上的视频。经过验证的做法如下：

1. 规划镜头列表——将视频拆分为 6-8 秒的片段，并为每个镜头指定具体的摄影术语
2. 并行生成片段——使用 background=True 并发启动所有片段的生成
3. 在 Remotion 中合成（见下文）——在生成的视频素材上叠加程序化动画
4. 用音频衔接——统一的旁白或音乐轨道可以平滑过渡不同片段之间的画面切换

为确保画面连贯，请在每条提示词中使用相同的风格锚点（例如，“BBC Earth 纪录片摄影风格”），并保持光线和色彩描述一致。

包含示例、转场类型和时长策略的完整制作指南：参见 references/production.md

混合工作流：AI 视频素材 + Remotion 动画

最佳效果来自将 AI 生成的视频素材与 Remotion 程序化动画相结合，而非二选一。

AI 视频生成能够制作出纯程序化渲染无法媲美的写实电影级视频素材。Remotion 则能制作出 AI 生成无法可靠控制的精确排版、动态图形、叠加层和转场。两者应结合使用。

规则：先生成，再合成

1. 生成 AI 片段，用于电影级／写实镜头（环境、产品演示、氛围视频素材）
2. 在 Remotion 中将这些片段用作视觉基础——将其作为 <Video> 或 <OffthreadVideo> 背景层导入
3. 在上层合成程序化元素——排版、动态图形、徽标、数据叠加层、转场、字幕
4. 用纯 Remotion 动画填补空缺——标题卡、片头序列，以及无需 AI 视频素材的纯动态图形片段

不要丢弃生成的片段

每个 AI 生成片段都耗费真实的金钱和时间。不要放弃生成的视频素材，转而只用程序化渲染。 这是一种常见的失败模式——Agent 生成片段后，发现一些小瑕疵（例如重复图案、轻微失真），便完全转向使用 OpenCV/PIL/moviepy 渲染，白白浪费所有生成预算。

正确做法：

情况	错误做法	正确做法
生成的片段有轻微瑕疵	丢弃片段，改用 OpenCV 从头渲染	将片段用作背景，并用叠加层／动态图形遮盖瑕疵
生成的片段与构想不完全一致	重新生成或放弃	在上层合成排版／特效，引导观众的注意力
需要精确放置文本／徽标	跳过 AI 生成，完全使用程序化方案	生成氛围视频素材，再在 Remotion 中叠加文本
部分镜头需要 AI 视频素材，其他镜头不需要	所有内容都采用同一种方案	混合使用：以 AI 素材为基础的镜头 + 纯 Remotion 动画镜头

成本意识

每次 generate_media(mode="video") 调用的成本都很高。生成前请先规划：

• 先确定哪些镜头需要 AI 视频素材——不是每个镜头都需要
• 只生成会用到的素材——不要为了碰运气而试探性生成 8 个片段
• 检查并使用生成的素材——用 read_media 分析每个片段，然后根据实际素材规划 Remotion 合成
• 合成得当的一个好片段，胜过五个未使用的片段——应投入精力提升合成质量，而非增加生成数量

后期制作：始终使用 Remotion

对于任何需要进行简单拼接以外编辑的视频，Remotion 都是默认的后期制作工具。 这包括字幕、标题、转场、叠加元素、动态图形——基本上任何旨在呈现专业效果的视频。请勿使用原始 ffmpeg drawtext 或手动滤镜链来完成这些任务；与 Remotion 的效果相比，这些结果显得很业余。

需要拼接视频片段时，请加载 Remotion 技能并使用它。 专业级输出必须如此。

加载 Remotion 技能

加载该技能以获取详细规则和代码示例：

• 本地路径（如果通过 quickstart 安装）：.agent/skills/remotion/SKILL.md
• 远程仓库（如果未安装）：https://github.com/remotion-dev/skills

Remotion 能为你提供什么

能力	Remotion	原始 ffmpeg
样式化动画字幕	通过 CSS 设置样式、逐词高亮、动画效果	drawtext——效果难看，转义处理令人头疼
标题卡／字幕条	React 组件，字体和布局任你选择	手动定位，字体选择有限
场景转场	时间曲线、弹簧动画、自定义效果	基础 xfade（淡入淡出、擦除）
动态图形	完整的 React/CSS/Three.js/Lottie 生态系统	无法实现
漏光／叠加效果	内置 @remotion/light-leaks	需要复杂的滤镜链
文本动画	字体效果、逐字符动画	无法实现
AI 影像 + 叠加元素	将片段作为 <Video> 导入，在上方叠加 React 组件	无法达到理想质量

何时仅使用 ffmpeg 就足够

以下情况可只使用 ffmpeg，不使用 Remotion：

• 拼接没有字幕、标题或转场的片段（仅硬切）
• 混音／闪避处理（ffmpeg 或 Pydub）
• 通过 LUT 文件进行调色（lut3d 滤镜）
• 快速转换格式或调整分辨率

工作流

1. 使用 generate_media 生成 AI 片段（并行、后台模式）——适用于需要电影感／照片级真实效果的镜头
2. 使用 read_media 检查片段——评估现有素材，并根据实际影像规划构图
3. 使用 generate_media(mode="audio") 生成音频（旁白、音乐）
4. 加载 Remotion 技能并设置 Remotion 项目
5. 使用 Remotion 进行合成：将 AI 片段作为 <Video> 背景图层导入，叠加文字排版／动态图形／字幕，并为标题卡和转场添加纯动画片段
6. 使用 Remotion 的无头渲染器进行渲染

需要加载的关键 Remotion 规则文件

处理具体任务时，请从 Remotion 技能中加载相关规则文件：

• 字幕：rules/subtitles.md、rules/display-captions.md、rules/transcribe-captions.md
• 转场：rules/transitions.md
• 文本动画：rules/text-animations.md
• 漏光效果：rules/light-leaks.md
• 音频：rules/audio.md、rules/audio-visualization.md
• 序列／时间线：rules/sequencing.md、rules/trimming.md
• 3D 动态图形：rules/3d.md
• 动画／时间设置：rules/animations.md、rules/timing.md

需要更多控制？

• 各后端的分辨率、时长详情和特性：参阅 references/backends.md
• 视频续接、混剪和图像转视频：参阅 references/editing.md
• 多镜头制作、转场和电影化工作流：参阅 references/production.md