PydanticAI ビジュアルガイド

Lesson CH06-L03

YouTube URL 直接入力

YouTubeのURLを渡すだけで動画内容を理解させるGemini固有機能。

読了目安
9 min
Colab目安
14 min
合計
23 min
前提
PDF解析

関連: 公式ドキュメント

一行サマリ

agent.run_sync(['要約して', VideoUrl(url='https://youtube.com/watch?v=...')]) のように、YouTube URL を VideoUrl でラップしてリストに含めるだけで Gemini が 動画を直接視聴 + 音声書き起こし + 内容理解 までしてくれる。動画のダウンロード / フレーム抽出 / 音声分離は不要。

ヒーロー: YouTube URL を「読む」

通常、動画解析は (1) ダウンロード (2) 音声分離 (3) フレーム抽出 (4) 文字起こし (5) 要約 という多段パイプラインが必要でした。Gemini は YouTube URL をそのまま受け取れる Google 固有機能 を持っており、この 5 段を 1 ステップに圧縮できます。

図を読み込み中…
図1. YouTube URL 直接入力 vs 従来パイプライン

概念: VideoUrl の制約

項目仕様
入力型VideoUrl(url='https://www.youtube.com/watch?v=XXXX') (短縮 youtu.be/XXXX も可)
1 リクエストの本数YouTube 動画は 1 本まで (Vertex AI 経由でも同じ)
動画長モデルにより数十分〜2 時間程度
公開設定「公開」または「限定公開」のみ。完全非公開動画は不可
プロバイダGemini 系のみ (他社モデルは VideoUrl を受け付けない)

社内の限定公開動画 (Vimeo / 自社配信) は VideoUrl 不可なので、BinaryContent(data=mp4_bytes, media_type='video/mp4') を使うことになります。

コード: 3 つのパターン

パターン 1: 動画を要約

from pydantic_ai import Agent, VideoUrl
from pydantic_ai.models.google import GoogleModel
 
agent = Agent(
    GoogleModel('gemini-3-flash-preview'),
    instructions='動画の内容を 5 行以内の日本語で要約してください。',
)
 
result = agent.run_sync([
    'この動画を要約してください。',
    VideoUrl(url='https://www.youtube.com/watch?v=dQw4w9WgXcQ'),
])
print(result.output)

ポイント:

  • VideoUrlpydantic_ai から直接 import
  • リスト第二引数以降に VideoUrl(url=...) を入れるだけ
  • 第一引数は テキスト指示 (どう要約するか・何を抽出するかを明示)

パターン 2: 構造化抽出 — チャプター / キーワード / 要点

from pydantic import BaseModel, Field
from pydantic_ai import Agent, VideoUrl
from pydantic_ai.models.google import GoogleModel
 
class VideoBrief(BaseModel):
    title_guess: str = Field(description='動画タイトルの推定 (見えていれば実タイトル)')
    chapters: list[str] = Field(description='主要チャプターを 5 つまで', max_length=5)
    keywords: list[str] = Field(description='重要キーワードを 5 つまで', max_length=5)
    one_line_ja: str = Field(description='100 字以内の日本語要約')
 
agent = Agent(
    GoogleModel('gemini-3-flash-preview'),
    output_type=VideoBrief,
    instructions='YouTube 動画から構造化メタを日本語で抽出してください。',
)
 
brief = agent.run_sync([
    'この動画から構造化情報を抽出してください。',
    VideoUrl(url='https://www.youtube.com/watch?v=XXXXXXXX'),
]).output
 
print(brief)
# VideoBrief(title_guess='...', chapters=['...', '...'], keywords=[...], one_line_ja='...')

「字幕すら無い動画」でも音声 + 映像を直接見て構造化してくれます。

パターン 3: ローカル動画ファイルを BinaryContent で渡す

from pathlib import Path
from pydantic_ai import Agent, BinaryContent
from pydantic_ai.models.google import GoogleModel
 
agent = Agent(GoogleModel('gemini-3-flash-preview'))
 
mp4_bytes = Path('./meeting.mp4').read_bytes()
 
result = agent.run_sync([
    'この会議動画の決定事項を箇条書きで日本語で抽出してください。',
    BinaryContent(data=mp4_bytes, media_type='video/mp4'),
])
print(result.output)

社内会議録画 (限定公開) はこちらが定石。media_typevideo/mp4 video/webm video/quicktime 等から動画形式に合わせて選びます。

図を読み込み中…
図2. 動画ソース別の入り口の選び方

観察: トークン消費は「秒数 + 解像度」

動画は内部で 1 fps 程度のフレーム + 音声に分解されるため、input_tokens が動画長に応じて大きく伸びます

result = agent.run_sync([
    'この動画を要約',
    VideoUrl(url='https://www.youtube.com/watch?v=...'),
])
print(result.usage())
# RunUsage(requests=1, input_tokens=50000, ...)  ← 10 分の動画でこれくらい

長尺動画は チャプター単位に分けて並列実行 が現実解。あるいは「まず 30 秒のサマリだけ取得 → 興味があれば全編」の段階的アプローチ。

まとめ

  • VideoUrl(url='https://www.youtube.com/watch?v=...') で YouTube 動画を直接入力
  • 1 リクエストにつき YouTube 動画は 1 本まで、Gemini 系モデル限定
  • ローカル動画 / 完全非公開動画は BinaryContent(data=bytes, media_type='video/mp4')
  • 構造化出力 (Ch4) と組み合わせれば「動画 → JSON」を 1 ステップで実現

🎉 マルチモーダル入力 (画像 / PDF / 動画) 完結

これで Ch6 全 3 レッスン が完了です。テキスト + 画像 + PDF + 動画 を 同じ agent.run_sync(リスト) で扱える という統一感を覚えておくと、新しいメディアタイプが増えても応用が利きます。

次の Ch7 Toolsets, MCP からは、Agent の機能を 外部にプラグインできる仕組み (Toolset / MCP) に入っていきます。

Colab で実際に動かす

本レッスンの内容を Google Colab 上で実行できるノートブックを用意しています。下のボタンから自分のColab環境に開けます (要 Google アカウント / GOOGLE_API_KEY)。

Open in Colab

notebooks/ch06/03-youtube-input.ipynb