Gemini Deep Research がプレビュー版で利用可能になりました。共同プランニング、可視化、MCP サポートなどが含まれています。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

ファイルの入力方法

注: このバージョンのページでは、現在ベータ版の新しい Interactions API について説明します。
安定した本番環境デプロイの場合は、引き続き generateContent API を使用することをおすすめします。このページの切り替えボタンを使用して、バージョンを切り替えることができます。

このガイドでは、Gemini API にリクエストを行う際に、画像、音声、動画、ドキュメントなどのメディアファイルを含めるさまざまな方法について説明します。新しい方法は、Batch API、Interactions API、Live API など、すべての Gemini API エンドポイントでサポートされています。適切な方法を選択するかどうかは、ファイルのサイズ、データの保存場所、ファイルの利用頻度によって異なります。

入力としてファイルを含める最も簡単な方法は、ローカルファイルを読み取ってプロンプトに含めることです。次の例は、ローカル PDF ファイルを読み取る方法を示しています。この方法では、PDF は 50 MB に制限されます。ファイルの入力タイプと上限の完全なリストについては、入力方法の比較表をご覧ください。

Python

# This will only work for SDK newer than 2.0.0
from google import genai
import pathlib
import base64

client = genai.Client()

filepath = pathlib.Path('my_local_file.pdf')

prompt = "Summarize this document"
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": prompt},
        {"type": "document", "data": base64.b64encode(filepath.read_bytes()).decode('utf-8'), "mime_type": "application/pdf"}
    ]
)
# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";
import * as fs from 'node:fs';

const client = new GoogleGenAI({});
const prompt = "Summarize this document";

async function main() {
    const filePath = 'my_local_file.pdf';

    const interaction = await client.interactions.create({
        model: "gemini-3-flash-preview",
        input: [
            { type: "text", text: prompt },
            {
                type: "document",
                data: fs.readFileSync(filePath).toString("base64"),
                mime_type: "application/pdf"
            }
        ]
    });
    const modelStep = interaction.steps.find(s => s.type === 'model_output');
    if (modelStep) {
      for (const contentBlock of modelStep.content) {
        if (contentBlock.type === 'text') console.log(contentBlock.text);
      }
    }
}

main();

REST

# Encode the local file to base64
B64_CONTENT=$(base64 -w 0 my_local_file.pdf)

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": [
      {"type": "text", "text": "Summarize this document"},
      {
        "type": "document",
        "data": "'${B64_CONTENT}'",
        "mime_type": "application/pdf"
      }
    ]
  }'

入力方法の比較

次の表に、各入力方法とファイルの上限、最適なユースケースを比較して示します。ファイルサイズの上限は、ファイル形式、ファイル処理に使用するモデルまたはトークナイザーによって異なる場合があります。

メソッド	最適な用途	最大ファイルサイズ	永続性
インラインデータ	クイックテスト、小さいファイル、リアルタイムアプリケーション。	リクエストまたはペイロードあたり 100 MB （PDF の場合は 50 MB）	なし（リクエストごとに送信）
File API アップロード	大きなファイル、複数回使用するファイル。	ファイルあたり 2 GB、プロジェクトあたり最大 20 GB	48 時間
File API GCS URI 登録	Google Cloud Storage にすでに保存されている大きなファイル、複数回使用するファイル。	ファイルあたり 2 GB、ストレージの上限なし	なし（リクエストごとに取得）。1 回の登録で最大 30 日間アクセスできます。
外部 URL	公開データまたはクラウドバケット（AWS、Azure、GCS）内のデータ（再アップロードなし）。	リクエスト/ペイロードあたり 100 MB	なし（リクエストごとに取得）

インラインデータ

小さいファイル（100 MB 未満、PDF の場合は 50 MB）の場合は、リクエストペイロードでデータを直接渡すことができます。これは、クイックテストや、リアルタイムの一時的なデータを処理するアプリケーションに最適な方法です。データは、Base64 エンコードされた文字列として提供することも、ローカルファイルを直接読み取ることもできます。

ローカルファイルから読み取る例については、このページの冒頭の例をご覧ください。

URL から取得する

URL からファイルを取得し、バイトに変換して入力に含めることもできます。

Python

# This will only work for SDK newer than 2.0.0
from google import genai
import httpx
import base64

client = genai.Client()

doc_url = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
doc_data = httpx.get(doc_url).content

prompt = "Summarize this document"

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "document", "data": base64.b64encode(doc_data).decode('utf-8'), "mime_type": "application/pdf"},
        {"type": "text", "text": prompt}
    ]
)
# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const docUrl = 'https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf';
const prompt = "Summarize this document";

