文件输入方法

本指南介绍了在向 Gemini API 发出请求时，您可以通过哪些不同的方式添加媒体文件，例如图片、音频、视频和文档。选择合适的方法取决于文件的大小、当前存储数据的位置以及您计划使用文件的频率。

将文件作为输入内容的最简单方法是读取本地文件并将其包含在提示中。以下示例展示了如何读取本地 PDF 文件。对于此方法，PDF 的大小上限为 50MB。如需查看文件输入类型和限制的完整列表，请参阅输入法比较表。

Python

from google import genai
from google.genai import types
import pathlib

client = genai.Client()

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

prompt = "Summarize this document"
response = client.models.generate_content(
  model="gemini-3-flash-preview",
  contents=[
      types.Part.from_bytes(
        data=filepath.read_bytes(),
        mime_type='application/pdf',
      ),
      prompt
  ]
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from 'node:fs';

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

async function main() {
    const filePath = path.join('content', 'my_local_file.pdf'); // Adjust path as needed

    const contents = [
        { text: prompt },
        {
            inlineData: {
                mimeType: 'application/pdf',
                data: fs.readFileSync(filePath).toString("base64")
            }
        }
    ];

    const response = await ai.models.generateContent({
        model: "gemini-3-flash-preview",
        contents: contents
    });
    console.log(response.text);
}

main();

REST

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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Summarize this document"}
        ]
      },
      {
        "parts": [
          {
            "inlineData": {
              "mimeType": "application/pdf",
              "data": "'"${B64_CONTENT}"'"
            }
          }
        ]
      }
    ]
  }'

输入法比较

下表比较了每种输入方法的文件限制和最佳使用情形。请注意，文件大小上限可能会因文件类型和用于处理文件的模型/分词器而异。

方法	适用场景	文件大小的最大值	持久性
内嵌数据	快速测试、小文件、实时应用。	每个请求/载荷 100 MB （PDF 为 50 MB）	无（随每个请求发送）
文件 API 上传	大型文件、多次使用的文件。	每个文件 2 GB，每个项目最多 20 GB	48 小时
文件 API GCS URI 注册	已在 Google Cloud Storage 中的大型文件、多次使用的文件。	每个文件的大小上限为 2 GB，没有总体存储空间限制	无（按请求提取）。一次性注册可提供长达 30 天的访问权限。
外部网址	公共数据或云存储分区（AWS、Azure、GCS）中的数据，无需重新上传。	每个请求/载荷 100 MB	无（按请求提取）

内嵌数据

对于较小的文件（小于 100MB，如果是 PDF 文件则小于 50MB），您可以直接在请求载荷中传递数据。这是最简单的方法，适用于快速测试或处理实时瞬态数据的应用。您可以提供 base64 编码的字符串形式的数据，也可以直接读取本地文件。

如需查看从本地文件读取数据的示例，请参阅本页开头的示例。

通过网址提取

您还可以从网址提取文件，将其转换为字节，并将其包含在输入中。

Python

from google import genai
from google.genai import types
import httpx

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"

response = client.models.generate_content(
  model="gemini-3-flash-preview",
  contents=[
      types.Part.from_bytes(
        data=doc_data,
        mime_type='application/pdf',
      ),
      prompt
  ]
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = 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 contents = [
        { text: prompt },
        {
            inlineData: {
                mimeType: 'application/pdf',
                data: Buffer.from(pdfResp).toString("base64")
            }
        }
    ];

    const response = await ai.models.generateContent({
        model: "gemini-3-flash-preview",
        contents: contents
    });
    console.log(response.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")

# Generate content using the base64 encoded PDF
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"inline_data": {"mime_type": "application/pdf", "data": "'"$ENCODED_PDF"'"}},
          {"text": "'$PROMPT'"}
        ]
      }]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

Gemini File API

File API 专为处理较大文件（最大 2 GB）或您打算在多个请求中使用的文件而设计。

标准文件上传

将本地文件上传到 Gemini API。以这种方式上传的文件会临时存储（48 小时），并经过处理，以便模型高效检索。

Python

from google import genai
client = genai.Client()

# Upload the file
audio_file = client.files.upload(file="path/to/your/sample.mp3")
prompt = "Describe this audio clip"

# Use the uploaded file in a prompt
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[prompt, audio_file]
)
print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});
const prompt = "Describe this audio clip";

async function main() {
  const filePath = "path/to/your/sample.mp3"; // Adjust path as needed

  const myfile = await ai.files.upload({
    file: filePath,
    config: { mimeType: "audio/mpeg" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: createUserContent([
      prompt,
      createPartFromUri(myfile.uri, myfile.mimeType),
    ]),
  });
  console.log(response.text);

}
await main();

REST

AUDIO_PATH="path/to/sample.mp3"
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D "${tmp_header_file}" \
  -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 "@${AUDIO_PATH}" 2> /dev/null > file_info.json

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

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this audio clip"},
          {"file_data":{"mime_type": "${MIME_TYPE}", "file_uri": '$file_uri'}}]
        }]
      }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

