Lección 12 · 5 min · Gratis

Usa la API de Archivos para subir y usar archivos multimedia

Copyright 2026 Google LLC.

# @title Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

La API de Gemini admite prompts con datos de texto, imagen y audio, también conocidos como prompts multimodales. Puedes incluir texto, imágenes y audio en tus prompts. Para imágenes pequeñas, puedes apuntar el modelo Gemini directamente a un archivo local al proporcionar un prompt. Para archivos de texto, imágenes, videos y audio más grandes, sube los archivos con la API de Archivos antes de incluirlos en los prompts.

La API de Archivos te permite almacenar hasta 20 GB de archivos por proyecto, sin que cada archivo exceda los 2 GB de tamaño. Los archivos se almacenan durante 48 horas y se puede acceder a ellos con tu clave de API para la generación dentro de ese período de tiempo. Está disponible sin costo en todas las regiones donde la API de Gemini está disponible.

Para obtener información sobre formatos de archivo válidos (tipos MIME) y modelos compatibles, consulta la documentación sobre formatos de archivo compatibles y consulta los ejemplos de texto al final de esta guía.

Esta guía muestra cómo usar la API de Archivos para subir un archivo multimedia e incluirlo en una llamada GenerateContent a la API de Gemini. Para obtener más información, consulta los ejemplos de código.

Nota: Este notebook usa la API de Interacciones, la forma más reciente de interactuar con los modelos Gemini. ¿Buscas la versión generateContent? Consulta la rama de archivo.

Instalar dependencias

%pip install -U -q "google-genai>=2.9.0"  # 1.57 for File API features # 2.0 is needed to use the interactions API

Autenticación

Importante: La API de Archivos usa claves de API para la autenticación y el acceso. Los archivos subidos se asocian con el proyecto de la nube de la clave de API. Tu clave de API debe almacenarse en un Secreto de Colab llamado GEMINI_API_KEY.

Configura tu clave de API

Para ejecutar la siguiente celda, tu clave de API debe almacenarse en un Secreto de Colab llamado GEMINI_API_KEY. Si aún no tienes una clave de API, o no estás seguro de cómo crear un Secreto de Colab, consulta Autenticación para ver un tutorial.

from google import genai
from google.colab import userdata

GEMINI_API_KEY = userdata.get("GEMINI_API_KEY")
client = genai.Client(api_key=GEMINI_API_KEY)

Subir archivo

La API de Archivos te permite subir una variedad de tipos MIME multimodales, incluidos formatos de imagen y audio. La API de Archivos maneja entradas que se pueden usar para generar contenido con client.interactions.create (o client.models.generate_content).

La API de Archivos acepta archivos de menos de 2 GB de tamaño y puede almacenar hasta 20 GB de archivos por proyecto. Los archivos duran 2 días y no se pueden descargar desde la API.

Primero, prepararás una imagen de muestra para subir a la API.

Nota: También puedes subir tus propios archivos para usar.

from IPython.display import Image, display
import urllib.request

urllib.request.urlretrieve(
    "https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg",
    "image.jpg"
)
display(Image(filename="image.jpg"))

<IPython.core.display.Image object>

A continuación, subirás ese archivo a la API de Archivos.

sample_file = client.files.upload(file="image.jpg")

print(f"Uploaded file '{sample_file.name}' as: {sample_file.uri}")

Uploaded file 'files/zyg60km4wauf' as: https://generativelanguage.googleapis.com/v1beta/files/zyg60km4wauf

El response muestra que la API de Archivos almacenó el display_name especificado para el archivo subido y un uri para referenciar el archivo en las llamadas a la API de Gemini. Usa response para rastrear cómo los archivos subidos se mapean a URIs.

Dependiendo de tus casos de uso, podrías almacenar los URIs en estructuras como un dict o una base de datos.

Obtener archivo

Después de subir el archivo, puedes verificar que la API haya recibido los archivos correctamente llamando a files.get.

Te permite obtener los metadatos de los archivos que se han subido a la API de Archivos que están asociados con el proyecto de Cloud al que pertenece tu clave de API. Solo el name (y por extensión, el uri) son únicos. Solo usa el displayName para identificar archivos si tú mismo gestionas la unicidad.

