从分镜到短片

输入故事构想后，应用会规划四个镜头，分别绘制关键帧，将其制作成八秒片段，并为故事配上旁白。网页实时展示从 Grok 的推理到成片的每一步。

你将学到

• 以结构化输出生成分镜列表，并在规划过程中流式展示 Grok 的推理

• 基于第一个关键帧进行编辑以保持角色形象一致，同时为每个镜头设置不同的场景和机位

• 用图生视频将静态图像变为动画，并行运行多个任务并等待完成

• 通过文本转语音添加旁白

• 通过服务器发送事件从 Node 服务器向网页实时传送进度

运行示例

需要 Node.js 22.13 或更高版本。将 API 密钥放在 .env（仓库根目录），或导出环境变量 XAI_API_KEY。如果已安装 ffmpeg，应用还会将镜头拼接成影片并混入旁白。

cd examples/storyboard-to-film/typescript
npm install
npm run web

打开 http://localhost:3000，输入或选择一个故事构想，点击 Make film。页面类似视频编辑器。左侧面板逐步显示分镜计划和 Grok 编写计划时的推理。各镜头绘制完关键帧并渲染视频后会填入时间线的对应位置，旁白进入下方的语音轨道。点击某个镜头即可在监视器中预览。镜头拼接完成后，监视器会播放成片，点击时间线可跳转。

要在终端制作短片，请传入故事构想：

npm start -- "A lighthouse keeper's cat on the night of the big storm"

如果不提供构想，默认拍摄一只纸船穿行雨中城市的故事。两个版本都将文件保存至 output/<title>/。终端版还会在该目录中写入 index.html，用来播放各镜头。每次运行生成四张图像和四段视频，耗时数分钟；本示例实测一次约花费 5 美元。两个版本都会在最后显示图像和视频费用。

工作原理

共享代码位于 src/storyboard.ts：

1. planStoryboard() 通过 grok-4.7 以结构化输出流式生成标题、视觉风格和四个镜头。每个镜头包含场景、运镜方式和一句旁白，各有不同的环境和机位。同时实时展示 Grok 的推理。

2. drawKeyframes() 使用 client.images.generate() 生成首个关键帧，再用 client.images.edit() 制作其余三个。以首帧为主体和风格参考，要求从新机位绘制新场景。采用编辑方式可使主角在不同镜头中保持一致。如果提示词只说要保留主体，模型也会保留构图，导致各镜头像是同一张图片的变体。每个关键帧绘制完成后都会立即上报。

3. animate() 会启动 grok-imagine-video-1.5 任务，通过 client.videos.generate() 将关键帧生成视频，并使用 client.videos.wait() 等待任务完成。生成的视频自带声音。

4. narrate() 会录制一句旁白，使用 client.voice.speak()。

5. assembleFilm() 用 ffmpeg 将各句旁白叠加在相应镜头上，调低原声后拼接镜头。

这些函数接收 AbortSignal，并将它传给 SDK 和 ffmpeg，使调用者能够中途停止。drawKeyframes() 和 animate() 还会返回每张图像和每段视频的费用。

src/server.ts 为网页执行上述步骤，同时生成四个镜头的动画并录制旁白。每个文件完成后便保存到 output/<title>/，并以服务器发送事件向页面报告进度。服务器仅提供它保存的文件，支持按字节范围传输，以便浏览器在视频中跳转。页面关闭后即停止调用 API。public/index.html 使用原生 HTML 和 JavaScript 展示这些事件。src/index.ts 在终端执行相同的工作。