PydanticAI ビジュアルガイド

Lesson CH06-L01

画像入力

ImageUrl / BinaryContentで画像をAgentに渡し解析させる。

読了目安
9 min
Colab目安
14 min
合計
23 min
前提
Safety Settings

関連: 公式ドキュメント

一行サマリ

PydanticAI では agent.run_sync([prompt, ImageUrl(url=...)]) または BinaryContent(data=..., media_type='image/jpeg') の形で テキストとメディアを混在したリスト を渡すだけで Gemini に画像を解析させられる。URL 参照とバイナリ直接の 2 つの入り口 を覚えると、ほぼ全てのユースケースに対応できる。

ヒーロー: テキストとメディアを 1 つのリストで渡す

PydanticAI のメッセージは「テキストだけ」ではなく、マルチモーダル要素を含むリスト を 1 ターンとして渡せます。Gemini はリスト内の画像とテキストを 同じ文脈 として読み、自然な日本語で応答します。

図を読み込み中…
図1. マルチモーダル入力の流れ

概念: 2 つの入り口 — URL と Binary

渡し方型使う場面
URL 参照ImageUrl(url='https://...')ネット上の画像。モデル側が直接ダウンロード
バイナリ直接BinaryContent(data=bytes, media_type='image/jpeg')ローカルファイル / アップロード画像 / プライベート画像

media_type は image/jpeg image/png image/webp image/gif 等 MIME 形式で指定。Gemini は概ねメジャー画像形式を受け付ける ので、ほとんどの場合 PNG/JPEG で OK です。

コード: 3 つのパターン

パターン 1: URL の画像を 1 枚渡す

from pydantic_ai import Agent, ImageUrl
from pydantic_ai.models.google import GoogleModel
 
model = GoogleModel('gemini-3-flash-preview')
agent = Agent(model, instructions='画像の内容を簡潔な日本語で説明してください。')
 
result = agent.run_sync([
    'この画像に何が写っていますか?',
    ImageUrl(url='https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/640px-Cat03.jpg'),
])
print(result.output)

ポイント:

  • 第一引数は 文字列ではなくリスト。リストの各要素はテキスト or メディア
  • ImageUrl は pydantic_ai から直接 import (sub-module 不要)
  • 公開 URL でないとモデルからアクセスできない (社内画像は次パターン)

パターン 2: ローカルファイルを 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'))
 
img_bytes = Path('./photo.jpg').read_bytes()
 
result = agent.run_sync([
    'この写真について 3 文で要約してください。',
    BinaryContent(data=img_bytes, media_type='image/jpeg'),
])
print(result.output)

BinaryContent は bytes と media_type の 2 つだけ で完結。Path.read_bytes() で読み込めば OK です。

パターン 3: 複数枚の画像を比較させる

from pydantic_ai import Agent, ImageUrl
from pydantic_ai.models.google import GoogleModel
 
agent = Agent(
    GoogleModel('gemini-3-flash-preview'),
    instructions='2 枚の画像の違いを箇条書きで日本語で挙げてください。',
)
 
result = agent.run_sync([
    '次の 2 枚を比較してください。',
    ImageUrl(url='https://example.com/before.jpg'),
    ImageUrl(url='https://example.com/after.jpg'),
])
print(result.output)

リストに 何枚でも積める のがポイント。Gemini はリスト順を意識するので、「最初が before、次が after」の順序を活用できます。

図を読み込み中…
図2. URL と BinaryContent の使い分け

観察: 構造化抽出と組み合わせる

画像入力は Ch4 の構造化出力 と組み合わせると威力を発揮します。

from pydantic import BaseModel, Field
from pydantic_ai import Agent, ImageUrl
from pydantic_ai.models.google import GoogleModel
 
class Receipt(BaseModel):
    store_name: str = Field(description='店舗名')
    total_yen: int = Field(description='合計金額 (円)')
    items: list[str] = Field(description='購入アイテム名のリスト')
 
agent = Agent(
    GoogleModel('gemini-3-flash-preview'),
    output_type=Receipt,
    instructions='レシート画像から構造化情報を抽出してください。',
)
 
result = agent.run_sync([
    'このレシートを読み取ってください。',
    ImageUrl(url='https://example.com/receipt.jpg'),
])
print(result.output)
# Receipt(store_name='○○商店', total_yen=1480, items=['牛乳', 'パン', ...])

「画像 → 構造化」は OCR + 後処理を 1 ステップで置き換える典型パターンです。

まとめ

  • agent.run_sync([prompt, ImageUrl(url=...)]) で URL 画像を渡す
  • BinaryContent(data=bytes, media_type='image/jpeg') でローカル画像
  • リストに複数のメディアを積めば比較や複数枚解析もそのまま
  • 構造化出力 (Ch4) と組み合わせると OCR + 後処理が 1 ステップ になる

次レッスンでは PDF 解析 — DocumentUrl / BinaryContent(media_type='application/pdf') でドキュメントをそのまま入力するパターンを扱います。

Colab で実際に動かす

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

Open in Colab

notebooks/ch06/01-image-input.ipynb