async function main() {
    const pdfResp = await fetch(docUrl)
      .then((response) => response.arrayBuffer());

    const interaction = await client.interactions.create({
        model: "gemini-3-flash-preview",
        input: [
            { type: "text", text: prompt },
            {
                type: "document",
                data: Buffer.from(pdfResp).toString("base64"),
                mime_type: "application/pdf"
            }
        ]
    });
    const modelStep = interaction.steps.find(s => s.type === 'model_output');
    if (modelStep) {
      for (const contentBlock of modelStep.content) {
        if (contentBlock.type === 'text') console.log(contentBlock.text);
      }
    }
}

main();

REST

DOC_URL="https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"
PROMPT="Summarize this document"
DISPLAY_NAME="base64_pdf"

# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"

# Check for FreeBSD base64 and set flags accordingly
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

# Base64 encode the PDF
ENCODED_PDF=$(base64 $B64FLAGS "${DISPLAY_NAME}.pdf")

# Create JSON payload file
cat <<EOF > payload.json
{
"model": "gemini-3-flash-preview",
"input": [
{"type": "document", "data": "${ENCODED_PDF}", "mime_type": "application/pdf"},
{"type": "text", "text": "${PROMPT}"}
]
}
EOF

# Generate content using interactions
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d @payload.json 2> /dev/null > response.json

cat response.json
echo

jq ".outputs[] | select(.type == \"text\") | .text" response.json

Gemini File API

File API は、大きなファイル（最大 2 GB）や、複数のリクエストで使用するファイルを対象としています。

標準のファイルアップロード

ローカルファイルを Gemini API にアップロードします。この方法でアップロードされたファイルは一時的に（48 時間）保存され、モデルによる効率的な取得のために処理されます。

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

# Upload the file
doc_file = client.files.upload(file="path/to/your/sample.pdf")
prompt = "Summarize this document"

# Use the uploaded file in an interaction
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": prompt},
        {"type": "document", "uri": doc_file.uri, "mime_type": doc_file.mime_type}
    ]
)
# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const prompt = "Summarize this document";

async function main() {
  const filePath = "path/to/your/sample.pdf";

  const myfile = await client.files.upload({
    file: filePath,
    config: { mime_type: "application/pdf" },
  });

  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
        { type: "text", text: prompt },
        { type: "document", uri: myfile.uri, mime_type: myfile.mimeType }
    ]
  });
  const modelStep = interaction.steps.find(s => s.type === 'model_output');
  if (modelStep) {
    for (const contentBlock of modelStep.content) {
      if (contentBlock.type === 'text') console.log(contentBlock.text);
    }
  }
}

await main();

REST

FILE_PATH="path/to/sample.pdf"
MIME_TYPE=$(file -b --mime-type "${FILE_PATH}")
NUM_BYTES=$(wc -c < "${FILE_PATH}")
DISPLAY_NAME=DOCUMENT

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -D "${tmp_header_file}" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${FILE_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)

# Now use in an interaction
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Api-Revision: 2026-05-20" \
    -d '{
      "model": "gemini-3-flash-preview",
      "input": [
        {"type": "text", "text": "Summarize this document"},
        {"type": "document", "uri": '$file_uri', "mime_type": "'${MIME_TYPE}'"}
      ]
    }'

Google Cloud Storage ファイルを登録する

データがすでに Google Cloud Storage に保存されている場合は、ダウンロードして再アップロードする必要はありません。File API で直接登録できます。

各バケットへのサービスエージェント のアクセス権を付与する
1. Google Cloud プロジェクトで Gemini API を有効にします。
2. サービスエージェントを作成します。
  
  gcloud beta services identity create --service=generativelanguage.googleapis.com --project=<your_project>
3. ストレージバケットを読み取るためのGemini API サービスエージェントの権限を付与 します。
  
  ユーザーは、使用する特定のストレージバケットに対して、このサービスエージェントに Storage Object Viewer IAM ロールを割り当てる必要があります。
このアクセス権はデフォルトでは期限切れになりませんが、いつでも変更できます。Google Cloud Storage IAM SDK コマンドを使用して権限を付与することもできます。
サービスを認証する

前提条件
- API を有効にする
- 適切な権限を持つサービスアカウントまたはエージェントを作成する。
まず、ストレージオブジェクト閲覧者の権限を持つサービスとして認証する必要があります。この処理は、ファイル管理コードが実行される環境によって異なります。

Google Cloud の外部

