Gemini 2.0 Flash が本番環境に対応しました。詳細

このページは Cloud Translation API によって翻訳されました。

Gemini API でビジョン機能を試す

ai.google.dev で表示

Colab ノートブックを試す

GitHub でノートブックを表示

Gemini モデルは画像と動画を処理できるため、従来はドメイン固有のモデルを必要としていたフロンティアデベロッパーの多くのユースケースを実現できます。Gemini のビジョン機能には、次のものがあります。

画像にキャプションを付け、画像に関する質問に回答する
最大 200 万トークンを含む PDF を音声文字変換して推論する
最大 90 分間の動画の説明、セグメンテーション、情報の抽出
画像内のオブジェクトを検出して、境界ボックスの座標を返す

Gemini はマルチモーダル向けにゼロから構築されており、Google は可能性の限界を押し広げ続けています。

画像入力

画像ペイロードの合計サイズが 20 MB 未満の場合は、base64 でエンコードされた画像をアップロードするか、ローカルに保存されている画像ファイルを直接アップロードすることをおすすめします。

ローカルイメージの操作

Python イメージライブラリ（Pillow ）を使用している場合は、PIL 画像オブジェクトも使用できます。

from google import genai
from google.genai import types

import PIL.Image

image = PIL.Image.open('/path/to/image.png')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=["What is this image?", image])

print(response.text)

Base64 エンコードされた画像

公開画像の URL は、Base64 ペイロードとしてエンコードしてアップロードできます。次のコードサンプルは、標準ライブラリツールのみを使用してこれを行う方法を示しています。

from google import genai
from google.genai import types

import requests

image_path = "https://goo.gle/instrument-img"
image = requests.get(image_path)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What is this image?",
              types.Part.from_bytes(image.content, "image/jpeg")])

print(response.text)

複数の画像

複数の画像でプロンプトを表示するには、generate_content の呼び出しで複数の画像を指定します。これらは、base64 や PIL など、サポートされている形式であればどれでもかまいません。

from google import genai
from google.genai import types

import pathlib
import PIL.Image

image_path_1 = "path/to/your/image1.jpeg"  # Replace with the actual path to your first image
image_path_2 = "path/to/your/image2.jpeg" # Replace with the actual path to your second image

image_url_1 = "https://goo.gle/instrument-img" # Replace with the actual URL to your third image

pil_image = PIL.Image.open(image_path_1)

b64_image = types.Part.from_bytes(
    pathlib.Path(image_path_2).read_bytes(), "image/jpeg")

downloaded_image = requests.get(image_url_1)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What do these images have in common?",
              pil_image, b64_image, downloaded_image])

print(response.text)

これらのインラインデータ呼び出しには、ファイルのメタデータの取得、一覧表示、ファイルの削除など、File API で利用できる多くの機能は含まれていません。

大きな画像ペイロード

送信するファイルとシステムインストラクションの組み合わせのサイズが 20 MB を超える場合は、File API を使用してファイルをアップロードします。

任意のサイズの画像をアップロードするには、File API の media.upload メソッドを使用します。

ファイルをアップロードしたら、File API URI を参照する GenerateContent リクエストを送信できます。生成モデルを選択し、テキストプロンプトとアップロードした画像を指定します。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

img_path = "/path/to/Cajun_instruments.jpg"
file_ref = client.files.upload(path=img_path)
print(f'{file_ref=}')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What can you tell me about these instruments?",
              file_ref])

print(response.text)

OpenAI の互換性

OpenAI ライブラリを使用して、Gemini の画像認識機能にアクセスできます。これにより、3 行のコードを更新して Gemini API キーを使用すると、Gemini を既存の OpenAI ワークフローに統合できます。Base64 ペイロードとしてエンコードされた画像を送信する方法については、画像認識の例をご覧ください。

画像によるプロンプト

このチュートリアルでは、File API を使用して画像をアップロードするか、画像をインラインデータとしてアップロードし、それらの画像に基づいてコンテンツを生成します。

技術的な詳細（画像）

Gemini 1.5 Pro と 1.5 Flash は、最大 3,600 個の画像ファイルをサポートしています。

画像は、次のいずれかの画像データ MIME タイプである必要があります。

PNG - image/png
JPEG - image/jpeg
WEBP - image/webp
HEIC - image/heic
HEIF - image/heif

トークン

画像のトークンの計算方法は次のとおりです。

