Методы ввода файлов

В этом руководстве описаны различные способы включения медиафайлов, таких как изображения, аудио, видео и документы, при отправке запросов к API Gemini. Новые методы поддерживаются во всех конечных точках API Gemini, включая пакетную обработку, взаимодействие и API в реальном времени. Выбор подходящего метода зависит от размера файла, места хранения данных и частоты использования файла.

Простейший способ включить файл в качестве входных данных — прочитать локальный файл и указать его в командной строке. В следующем примере показано, как прочитать локальный PDF-файл. Для этого метода размер PDF-файлов ограничен 50 МБ. Полный список типов входных файлов и ограничений см. в таблице сравнения методов ввода.

from google import genai
import pathlib

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": filepath.read_bytes(), "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)

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"),
                mimeType: "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();

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

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

Сравнение методов ввода

В следующей таблице сравниваются различные методы ввода данных с учетом ограничений на размер файла и оптимальных сценариев использования. Обратите внимание, что ограничение на размер файла может варьироваться в зависимости от типа файла и модели или токенизатора, используемого для его обработки.

Встроенные данные

Для файлов меньшего размера (менее 100 МБ или 50 МБ для PDF-файлов) данные можно передавать непосредственно в полезной нагрузке запроса. Это самый простой способ для быстрых тестов или приложений, обрабатывающих данные в реальном времени. Данные можно предоставлять в виде строк, закодированных в base64, или путем прямого чтения локальных файлов.

Пример чтения из локального файла можно найти в начале этой страницы.

Получить данные с URL-адреса

Также можно получить файл по URL-адресу, преобразовать его в байты и включить в качестве входных данных.

from google import genai
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"

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "document", "data": doc_data, "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)

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"),
                mimeType: "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();

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 interactions
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3-flash-preview",
      "input": [
        {"type": "document", "data": "'$ENCODED_PDF'", "mimeType": "application/pdf"},
        {"type": "text", "text": "'$PROMPT'"}
      ]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".steps[] | select(.type == \"model_output\") | .content[] | select(.type == \"text\") | .text" response.json

Gemini File API

API для работы с файлами предназначен для файлов больших размеров (до 2 ГБ) или файлов, которые вы планируете использовать в нескольких запросах.

Стандартная загрузка файлов

Загрузите локальный файл в API Gemini. Файлы, загруженные таким образом, хранятся временно (48 часов) и обрабатываются для эффективного извлечения моделью.

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 an interaction
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": prompt},
        {"type": "audio", "uri": audio_file.uri, "mime_type": audio_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)

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

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

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

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

  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
        { type: "text", text: prompt },
        { type: "audio", uri: myfile.uri, mimeType: 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();

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.
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 "@${AUDIO_PATH}" 2> /dev/null > file_info.json

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

# Now use in an interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3-flash-preview",
      "input": [
        {"type": "text", "text": "Describe this audio clip"},
        {"type": "audio", "uri": '$file_uri', "mimeType": "'${MIME_TYPE}'"}
      ]
    }'

Зарегистрируйте файлы в Google Cloud Storage.

Если ваши данные уже находятся в Google Cloud Storage, вам не нужно их скачивать и загружать заново. Вы можете зарегистрировать их напрямую через File API.

1. Доступ агента по предоставлению грантов к каждому разделу

   1. Включите API Gemini в своем проекте Google Cloud.

   2. Создайте агента службы:

      gcloud beta services identity create --service=generativelanguage.googleapis.com --project=<your_project>

   3. Предоставьте агенту службы Gemini API разрешения на чтение ваших хранилищ.

      Пользователю необходимо назначить роль IAM « Storage Object Viewer » этому агенту службы для конкретных сегментов хранилища, которые он планирует использовать.

   Этот доступ по умолчанию не истекает, но его можно изменить в любое время. Вы также можете использовать команды SDK IAM Google Cloud Storage для предоставления разрешений.

2. Подтвердите подлинность вашей услуги.

   Предварительные требования

   • Включить API
   • Создайте учетную запись службы или агента с соответствующими правами доступа.

   Сначала необходимо пройти аутентификацию в качестве службы, имеющей права на просмотр объектов хранилища. Способ аутентификации зависит от среды, в которой будет выполняться ваш код управления файлами.

   Вне облачной среды Google

   Если ваш код выполняется вне 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

   Если вы работаете непосредственно в 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"
   

3. Регистрация файлов (API файлов)

   Используйте Files API для регистрации файлов и создания пути Files API, который можно напрямую использовать в Gemini API.

   Python

   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

   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, mimeType: 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-адреса. API Gemini безопасно получит контент во время обработки. Это идеально подходит для файлов размером до 100 МБ, которые вы не хотите загружать повторно.

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)

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, mimeType: "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();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
      -H 'x-goog-api-key: $GEMINI_API_KEY' \
      -H 'Content-Type: application/json' \
      -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",
              "mimeType": "application/pdf"
            }
          ]
        }'

Доступность

Убедитесь, что предоставленные вами URL-адреса не ведут на страницы, требующие авторизации или находящиеся за платным доступом. Для частных баз данных убедитесь, что вы создали подписанный URL-адрес с правильными правами доступа и сроком действия.

проверки безопасности

Система выполняет проверку модерации контента по URL-адресу, чтобы убедиться в его соответствии стандартам безопасности и политике. Если URL-адрес не проходит эту проверку, вы получите статус url_retrieval_status равный URL_RETRIEVAL_STATUS_UNSAFE .

Поддерживаемые типы контента

Этот список поддерживаемых типов файлов и ограничений предназначен в качестве первоначального руководства и не является исчерпывающим. Фактический набор поддерживаемых типов может изменяться и варьироваться в зависимости от конкретной модели и версии токенизатора. Неподдерживаемые типы приведут к ошибке. Кроме того, получение контента для этих типов файлов поддерживает только общедоступные URL-адреса.

Передовые методы

• Выберите подходящий метод: используйте встроенные данные для небольших, временных файлов. Используйте File API для больших или часто используемых файлов. Используйте внешние URL-адреса для данных, уже размещенных в интернете.
• Укажите MIME-типы: Всегда указывайте правильный MIME-тип для данных файла, чтобы обеспечить корректную обработку.
• Обработка ошибок: Внедрите в свой код обработку ошибок для управления потенциальными проблемами, такими как сбои в сети, проблемы с доступом к файлам или ошибки API.

Ограничения

• Ограничения на размер файлов различаются в зависимости от метода (см. сравнительную таблицу ) и типа файла.
• Встраивание данных увеличивает размер полезной нагрузки запроса.
• Загрузка файлов через File API носит временный характер и истекает через 48 часов.
• Загрузка внешних URL-адресов ограничена 100 МБ на один полезный объем данных и поддерживает определенные типы контента.

Что дальше?

• Попробуйте создать собственные мультимодальные подсказки с помощью Google AI Studio .
• Информацию о включении файлов в ваши запросы см. в руководствах по обработке изображений , аудио и документов .