notebooklm

用途

notebooklm-py 通过 notebooklm 命令行接口或带类型的异步 Python API，对 Gemini Notebook（NotebookLM）进行安装、认证、故障排查与日常操作。适用于笔记本与来源管理、基于来源的问答与研究，以及生成物的创建和下载。当用户提到 Gemini Notebook、notebooklm-py、notebooklm CLI 或其 Python API 时使用；不适用于通用 Gemini API 或无关的内容创作。

主要能力

笔记本管理：列出、创建笔记本（notebooklm list --json、notebooklm create "Title" --json）。
来源管理：添加来源并等待就绪（notebooklm source add、notebooklm source wait），支持 URL 回退抓取（--fallback-fetch）。
问答：基于已就绪来源进行提问（notebooklm ask）。
研究：快速（fast）与深度（deep）研究模式（notebooklm source add-research）。
生成物：audio、video、slide-deck、infographic、report、mind-map、data-table、quiz、flashcards。
下载：将生成物下载到指定路径。
用量查询：notebooklm usage --json 及按类别查询。
技能安装：notebooklm skill install、notebooklm skill package、notebooklm skill status --json。

使用方式

安装需要 Python 3.10+：

pip install "notebooklm-py[browser]"
pip install "notebooklm-py[cookies]"  # 可选浏览器 cookie 提取
pip install "notebooklm-py[headless]"  # 无人值守/无头环境

若系统 pip 报 externally-managed-environment，不要使用 --break-system-packages。仅用 CLI 时可考虑 uv tool install "notebooklm-py[browser]" 或等效的 pipx 命令。

认证：无人值守或无头场景推荐使用持久化的 profile 与 master token 认证。在可信工作站运行 notebooklm login --master-token --account <email>，随后部署 master_token.json（而非 storage_state.json）。NOTEBOOKLM_HOME 选择私有基础目录，NOTEBOOKLM_PROFILE 选择 profile。CI 中 NOTEBOOKLM_MASTER_TOKEN_JSON 是密钥传输约定（包不直接读取），需将其值写入所选 profile 的 master_token.json（权限 0600），取消该变量后运行 notebooklm auth refresh 生成 storage_state.json。

工作流前验证真实认证：

notebooklm auth check --test --json

需满足 .status == "ok" 且 .checks.token_fetch == true。认证文件应按 bearer 凭据处理，绝不打印、记录或提交。notebooklm status 报告的是所选笔记本上下文，而非认证状态。

命令发现以已安装 CLI 的帮助为准：

notebooklm --help
notebooklm source --help
notebooklm research --help
notebooklm generate --help
notebooklm artifact --help
notebooklm download --help

典型来源到生成物工作流（保留 JSON 输出中的 notebook_id、source_id、artifact_id）：

notebooklm create "Research: topic" --json
notebooklm source add <input> -n {notebook_id} --json
notebooklm source wait {source_id} -n {notebook_id} --timeout 600
notebooklm generate audio "instructions" -n {notebook_id} -s {source_id} --json
notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 1200
notebooklm download audio ./podcast.m4a -a {artifact_id} -n {notebook_id}

仅分析不生成时，在来源就绪后使用 ID 固定的问答命令：notebooklm ask "Summarize the key arguments" -n {notebook_id} --json。

Python API 基线（需使用已安装的类型化 API 及其 docstring，不要猜测方法名）：

import asyncio

from notebooklm import NotebookLMClient


async def main(url: str) -> None:
    async with NotebookLMClient.from_storage() as client:
        notebook = await client.notebooks.create("Research: topic")
        source = await client.sources.add_url(notebook.id, url)
        await client.sources.wait_until_ready(notebook.id, source.id, timeout=600)

        answer = await client.chat.ask(
            notebook.id, "Summarize the key arguments", source_ids=[source.id]
        )
        print(answer.answer)

        task = await client.artifacts.generate_audio(
            notebook.id,
            source_ids=[source.id],
            instructions="Focus on the key arguments",
        )
        final = await client.artifacts.wait_for_completion(notebook.id, task.task_id, timeout=1200)
        if not final.is_complete:
            raise RuntimeError(f"Generation ended with {final.status}: {final.error}")
        await client.artifacts.download_audio(
            notebook.id, "./podcast.m4a", artifact_id=task.task_id
        )


asyncio.run(main("https://example.com"))

NotebookLMClient.from_storage() 是异步上下文管理器，不需 await。客户端在单个事件循环内可重入，但非线程安全，每个循环创建一个客户端。公开命名空间包括 notebooks、sources、chat、research、artifacts、mind_maps、notes、settings、sharing、labels、collections。

适用场景

智能体工作流中的 NotebookLM 自动化操作。
无头/无人值守环境中的持久化认证与批量任务。
CI 环境中通过 master token 部署并生成会话状态。
并发运行多条工作流时使用独立 profile 隔离上下文。
需要基于来源的问答、研究与生成物产出（如播客音频、报告、思维导图等）。

限制与约束

需 Python 3.10+。
生成受 Google 速率限制；深度研究可能耗时 15-30+ 分钟。
需显式授权才可执行删除、分享移除、注销、清空、研究取消、ask --new、language set、生成、长前台等待、下载、research wait --import-all、ask --save-as-note、history --save 等操作。
仅可在来源状态为 ready、生成物状态为 completed 时继续或下载。
思维导图 --kind interactive（默认）不运行 artifact wait；--kind note-backed 为服务端同步。
generate video --format cinematic 忽略 --style，需要 Google AI Ultra，约 30-40 分钟。
幻灯片无方向标志，需在描述中指定（如 9:16 portrait）；幻灯片修订不能改变版面方向。
自定义报告用 --format custom 并将提示作为位置描述传入，--append 仅适用于内置报告格式。
认证文件绝不能打印、记录或提交；master token 是持久化的全账户凭据，更换密码后仍有效，应使用专用账户并以 0600 权限保护，一旦泄露立即撤销。
不要对并发运行共享同一个可写 storage_state.json。

技能介绍

用途

主要能力

使用方式

适用场景

限制与约束