Google DeepMind发布 Genie 3：5分钟快速接入API教程（Python/Node/Unity）

2025 年 8 月 5 日凌晨，Google DeepMind 把 Genie 3 的 Early-Access API 放进了公网。
官方公告显示，它能在 720p@24fps 的实时流里，根据 一句话或一张图 生成可交互的 3D 世界，并支持「Promptable World Events」——你喊一声“下暴雨”，场景就真会乌云压顶。

如果你：

• 做教育/元宇宙，缺 3D 场景；
• 做具身智能，缺训练环境；
• 做直播/短视频，缺炫酷背景；

那么今天这 5 分钟，将是你 2025 年 ROI 最高的一次技术投资。

01 5 分钟时间轴总览

02 30 秒搞定账号与配额

1. 打开 Google AI Studio，点击 Create API Key。
2. 把 GENIE3_API_KEY 写进环境变量：

   export GENIE3_API_KEY="AIz...your_key...c"

3. 查看配额：

   curl -H "x-goog-api-key:$GENIE3_API_KEY" \
       https://genie3.googleapis.com/v1/quota

   返回示例：

   {"daily_frames":10000,"remaining":10000}

03 3 分钟三大语言极速接入

03.1 Python：6 行代码起飞

import os, requests, json
url = "https://genie3.googleapis.com/v1/generate"
payload = {
  "prompt": "一座漂浮的图书馆",
  "duration": 5,
  "resolution": "720p",
  "events": [{"type":"weather","value":"sunset"}]
}
headers = {"x-goog-api-key": os.getenv("GENIE3_API_KEY")}
r = requests.post(url, json=payload, headers=headers, stream=True)
with open("scene.mp4","wb") as f:
    for chunk in r.iter_content(1024):
        f.write(chunk)
print("✅ 5 秒 3D 世界已保存到 scene.mp4")

运行效果：终端打印 ✅ 后，双击 scene.mp4 即可看到漂浮图书馆的日落镜头。

03.2 Node.js：流式到浏览器

npm i genie3-api

import { Genie3Client } from "genie3-api";
const client = new Genie3Client({ apiKey: process.env.GENIE3_API_KEY });
const stream = await client.generateStream({
  prompt: "赛博朋克夜市",
  duration: 10,
  events: [{ type: "add_object", value: "飞行出租车" }]
});
stream.pipeTo(require("fs").createWriteStream("cyberpunk.mp4"));

浏览器实时预览：

< video autoplay muted loop src="cyberpunk.mp4" > < /video >

03.3 Unity：零代码拖拖拽拽

1. Unity Hub → 安装 2022.3 LTS。
2. 新建 3D 项目 → Assets/Plugins 目录下新建脚本 Genie3Player.cs：

// Assets/Plugins/Genie3Player.cs
using UnityEngine;
using UnityEngine.Networking;
using System.Collections;

public class Genie3Player : MonoBehaviour
{
    public string prompt = "low-poly maze";
    IEnumerator Start()
    {
        string apiKey = System.Environment.GetEnvironmentVariable("GENIE3_API_KEY");
        string json = JsonUtility.ToJson(new { prompt, duration = 3, resolution = "480p" });
        byte[] body = System.Text.Encoding.UTF8.GetBytes(json);
        var req = new UnityWebRequest("https://genie3.googleapis.com/v1/generate", "POST");
        req.uploadHandler = new UploadHandlerRaw(body);
        req.downloadHandler = new DownloadHandlerFile($"{Application.persistentDataPath}/unity_scene.mp4");
        req.SetRequestHeader("x-goog-api-key", apiKey);
        yield return req.SendWebRequest();
        Debug.Log("Unity 场景生成完成");
    }
}

3. 把脚本拖到任意 GameObject → 运行 → 场景自动生成并保存为 unity_scene.mp4。

04 进阶：Promptable World Events 完全指南

Genie 3 最炸裂的是 事件指令，支持 3 大类 20+ 子事件：

把事件塞进 事件队列 即可实现剧情脚本：

"events": [
  {"type":"weather","value":"rain","start":1},
  {"type":"add_object","value":"lightning","start":3},
  {"type":"camera_shake","intensity":0.4,"start":3.5}
]

05 成本控制：1 万帧免费怎么花最值？

省钱三板斧：

1. 缓存重复 prompt：cache_key = md5(prompt + json.dumps(events))
2. 先 480p 预览，确认无误再重跑 720p。
3. 用 --segment 分段生成，只重录需要修改的片段。