file = client.files.get(name=sample_file.name)
print(f"Retrieved file '{file.name}' as: {sample_file.uri}")

Retrieved file 'files/zyg60km4wauf' as: https://generativelanguage.googleapis.com/v1beta/files/zyg60km4wauf

Generar contenido

Después de subir el archivo, puedes hacer solicitudes interactions.create que hagan referencia al URI de la API de Archivos.

MODEL_ID = "gemini-3.7-flash"  # @param ["gemini-3.1-pro-preview", "gemini-3.7-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input":true, isTemplate: true}
interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "text", "text": "Describe the image with a creative description."},
        {"type": "document", "uri": sample_file.uri},
    ],
)

print(interaction.steps[-1].content[0].text)

In the humble margins of a blue-lined notebook, a revolution in student transit is taking shape. This hand-drawn blueprint, rendered in confident strokes of ballpoint blue ink, reveals the "Jetpack Backpack"—the ultimate "sleeper" accessory for the modern commuter.

At first glance, it poses as a standard, lightweight rucksack, complete with comfortable padded straps and enough room to swallow a massive 18-inch laptop. But look closer at the base, where the mundane meets the miraculous. A pair of retractable boosters are deployed, exhaling whimsical, swirling plumes of steam. This isn’t just a bag; it’s a clean, green flying machine designed to turn a ten-minute trek across campus into a thirty-second aerial sprint.

The sketch captures the delightful tension between futuristic ambition and practical reality. While it boasts high-tech features like USB-C charging and eco-friendly propulsion, the inventor remains grounded, noting an endearingly honest fifteen-minute battery life—just enough time to soar over morning traffic before needing a quick plug-in at the back of the lecture hall. It is a doodle of pure inspiration, where the dream of flight is tucked neatly behind a laptop sleeve.

Múltiples archivos

A menudo querrás subir varios archivos a la vez. Aquí tienes un ejemplo rápido de cómo puedes hacerlo:

!git clone -q --depth 1 https://github.com/googleapis/python-genai

import pathlib

files = []
for p in pathlib.Path("python-genai").rglob('*.py'):
  if 'test' in str(p):
    continue
  f = client.files.upload(file=p, config={'display_name': str(p)})
  # The API doesn't see the file name, so add those to the list of parts.
  files.append(f"<<<File: {str(p)}>>>")
  files.append(f)
  print('.', end='')

....................................................................................................................................................................................

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "text", "text": "Hi, could you give me a summary of this code base?"},
    ] + [{"type": "document", "uri": f.uri} for f in files],
)

print(interaction.steps[-1].content[0].text)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "File_API.ipynb:cell_23", line 5, in <module>
AttributeError: 'str' object has no attribute 'uri'

Usar archivos de Google Cloud Storage

La API de Gemini admite el acceso a objetos almacenados en Google Cloud Storage (GCS). Como los objetos de GCS tienen un modelo de seguridad diferente al de la API de Gemini, primero debes registrar los archivos antes de poder usarlos.

Para registrar un objeto de GCS para usarlo en la API de Archivos, debes autenticarte con una identidad que tenga permisos de Storage Object Viewer y con el ámbito de OAuth apropiado habilitado. El mecanismo varía según el entorno; por ejemplo, puedes descargar credenciales de cuenta de servicio para usar en tu propia infraestructura, o ejecutar en una instancia de Compute Engine que tenga una cuenta de servicio configurada.

Para este notebook, configurarás tus credenciales de usuario a través de gcloud.

# Use the same project ID you're using for the Gemini API project
PROJECT_ID = "your-project-id"  # @param {type: "string"}

!gcloud config set project {PROJECT_ID}
!gcloud auth application-default login --no-launch-browser --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"

