PixVerse R2 实战：单图到可交互实时视频流

实时世界模型这条线，2024 年下半年起被反复提起，核心卖点就一句话：给一张图，你能"走进去"，而且画面是当场生成的。PixVerse R2 属于这一类工具。它不是"输入提示词、等 30 秒出一段 5 秒视频"的批量生成器，而是维持一条长连接，你按方向键，画面跟着变，像在玩一个用扩散模型渲染的第一人称游戏。

这篇教程把整条链路拆开：输入怎么准备、交互信号怎么发、流怎么接回来、怎么导出。看完你能跑通一个最小可用的"单图 → 可交互视频流"闭环。

---

这篇能做出什么

做完之后你手上会有：

1. 一个单图驱动的世界：上传一张场景图（街道、房间、山谷都行），模型把它"展开"成可漫游的空间。

2. 一个实时控制回路：键盘 WASD 或手柄摇杆 → 控制信号 → 画面里的视角/位置变化，端到端延迟落在几百毫秒量级。

3. 一条可播放、可录制的视频流：浏览器里直接看，或者用 OBS / ffmpeg 录下来做素材。

4. 一套可复用的脚手架代码：换图片、换提示词就能开新场景。

它做不到的：长距离精确导航（世界模型会有漂移）、多人同场景协作、把任意照片变成物理正确的 3D 场景。这些按当前技术阶段都还不稳，期望值先放这儿。

---

前置条件清单

硬件与环境

• 一张显存足够的显卡（本地跑的话），或者直接用云端推理。云端更省事，也更容易控制延迟。
• 稳定的网络，上行带宽建议 5 Mbps 以上，实时流对上行抖动比下行更敏感。
• 一个现代浏览器（Chrome / Edge 较新版本），WebRTC 支持完整。

账号与凭证

• PixVerse 账号，以及对应的 API Key / 访问令牌。具体申请入口、配额、计费方式以官方页面为准，这部分变化快，别照抄任何第三方截图。
• 记下服务端点（endpoint）。下面代码里统一写成占位符 <YOUR_ENDPOINT>。

软件

• Python 3.10+（示例用 websockets、aiohttp）
• Node.js 18+（如果要用官方 JS SDK 或自建前端）
• ffmpeg（录制与转码）
• 可选：OBS（录屏最省心）、一个手柄（体验比键盘好很多）

一张好图

这是最容易被忽略、又最影响成败的一步。选图原则：

• 有明确纵深：走廊、街道、林间小路，模型容易推断"往前的空间"。
• 地平线稳定：手机随手拍的歪斜照片，展开后会歪。
• 光照均匀：大逆光、强噪点会让画面很快崩。
• 分辨率适中：1024～2048 长边通常够用，太大只是徒增上传时间。
• 避免大量文字和 UI：这些区域一变形就很出戏。

---

分步骤

第 1 步：先跑一次"单次生成"确认链路

别一上来就写实时循环。先用最短路径确认：图能传上去、凭证是对的、能拿回结果。

```bash

用 curl 验证鉴权与端点是否可达（字段名请以官方文档为准）

export PIXVERSE_API_KEY="<YOUR_API_KEY>"

export PIXVERSE_ENDPOINT="<YOUR_ENDPOINT>"

curl -sS -X POST "$PIXVERSE_ENDPOINT" \

-H "Authorization: Bearer $PIXVERSE_API_KEY" \

-H "Content-Type: application/json" \

-d '{

"prompt": "雨后的赛博朋克街道，霓虹灯在地面积水里反光",

"image": "<base64 或图片 URL>",

"duration": 4

}' | head -c 500

```

拿到 200 和一段任务 ID，说明凭证与网络没问题。这一步返回的 JSON 结构，就是你后面要照着填的字段模板——不同版本的参数命名会调整，直接以你账号对应的文档为准。

第 2 步：理解三个环节，别混在一起调

实时世界模型的链路可以拆成三段，排错时一定要分段定位：

新手常见错误是把三段混在一个脚本里调，一出问题就不知道是图的问题还是网络的问题。先让输入稳定，再让控制稳定，最后才调画质。

第 3 步：建立长连接会话