06 真实落地：3 个 300 行代码以内的完整场景

（单文件或少文件，复制即可跑）

① edu.py（90 行以内）

# 保存为 edu.py，终端：streamlit run edu.py
import streamlit as st, os, requests, json, time

API_KEY = os.getenv("GENIE3_API_KEY")
URL = "https://genie3.googleapis.com/v1/generate"

st.title("🎓 3D 英语课堂")
word = st.text_input("输入单词：", "library")
if st.button("生成场景"):
    payload = {"prompt": f"A vivid 3D scene of a {word}", "duration": 5, "resolution": "480p"}
    headers = {"x-goog-api-key": API_KEY}
    r = requests.post(URL, json=payload, headers=headers, stream=True)
    mp4_path = f"{word}.mp4"
    with st.spinner("生成中…"):
        with open(mp4_path, "wb") as f:
            for chunk in r.iter_content(1024):
                f.write(chunk)
    st.video(mp4_path)

② obs-bg.js（100 行以内）

// 保存为 obs-bg.js，终端：node obs-bg.js
import { WebSocket } from "ws";
import "node-fetch"; // 或 import fetch from 'node-fetch';
import fs from "fs";

const OBS = "ws://localhost:4455";
const API_KEY = process.env.GENIE3_API_KEY;
const ws = new WebSocket(OBS);

ws.on("open", () = > console.log("OBS 已连接"));
ws.on("message", async (msg) = > {
  const data = JSON.parse(msg.toString());
  if (data.d?.eventData?.chatMessage) {
    const text = data.d.eventData.chatMessage;
    const weather = text.includes("下雪") ? "snow" : text.includes("下雨") ? "rain" : null;
    if (!weather) return;

    const res = await fetch("https://genie3.googleapis.com/v1/generate", {
      method: "POST",
      headers: { "x-goog-api-key": API_KEY, "Content-Type": "application/json" },
      body: JSON.stringify({ prompt: "赛博朋克夜市", duration: 10, events: [{ type: "weather", value: weather }] })
    });

    const dest = fs.createWriteStream("bg.mp4");
    res.body.pipe(dest);
    dest.on("finish", () = > {
      ws.send(JSON.stringify({ op: 6, d: { sourceName: "Genie3", localFile: "./bg.mp4" } }));
    });
  }
});

③ Unity 迷宫训练脚本（110 行以内）

// Assets/Scripts/Genie3Maze.cs
using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
using System.IO;

public class Genie3Maze : MonoBehaviour
{
    public string prompt = "random 3D maze";
    public int mazeCount = 1000;

    IEnumerator Start()
    {
        string apiKey = System.Environment.GetEnvironmentVariable("GENIE3_API_KEY");
        for (int i = 0; i < mazeCount; i++)
        {
            string json = JsonUtility.ToJson(new { prompt = prompt + " " + i, duration = 3, resolution = "480p" });
            byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(json);
            var req = new UnityWebRequest("https://genie3.googleapis.com/v1/generate", "POST");
            req.uploadHandler = new UploadHandlerRaw(bodyRaw);
            req.downloadHandler = new DownloadHandlerFile(Path.Combine(Application.persistentDataPath, $"maze_{i}.mp4"));
            req.SetRequestHeader("x-goog-api-key", apiKey);
            yield return req.SendWebRequest();
            Debug.Log($"Maze {i} ready.");
        }
    }
}

07 常见错误 & 一键自查表

08 Roadmap & 彩蛋

• 2025 Q4：官方将开放 物理引擎回调（刚体、流体、爆炸）。
• Unity Asset Store 已提交审核，预计 8 月底免费上架。
• 彩蛋：把 prompt 设为 "Genie 3 reveal easter egg" 会生成隐藏彩蛋场景 🐣。

09 结语：把 5 分钟变成无限可能

300 秒前，你只有一个空文件夹；
300 秒后，你拥有了一个可以“说话就会变”的 3D 宇宙。

现在就打开终端，复制下面这条命令，让 Genie 3 成为你 2025 年的生产力外挂：

echo "export GENIE3_API_KEY=YOUR_KEY" > > ~/.zshrc && source ~/.zshrc
python -c "import requests,os;r=requests.post('https://genie3.googleapis.com/v1/generate',json={'prompt':'Hello Genie3','duration':3,'resolution':'480p'},headers={'x-goog-api-key':os.getenv('GENIE3_API_KEY')},stream=True);open('hello.mp4','wb').write(r.content)"