如何使用 Opus 5.5 构建 2.5D 动态图形工作室

手把手教你用 Claude Opus 5.5 在一次 Claude Code 会话中构建单文件 2.5D 动态图形工作室,涵盖 CSS 3D 透视补偿、关键帧插值、Playwright + ffmpeg 无掉帧导出与 API 测试。

用 Apifox,节省研发团队的每一分钟

如何使用 Opus 5.5 构建 2.5D 动态图形工作室

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

借助 Opus 5.5,你可以在一次 Claude Code 会话中构建出一个完整的 2.5D 动态图形工作室(Motion Studio):仅需一个单文件 HTML,即可在不同深度上堆叠平面图层、通过带缓动曲线(easing)的关键帧驱动虚拟摄像机穿行其中,再配合一段 25 行的 Playwright 脚本逐帧截图并推流给 ffmpeg。在我们的实测中,一台普通笔记本电脑仅用约 20 秒就渲染出了一段 6 秒的 720p MP4 视频(共 180 帧)。

本文将展示完整的提示词、智能体编写的核心代码、构建过程中遇到的典型 bug,以及如何使用 Apifox CLI 为“一句话生成镜头脚本(describe a shot)”功能背后的 Opus 5.5 API 调用编写测试。

AI Coding 交流群

如果你也在用 AI 写代码,或者正在研究 Cursor、Claude Code 这些工具,欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流,还有各种新工具和新玩法。

AI Coding 交流群二维码

什么是 2.5D 动态图形工作室?

2.5D 动态图形工作室是一种将平面 2D 图层(如天空、山丘、城市天际线、标题卡片、前景枝叶)放置在 3D 空间的不同深度上,再移动虚拟摄像机穿行其中的动画工具。离摄像机越近的图层滑动速度越快,离得越远的图层移动越慢,从而在不借助任何 3D 模型的情况下产生视差(parallax)和纵深感。

要算作一个真正的“工作室”而非一次性动画脚本,需要具备三个核心模块:

  1. 场景图(Scene graph):包含 z 轴深度、尺寸、位置和 HTML 内容的图层定义。
  2. 时间轴(Timeline):针对摄像机(推拉 dolly、横移 truck、环绕 orbit)以及各个图层(透明度、缩放、位置)的关键帧轨道,且每段过渡都支持独立的缓动曲线。
  3. 确定性渲染器(Deterministic renderer):一个 renderAt(t) 纯函数,能够根据任意时间点 t 精确绘制对应帧,确保视频导出质量永远不会受本机实时播放帧率波动的影响。

第三点是大多数教程都会忽略的关键,而它直接决定了导出的 MP4 视频是否会卡顿掉帧。

将 Claude Code 配置为 Opus 5.5

对于这类综合性编码任务,Opus 5.5 是最理想的起点。Anthropic 的模型概览文档将其定位为“面向长周期智能体编程与知识工作”,提供 1M token 上下文窗口、128K 最大输出,定价为每百万输入 / 输出 token $4 / $20。

建议在启动时直接锁定具体模型名称,避免后续模型别名指向变动导致项目半途切换模型:

claude --model claude-opus-5-5 --effort high

根据 Anthropic 的思考力度(effort)文档,Opus 5.5 默认使用 medium 力度。在首次构建项目、需要智能体一次性算准透视投影数学公式时,建议将其调高至 high;后续仅微调关键帧和配色时,再降回 medium 即可。如果你想先了解该模型的基础信息,可以参考 Claude Opus 5.5 深度解析以及提示词缓存如何改变其调用成本。

构建工作室的完整提示词

一条精准具体的提示词远胜过五条含糊不清的指令。以下是我们编写的单条完整构建规范提示词:

Build a 2.5D motion studio as one file, studio.html, with no dependencies.
- Scene: 6 layers (sky, moon, hills, city skyline, a title card "Ship it.",
  foreground foliage), each at its own z depth, using CSS perspective and
  preserve-3d.
- Camera: keyframes for x, y, z (dolly) and yaw (orbit around the card).
- Per-layer tracks: opacity, scale, y. Easings: linear, easeInOutCubic,
  easeInOutSine, easeOutBack.
- A timeline bar with keyframe markers, a playhead, click to scrub,
  space to play or pause.
- renderAt(t) must be pure in t. Expose window.__seek(t) that resolves after
  the frame paints, and a ?capture mode that hides the UI.
Then write export.mjs: Playwright opens ?capture, seeks every frame at 30 fps,
screenshots it and pipes PNGs to ffmpeg as H.264.

最后两行尤为关键:它们将视频导出能力直接纳入了架构设计,而不是事后拼凑的附加脚本。

智能体编写的核心代码

整个工作室代码约 150 行,其中最核心的是以下三部分。

关键帧插值与缓动计算

每条动画轨道都是一个按时间排序的关键帧列表。sample() 函数会找到时间点 t 前后的两个关键帧,应用起始关键帧的缓动函数,并对所有数值字段进行插值计算:

