Genie 4 接入配置 按官方文档操作:用付费档 API Key,在 Google AI Studio 或 Interactions API(v1beta)调用 genie-4;结束时必须执行 complete() 停止计费。

本站上午已介绍过 Genie 4 上线与官方规格。本文只整理官方接入步骤,不涉及第三方中转。付费档 Key 的创建也可对照 Gemini 4 Neon 接入配置教程。步骤和参数据官方文档整理,核实时间 2026-11-20(Asia/Shanghai),本文未在本地逐项实测。
接入前先确认
- 型号写成
models/genie-4或genie-4,走 Interactions API 的v1beta。 - 仅开放付费档,不支持 Free、Batch、Flex、Priority,也不支持函数调用、上下文缓存、会话恢复和实时麦克风或摄像头输入。
- 输出固定为 1280×720(16:9、24 fps),并同步 48 kHz 立体声音频(WebSocket 为 16-bit PCM,WebRTC 为 Opus,音频计入视频输出 token)。每一帧 240 个视频输出 token,即每秒 5,760 tokens。
- 会话最长 120 秒,视觉连贯性和物体持久性在前 45–90 秒最强。首帧大约需要 5–9 秒。
- 服务区域是美国、西欧和日本;北美、西欧 / 中欧和东亚往返时延低于 150 ms 更合适,时延更高会拖慢操控,也可能掉帧。
- 若要做离线固定时长视频、多轮剪辑,或最高到 4K 的上采样,官方建议改用 Gemini Omni 1.2 Flash。
- API 地址是
generativelanguage.googleapis.com。中国大陆访问 Google 服务可能受限,请先确认能打开 AI Studio,并遵守服务条款和可用地区规定。
在 Google AI Studio 里试用
写代码前,可先打开 Google AI Studio Live(model=genie-4) 试用,需要付费档 API Key。
- 先点击画面,才能捕获键盘。
W、A、S、D控制前进、后退和左右平移;方向键控制镜头。时延较低时,原生移动的视觉响应大约是 0.2–0.5 秒。- 自定义键(如
E、Q、R)可绑定动作提示词,并有 2 秒冷却,避免多条文本指令重叠。 - 中途可用提示栏发送环境变化;对面前角色说话时,把台词放在引号里。
- 接近 90 秒会有提示;标签页切到后台超过 10 秒,会话会自动暂停或结束,以免空耗 token。

