notebooklm

Gemini Notebook の自動化

エージェントのワークフローには notebooklm CLI を使用してください。すべての操作を確認可能にし、並行実行時にも安全にするため、--json と明示的な ID を優先してください。ユーザーがアプリケーションコードを求めている場合、または CLI ではワークフローを表現できない場合に限り、型付きの非同期 Python API を使用してください。以下の準備状態、ID、認可、認証情報の取り扱いに関するルールは、どちらのインターフェースにも適用されます。

セットアップと認証

Python 3.10 以降が必要です。ユーザーの既存の環境にパッケージをインストールしてください。依頼がない限り、別の環境は作成しないでください。

pip install "notebooklm-py[browser]"
pip install "notebooklm-py[cookies]"  # optional browser-cookie extraction

システムの pip が externally-managed-environment を報告した場合、--break-system-packages は使用しないでください。CLI のみを使用する場合は、uv tool install "notebooklm-py[browser]" または同等の pipx コマンドを提案してください。アプリケーションコードの場合は、ユーザーが現在使用しているプロジェクト環境を使ってください。

無人環境またはヘッドレス環境で作業する場合は、コピーした Cookie スナップショットよりも、永続的なプロファイルベースのマスタートークン認証を優先してください。pip install "notebooklm-py[headless]" をインストールしてください。一度限りの自動 OAuth キャプチャには [browser] も必要です。信頼できるワークステーションで notebooklm login --master-token --account <email> を実行し、その後 storage_state.json ではなく master_token.json を選択したプロファイルにデプロイしてください。NOTEBOOKLM_HOME でプライベートなベースディレクトリを選択し、NOTEBOOKLM_PROFILE でそのプロファイルを選択します。デフォルトの保存先は ~/.notebooklm/profiles/default/master_token.json です。

CI では、NOTEBOOKLM_MASTER_TOKEN_JSON はシークレットを受け渡すための慣例であり、パッケージが直接読み取る環境変数ではありません。その正確な値を、選択したプロファイルの master_token.json にモード 0600 で書き込み、変数の設定を解除してから、notebooklm auth refresh を実行して storage_state.json を生成してください。同じディレクトリにあるマスタートークンがあれば、ファイルベースの Cookie の期限切れ時に自動で再生成できます。インラインの NOTEBOOKLM_AUTH_JSON は短期間のみ使用する代替手段です。これはこの復旧経路を迂回します。

未リリースの main チェックアウトではなく、PyPI またはリリースタグを使用してください。利用可能な場合は、インストールガイドを参照してください。

ワークフローの実行前に、Cookie ファイルを読み取れるかどうかだけで判断せず、実際に認証が行われることを確認してください。

notebooklm auth check --test --json

.status == "ok" かつ .checks.token_fetch == true であることを必須としてください。検証に失敗した場合：

• ディスプレイがある場合は、notebooklm login を実行して、もう一度検証してください。
• ヘッドレス環境では、[cookies] をインストールし、notebooklm login --browser-cookies <browser> を使用してください。アカウントの選択が不明確な場合は、まず notebooklm auth inspect --browser <browser> を使用してください。
• 以前は有効だった Cookie が古くなった場合は、notebooklm auth refresh を試してください。ブラウザーに再度サインインした後、notebooklm auth refresh --browser-cookies <browser> を使用してください。

通常の --test 事前チェックでは、更新された Cookie を修復して保存することがあります。以下の失敗診断ワークフローを含め、チェックを厳密に読み取り専用にする必要がある場合は --passive を追加してください。

notebooklm status が報告するのは、選択中のノートブックのコンテキストであり、認証状態ではありません。

どちらの認証ファイルもベアラー認証情報として扱ってください。表示、ログへの記録、コミットは絶対にしないでください。マスタートークンは、パスワードを変更しても有効なままの、アカウント全体に対する永続的な認証情報です。専用アカウントを使用し、シークレットストアとディスク上のモード 0600 で保護してください。漏えいした場合は、必ず明示的に失効させてください。

運用上の不変条件