^^^^^^^^^^^^^^^^^^
  File "File_API.ipynb:cell_25", line 5
    os.system("""gcloud auth application-default login --no-launch-browser --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/devstorage.read_only"""")
                                                                                                                                                                                           ^
SyntaxError: unterminated string literal (detected at line 5)

Ahora recupera tus credenciales y registra tus objetos.

Nota: Si estás registrando archivos por separado de tu código de generación, deberás crear un objeto genai.Client inicializado con una clave de API. La clave de API no es utilizada por este método, pero aún es necesaria para asegurar que el cliente no esté conectado al backend de Vertex AI.

Sube archivos a un bucket en el proyecto que estás usando: https://docs.cloud.google.com/storage/docs/uploading-objects. Luego obtén los URIs y registra los archivos:

import google.auth

credentials, project_id = google.auth.default()

registered_gcs_files = client.files.register_files(
    auth=credentials,
    uris=["gs://your-bucket/some-file.pdf"]
)

ookbook-agentB-interactions/.venv/lib/python3.13/site-packages/google/auth/_agent_identity_utils.py", line 122, in get_agent_identity_certificate_path
    raise exceptions.RefreshError(
    ...<4 lines>...
    )
google.auth.exceptions.RefreshError: Certificate config or certificate file not found after multiple retries. Token binding protection is failing. You can turn off this protection by setting GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES to false to fall back to unbound tokens.

El endpoint register_files devuelve los archivos asociados con los URIs proporcionados. Luego puedes usarlos directamente en tu prompt con generate_content, o almacenar los name para usarlos más tarde.

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "text", "text": "What are these documents about?"},
    ] + [{"type": "document", "uri": f.uri} for f in registered_gcs_files.files],
)

print(interaction.steps[-1].content[0].text)

Traceback (most recent call last):
  File "/tmp/execute_notebook.py", line 103, in execute_notebook
    result = exec(compile(prepared, f"{name}:cell_{i}", 'exec'), ns)
  File "File_API.ipynb:cell_29", line 5, in <module>
NameError: name 'registered_gcs_files' is not defined

Eliminar archivos

Los archivos se eliminan automáticamente después de 2 días o puedes eliminarlos manualmente usando files.delete().

client.files.delete(name=sample_file.name)
print(f"Deleted {sample_file.name}.")

Deleted files/zyg60km4wauf.

Tipos de texto compatibles

Además de admitir la carga de medios, la API de Archivos se puede usar para incrustar archivos de texto, como código Python o archivos Markdown, en tus prompts.

Este ejemplo te muestra cómo cargar un archivo markdown en un prompt usando la API de Archivos.

# Download a markdown file and ask a question.
from IPython.display import Markdown, display
import urllib.request

urllib.request.urlretrieve(
    "https://raw.githubusercontent.com/google-gemini/cookbook/main/CONTRIBUTING.md",
    "contrib.md"
)

md_file = client.files.upload(
    file="contrib.md",
    config={
        "display_name": "CONTRIBUTING.md",
    },
)

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "document", "uri": md_file.uri},
        {"type": "text", "text": "Summarize this document in a few sentences."},
    ],
)
display(Markdown(interaction.steps[-1].content[0].text))

<IPython.core.display.Markdown object>

Algunos formatos de texto comunes se detectan automáticamente, como text/x-python, text/html y text/markdown. Si estás usando un archivo que sabes que es texto, pero la API no lo detecta automáticamente como tal, puedes especificar el tipo MIME como text/plain explícitamente.

# Download some C++ code and force the MIME as text when uploading.
import urllib.request
from IPython.display import Markdown, display

urllib.request.urlretrieve(
    "https://raw.githubusercontent.com/google/gemma.cpp/main/examples/hello_world/run.cc",
    "gemma.cpp"
)

cpp_file = client.files.upload(
    file="gemma.cpp",
    config={
        "display_name":"gemma.cpp",
        "mime_type":"text/plain"
    }
)

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "document", "uri": cpp_file.uri},
        {"type": "text", "text": "Explain this code and identify any potential bugs."},
    ],
)
display(Markdown(interaction.steps[-1].content[0].text))

<IPython.core.display.Markdown object>

Archivos externos y URLs

Además de la API de Archivos, puedes proporcionar algunas URLs directamente a la API de Gemini, incluidas URLs HTTPS públicas y URLs firmadas de contenido en plataformas de almacenamiento en la nube.

URLs HTTPS directas