用官方 SDK / API 接入
1. 创建 API Key
打开 Google AI Studio 的 API Keys 页面 新建 Key。官方建议写成环境变量,不要写入代码或版本库:
export GEMINI_API_KEY="你的 API Key"
再安装或升级官方 SDK:pip install -U google-genai 或 npm install @google/genai。下面的示例都使用 v1beta。
2. 在服务端创建会话并签发临时令牌
官方推荐:服务端用付费档 GEMINI_API_KEY 创建 interaction 并签发单次会话 auth_token;浏览器走 WebRTC,不要把长期 Key 放到浏览器。Python 可用 WebSocket。浏览器若走 WebSocket,也必须使用 auth_token,不能传 AIza... 原始 Key,否则官方 SDK 会按设计抛出 usage error。
REST 官方示例如下:
# 1. 创建 Genie 4 interaction
INTERACTION_ID=$(curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"model":"genie-4"}' | jq -r '.id')
# 2. 签发仅限该 INTERACTION_ID 的临时令牌
AUTH_TOKEN=$(curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/interactions/${INTERACTION_ID}/auth_tokens" \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{}' | jq -r '.auth_token')
把 interactionId 和 authToken 返回给浏览器即可。Node.js 对应 interactions.create 与 interactions.authTokens.create,型号和版本同样是 genie-4、v1beta。
3. 浏览器走 WebRTC
官方建议浏览器使用 WebRTC,把视频和 Opus 音频解码到 <video autoplay playsinline>,控制事件走 SCTP 数据通道:
import {GoogleGenAI} from '@google/genai';
async function startWorld(interactionId, authToken, videoElement) {const clientAi = new GoogleGenAI({ apiKey: authToken, apiVersion: 'v1beta'});
const session = await clientAi.interactions.connect(
interactionId,
{transport: 'webrtc', api_version: 'v1beta'},
{timeout_ms: 30000}
);
session.transport.setVideoElement(videoElement);
await session.send({
event_type: 'world_setup',
world_prompt: {text: 'Immersive first-person POV standing on a cobblestone canal bridge inside a vibrant oil painting of a riverside village at twilight. Audio: Gentle water lapping, leaves rustling, footsteps on cobblestone.',},
});
// 原生移动:按下发 key_down,松开发 key_up
// input 使用 key_w / key_a / key_s / key_d 或 arrow_up 等
return {stop: async () => {await session.complete(); } };
}
完整按键映射见 Interactive world generation with Genie 4。world_setup 只发送一次,结束时调用 complete()。
4. Python 走 WebSocket
Python SDK 默认经 WebSocket 异步连接,step.delta 中会给出 base64 的 JPEG 帧和 48 kHz、16-bit 立体声 PCM 音频:
import asyncio
from google import genai
async def main() -> None:
client = genai.Client(http_options={"api_version": "v1beta"})
interaction = await client.aio.interactions.create(model="genie-4", api_version="v1beta")
async with client.aio.interactions.connect(interaction.id, api_version="v1beta") as session:
await session.send({
"event_type": "world_setup",
"world_prompt": {"text": "First-person POV standing on a cobblestone canal bridge."},
})
async for event in session.receive():
if event.event_type == "step.delta":
pass # 按需解码 JPEG 或 PCM,再用 user_action / input 操控
elif event.event_type == "interaction.completed":
break
await session.complete()
asyncio.run(main())
只退出 async with 或调用 detach() 不会立即停止生成,结束时仍要调用 complete() 或 cancel()。

提示词、参考图和实时操控
连接后用 send() 发送事件。这里只列关键规则,完整模式见 Genie 4 prompt and controls guide。
- 开始时发送且只发送一次
world_setup。文本放在world_prompt.text;可选的 16:9 参考图是平级的顶层字段reference_image(含mime_type和data),不要把图嵌进world_prompt。 - 走 WebRTC 时,把参考图缩到 1280×720 或 640×360,并压成 48 KB 以内的 JPEG 再做 base64。SCTP 上限是 64 KB,base64 还会增加约 33% 体积;更大的 PNG 请改走 WebSocket。
- 移动和转镜头用
user_action:按下为key_down,松开为key_up;input使用key_w/key_a/key_s/key_d以及arrow_*。按住会持续生效,直到key_up;客户端应忽略系统的按键重复。 - 自定义的
E、Q、R应发送文本input,不是原生玩法。协议里虽有key_e和space,但它们没有被训练成“交互”或“跳跃”。 - 中途文本可用
event_type: "input",或直接session.send("...")。官方建议同一条指令连续发送 10 次、间隔 150 ms,并设约 2 秒冷却;画面大约 1–2 秒后才会变化。 - 按连续的第一人称或第三人称场景来写,并写明环境声和接触音效;不要写成预告片式的硬切镜头或背景配乐。
- 安全过滤可识别真人、公众人物和受版权品牌 IP,启动或中途都可能拦截。官方建议使用风格化、原创虚构或公有领域素材。

定价、用量与如何结束会话
据 2026 年 11 月 20 日查阅的官方定价页,Genie 4 只在付费档按美元 / 百万 tokens 计费:
| 项目 | Free 档 | 付费档(美元 / 百万 tokens) |
|---|---|---|
| 输入(文本或参考图) | 不支持 | 1.50 |
| 文本输出 | 不支持 | 9.00 |
| 视频输出(含音频) | 不支持 | 17.50 |
| 上下文缓存 | 不支持 | 不支持 |
视频按每帧 240 个输出 token 计费,即每秒 5,760 tokens,大约合每秒 0.10 美元、每分钟约 6.05 美元;音频已计入视频输出。该型号不支持 Free、Batch、Flex、Priority。
用量按并发会话和每日请求(RPD)计算。会话内的 user_action 和中途 input 不另计 RPM 或 RPD:
| 用量档位 | 并发会话 | 每日请求(RPD) |
|---|---|---|
| Free | 不支持 | 不支持 |
| Tier 1 | 2 | 50 |
| Tier 2 | 5 | 250 |
| Tier 3 | 10 | 1,000 |
结束时必须调用 await session.complete(),它会发送 interaction.complete,停止生成和计费,并在 receive() 中给出 interaction.completed。也可用 cancel() 立即中止。关掉标签页、调用 detach() 或退出 async with 都不会立即停计费;该型号也不支持会话恢复。
常见报错与解决
无法创建会话,或提示权限不足
先确认项目已开通付费档,且 Key 属于该项目。官方写明该型号需要付费档 Key,不支持 Free 档。型号用 genie-4 或 models/genie-4,接口为 v1beta。
把长期 Key 放到浏览器
不要在前端嵌入长期 GEMINI_API_KEY。应由服务端签发 auth_token,浏览器只用这枚单次会话令牌。若在浏览器把 AIza... 原始 Key 传给 {transport: 'websocket'},官方 SDK 会按设计抛出 usage error。
未调用 complete(),会话仍在计费
关掉标签页、调用 detach() 或退出 async with,都不会立即停止生成。结束时务必调用 complete() 或 cancel()。
并发或每日请求被限制
并发或当日请求超出当前档位时,新会话可能无法创建。请按上表核对并发上限和 RPD;会话内控制事件不另占这两项额度。
参考图发送失败
走 WebRTC 时,参考图 JPEG 应压到 48 KB 以内,否则容易超过 64 KB 的 SCTP 限制。需要更大的 PNG 时改用 WebSocket。
提示词或参考图被拦截,或会话中途断开
安全过滤可能拦截可识别的真人、公众人物或受版权品牌 IP。改用风格化、原创或公有领域素材后再试。
操控延迟高,或出现掉帧
服务只在美国、西欧和日本。往返时延明显高于 150 ms 时,操控会变慢,也可能掉帧。官方建议把后端中继放在服务区域附近,并先在目标地区测试时延。
会话超过 120 秒,或回头看时场景已变
会话硬上限是 120 秒,连贯性在 60–90 秒后可能下降。离开物体 8 秒以上或转身后再看回来,地标或按钮可能移位。更适合 30–60 秒的前进路线,或镜头锁定的短场景。
常见问题
Genie 4 能在 Free 档使用吗?
不能。官方型号页、定价页和用量限制页都写明该型号不支持 Free 档。
为什么必须调用 complete()?
计费按服务端正在生成的视频输出 token 计算。本地断开不会立刻停下生成,只有 complete() 或 cancel() 才会停止计费。
可以用它生成离线视频或 4K 成片吗?
不适合。它输出的是 720p、24 fps 的实时可操控世界,会话最长 120 秒。离线固定时长视频、多轮剪辑或最高到 4K 的上采样,官方建议改用 Gemini Omni 1.2 Flash。
浏览器能否直接使用 WebSocket?
可以,但必须使用服务端签发的 auth_token,不能传原始 API Key。官方仍更推荐浏览器走 WebRTC。
信息来源
- Google 官方博客:Genie 4 now available through the Gemini API(2026-11-19)
- Gemini API 文档:Interactive world generation with Genie 4
- Gemini API 文档:Genie 4 prompt and controls guide
- Gemini API 型号页:Genie 4
- Gemini API 定价页:Genie 4
- Gemini API 用量限制页:Genie 4
- Google AI Studio Live(model=genie-4)
- Google DeepMind 型号页:Genie 4
- Google DeepMind:Genie 4: A new generation of world simulation(2026-10-27)
核实时间:2026-11-20(Asia/Shanghai)。命令、配置项、价格和限制均据上述官方文档整理,本文未在本地逐项实测。
