Métodos de entrada de arquivo

Este guia explica as diferentes maneiras de incluir arquivos de mídia, como imagens, áudio, vídeo e documentos, ao fazer solicitações à API Gemini. Os novos métodos são compatíveis com todos os endpoints da API Gemini, incluindo Batch, Interactions e Live API. A escolha do método certo depende do tamanho do arquivo, de onde os dados estão armazenados e da frequência com que você planeja usar o arquivo.

A maneira mais simples de incluir um arquivo como entrada é ler um arquivo local e incluí-lo em um comando. O exemplo a seguir mostra como ler um arquivo PDF local. Os PDFs são limitados a 50 MB para esse método. Consulte a tabela de comparação de métodos de entrada para uma lista completa de tipos e limites de entrada de arquivos.

Python

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.6-flash",
    input=[
        {"type": "text", "text": prompt},
        {"type": "document", "data": base64.b64encode(filepath.read_bytes()).decode('utf-8'), "mime_type": "application/pdf"}
    ]
)
print(interaction.output_text)

JavaScript

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.6-flash",
        input: [
            { type: "text", text: prompt },
            {
                type: "document",
                data: fs.readFileSync(filePath).toString("base64"),
                mime_type: "application/pdf"
            }
        ]
    });
    console.log(interaction.output_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/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.6-flash",
    "input": [
      {"type": "text", "text": "Summarize this document"},
      {
        "type": "document",
        "data": "'${B64_CONTENT}'",
        "mime_type": "application/pdf"
      }
    ]
  }'

Comparação de métodos de entrada

A tabela a seguir compara cada método de entrada com limites de arquivo e casos de uso recomendados. O limite de tamanho do arquivo pode variar dependendo do tipo de arquivo e do modelo ou tokenizador usado para processar o arquivo.

Método Ideal para Tamanho máximo do arquivo Persistência
Dados inline Testes rápidos, arquivos pequenos, aplicativos em tempo real. 100 MB por solicitação ou payload
(50 MB para PDFs)		 Nenhum (enviado com cada solicitação)
Upload de arquivo da API Arquivos grandes, arquivos usados várias vezes. 2 GB por arquivo,
até 20 GB por projeto		 48 horas
Registro de URI do GCS da API File Arquivos grandes já no Google Cloud Storage, arquivos usados várias vezes. 2 GB por arquivo, sem limites gerais de armazenamento Nenhum (buscado por solicitação). O registro único pode dar acesso por até 30 dias.
URLs externos Dados públicos ou dados em buckets de nuvem (AWS, Azure, GCS) sem fazer o upload novamente. 100 MB por solicitação/payload Nenhum (buscado por solicitação)

Dados inline

Para arquivos menores (menos de 100 MB ou 50 MB para PDFs), é possível transmitir os dados diretamente no payload da solicitação. Esse é o método mais simples para testes rápidos ou aplicativos que processam dados temporários em tempo real. É possível fornecer dados como strings codificadas em base64 ou lendo arquivos locais diretamente.

Para um exemplo de leitura de um arquivo local, consulte o exemplo no início desta página.

Buscar em um URL

Também é possível buscar um arquivo em um URL, convertê-lo em bytes e incluí-lo na entrada.

Python

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.6-flash",
    input=[
        {"type": "document", "data": base64.b64encode(doc_data).decode('utf-8'), "mime_type": "application/pdf"},
        {"type": "text", "text": prompt}
    ]
)
print(interaction.output_text)

JavaScript

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.6-flash",
        input: [
            { type: "text", text: prompt },
            {
                type: "document",