如果你想做一个能用键盘走动、画面实时生成的互动场景原型,这篇适合你。读完你能在后端创建 Genie 4 会话,在浏览器或 Python 里连上它,发出第一组世界设定和移动指令,并知道怎么计费、怎么结束会话,以及它在哪些情况下会不稳定。
Genie 4 是什么
Genie 4 的模型名是 models/genie-4。它通过 Interactions API 生成一个连续、可交互的 16:9 世界,画面 24 fps,音频为 48 kHz 立体声,并与画面同步[1]。它和 Gemini Omni 1.2 Flash 不同:Omni 用于离线生成视频片段,Genie 4 则是根据你实时按下的键盘按键(WASD 和方向键),以及会话中途发送的自然语言事件,逐帧即时渲染[1]。
如果你要做的是可以实时操控的场景、游戏原型或空间探索,Genie 4 是对口的工具。离线生成视频片段则是 Gemini Omni 1.2 Flash 的用途[1]。
准备工作和费用
Genie 4 只对付费层级的 Gemini API 密钥开放,免费密钥无法使用[1]。计费按视频输出 token 算:每帧 240 个 token,24 fps 下每秒 5,760 个 token,带上立体声音频后约合每秒 0.10 美元[1]。会话只要还开着就在计费,所以每次测试结束都要显式结束会话。
地域也会影响体验。Genie 4 的服务器位于美国、西欧和日本。在北美、西欧和中欧、东亚,往返延迟预计低于 150 毫秒,键盘操控才跟手;在其他地区,操控延迟会变大,帧率也可能下降。如果你的后端在别的地区,可以把中继放到这些地区附近[1]。具体的价格、速率限制和规格,以定价页和模型页为准[1]。
四步流程
每个 Genie 4 会话都遵循同一个四步流程,全部在 v1beta 上进行[1]:
- 在服务端创建 interaction。
- 建立实时连接。浏览器应用用 WebRTC,Python、Node.js 或其他浏览器场景用 WebSocket。
- 发送一条
world_setup事件设定场景,之后用user_action或input事件操控。 - 会话结束时调用
complete()。
浏览器端不能拿到长期有效的 GEMINI_API_KEY。正确做法是在后端创建 interaction,再为它生成一次性的会话令牌(interactions.authTokens.create),只把令牌和 interaction ID 交给浏览器[1]。下面的 Python 例子展示了后端和客户端各自做什么:
from google import genai
# Backend: create interaction and mint single-session token
server_client = genai.Client(http_options={"api_version": "v1beta"})
interaction = await server_client.aio.interactions.create(
model="models/genie-4", api_version="v1beta"
)
token_resp = await server_client.aio.interactions.auth_tokens.create(
interaction_id=interaction.id, api_version="v1beta"
)
# Client worker: authenticate solely with the ephemeral session token
scoped_client = genai.Client(
api_key=token_resp.auth_token,
http_options={"api_version": "v1beta"},
)
async with scoped_client.aio.interactions.connect(
interaction.id, api_version="v1beta"
) as session:
...第一次运行会怎样
初始化世界大约要 5 到 9 秒,之后才会出现第一帧[1]。会话中途改变场景,比如让村庄下雪,文字指令要 1 到 2 秒才能显示在画面上,因为 Genie 4 会在生成步骤之间规划环境变化[1]。
还要注意它的空间记忆。Genie 4 维护的是一个滚动的视觉地平线,而不是持久的 3D 场景。如果你转身离开一段时间再转回来,背景里的建筑可能已经重新排布[1]。
设定场景:world_setup
每个会话只发送一次 world_setup。它可以只有文字描述,也可以附上一张 16:9 的起始图片,或者两者都有[1]。只用文字的写法如下:
{
"event_type": "world_setup",
"world_prompt": {
"text": "First-person POV standing in front of an espresso machine. An empty ceramic mug rests on the drip tray beneath the spout. A glowing \"brew\" button is visible on the front panel."
}
}移动和转向:user_action
移动和转向用 user_action。action 可以是 key_down、key_up 或 key_click。用户按下按键时发送 key_down,并且不要把系统自动产生的按键重复事件也发出去;松开时发送 key_up。在收到 key_up 之前,按住的键会在每一步里持续生效[1]。
{
"event_type": "user_action",
"action": "key_down",
"input": "key_w"
}可以直接用的移动键是 key_w、key_s、key_a、key_d,视角键是 arrow_up、arrow_down、arrow_left、arrow_right[1]。key_e 和 space 虽然在协议里有定义,Genie 4 却不会给它们内置跳跃或交互的行为。要做开门、召唤天气这类自定义操作,应该在客户端拦截这些按键,改为发送描述性的 input 文字事件[1]。
会话中途用文字改变场景:input
input 事件用来在运行中改变环境、物体状态或角色对话。世界规划每 4 帧(24 fps 下约 0.17 秒)读取一次文字输入,所以一次性的指令最好连续发送约 10 次,每次间隔 150 毫秒,总共约 1.5 秒,这样下一个规划窗口才能稳定收到。两条冲突的指令之间,客户端还应留出约 2 秒的冷却时间[1]。
结束会话:complete、cancel 和 detach
这三个操作的区别直接关系到账单。complete() 会通知服务端结束 interaction,停止生成和计费,并在 receive() 里发出终止事件 interaction.completed。用户结束体验时必须调用它[1]。cancel() 则立即中止服务端的生成[1]。
detach(),以及 Python 里退出 async with 块,只是断开本地连接,服务端的 interaction 并未结束。Genie 4 不支持会话恢复,所以不能指望断开来暂停或停止计费[1]。用户关闭浏览器标签页时,连接也只是分离,生成并不会立即停止[1]。
解析音视频流
用 WebSocket 时,画面数据出现在 step.delta 事件里,类型为 video,每个事件带一帧 base64 编码的 JPEG。声音的类型为 audio,是 base64 编码的 16 位小端立体声 PCM,采样率 48,000 Hz[1]。解码时要按采样率和声道正确还原,否则声音会失真。
限制
- 响应速度:键盘移动通常 0.2 到 0.5 秒见效,文字指令要 1 到 2 秒[1]。
- 画面规格:输出固定为 1280x720、24 fps 的 16:9 画面。竖屏 9:16 和自定义帧率都不支持[1]。
- 输入范围:不接收麦克风或摄像头的实时输入,也不支持函数调用、Google 搜索 grounding、结构化输出和会话恢复[1]。
- 空间记忆:看向一个物体超过 8 秒或转身 360 度,地标、门或按钮可能移动或重置。画面稳定性在 60 到 90 秒后可能下降,硬上限为 120 秒[1]。
- 内容审核:提示或起始图片里如果有可识别的真人、公众人物或受版权保护的品牌形象,启动时可能被拦截,运行中也可能中断流[1]。
- 细节:标牌、仪表和时钟上的文字会随时间变形,镜头平移时物体数量的统计也会漂移[1]。
下一步
做出稳定的互动场景前,可以先用小场景验证操控延迟和场景连贯性,再决定要不要扩展。模型规格、定价和并发限制都以官方页面为准,上文的数字均来自官方页面[1]。
来源
- 1Interactive world generation with Genie 4Gemini API docs
引用本页: 用 Gemini API 调用 Genie 4 生成可交互世界. TellWorld, https://www.tellworld.net/zh/practice/practice-genie-4-api. 更新于 2026-11-20