function sample(keys, t) {
  if (t <= keys[0].t) return keys[0];
  for (let i = 0; i < keys.length - 1; i++) {
    const a = keys[i], b = keys[i + 1];
    if (t <= b.t) {
      const p = (easings[a.ease] || easings.linear)((t - a.t) / (b.t - a.t));
      const out = {};
      for (const k in b) if (typeof b[k] === 'number' && k !== 't') out[k] = a[k] + (b[k] - a[k]) * p;
      return out;
    }
  }
  return keys[keys.length - 1];
}

透视深度补偿技巧

在 CSS 3D 空间里,摄像机本身并不移动,而是让整个世界向相反方向移动。随后,每个图层都会设置一个 z 轴平移量,并乘以一个透视补偿缩放系数:

const PERSPECTIVE = 1200; // must match #viewport perspective
world.style.transform =
  `translate3d(${-cam.x}px, ${-cam.y}px, ${cam.z}px) rotateY(${-cam.yaw}deg)`;
const comp = 1 - L.z / PERSPECTIVE;
el.style.transform = `translate(-50%,-50%) ` +
  `translate3d(${x * comp}px, ${y * comp}px, ${L.z}px) scale(${comp * s})`;

当 CSS perspective 设为 1200px 时,位于 z = -900 处的图层在屏幕上只会渲染出 1200 / 2100(即原始尺寸的 57%)。将其缩放比例和 x/y 偏移量同时乘以 1 + 900/1200 = 1.75,就能正好抵消透视缩小效应。这样一来,当摄像机静止在原点时,所有图层都会严格按你设计的尺寸和位置呈现;而当摄像机运动时,不同深度的图层依然会按各自的速度产生视差位移。这就是 2.5D 视觉错觉的全部奥秘。

浏览器中的 2.5D 动态图形工作室界面:标题卡片位于月亮、山丘与城市天际线前方,底部时间轴以蓝色标记摄像机关键帧、黄色标记图层关键帧,红色播放头停在 2.10s 处

一个值得注意的典型 Bug

智能体生成的第一版代码只对图层本身乘了补偿缩放系数,却漏掉了对偏移量 x 和 y 的补偿,导致远景山丘向上大幅偏移,遮住了三分之二的天空。修复方法很简单:将 x 和 y 也乘以 comp 即可。这个问题是我们通过渲染出的静态帧画面一眼发现的,而不是靠肉眼读代码看出来的——因此在验收任何摄像机运镜效果前,建议先让智能体分别渲染片头、片中和片尾三张静态截图来检查画面构图。

将时间轴导出为 MP4 视频

浏览器实时预览依赖 requestAnimationFrame,一旦机器负载升高就会掉帧;但视频导出绝不能掉帧。因此,导出脚本直接根据帧序号计算时间点,并在每一帧完成绘制后再调用 Playwright 截图:

import { chromium } from 'playwright';
import { spawn } from 'node:child_process';
import { pathToFileURL } from 'node:url';

const out = process.argv[2] || 'out.mp4';
const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
await page.goto(pathToFileURL('studio.html').href + '?capture');

const { duration, fps } = await page.evaluate(() => window.__scene);
const ffmpeg = spawn('ffmpeg', ['-y', '-f', 'image2pipe', '-framerate', String(fps),
  '-i', '-', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '18', out],
  { stdio: ['pipe', 'ignore', 'inherit'] });

const frames = Math.round(duration * fps);
for (let i = 0; i < frames; i++) {
  await page.evaluate(t => window.__seek(t), i / fps);
  ffmpeg.stdin.write(await page.screenshot({ type: 'png' }));
}
ffmpeg.stdin.end();
await new Promise(r => ffmpeg.on('close', r));
await browser.close();

window.__seek(t) 会在等待两个动画帧(animation frames)后才 resolve,确保每次截图都已应用最新的 CSS 变换。image2pipe(详见 ffmpeg 格式文档)直接从标准输入(stdin)读取 PNG 数据流,而 yuv420p 像素格式则保证了生成的 MP4 可在各类浏览器中直接播放。

实测数据:180 帧、1280x720 分辨率、30 fps、总长 6.0 秒的视频,生成文件大小约 420 KB,总耗时仅 20 秒。如果本地 Playwright 尚未安装浏览器内核,首次运行前需执行一次 npx playwright install chromium。

导出 MP4 视频在 0.3s、2.5s 与 5.9s 处的三帧画面对比:摄像机向标题卡片缓慢推进,城市天际线与前景深色山丘以不同速度移动,随后摄像机环绕旋转使卡片产生透视倾斜

可以看到,远处城市塔楼的位移幅度明显小于前景的深色山丘(后者在推进过程中已完全移出画幅),这就是标准的视差效果。

接入 Opus 5.5 API 实现“一句话生成镜头脚本”