1. 検出と変更には --json を使用し、返された完全な UUID を保持します。重要なエンベロープは、create の .notebook.id、source add の .source.id、非同期ジェネレーターの .task_id です。generate mind-map は代わりに mind_map、note_id、kind を返します。どちらの種類もタスク ID や個別の artifact wait 手順を必要とせず、完了した結果を返します。
2. 自動化または並行作業でノートブックに関連するすべてのコマンドに -n/--notebook <id> を指定します。notebooklm use に依存しないでください。並行して実行する各処理では、コンテキストとプロファイルへの書き込みを分離するため、一意の NOTEBOOKLM_PROFILE=agent-<id> も設定します。新しいプロファイルには認証情報がありません。使用前に、そのプロファイルに master_token.json のコピーを配置し、ストレージを作成してください。書き込み可能な storage_state.json を複数のエージェント間で共有しないでください。
3. ソースを追加したら、すべての .source.id を保持し、チャットや生成の前に、それぞれに対して source wait を実行します。add エンベロープにはステータスがありません。wait が終了コード 0 で完了し、status == "ready" になることを必須とします。メディア固有の一時的な error 行は waiter に処理させます。
4. 非同期ジェネレーターがタスク ID またはアーティファクト ID を返したら、-n <notebook_id> を指定し、位置引数として artifact wait に渡します。-a <artifact_id> -n <notebook_id> を指定して、その特定のアーティファクトをダウンロードします。最新の表示アーティファクトを選択しないでください。マインドマップ生成は完了した結果を直接返すため、artifact wait は不要です。
5. 重複する調査実行では、常に --run-id <research_run_id> を指定します。
6. ホストにバックグラウンド実行機能が実際にある場合にのみ使用します。wait コマンドと依存するダウンロードコマンドは、1 つの逐次ジョブにまとめ、wait が終了コード 0 で完了した後にのみダウンロードします。それ以外の場合はフォアグラウンドで実行するか、正確な ID を指定したコマンドをユーザーに提示します。

認可の境界

安全な確認と、明示的に依頼された作成、ソースの追加、チャット、プロンプトの提案は、そのまま実行できます。復旧を試みる前に、読み取り専用コマンドで失敗の原因を診断してください。

すでに明確な許可を得ていない操作については、実行の直前に確認を取ってください。

• ノートブック／ソース／ノート／アーティファクト／ラベル／プロファイルの削除、共有の削除、ログアウト、クリア、調査のキャンセル、ask --new などの破壊的なコマンド。
• language set。デフォルトモードがアカウント全体の出力言語を変更するためです（生成コマンドの --language オーバーライドを優先してください）。
• 数分かかる可能性があり、レート制限の対象となる生成や、長時間のフォアグラウンド待機。
• ファイルを書き込むダウンロード。
• ソースをインポートする research wait --import-all。
• ノートを作成する ask --save-as-note と history --save。

CLI プロンプトの有無ではなく、ユーザーの意図が認可の境界です。許可を得た後は、サポートされている場合に --yes／-y を渡してください。ほとんどの破壊的な JSON コマンドはこの指定がないとプロンプトを表示せずに拒否しますが、ask --new --json や share remove --json など、一部のコマンドはプロンプトなしで実行されます。プロンプトが表示されないことを同意と見なさないでください。

research cancel は実行後に結果を待たずに終了します。許可を得てキャンセルした後は、notebooklm research status -n <notebook_id> --run-id <research_run_id> --json で該当する実行を確認してください。

コマンドの確認

フラグを推測するのではなく、インストール済み CLI のヘルプを、バージョンに対応した信頼できる情報源として使用してください。

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

また、notebooklm --version を確認し、ヘルプがこのスキルと異なる場合は、notebooklm generate audio --help のように該当するコマンドまで掘り下げて確認してください。

一般的な操作：

目的	コマンド
コンピューティングの使用状況を確認する	notebooklm usage --json；カテゴリの利用可否と推定コストを確認するには notebooklm usage --categories
ノートブックを一覧表示または作成する	notebooklm list --json；notebooklm create "Title" --json
ソースを追加して待機する	notebooklm source add <input> -n <nb> --json；notebooklm source wait <src> -n <nb>
URL の取得を再試行する	notebooklm source add <url> --fallback-fetch
チャットする	notebooklm ask "question" -n <nb> --json
リサーチする	notebooklm source add-research "query" -n <nb> --mode fast --json（deep もサポートされています）
成果物を一覧表示または待機する	notebooklm artifact list -n <nb> --json；notebooklm artifact wait <id> -n <nb>
生成する	notebooklm generate <type> ... -n <nb> --json
ダウンロードする	notebooklm download <type> <path> -n <nb> -a <artifact>