デスクトップなど、Google Cloud の外部からコードを実行している場合は、次の手順で Google Cloud コンソールからアカウント認証情報をダウンロードします。
1. サービスアカウントコンソールに移動します。
2. 関連するサービスアカウントを選択します。
3. [鍵] タブを選択し、[鍵を追加、新しい鍵を作成] を選択します。
4. 鍵のタイプとして [JSON] を選択し、ファイルがダウンロードされた場所をメモします。
詳細については、サービスアカウントの鍵の管理に関する Google Cloud の公式ドキュメントをご覧ください。

次のコマンドを使用して認証します。これらのコマンドは、サービスアカウントファイルが現在のディレクトリにあり、service-account.json という名前であることを前提としています。
Python
from google.oauth2.service_account import Credentials GCS_READ_SCOPES = [ 'https://www.googleapis.com/auth/devstorage.read_only', 'https://www.googleapis.com/auth/cloud-platform' ] SERVICE_ACCOUNT_FILE = 'service-account.json' credentials = Credentials.from_service_account_file( SERVICE_ACCOUNT_FILE, scopes=GCS_READ_SCOPES )
JavaScript
const { GoogleAuth } = require('google-auth-library'); const GCS_READ_SCOPES = [ 'https://www.googleapis.com/auth/devstorage.read_only', 'https://www.googleapis.com/auth/cloud-platform' ]; const SERVICE_ACCOUNT_FILE = 'service-account.json'; const auth = new GoogleAuth({ keyFile: SERVICE_ACCOUNT_FILE, scopes: GCS_READ_SCOPES });
CLI
gcloud auth application-default login \ --client-id-file=service-account.json \ --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only'
Google Cloud

Cloud Run 関数や Compute Engine インスタンスを使用して Google Cloud で直接実行している場合は、暗黙的な認証情報がありますが、適切なスコープを付与するために再認証する必要があります。
Python
このコードは、Cloud Run や Compute Engine など、アプリケーションのデフォルト認証情報を自動的に取得できる環境でサービスが実行されていることを前提としています。
import google.auth GCS_READ_SCOPES = [ 'https://www.googleapis.com/auth/devstorage.read_only', 'https://www.googleapis.com/auth/cloud-platform' ] credentials, project = google.auth.default(scopes=GCS_READ_SCOPES)
JavaScript
このコードは、Cloud Run や Compute Engine など、アプリケーションのデフォルト認証情報を自動的に取得できる環境でサービスが実行されていることを前提としています。
const { GoogleAuth } = require('google-auth-library'); const auth = new GoogleAuth({ scopes: [ 'https://www.googleapis.com/auth/devstorage.read_only', 'https://www.googleapis.com/auth/cloud-platform' ] });
CLI
これはインタラクティブなコマンドです。Compute Engine などのサービスでは、構成レベルで実行中のサービスにスコープをアタッチできます。例については、ユーザー管理サービスのドキュメントをご覧ください。
gcloud auth application-default login \ --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"

ファイルの登録（Files API）

Files API を使用してファイルを登録し、Gemini API で直接使用できる Files API パスを生成します。

Python

# This will only work for SDK newer than 2.0.0
from google import genai

# Note that you must provide an API key in the GEMINI_API_KEY
# environment variable, but it is unused for the registration endpoint.
client = genai.Client(credentials=credentials)

registered_gcs_files = client.files.register_files(
    uris=["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"]
)
prompt = "Summarize this file."

# call interactions.create for each file
for f in registered_gcs_files.files:
  print(f.name)
  interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
      {"type": "text", "text": prompt},
      {"type": "document", "uri": f.uri, "mime_type": f.mime_type}
    ],
  )
  # Print the model's text response
  for step in interaction.steps:
      if step.type == "model_output":
          for content_block in step.content:
              if content_block.type == "text":
                  print(content_block.text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ auth: auth });

async function main() {
    const registeredGcsFiles = await ai.files.registerFiles({
        uris: ["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"]
    });

    const prompt = "Summarize this file.";

    for (const file of registeredGcsFiles.files) {
        console.log(file.name);
        const interaction = await ai.interactions.create({
            model: "gemini-3-flash-preview",
            input: [
                { type: "text", text: prompt },
                { type: "document", uri: file.uri, mime_type: file.mimeType }
            ]
        });

        const modelStep = interaction.steps.find(s => s.type === 'model_output');
        if (modelStep) {
            for (const contentBlock of modelStep.content) {
                if (contentBlock.type === 'text') console.log(contentBlock.text);
            }
        }
    }
}

main();

CLI