接下来,我们可以让创作者直接输入一段自然语言镜头描述,由模型自动返回关键帧配置。工作室可直接调用 Anthropic 的 Messages API:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "output_config": { "effort": "low" },
    "system": "Return only JSON: {\"camera\": [{\"t\",\"x\",\"y\",\"z\",\"yaw\",\"ease\"}], \"tracks\": {}}. Times in seconds, 0 to 6.",
    "messages": [{ "role": "user", "content": "Slow push-in, slight orbit right, title fades up in the first second." }]
  }'

这里有两个来自思考力度文档的关键细节需要注意:第一,在 Messages API 请求中,思考力度参数位于 output_config.effort;第二,Opus 5.5 始终启用自适应思考(如果传入 thinking: {"type": "disabled"} 会直接返回 400 错误),因此思考 token 也会计入 max_tokens 配额。如果将 max_tokens 设得太小,返回的 JSON 就会在数组半途被截断,并返回 stop_reason: "max_tokens"。由于生成镜头关键帧列表属于指令清晰的小型任务,建议先从 low 力度开始测试,在对比实际生成效果后再做定夺。

使用 Apifox CLI 让 Claude Code 自动化测试 API 调用

如果接口返回的 JSON 被截断或夹杂了多余的寒暄文本,渲染时的 sample() 函数就会直接报错崩溃,因此我们需要为该调用加上契约测试。同一个 Claude Code 会话可以直接借助 Apifox CLI 编写并执行这套测试。

首次使用时先完成安装与登录:

npm install -g apifox-cli@latest
apifox auth login --with-token <YOUR_TOKEN>
apifox skill install

随后向智能体发送一条提示词:

In Apifox project <projectId>, create an endpoint for POST /v1/messages and a
test case that sends the "describe a shot" request above with model
claude-opus-5-5. Assert: status 200, body.model is "claude-opus-5-5",
stop_reason is not "max_tokens", and content[0].text parses as JSON with a
non-empty camera array whose t values rise from 0 to 6. Use an environment
with base URL https://api.anthropic.com and the key in a variable. Run it and
summarize failures.

智能体会先读取载荷 schema(而不是凭空猜测字段格式),校验本地生成的 JSON 文件,随后自动创建并运行接口与测试用例:

apifox cli-schema get endpoint-create
apifox cli-schema get test-case-create
apifox cli-schema validate test-case-create --file case.json
apifox environment create anthropic --project <projectId> --base-url https://api.anthropic.com
apifox endpoint create --project <projectId> --file endpoint.json
apifox test-case create --project <projectId> --file case.json
apifox run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

在运行测试时通过 --env-var "api_key=$ANTHROPIC_API_KEY" 动态传入密钥,这样密钥就永远不会明文保存在项目配置中。每当你修改系统提示词(system prompt)或调整 effort 思考力度时,都可以重新运行一次该用例,验证返回格式是否依然稳定。同一条 apifox run 命令加上 -r junit 参数即可直接接入 CI 流水线,详见 Apifox CLI CI/CD 指南与在 Claude Code 中使用 Apifox CLI。

工作室的后续扩展方向

  • 增加更多图层,复用同一套数学公式。 无论是添加雨滴特效、副标题还是品牌 Logo,只需为新图层分配一个 z 轴深度,透视补偿公式会自动处理其余一切。
  • 替换底层渲染方案。 如果你更倾向于用 React 组件来编写动画场景,可以参考结合 Remotion 使用 Claude Code 的方案。而本文介绍的单文件方案则完全无需构建步骤。关于会话管理与权限控制的更多细节,请参阅 Claude Code 官方概览文档。

常见问题

动态图形(Motion Graphics)中的 2.5D 是什么意思? 它是指将平面的 2D 美术图层放置在 3D 空间的不同深度上,再通过移动虚拟摄像机进行拍摄。这样无需 3D 建模、灯光渲染或重量级 3D 引擎,就能获得自然的视差与纵深感。

为什么首次构建要用 Opus 5.5 而不是更小的模型? 首次构建需要一次性跑通透视投影数学公式、关键帧插值引擎和无头浏览器录制管道。Anthropic 将 Opus 5.5 定位为面向长周期智能体编程的模型,在我们的实测中,仅靠一条提示词加一轮微调就得到了可运行的完整工作室。对于后续的小幅修改,调低思考力度即可。

为什么不直接录屏,而要逐帧截图导出? 屏幕录制依赖实时播放速度,一旦某一帧渲染较慢就会变成掉帧或重复帧。通过主动跳转到 i / fps 时间点并逐帧截图,可以保证在任何性能的机器上导出的视频都分毫不差。

不配置 API Key 可以使用“一句话生成镜头脚本”功能吗? 不可以。该功能直接调用 Anthropic 的 Messages API,必须传入你自己的 Anthropic API Key。不过工作室的其余全部功能以及 MP4 视频导出均在本地运行,无需任何密钥。

生成镜头列表的接口调用应该使用哪个思考力度(effort)? 建议从 low 开始,因为该任务篇幅短且输出 JSON 结构固定。只有当 Apifox 测试用例发现返回的关键帧格式异常或偏离指令时,才需要上调思考力度。