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.

Algunas partes de la API de Gemini, como el ajuste de modelos y la recuperación semántica, usan OAuth para la autenticación.

Si eres principiante, debes comenzar usando claves de API y regresar a esta guía de OAuth solo cuando la necesites para estas funciones.

Para ayudarte a comenzar con OAuth, este notebook muestra un enfoque simplificado que es apropiado para un entorno de prueba.

Para un entorno de producción, aprende sobre autenticación y autorización antes de elegir las credenciales de acceso que sean apropiadas para tu app.

Requisitos previos

Para ejecutar esta guía de inicio rápido, necesitas:

• La CLI de Google Cloud instalada en tu máquina local.
• Un proyecto de Google Cloud.

Si creaste una clave de API en Google AI Studio, se creó un proyecto de Google Cloud para ti. Ve a Google AI Studio y anota el nombre del proyecto de Google Cloud para usar ese proyecto.

Configura tu proyecto de Cloud

Para completar esta guía de inicio rápido, primero debes configurar tu proyecto de Cloud.

1. Habilita la API

Antes de usar las API de Google, debes activarlas en un proyecto de Google Cloud.

• En la consola de Google Cloud, habilita la API de Google Generative Language. Si creaste una clave de API en AI Studio, esto ya se hizo por ti.
  

2. Configura la pantalla de consentimiento de OAuth

Luego, configura la pantalla de consentimiento de OAuth del proyecto y añádete como usuario de prueba. Si ya completaste este paso para tu proyecto de Cloud, salta a la siguiente sección.

1. En la consola de Google Cloud, ve a la pantalla de consentimiento de OAuth, que se encuentra en Menú > APIs y servicios > Pantalla de consentimiento de OAuth.

2. Selecciona el tipo de usuario Externo para tu app y luego haz clic en Crear.

3. Completa el formulario de registro de la app (puedes dejar la mayoría de los campos en blanco) y luego haz clic en Guardar y continuar.

4. Por ahora, puedes omitir la adición de alcances y hacer clic en Guardar y continuar. En el futuro, cuando crees una app para usarla fuera de tu organización de Google Workspace, debes añadir y verificar los alcances de autorización que tu app requiere.

5. Añade usuarios de prueba:

   1. En Usuarios de prueba, haz clic en Añadir usuarios.
   2. Ingresa tu dirección de correo electrónico y la de cualquier otro usuario de prueba autorizado, y luego haz clic en Guardar y continuar.

6. Revisa el resumen del registro de tu app. Para hacer cambios, haz clic en Editar. Si el registro de la app se ve bien, haz clic en Volver al panel.

3. Autoriza credenciales para una aplicación de escritorio

Para autenticarte como usuario final y acceder a los datos del usuario en tu app, debes crear uno o más ID de cliente de OAuth 2.0. Un ID de cliente se usa para identificar una sola app en los servidores de OAuth de Google. Si tu app se ejecuta en varias plataformas, debes crear un ID de cliente separado para cada plataforma.

1. En la consola de Google Cloud, ve a Credenciales, que se encuentra en Menú > APIs y servicios > Credenciales.

2. Haz clic en Crear credenciales > ID de cliente de OAuth.

3. Haz clic en Tipo de aplicación > Aplicación de escritorio.

4. En el campo Nombre, escribe un nombre para la credencial. Este nombre solo se muestra en la consola de Google Cloud.

5. Haz clic en Crear. Aparece la pantalla de cliente de OAuth creado, mostrando tu nuevo ID de cliente y secreto de cliente.

6. Haz clic en Aceptar. La credencial recién creada aparece en ID de cliente de OAuth 2.0.

7. Haz clic en el botón de descarga para guardar el archivo JSON. Se guardará como client_secret_<identifier>.json.

Configura las credenciales predeterminadas de la aplicación

En esta guía de inicio rápido, usarás credenciales predeterminadas de la aplicación para autenticarte.

Añade el secreto de cliente a los secretos de Colab

Si necesitas usar OAuth con la API de Gemini en Google Colab con frecuencia, lo más fácil es añadir el contenido de tu archivo client_secret.json al administrador de secretos de Colab.

1. Abre tu notebook de Google Colab y haz clic en la pestaña 🔑 Secretos en el panel izquierdo.
2. Crea un nuevo secreto con el nombre CLIENT_SECRET.
3. Abre tu archivo client_secret.json en un editor de texto y copia/pega el contenido en el cuadro de entrada Value de CLIENT_SECRET.
4. Activa el botón de la izquierda para permitir el acceso del notebook al secreto.

Ahora puedes crear el archivo mediante programación en lugar de subirlo cada vez. El secreto de cliente también está disponible en todos tus notebooks de Google Colab después de que permites el acceso.

from google.colab import userdata
import pathlib
pathlib.Path('client_secret.json').write_text(userdata.get('CLIENT_SECRET'))

413

Establece las credenciales predeterminadas de la aplicación

Para convertir el archivo client_secret.json en credenciales utilizables, pasa su ubicación al argumento --client-id-file del comando gcloud auth application-default login.

La configuración simplificada del proyecto en este tutorial activa un cuadro de diálogo que dice Google no ha verificado esta app. Esto es normal, elige Continuar.