コマンドの全機能については、インストール済みコマンドのヘルプ、または利用可能な場合は CLI リファレンスを参照してください。 アプリケーションコードについては、以下のベースラインを使用し、利用可能な場合は Python API ガイドを参照してください。

標準的なソースから成果物を作成するワークフロー

JSON 出力から {notebook_id}、すべての {source_id}、および {artifact_id} を保持してください。

このワークフローの完了を明示的に依頼された場合、その通常の前提条件となる待機、依頼された生成、および依頼された出力ファイルの作成が許可されます。その依頼によってすでに許可されていない作業についてのみ、確認してください。

1. notebooklm create "Research: topic" --json
2. 入力ごとに notebooklm source add <input> -n {notebook_id} --json を実行します。
3. フォアグラウンドでの待機が許可されたら、取得したソースごとに notebooklm source wait {source_id} -n {notebook_id} --timeout 600 を実行します。
4. 生成が許可されたら、依頼された種類の成果物を生成します。音声の場合： notebooklm generate audio "instructions" -n {notebook_id} -s {source_id} --json。 選択したソースごとに -s を繰り返し、.task_id を {artifact_id} として取得します。
5. フォアグラウンドでの待機が許可されたら、 notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 1200 を実行します。
6. 出力ファイルの書き込みが許可されたら、 notebooklm download audio ./podcast.m4a -a {artifact_id} -n {notebook_id} を実行します。

生成せずに分析する場合は、すべてのソースが準備できた後に限り、ステップ 4～6 を ID を指定したチャットコマンドに置き換えてください。

notebooklm ask "Summarize the key arguments" -n {notebook_id} --json

ディープリサーチ

ディープリサーチには 15～30 分以上かかることがあります。ブロッキングせずに開始し、 .poll_task_id // .task_id を {research_run_id} として保持してください。

notebooklm source add-research "query" -n {notebook_id} --mode deep --no-wait --json

明示的な許可を得た後にのみインポートし、両方の ID を指定してください。

notebooklm research wait -n {notebook_id} --run-id {research_run_id} \
  --import-all --timeout 1800 --json

--import-all を指定した場合、--timeout はポーリングとインポートの再試行に対するフェーズごとの予算です。この例では、ホストの実経過時間が約 3600 秒に達することがあります。

.imported_sources[].id から新たに作成されたソース ID を保持し、後続のチャットや生成の前に準備が完了するまで待機してください。

Python API のベースライン

完全な API ガイドを利用できない場合は、インストール済みの型付き API とその docstring を使用し、メソッド名を推測しないでください。CLI ワークフローと同じ ID および準備完了の確認手順を維持してください。

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 しません。クライアントは同じイベントループ上で再入可能ですが、スレッドセーフではありません。ループごとにクライアントを 1 つ作成してください。公開されている名前空間には、notebooks、sources、chat、research、artifacts、mind_maps、notes、settings、sharing、labels、および collections があります。状態を変更する呼び出し、長時間実行される呼び出し、またはファイルに書き込む呼び出しを実行する前に、上記の許可境界を適用してください。

生成に関する注意事項

利用可能な生成タイプには、audio、video、slide-deck、infographic、report、mind-map、 data-table、quiz、flashcardsがあります。形式、スタイル、ソースの選択、言語、再試行のサポートはタイプによって異なるため、notebooklm generate <type> --helpを確認してください。

次の、分かりにくい違いに注意してください。