Gemini 1.0 Pro Vision: 1 つの画像は 258 個のトークンに相当します。
Gemini 1.5 Flash と Gemini 1.5 Pro: 画像の両方の寸法が 384 ピクセル以下の場合、258 個のトークンが使用されます。画像の 1 つの寸法が 384 ピクセルを超える場合、画像はタイルに切り抜かれます。各タイルサイズは、デフォルトで最小の寸法（幅または高さ）を 1.5 で割った値になります。必要に応じて、各タイルは 256 ピクセル以上、768 ピクセル以下になるように調整されます。各タイルは 768x768 にサイズ変更され、258 個のトークンを使用します。
Gemini 2.0 Flash: 両方の寸法が 384 ピクセル以下の画像入力は、258 個のトークンとしてカウントされます。1 つまたは両方の寸法が大きい画像は、必要に応じて切り抜かれ、768x768 ピクセルのタイルにスケーリングされます。各タイルは 258 個のトークンとしてカウントされます。

最適な結果を得るために

アップロードする前に画像を適切な向きに回転します。
ぼやけた画像は使用しないでください。
1 つの画像を使用する場合は、テキストプロンプトを画像の後に配置します。

機能

このセクションでは、Gemini モデルの特定のビジョン機能（オブジェクト検出、境界ボックスの座標など）について概説します。

オブジェクトの境界ボックスを取得する

Gemini モデルは、境界ボックス座標を [0, 1] の範囲内の相対幅または高さとして返すようにトレーニングされています。これらの値は 1,000 倍にスケーリングされ、整数に変換されます。つまり、座標は 1,000 x 1,000 ピクセルの画像の境界ボックスを表します。そのため、境界ボックスを正確にマッピングするには、これらの座標を元の画像のサイズに変換する必要があります。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

prompt = (
  "Return a bounding box for each of the objects in this image "
  "in [ymin, xmin, ymax, xmax] format.")

response = client.models.generate_content(
  model="gemini-1.5-pro",
  contents=[sample_file_1, prompt])

print(response.text)

境界ボックスは、画像や動画内のオブジェクトの検出とローカライズに使用できます。境界ボックスを使用してオブジェクトを正確に特定して区切ることで、幅広いアプリケーションを実現し、プロジェクトのインテリジェンスを強化できます。

主なメリット

シンプル: コンピュータビジョンの専門知識に関係なく、オブジェクト検出機能をアプリケーションに簡単に統合できます。
カスタマイズ可能: カスタムモデルをトレーニングしなくても、カスタムインストラクション（「この画像内のすべての緑色のオブジェクトの境界ボックスを表示したい」など）に基づいて境界ボックスを生成できます。

技術的な詳細情報

入力: プロンプトと、関連する画像または動画フレーム。
出力: [y_min, x_min, y_max, x_max] 形式の境界ボックス。左上は原点です。x 軸と y 軸は、それぞれ水平方向と垂直方向に進みます。座標値は、画像ごとに 0 ～ 1,000 に正規化されます。
可視化: AI Studio ユーザーには、UI 内に境界ボックスが表示されます。

Python デベロッパーは、2D 空間認識ノートブックまたは試験運用版の 3D ポインティングノートブックをお試しください。

座標を正規化する

モデルは、境界ボックスの座標を [y_min, x_min, y_max, x_max] の形式で返します。これらの正規化された座標を元の画像のピクセル座標に変換する手順は次のとおりです。

各出力座標を 1,000 で割ります。
x 座標に元の画像の幅を掛けます。
y 座標に元の画像の高さを掛けます。

境界ボックス座標の生成と画像での可視化の詳細な例については、オブジェクト検出の Cookbook の例をご覧ください。

動画によるプロンプト

このチュートリアルでは、File API を使用して動画をアップロードし、それらの画像に基づいてコンテンツを生成します。

技術的な詳細（動画）

Gemini 1.5 Pro と Flash は、最大 1 時間の動画データをサポートしています。

動画は、次のいずれかの動画形式 MIME タイプである必要があります。

video/mp4
video/mpeg
video/mov
video/avi
video/x-flv
video/mpg
video/webm
video/wmv
video/3gpp

File API サービスは、動画から 1 秒あたり 1 フレーム（FPS）の画像フレームと 1 Kbps の単一チャネルの音声を抽出し、1 秒ごとにタイムスタンプを追加します。これらのレートは、推論の改善のために今後変更される可能性があります。

個々のフレームは 258 トークン、オーディオは 1 秒あたり 32 トークンです。メタデータを使用すると、動画の 1 秒あたりのトークンは約 300 トークンになります。つまり、100 万トークンのコンテキストウィンドウに収まる動画は 1 時間弱です。