Deberás hacer este paso una vez por cada nuevo notebook o entorno de ejecución de Google Colab.

Nota: Sigue cuidadosamente las instrucciones que imprime el siguiente comando (no solo hagas clic en el enlace). También asegúrate de que tu gcloud --version local sea la versión más reciente para que coincida con la versión preinstalada en Google Colab.

!gcloud auth application-default login \
  --no-browser --client-id-file client_secret.json \
  --scopes https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language.tuning,https://www.googleapis.com/auth/generative-language.retriever

El scopes específico que necesitas depende de la API que estés usando. Por ejemplo, al mirar la referencia de la API para tunedModels.create, verás:

Requiere uno de los siguientes alcances de OAuth:

• https://www.googleapis.com/auth/generative-language.tuning

Esta muestra solicita todos los alcances para el ajuste y la recuperación semántica, pero la mejor práctica es usar el conjunto más pequeño de alcances para la seguridad y la confianza del usuario.

Uso del SDK de Python con OAuth

El SDK de Python encontrará y usará automáticamente las credenciales predeterminadas de la aplicación.

%pip install -U -q google-genai

     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 137.4/137.4 kB 2.7 MB/s eta 0:00:00a 0:00:01
[?25h

Hagamos una prueba rápida. ¡Ten en cuenta que no configuraste una clave de API usando genai.configure()!

from google import genai

client = genai.Client()
print("Available base models:", [m.name for m in client.models.list()])

Apéndice

Realización de llamadas REST autenticadas desde Colab

En general, debes usar el SDK de Python para interactuar con la API de Gemini cuando sea posible. Este ejemplo muestra cómo hacer llamadas REST autenticadas con OAuth desde Python para fines de depuración o prueba. Asume que ya configuraste las credenciales predeterminadas de la aplicación desde la guía de inicio rápido.

import requests

access_token = !gcloud auth application-default print-access-token

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token[0]}',
}

response = requests.get('https://generativelanguage.googleapis.com/v1/models', headers=headers)
response_json = response.json()

# All the model names
for model in response_json['models']:
    print(model['name'])

Comparte un modelo ajustado

Algunas funciones de la API beta pueden no ser compatibles con el SDK de Python todavía. Este ejemplo muestra cómo hacer una llamada REST para añadir un permiso a un modelo ajustado desde Python.

import requests

model_name = ''   # @param {type:"string"}
emailAddress = '' # @param {type:"string"}


access_token = !gcloud auth application-default print-access-token

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token[0]}',
}

body = {
  'granteeType': 'USER',        # Or 'GROUP' or 'EVERYONE' https://ai.google.dev/api/rest/v1beta/tunedModels.permissions
  'emailAddress': emailAddress, # Optional if 'granteeType': 'EVERYONE'
  'role': 'READER'
}

response = requests.post(f'https://generativelanguage.googleapis.com/v1beta/tunedModels/{model_name}/permissions', json=body, headers=headers)
print(response.json())

Usa una cuenta de servicio para autenticarte

Las cuentas de servicio de Google Cloud son cuentas que no representan a un usuario humano. Proporcionan una forma de gestionar la autenticación y la autorización cuando un humano no está directamente involucrado, como tu aplicación llamando a la API de Gemini para cumplir una solicitud de usuario, pero no autenticada como el usuario. Una forma sencilla de usar cuentas de servicio para autenticarse con la API de Gemini es usar una clave de cuenta de servicio.

Esta guía cubre brevemente cómo usar claves de cuenta de servicio en Google Colab.

Importante: ¡Las claves de cuenta de servicio pueden ser un riesgo de seguridad! Para obtener más información, consulta las mejores prácticas para gestionar claves de cuenta de servicio.

1. Crea una cuenta de servicio

Sigue las instrucciones para crear una cuenta de servicio. Las instrucciones de la Consola son las más fáciles si lo haces manualmente.

2. Crea una clave de cuenta de servicio

Sigue las instrucciones para crear una clave de cuenta de servicio. Anota el nombre de la clave descargada.

3. Añade la clave de cuenta de servicio a Colab

1. Abre tu notebook de Google Colab y haz clic en la pestaña 🔑 Secretos en el panel izquierdo.
2. Crea un nuevo secreto con el nombre SERVICE_ACCOUNT_KEY.
3. Abre tu archivo de clave de cuenta de servicio en un editor de texto y copia/pega el contenido en el cuadro de entrada Value de SERVICE_ACCOUNT_KEY.
4. Activa el botón de la izquierda para permitir el acceso del notebook al secreto.

4. Autentícate con el SDK de Python mediante una clave de cuenta de servicio

import pathlib
from google import genai
from google.colab import userdata
from google.oauth2 import service_account

pathlib.Path("service_account_key.json").write_text(userdata.get("SERVICE_ACCOUNT_KEY"))

credentials = service_account.Credentials.from_service_account_file("service_account_key.json")

# Adjust scopes as needed
scoped_credentials = credentials.with_scopes(
    ["https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/generative-language.retriever"]
)

client = genai.Client(credentials=scoped_credentials)
print("Available base models:", [m.name for m in client.models.list()])