• マインドマップ（--kind interactive、デフォルト）は内部的には非同期のスタジオ成果物ですが、CLI が完了までポーリングし、{mind_map, note_id, kind}を返します。artifact waitは実行しないでください。
• マインドマップ（--kind note-backed）はサーバー側で同期的に処理されます。どちらのタイプも--instructionsを受け付けます。interactive では確実に適用されますが、サーバーは note-backed マップでは無視する場合があります。
• generate video --format cinematicは--styleを無視し、Google AI Ultra が必要です。完了まで約30～40分かかる場合があります。
• スライドデッキには向きを指定するフラグがありません。説明文で縦向きの出力を指定してください（例：9:16 portrait）。スライドの修正ではデッキの向きを変更できません。
• カスタムレポートを作成するには、プロンプトを位置引数の説明文として--format customとともに渡してください。--appendは組み込みのレポート形式にのみ適用されます。

プロンプトが長すぎる場合や、シェルで引用符を使って指定しにくい場合は、ask、source add-research、および対応する生成コマンドで--prompt-file PATHを使用してください。このファイルにはプロンプトのテキストを記述します。ソース文書のアップロードには、代わりにsource addを使用してください。

出力と引用

人間向けの出力を解析するのではなく、構造化データとして JSON を使用してください。よく使われるライフサイクルの値は次のとおりです。

• ソース：unknown／preparing／processingからreadyまたはerrorへ進みます。readyになってから先に進んでください。
• 成果物：pending／in_progressからcompleted、failed、またはremovedへ進みます。not_foundは一覧への反映が一時的に遅れている可能性があります。completedになってから先に進むか、ダウンロードしてください。

チャット JSON にはanswer、conversation_id、references[].source_idが含まれます。参照のstart_char／end_charは、フラットなSourceFulltext.contentではなく、構造化されたソース文書内の UTF-16 オフセットです。Python では、from notebooklm import resolve_chat_reference_passageを使用し、続いてawait resolve_chat_reference_passage(client, notebook_id, reference)を呼び出してください。正確な文書範囲を使用し、必要に応じてfind_citation_context()にフォールバックします。

失敗への対応

失敗した場合は、まず安全な読み取り専用の診断を実行してください。

notebooklm auth check --test --passive --json
notebooklm list --json
notebooklm source list -n {notebook_id} --json
notebooklm artifact list -n {notebook_id} --json
notebooklm research status -n {notebook_id} --run-id {research_run_id} --json

失敗したワークフローに関連するコマンドだけを確認してください。診断中に状態を変更しないでください。

• 終了コード 0 は成功を意味します。想定されるコマンドの失敗では終了コード 1 が返されます。source waitのタイムアウトでは終了コード 2、artifact waitおよびresearch waitのタイムアウトでは終了コード 1 が返されます。
• まず終了コードに基づいて分岐してください。通常の処理対象となる JSON エラーでは{error, code, message}が返されます。一方、wait コマンドでは{"status": "timeout", "error": "..."}のようなドメイン固有のエンベロープが返されます。
• 認証エラーの場合は、checks.token_fetchを再検証してください。値がtrueでない場合にのみログインしてください。
• wait がタイムアウトした場合は、その旨を報告し、該当するソース、成果物、またはリサーチの実行を確認してください。
• 生成には Google によるレート制限があります。タスク ID を保持し、ステータスを確認してください。再試行はユーザーの許可がある場合にのみ行い、無期限に繰り返さないでください。既存の失敗した Studio 成果物について、その場で再試行する前にnotebooklm artifact retry <artifact_id> -n {notebook_id} --helpを確認してください。
• プロトコルエラーの場合は、インストール済みのバージョン、正確なコマンド、関連する ID、秘匿情報を除いたエラーを記録してください。ネットワークにアクセスできる場合は、プロジェクトの課題トラッカーを確認してください。アクセスできない場合は、回避策を捏造しないでください。

進捗の更新は簡潔にし、関連する返却 ID を含めてください。認証情報の内容は決して公開しないでください。

スキルのインストール

このファイルがすでにエージェントスキルのディレクトリ内にある場合、スキルはインストール済みです。それ以外の場合：

• notebooklm skill installは、対応するローカルのスキル配置先にインストールまたは更新します。
• notebooklm skill packageは、サンドボックス化されたエージェント環境向けの、アップロード可能なアーカイブを作成します。
• notebooklm skill status --jsonは、インストール済みのバージョンとcontent_mismatchを報告します。