タイムスタンプ付きの場所について質問するには、MM:SS 形式を使用します。最初の 2 桁が分、最後の 2 桁が秒を表します。

最良の結果を得るために、次のことを行います。

1 つのプロンプトに 1 つの動画を使用します。
1 つの動画を使用する場合は、テキストプロンプトを動画の後に配置します。

File API を使用して動画ファイルをアップロードする

File API は動画ファイル形式を直接受け入れます。この例では、NASA の短い映画「Jupiter's Great Red Spot Shrinks and Grows」を使用します。クレジット: ゴダード宇宙飛行センター（GSFC）/ David Ladd（2018 年）。

「Jupiter's Great Red Spot Shrinks and Grows」はパブリックドメインであり、特定できる人物は写っていません。（NASA の画像とメディアの使用に関するガイドライン）。

まず、ショート動画を取得します。

wget https://storage.googleapis.com/generativeai-downloads/images/GreatRedSpot.mp4

File API を使用して動画をアップロードし、URI を出力します。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print("Uploading file...")
video_file = client.files.upload(path="GreatRedSpot.mp4")
print(f"Completed upload: {video_file.uri}")

ファイルのアップロードを確認して状態を確認する

files.get メソッドを呼び出して、API がファイルを正常に受信したことを確認します。

import time

# Check whether the file is ready to be used.
while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(1)
    video_file = client.files.get(name=video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

print('Done')

動画とテキストでプロンプトを表示する

アップロードされた動画が ACTIVE 状態になったら、その動画の File API URI を指定する GenerateContent リクエストを送信できます。生成モデルを選択し、アップロードした動画とテキストプロンプトを指定します。

from IPython.display import Markdown

# Pass the video file reference like any other media part.
response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[
        video_file,
        "Summarize this video. Then create a quiz with answer key "
        "based on the information in the video."])

# Print the response, rendering any Markdown
Markdown(response.text)

コンテンツ内のタイムスタンプを参照する

HH:MM:SS 形式のタイムスタンプを使用して、動画内の特定の瞬間を参照できます。

prompt = "What are the examples given at 01:05 and 01:19 supposed to show us?"

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

動画を文字起こしして、動画の説明を提供する

Gemini モデルは、音声トラックと映像フレームの両方を処理することで、動画コンテンツの文字起こしを行い、動画コンテンツの視覚的な説明を提供できます。画像の説明の場合、モデルは動画を 1 秒あたり 1 フレームのレートでサンプリングします。このサンプリングレートは、特に映像が急速に変化する動画の場合、説明の詳細レベルに影響する可能性があります。

prompt = (
    "Transcribe the audio from this video, giving timestamps for "
    "salient events in the video. Also provide visual descriptions.")

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

ファイルの一覧表示

File API を使用してアップロードされたすべてのファイルとその URI を一覧表示するには、files.list を使用します。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print('My files:')
for f in client.files.list():
  print(" ", f'{f.name}: {f.uri}')

ファイルを削除

File API を使用してアップロードされたファイルは、2 日後に自動的に削除されます。files.delete を使用して手動で削除することもできます。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

# Upload a file
poem_file = client.files.upload(path="poem.txt")

# Files will auto-delete after a period.
print(poem_file.expiration_time)

# Or they can be deleted explicitly.
dr = client.files.delete(name=poem_file.name)

try:
  client.models.generate_content(
      model="gemini-2.0-flash-exp",
      contents=['Finish this poem:', poem_file])
except genai.errors.ClientError as e:
  print(e.code)  # 403
  print(e.status)  # PERMISSION_DENIED
  print(e.message)  # You do not have permission to access the File .. or it may not exist.

次のステップ

このガイドでは、File API を使用して画像ファイルと動画ファイルをアップロードし、画像と動画の入力からテキスト出力を生成する方法について説明します。詳細については、次のリソースをご覧ください。

ファイルプロンプト戦略: Gemini API は、テキスト、画像、音声、動画データによるプロンプト（マルチモーダルプロンプト）をサポートしています。
システム指示: システム指示を使用すると、特定のニーズやユースケースに基づいてモデルの動作を制御できます。
安全性に関するガイダンス: 生成 AI モデルは、不正確な出力、偏見のある出力、不適切な出力など、予期しない出力を生成することがあります。このような出力による被害のリスクを軽減するには、後処理と人間による評価が不可欠です。