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

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

Простейший способ включить файл в качестве входных данных — прочитать локальный файл и указать его в командной строке. В следующем примере показано, как прочитать локальный 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-flash-preview",
  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-flash-preview",
        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-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 МБ или 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-flash-preview",
  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-flash-preview",
        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-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

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 a prompt
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    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-flash-preview",
    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-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. Доступ агента по предоставлению грантов к каждому разделу

   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
   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 / Подписанные URL-адреса

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

В качестве входных данных можно использовать общедоступные или подписанные 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-flash-preview",
    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-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();

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-адреса не ведут на страницы, требующие авторизации или находящиеся за платным доступом. Для частных баз данных убедитесь, что вы создали подписанный URL-адрес с правильными правами доступа и сроком действия.

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

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

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

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

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

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

Ограничения

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

Что дальше?

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