Métodos de entrada de archivos

En esta guía, se explican las diferentes formas en que puedes incluir archivos multimedia, como imágenes, audio, video y documentos, cuando realizas solicitudes a la API de Gemini. Los métodos nuevos son compatibles con todos los extremos de la API de Gemini, incluidas las APIs de Batch, Interactions y Live. Elegir el método correcto depende del tamaño del archivo, de dónde se almacenan los datos y de la frecuencia con la que planeas usar el archivo.

La forma más sencilla de incluir un archivo como entrada es leer un archivo local y agregarlo a una instrucción. En el siguiente ejemplo, se muestra cómo leer un archivo PDF local. Los archivos PDF están limitados a 50 MB para este método. Consulta la tabla de comparación de métodos de entrada para obtener una lista completa de los tipos y límites de entrada de archivos.

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

Comparación de métodos de entrada

En la siguiente tabla, se compara cada método de entrada con los límites de archivos y los casos de uso recomendados. Ten en cuenta que el límite de tamaño de los archivos puede variar según el tipo de archivo y el modelo o tokenizador que se use para procesarlo.

Método Ideal para Tamaño máximo de los archivos Persistencia
Datos intercalados Pruebas rápidas, archivos pequeños y aplicaciones en tiempo real 100 MB por solicitud o carga útil
(50 MB para archivos PDF)		 Ninguna (se envía con cada solicitud)
Carga de archivos de la API Archivos grandes y archivos que se usan varias veces 2 GB por archivo,
hasta 20 GB por proyecto		 48 horas
Registro de URI de GCS de la API de Files Archivos grandes que ya están en Google Cloud Storage y archivos que se usan varias veces 2 GB por archivo, sin límites de almacenamiento generales Ninguna (se recupera por solicitud). El registro único puede otorgar acceso por hasta 30 días.
URLs externas Datos públicos o datos en buckets de la nube (AWS, Azure, GCS) sin volver a subirlos 100 MB por solicitud o carga útil Ninguna (se recupera por solicitud)

Datos intercalados

Para archivos más pequeños (menos de 100 MB o 50 MB para archivos PDF), puedes pasar los datos directamente en la carga útil de la solicitud. Este es el método más sencillo para pruebas rápidas o aplicaciones que manejan datos transitorios en tiempo real. Puedes proporcionar datos como cadenas codificadas en base64 o leyendo archivos locales directamente.

Para ver un ejemplo de lectura desde un archivo local, consulta el ejemplo al comienzo de esta página.

Recupera desde una URL

También puedes recuperar un archivo desde una URL, convertirlo en bytes y agregarlo a la 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",
                data: Buffer.from(pdfResp).toString("base64"),
                mime_type: "application/pdf"
            }
        ]
    });
    console.log(interaction.output_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")

# Create JSON payload file
cat <<EOF > payload.json
{
"model": "gemini-3.6-flash",
"input": [
{"type": "document", "data": "${ENCODED_PDF}", "mime_type": "application/pdf"},
{"type": "text", "text": "${PROMPT}"}
]
}
EOF

# 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 @payload.json 2> /dev/null > response.json

cat response.json
echo

jq ".outputs[] | select(.type == \"text\") | .text" response.json

API de Gemini Files

La API de Files está diseñada para archivos más grandes (hasta 2 GB) o archivos que deseas usar en varias solicitudes.

Carga de archivos estándar

Sube un archivo local a la API de Gemini. Los archivos que se suben de esta manera se almacenan de forma temporal (48 horas) y se procesan para que el modelo los recupere de manera eficiente.

Python

from google import genai

client = genai.Client()

doc_file = client.files.upload(file="path/to/your/sample.pdf")
prompt = "Summarize this document"

interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input=[
        {"type": "text", "text": prompt},
        {"type": "document", "uri": doc_file.uri, "mime_type": doc_file.mime_type}
    ]
)
print(interaction.output_text)

JavaScript

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

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

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

  const myfile = await client.files.upload({
    file: filePath,
    config: { mime_type: "application/pdf" },
  });

  const interaction = await client.interactions.create({
    model: "gemini-3.6-flash",
    input: [
        { type: "text", text: prompt },
        { type: "document", uri: myfile.uri, mime_type: myfile.mimeType }
    ]
  });
  console.log(interaction.output_text);
}

await main();

REST

FILE_PATH="path/to/sample.pdf"
MIME_TYPE=$(file -b --mime-type "${FILE_PATH}")
NUM_BYTES=$(wc -c < "${FILE_PATH}")
DISPLAY_NAME=DOCUMENT

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 "@${FILE_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.6-flash",
      "input": [
        {"type": "text", "text": "Summarize this document"},
        {"type": "document", "uri": '$file_uri', "mime_type": "'${MIME_TYPE}'"}
      ]
    }'

Registra archivos de Google Cloud Storage

Si tus datos ya están en Google Cloud Storage, no es necesario que los descargues y vuelvas a subirlos. Puedes registrarlos directamente con la API de Files.

  1. Otorga acceso al agente de servicio a cada bucket.

    1. Habilita la API de Gemini en tu proyecto de Google Cloud.

    2. Crea el agente de servicio:

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

    3. Otorga permisos al agente de servicio de la API de Gemini para leer tus buckets de almacenamiento.

      El usuario debe asignar el Storage Object Viewer rol de IAM a este agente de servicio en los buckets de almacenamiento específicos que desea usar.

    Este acceso no vence de forma predeterminada, pero se puede cambiar en cualquier momento. También puedes usar los comandos del SDK de IAM de Google Cloud Storage para otorgar permisos.

  2. Autentica tu servicio

    Requisitos previos

    • Habilitar API
    • Crea una cuenta de servicio o un agente con los permisos adecuados.

    Primero, debes autenticarte como el servicio que tiene permisos de visualizador de objetos de almacenamiento. La forma en que esto sucede depende del entorno en el que se ejecutará el código de administración de archivos.

    Fuera de Google Cloud

    Si tu código se ejecuta fuera de Google Cloud, como en tu computadora, descarga las credenciales de la cuenta desde la consola de Google Cloud con los siguientes pasos:

    1. Navega a la consola de cuentas de servicio.
    2. Selecciona la cuenta de servicio pertinente.
    3. Selecciona la pestaña Claves y elige Agregar clave, Crear clave nueva.
    4. Elige el tipo de clave JSON y anota dónde se descargó el archivo en tu máquina.

    Para obtener más detalles, consulta la documentación oficial de Google Cloud sobre la administración de claves de cuentas de servicio.

    Luego, usa los siguientes comandos para autenticarte. Estos comandos suponen que el archivo de tu cuenta de servicio está en el directorio actual y se llama service-account.json.

    Python

    from