实时模式基本都走 WebSocket 或 WebRTC 信令通道。下面是 Python 骨架，重点是结构，字段名照官方文档替换。

```python

realtime_client.py

import os, json, base64, asyncio, time

import websockets

WS_ENDPOINT = os.environ["PIXVERSE_WS_ENDPOINT"] # 形如 wss://<host>/<path>

API_KEY = os.environ["PIXVERSE_API_KEY"]

def img_b64(path: str) -> str:

with open(path, "rb") as f:

return base64.b64encode(f.read()).decode()

async def open_session(ws, image_path: str):

init = {

"type": "session.create",

"auth": {"api_key": API_KEY},

"seed_image": {"format": "base64", "data": img_b64(image_path)},

"world": {

"prompt": "雨后的赛博朋克街道，霓虹反光，轻微雾气",

"style": "cinematic",

},

"stream": {

"protocol": "webrtc", # 也可为 hls / flv，看端支持

"resolution": "1280x720",

"fps": 24,

},

}

await ws.send(json.dumps(init))

等 session.ready 或错误消息

while True:

msg = json.loads(await ws.recv())

print("[server]", msg.get("type"))

if msg.get("type") in ("session.ready", "error"):

return msg

async def main():

async with websockets.connect(WS_ENDPOINT, max_size=None) as ws:

ready = await open_session(ws, "scene.jpg")

if ready.get("type") == "error":

print("建立会话失败：", ready)

return

ready 里通常带 sdp / offer / stream_url，交给前端去连

print(json.dumps(ready, ensure_ascii=False)[:300])

asyncio.run(main())

```

会话建立后，服务端一般会给你一个 SDP offer 或一个播放地址，二选一，取决于协议。

第 4 步：把键盘变成控制信号

控制信号的语义无非三组：移动（前后左右）、视角（俯仰偏航）、动作（跳跃/交互/重置）。用一个约 20 Hz 的循环上报就够，不必每帧都发。

```python

control.py

import asyncio, json, time

KEYS = {"w": (0, -1), "s": (0, 1), "a": (-1, 0), "d": (1, 0)}

async def control_loop(ws, get_input):

"""get_input() 返回 {"move":[x,y], "look":[dx,dy], "action":"none"}"""

period = 0.05 # 20 Hz

while True:

payload = get_input()

await ws.send(json.dumps({

"type": "control",

"ts": int(time.time() * 1000), # 带上时间戳，方便对齐

"payload": payload,

}))

await asyncio.sleep(period)

```

前端侧（浏览器里读键盘）大概长这样：

```javascript

// input.js —— 把按键累积成一个方向向量，按固定频率发送

const pressed = new Set();

addEventListener("keydown", e => pressed.add(e.code));

addEventListener("keyup", e => pressed.delete(e.code));

function snapshot() {

const move = [0, 0];

if (pressed.has("KeyW")) move[1] -= 1;

if (pressed.has("KeyS")) move[1] += 1;

if (pressed.has("KeyA")) move[0] -= 1;

if (pressed.has("KeyD")) move[0] += 1;

return { move, look: [0, 0], action: "none" };

}

setInterval(() => {

if (socket.readyState === WebSocket.OPEN) {

socket.send(JSON.stringify({ type: "control", payload: snapshot() }));

}

}, 50);

```

关键原则：控制信号是"状态快照"，不是"事件队列"。 每次发的是"此刻我按着什么"，而不是"我刚刚按了什么"。服务端一旦丢包，状态快照能自愈，事件队列会永久错位。

第 5 步：把视频流接回浏览器

如果用 WebRTC，前端就这么几行：

```html

<video id="stage" autoplay playsinline muted></video>

<script>

const video = document.getElementById("stage");

const pc = new RTCPeerConnection({

iceServers: [] // 局域网可留空；跨网段需要自建 STUN/TURN

});

pc.ontrack = (ev) => { video.srcObject = ev.streams[0]; };

// offer 由服务端给出，这里做 answer

async function attach(offer) {

await pc.setRemoteDescription(offer);

const answer = await pc.createAnswer();

await pc.setLocalDescription(answer);

return pc.localDescription; // 回传给服务端

}

</script>

```

