Способы ввода файлов

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

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

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.8-flash",
  contents=[
      types.Part.from_bytes(
        data=filepath.read_bytes(),
        mime_type='application/pdf',
      ),
      prompt
  ]
)
print(response.text)

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.8-flash",
        contents: contents
    });
    console.log(response.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/models/gemini-3.8-flash: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 МБ (или 50 МБ для PDF-файлов), вы можете передать данные непосредственно в полезной нагрузке запроса. Это самый простой способ для быстрого тестирования или приложений, обрабатывающих временные данные в реальном времени. Вы можете предоставить данные в виде строк, закодированных в формате base64, или напрямую из локальных файлов.

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

Получение данных с URL

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

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.8-flash",
  contents=[
      types.Part.from_bytes(
        data=doc_data,
        mime_type='application/pdf',
      ),
      prompt
  ]
)
print(response.text)

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.8-flash",
        contents: contents
    });
    console.log(response.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 the base64 encoded PDF
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash: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

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

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

Загрузите локальный файл в Gemini API. Загруженные таким образом файлы хранятся временно (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 a prompt
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[prompt, audio_file]
)
print(response.text)

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.8-flash",
    contents: createUserContent([
      prompt,
      createPartFromUri(myfile.uri, myfile.mimeType),
    ]),
  });
  console.log(response.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.
# 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.8-flash: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. Предоставьте агенту сервиса доступ к каждому сегменту.

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

   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, чтобы предоставлять разрешения.

2. Как пройти аутентификацию в сервисе

   Требования

   • Включить 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
   });
   

   ИКС

   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

   Этот код предполагает, что сервис работает в среде, где Application Default Credentials можно получить автоматически, например в 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

   Этот код предполагает, что сервис работает в среде, где Application Default Credentials можно получить автоматически, например в 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'
     ]
   });
   

   ИКС

   Это интерактивная команда. Для таких сервисов, как Compute Engine, области действия можно прикрепить к работающему сервису на уровне конфигурации. Пример можно найти в документации по сервису, управляемому пользователем.

   gcloud auth application-default login \
   --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"
   

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

   Используйте Files API, чтобы зарегистрировать файлы и создать путь Files API, который можно напрямую использовать в Gemini 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.8-flash",
       contents=[Part.from_uri(
         file_uri=f.uri,
         mime_type=f.mime_type,
       ),
       prompt],
     )
     print(response.text)
   

   ИКС

   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"]}'
   

Внешние URL HTTP / подписанные URL

Вы можете передавать общедоступные URL с протоколом HTTPS или предварительно подписанные URL (совместимые с предварительно подписанными URL S3 и SAS Azure) непосредственно в запросе на создание. Gemini API будет безопасно получать контент во время обработки. Это удобно, если вы не хотите загружать файлы повторно. Размер каждого файла не должен превышать 15 МБ. Для больших файлов используйте File API.

Вы можете использовать общедоступные или подписанные URL в качестве входных данных, указав их в поле file_uri.

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.8-flash",
    contents=[
        Part.from_uri(
            file_uri=uri,
            mime_type="application/pdf",
        ),
        prompt
    ],
)
print(response.text)

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.8-flash',
    contents: [
      // equivalent to Part.from_uri(file_uri=uri, mime_type="...")
      createPartFromUri(uri, "application/pdf"),
      "summarize this file",
    ],
  });

  console.log(response.text);
}

main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash: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, которые вы предоставляете, не ведут на страницы, требующие авторизации или платного доступа. Для частных баз данных создайте подписанный 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

Видеофайлы

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

Рекомендации

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

Ограничения

• Максимальный размер файла зависит от способа загрузки (см. сравнительную таблицу) и типа файла.
• Встроенные данные увеличивают размер полезной нагрузки запроса.
• Загруженные через File API файлы хранятся временно и удаляются через 48 часов.
• Извлечение данных из внешних URL ограничено 15 МБ на файл и поддерживает определенные типы контента.
• Для регистрации в Google Cloud Storage требуется правильная настройка IAM и управление токенами OAuth.

Дальнейшие действия

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