注册 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 控制台中下载账号凭据：

浏览到服务账号控制台
选择相关服务账号
选择密钥标签页，然后选择添加密钥、创建新密钥
选择 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 上

如果您直接在 Google Cloud 中运行（例如使用 Cloud Run 函数或 Compute Engine 实例），则会拥有隐式凭据，但需要重新进行身份验证以授予适当的范围。

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

from google import genai
from google.genai.types import Part

# 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()

registered_gcs_files = client.files.register_files(
    uris=["gs://my_bucket/some_object.pdf", "gs://bucket2/object2.txt"],
    # Use the credentials obtained in the previous step.
    auth=credentials
)
prompt = "Summarize this file."

# call generateContent for each file
for f in registered_gcs_files.files:
  print(f.name)
  response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[Part.from_uri(
      file_uri=f.uri,
      mime_type=f.mime_type,
    ),
    prompt],
  )
  print(response.text)

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 / 签名网址

您可以在生成请求中直接传递可公开访问的 HTTPS 网址或预签名网址（与 S3 预签名网址和 Azure SAS 兼容）。Gemini API 会在处理过程中安全地提取内容。此方法非常适合不想重新上传且大小不超过 100MB 的文件。

您可以使用 file_uri 字段中的网址作为输入，使用公开网址或签名网址。

Python

from google import genai
from google.genai.types import Part

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

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[
        Part.from_uri(
            file_uri=uri,
            mime_type="application/pdf",
        ),
        prompt
    ],
)
print(response.text)

JavaScript

import { GoogleGenAI, createPartFromUri } from '@google/genai';

const client = new GoogleGenAI({});

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

async function main() {
  const response = await client.models.generateContent({
    model: 'gemini-3-flash-preview',
    contents: [
      // equivalent to Part.from_uri(file_uri=uri, mime_type="...")
      createPartFromUri(uri, "application/pdf"),
      "summarize this file",
    ],
  });

  console.log(response.text);
}

main();

REST

curl "https://autopush-generativelanguage.sandbox.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent \
      -H 'x-goog-api-key: $GEMINI_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
          "contents":[
            {
              "parts":[
                {"text": "Summarize this pdf"},
                {
                  "file_data": {
                    "mime_type":"application/pdf",
                    "file_uri": "https://ontheline.trincoll.edu/images/bookdown/sample-local-pdf.pdf"
                  }
                }
              ]
            }
          ]
        }'

无障碍

验证您提供的网址是否不会指向需要登录或付费才能访问的网页。对于私密数据库，请确保您创建的签名网址具有正确的访问权限和到期时间。

安全检查

系统会对网址进行内容审核检查，以确认其符合安全和政策标准（例如，未选择不参与实验且未设置付费墙的内容）。如果您提供的网址未通过此检查，您将获得 URL_RETRIEVAL_STATUS_UNSAFE 的 url_retrieval_status。

支持的内容类型

此支持的文件类型和限制列表仅为初步指南，并不全面。支持的有效类型集可能会发生变化，并且会因所用的具体模型和分词器版本而异。不支持的类型会导致错误。此外，目前仅支持通过可公开访问的网址检索这些文件类型的内容。

文本文件类型

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

应用文件类型

application/json
application/pdf

图片文件类型

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

最佳做法

选择合适的方法：对于小型临时文件，请使用内嵌数据。对于较大或经常使用的文件，请使用 File API。使用已在线托管的数据的外部网址。
指定 MIME 类型：请务必为文件数据提供正确的 MIME 类型，以确保正确处理。
处理错误：在代码中实现错误处理，以管理潜在问题，例如网络故障、文件访问问题或 API 错误。
管理 GCS 权限：使用 GCS 注册时，仅向 Gemini API 服务代理授予特定存储分区的必要 Storage Object Viewer 角色。
签名网址安全性：确保签名网址具有适当的过期时间和有限的权限。

限制

文件大小限制因方法（请参阅对照表）和文件类型而异。
内嵌数据会增加请求载荷大小。
文件 API 上传是临时性的，会在 48 小时后过期。
外部网址提取功能限制为每个载荷 100 MB，并支持特定内容类型。
Google Cloud Storage 注册需要正确的 IAM 设置和 OAuth 令牌管理。

后续步骤

不妨使用 Google AI Studio 尝试自行撰写多模态提示。
如需了解如何在提示中添加文件，请参阅 Vision、Audio 和文档处理指南。
如需获取有关提示设计的更多指导（例如调整采样参数），请参阅提示策略指南。