如果服务端返回的是播放地址（HLS / HTTP-FLV），直接用播放器组件挂上去更简单，代价是延迟通常更高。

第 6 步：导出与录制

三种场景，三种做法：

A. 录一次 demo 给同事看 —— OBS 添加"浏览器源"，指向你的页面，直接录。

B. 拉流存文件 —— 有标准流地址时：

```bash

拉流转存，-c copy 表示不重新编码，速度快、画质无损

ffmpeg -i "<STREAM_URL>" -c copy -y session.mp4

需要切成小段方便回看

ffmpeg -i "<STREAM_URL>" -c copy -f segment -segment_time 30 -reset_timestamps 1 part_%03d.mp4

```

C. 逐帧导出做训练/分析 —— 先存成 mp4，再拆帧：

```bash

mkdir -p frames

ffmpeg -i session.mp4 -vf fps=24 frames/%06d.png

```

导出前的检查项：分辨率是否被流本身限制、帧率是否稳定、有没有掉帧导致的时间戳错位。实时流录下来的东西，时长和真实秒数不一定严格一致，做研究用途时要打日志校验。

第 7 步：压延迟与调画质

延迟预算大致是这样分布的，用这张表定位瓶颈：

调优顺序建议：

1. 先降分辨率：1280×720 → 960×540，收益立竿见影。

2. 再降帧率：24 → 20 → 16，观感损失比想象中小。

3. 考虑帧间一致性技巧：很多实时世界模型走"关键帧 + 中间插值"路线，关键帧贵、插值便宜，把关键帧频率调低能省不少算力。

4. 最后才动提示词：提示词复杂度对延迟的影响通常小于分辨率。

---

常见坑与排错

黑屏，但连接是通的

八成是 ontrack 没触发或 ICE 没打通。先看浏览器 chrome://webrtc-internals，确认有没有 candidate 配对成功。跨公网时，iceServers: [] 基本不通，需要自建 STUN/TURN。

延迟越跑越大

控制信号发得太快，服务端在排队。把上行频率固定在一个值（比如 20 Hz），并且不要因为"感觉卡"就加倍发送——那只会让队列更长。

画面跑着跑着就"漂"了

这是世界模型的固有现象：长时间AI 词典：自回归生成">自回归生成会累积误差，画面逐渐偏离原始场景。缓解办法是定期重新锚定：每隔一段时间把原始种子图或某个关键帧重新注入一次，让模型回到轨道上。

按方向键没反应

先确认信号真的发出去了（在 ws.send 前打日志）。如果发出去了但画面不动，检查控制字段是不是服务端期望的命名——很多问题就是字段名不一致。

鉴权 401 / 403

Key 过期、Header 格式不对、或者该 Key 没有实时接口权限。这三件事优先级依次排查。

同一张图每次效果差很多

扩散类模型本身带随机性。想稳定复现，就固定随机种子（seed），并把提示词写得具体一点。

上行带宽被吃满

如果你每次控制都带图片或大 payload，那就是设计错了。种子图只在会话建立时传一次，控制信号应该是几十字节的 JSON。

---

下一步建议

跑通最小闭环之后，可以往这几个方向延伸：

1. 换场景做压力测试：室内、室外、水下、太空各试一张，记录哪类图最容易崩。你会发现"结构清晰 + 纵深明确"的图稳定性明显更好。

2. 接手柄代替键盘：摇杆给的是连续量，比 WASD 的离散量自然得多，视角转动会顺滑一个档。

3. 做场景切换（re-anchor）：把"走进去"和"换地图"做成两个动作，中途注入新种子图。这是做交互式叙事的基础。

4. 接入自动化：把控制信号换成脚本化的轨迹（比如一条预设路径），就能批量生成可复现的漫游素材。

5. 做延迟埋点：在控制信号里带上发送时间戳，在渲染端记录接收时间，把端到端延迟画成曲线。优化没有度量就是瞎猜。

最后提醒一句：这个领域的接口、参数名和配额变动都比较频繁，代码里所有跟服务端字段相关的部分，都以官方文档当前版本为准。把上面这套骨架当成"管道"，字段替换掉就能跑。