access_token=$(gcloud auth application-default print-access-token)
project_id=$(gcloud config get-value project)
curl -X POST https://generativelanguage.googleapis.com/v1beta/files:register \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ${access_token}" \
    -H "x-goog-user-project: ${project_id}" \
    -d '{"uris": ["gs://bucket/object1", "gs://bucket/object2"]}'

外部 HTTP / 署名付き URL

一般公開されている HTTPS URL または事前署名付き URL をリクエストで直接渡すことができます。Gemini API は、処理中にコンテンツを安全に取得します。これは、再アップロードしたくない 100 MB までのファイルに最適です。

Python

# This will only work for SDK newer than 2.0.0
from google import genai

uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf"
prompt = "Summarize this file"

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "document", "uri": uri, "mime_type": "application/pdf"},
        {"type": "text", "text": prompt}
    ]
)
# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const uri = "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf";

async function main() {
  const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: [
      { type: "document", uri: uri, mime_type: "application/pdf" },
      { type: "text", text: "summarize this file" }
    ]
  });

  const modelStep = interaction.steps.find(s => s.type === 'model_output');
  if (modelStep) {
    for (const contentBlock of modelStep.content) {
      if (contentBlock.type === 'text') console.log(contentBlock.text);
    }
  }
}

main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
      -H 'x-goog-api-key: $GEMINI_API_KEY' \
      -H 'Content-Type: application/json' \
      -H "Api-Revision: 2026-05-20" \
      -d '{
          "model": "gemini-3-flash-preview",
          "input": [
            {"type": "text", "text": "Summarize this pdf"},
            {
              "type": "document",
              "uri": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf",
              "mime_type": "application/pdf"
            }
          ]
        }'

ユーザー補助

指定した URL が、ログインが必要なページやペイウォールの背後にあるページにリンクしていないことを確認します。非公開データベースの場合は、正しいアクセス権と有効期限を持つ署名付き URL を作成してください。

安全チェック

システムは、URL が安全基準とポリシー基準を満たしていることを確認するため、URL に対してコンテンツモデレーションチェックを実行します。このチェックに失敗すると、url_retrieval_status が URL_RETRIEVAL_STATUS_UNSAFE になります。

サポートされているコンテンツの種類

サポートされているファイル形式と制限事項のリストは、最初のガイダンスとして提供されており、包括的なものではありません。サポートされているタイプの有効なセットは変更される可能性があり、使用する特定のモデルとトークナイザのバージョンによって異なります。サポートされていないタイプを使用すると、エラーが発生します。また、これらのファイル形式のコンテンツ取得では、一般公開されている URL のみがサポートされます。

テキストファイル形式

text/html
text/css
text/plain
text/xml
text/csv
text/rtf
text/javascript

アプリケーションファイル形式

application/json
application/pdf

画像ファイル形式

image/bmp
image/jpeg
image/png
image/webp

ベストプラクティス

適切な方法を選択する: 小さな一時ファイルにはインラインデータを使用します。大きなファイルや頻繁に使用するファイルには File API を使用します。すでにオンラインでホストされているデータには外部 URL を使用します。
MIME タイプを指定する: 適切な処理を行うため、ファイルデータの正しい MIME タイプを常に指定してください。
エラーを処理する: ネットワーク障害、ファイルアクセスの問題、API エラーなどの潜在的な問題を管理するため、コードにエラー処理を実装します。

制限事項

ファイルサイズの上限は、方法（比較表を参照）とファイル形式によって異なります。
インラインデータを使用すると、リクエストペイロードのサイズが増加します。
File API のアップロードは一時的なもので、48 時間後に期限切れになります。
外部 URL の取得は、ペイロードあたり 100 MB に制限され、特定のコンテンツタイプをサポートしています。

次のステップ

Google AI Studio を使用して、独自のマルチモーダルプロンプトを作成してみましょう。
プロンプトにファイルを含める方法については、 Vision、音声、およびドキュメント処理のガイドをご覧ください。

ファイルの入力方法

Python

JavaScript

REST

入力方法の比較

インライン データ

URL から取得する

Python

JavaScript

REST

Gemini File API

標準のファイル アップロード

Python

JavaScript

REST

Google Cloud Storage ファイルを登録する

Python

JavaScript

CLI

Python

JavaScript

CLI

Python

JavaScript

CLI

外部 HTTP / 署名付き URL

Python

JavaScript

REST

ユーザー補助

安全チェック

サポートされているコンテンツの種類

テキスト ファイル形式

アプリケーション ファイル形式

画像ファイル形式

ベスト プラクティス

制限事項

次のステップ

インラインデータ

標準のファイルアップロード

テキストファイル形式

アプリケーションファイル形式

ベストプラクティス