Siempre que las URLs sean públicas, no estén detrás de un muro de pago y contengan un tipo de archivo compatible, puedes agregarlas a tu prompt y la API descargará el contenido mientras procesa el prompt.

MODEL_ID = "gemini-3.7-flash"  # @param ["gemini-3.1-pro-preview", "gemini-3.7-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input":true, isTemplate: true}
interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "text", "text": "Describe the image with a creative description."},
        {"type": "image", "uri": "https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg"},
    ],
)

print(interaction.steps[-1].content[0].text)

        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/google/home/giom/.gemini/jetski/scratch/cookbook-agentB-interactions/.venv/lib/python3.13/site-packages/google/genai/_interactions/_base_client.py", line 1080, in request
    raise self._make_status_error_from_response(err.response) from None
google.genai._interactions.RateLimitError: Error code: 429 - {'error': {'message': 'Resource has been exhausted (e.g. check quota).', 'code': 'too_many_requests'}}

URLs firmadas

Si tus datos están almacenados en un sistema de almacenamiento en la nube privado, como S3 o Azure Blob Storage, puedes generar una URL firmada y pasarla a la API de Gemini para usarla directamente, lo que te evita descargar el archivo de tu propio almacenamiento y gestionar su ciclo de vida en otra plataforma.

Las URLs se solicitan cada vez que se usan, por lo que revocar el acceso en la plataforma anfitriona asegurará que el contenido no esté disponible a través de una solicitud no almacenada en caché de la API de Gemini.

El siguiente código demuestra cómo firmar un objeto S3. Consulta la documentación de tu proveedor específico para aprender cómo firmar tus objetos específicos.

# pip install boto3

import boto3

s3 = boto3.client('s3')
signed_url = s3.generate_presigned_url(
    'get_object',
    Params={
      # Set your bucket name here.
      'Bucket': 'my-bucket-name',
      # And the path to the object here.
      'Key': 'document.pdf'
    },
    ExpiresIn=3600  # In seconds
)

MODEL_ID = "gemini-3.7-flash"  # @param ["gemini-3.1-pro-preview", "gemini-3.7-flash", "gemini-3.5-flash-lite", "gemini-2.5-pro"] {"allow-input":true, isTemplate: true}
# Obtain the signed URL from your provider, or see the S3
# example code above.
signed_url = "https://..."  # @param {type: "string"}

interaction = client.interactions.create(
    model=MODEL_ID,
    input=[
        {"type": "text", "text": "Summarise this document."},
        {"type": "document", "uri": signed_url},
    ],
)

print(interaction.steps[-1].content[0].text)

             ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/google/home/giom/.gemini/jetski/scratch/cookbook-agentB-interactions/.venv/lib/python3.13/site-packages/google/genai/_interactions/_base_client.py", line 1080, in request
    raise self._make_status_error_from_response(err.response) from None
google.genai._interactions.BadRequestError: Error code: 400 - {'error': {'message': 'Cannot fetch content from the provided URL.', 'code': 'invalid_request'}}

Próximos pasos

Referencias útiles de la API:

Para obtener más información sobre la API de Archivos, consulta su referencia de la API. También encontrarás más ejemplos de código en esta carpeta.

Ejemplos relacionados

Consulta estos ejemplos que usan la API de Archivos para darte más ideas sobre cómo usar esta característica tan útil:

Comparte notas de voz con la API de Gemini y haz una lluvia de ideas
Analiza videos para clasificarlos o resumirlos

Continúa tu descubrimiento de la API de Gemini

Si aún no estás familiarizado con ella, aprende cómo se cuentan los tokens. Luego, consulta cómo usar la API de Archivos para usar archivos de audio o video con la API de Gemini.

Lección del curso «Gemini API Cookbook (quickstarts)» de Google, publicado con licencia Apache 2.0. Traducción y adaptación al español de IA con Clase. IA con Clase no está afiliado a Google. Ver el original · Licencia

Esta lección es gratuita. El resto del curso se abre con la Membresía de IA con Clase, que incluye todos los cursos del catálogo. Ver precios

← Anterior Siguiente: Búsqueda de archivos con Gemini →