Herramientasgemini
API de Gemini: primera integración con Python
Aprende a usar la API de Gemini con Python: instala el SDK oficial, envía una petición y procesa la respuesta con un ejemplo de marketing y controles de coste.
- Autor: humAIns
- 9 min de lectura
índice · 6 apartados
La API de Gemini permite que un programa envíe instrucciones a un modelo y reciba una respuesta, por ejemplo para convertir un briefing de campaña en un primer borrador. Con Python, la ruta básica consiste en instalar el SDK oficial de Google, configurar una clave fuera del código y hacer una solicitud desde el servidor. Google AI Studio sirve para gestionar proyectos y probar modelos; no es lo mismo que la API, y disponer de una clave no garantiza que cualquier modelo o volumen sea gratuito.
Antes de empezar: proyecto, modelo y credencial
Necesitas Python, acceso a un proyecto que pueda usar Gemini API y una credencial válida. Google documenta el SDK google-genai y recomienda configurar GEMINI_API_KEY o GOOGLE_API_KEY en el entorno; si están definidas ambas, el cliente da prioridad a GOOGLE_API_KEY. La documentación también describe claves de autorización y estándar, y las condiciones actuales para las claves estándar. Sigue la guía oficial de claves para conocer el tipo que corresponde a tu proyecto.
Una clave autentica solicitudes, pero no selecciona por sí sola el modelo ni concede acceso ilimitado. La interfaz de Google AI Studio permite trabajar con proyectos, claves y pruebas; la API es el servicio que consumirá tu integración. Antes de elegir un modelo revisa la lista vigente de modelos y comprueba su identificador y disponibilidad en tu proyecto. Los nombres y las condiciones cambian, así que no copies un identificador de un tutorial antiguo sin confirmarlo.
Google ofrece modalidades y precios que dependen de modelo y uso. La tabla vigente de precios de Gemini API distingue un nivel gratuito limitado a determinados modelos y un nivel de pago. También describe diferencias en el tratamiento del contenido. No infieras de ello que una cuenta concreta tenga acceso gratuito: revisa los términos que muestra el proyecto y evita mandar información real hasta que tu organización haya validado privacidad y condiciones.
Si todavía necesitas crear o proteger la credencial, sigue nuestra guía sobre API key de Gemini. Allí se trata la creación de la clave; aquí nos centraremos en usar el cliente de Python sin incrustar secretos.
Primera petición de Gemini API con Python
Usa un entorno aislado para no mezclar dependencias de este ejemplo con otros proyectos. Desde el directorio de trabajo, crea y activa un entorno virtual según tu sistema operativo. En un terminal de macOS o Linux, el patrón habitual es:
python -m venv .venv
source .venv/bin/activate
python -m pip install -U google-genai
La instalación del SDK y el ejemplo siguiente siguen el inicio rápido oficial de Google. Configura la variable de entorno en tu sesión o en el gestor de secretos aprobado por tu equipo. En macOS o Linux, el patrón es export GEMINI_API_KEY="tu_clave"; en PowerShell, puedes establecerla para la sesión con $env:GEMINI_API_KEY="tu_clave". No pegues el valor en un archivo Python, en el historial de un comando que vayas a compartir, ni en un repositorio. No imprimas la variable para comprobarla: verifica que existe sin revelar su contenido.
Crea un archivo local primera_peticion.py con este ejemplo:
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Resume en una frase: lanzamiento ficticio de una cafetería de barrio.",
)
print(interaction.output_text)
El identificador de modelo del ejemplo y el método interactions.create aparecen en el inicio rápido consultado el 21 de noviembre de 2026. Antes de ejecutar, confirma que ese modelo sigue disponible para tu proyecto. El cliente detecta la clave en las variables de entorno documentadas; la solicitud envía una instrucción de texto y output_text ofrece el texto de salida. Ejecuta el archivo desde el mismo entorno donde configuraste la variable:
python primera_peticion.py
Si recibes una respuesta, has comprobado el ciclo mínimo: cliente, autenticación, solicitud y lectura del resultado. La salida será texto generado, no una decisión validada ni una publicación lista. Revísala antes de reutilizarla, sobre todo si contiene afirmaciones de producto, fechas o promesas comerciales.
Caso de marketing: del briefing a un borrador revisable
Imagina un briefing enteramente ficticio: una cafetería de barrio quiere anunciar un nuevo café de temporada, dirigirse a personas que trabajan cerca y mantener un tono cercano. Puedes cambiar el valor de input para pedir un esquema útil, sin incorporar datos de clientes:
brief = """
Caso ficticio: cafetería de barrio presenta un café de temporada.
Público: personas que trabajan cerca.
Tono: cercano, sin exageraciones.
Devuelve un borrador con estos apartados:
- idea central
- dos asuntos de correo
- texto breve para redes
No inventes precio, ingredientes ni fechas; marca como pendiente cualquier dato que falte.
"""
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=brief,
)
print(interaction.output_text)
El ejemplo ilustra una tarea, no una capacidad exclusiva del curso ni una garantía de calidad. La instrucción delimita el material de partida y señala qué no debe inventarse. Una persona de marketing aún debe comprobar tono, afirmaciones, derechos de uso y adecuación al canal antes de publicar. Si la respuesta introduce una fecha o un precio ausentes, elimínalos o verifica el dato con una fuente propia.
Para usar la respuesta en un proceso automático quizá necesites campos consistentes. Google documenta salidas estructuradas: se puede proporcionar un esquema JSON y, en los SDK de Google, usar Pydantic en Python para definirlo y validar la respuesta. La compatibilidad concreta depende del modelo y de la interfaz vigente; consulta la documentación antes de implementar ese flujo. Incluso si la salida cumple un esquema y se puede validar como JSON, eso solo comprueba su forma y tipos: no demuestra que el contenido sea cierto, completo o adecuado para la campaña.
Empieza con texto normal si tu necesidad es revisar un borrador. Añade estructura cuando una aplicación realmente necesite campos predecibles, valida los datos recibidos en tu programa y conserva una comprobación humana del contenido antes de activar acciones externas.
Coste, cuotas y errores habituales
Las cuotas no son una bolsa independiente por cada clave. Google aplica límites por proyecto y modelo; entre las dimensiones habituales documentadas están solicitudes por minuto, tokens de entrada por minuto y solicitudes por día. Puede haber otros límites por modelo o función. Los valores activos varían, por lo que no tomes una cifra de ejemplo o de una publicación anterior como compromiso para tu integración.
Ante un 429, registra el modelo, el proyecto, la hora y el mensaje no sensible de la respuesta. Revisa los límites oficiales para identificar qué dimensión se alcanzó. Reduce concurrencia o el tamaño de la entrada y espera antes de reintentar; configura un máximo de intentos y una espera progresiva para evitar llamadas repetidas. Nuestra guía de cuotas de Gemini API amplía el diagnóstico de errores 429.
Un 401 o 403 suele requerir que compruebes credencial, permisos, estado del proyecto y disponibilidad del servicio para tu configuración; consulta el detalle devuelto y la documentación de errores de API. No publiques la clave ni la respuesta completa si contiene contenido privado. Si el problema es el coste, revisa el modelo, el nivel de facturación, los límites activos y la página de precios antes de escalar el uso. Una clave válida no convierte automáticamente todas las solicitudes en gratuitas.
Privacidad y despliegue: protege la credencial
En un desarrollo local, una variable de entorno evita escribir la clave en el código. En producción, utiliza el gestor de secretos que corresponda a tu plataforma y permite que solo el servicio que necesita llamar a Gemini acceda al secreto. No incrustes una credencial en JavaScript enviado al navegador ni en una app móvil distribuida: un usuario podría extraerla. El navegador debe comunicarse con tu servidor, y ese servidor mantiene la credencial fuera del cliente.
Usa texto ficticio durante la prueba. Para datos reales, confirma antes las condiciones aplicables a tu tipo de cuenta, las políticas de tu organización y qué información se permite compartir con el proveedor. La página de precios y niveles describe diferencias de tratamiento entre modalidades, pero no sustituye la revisión legal, contractual o de privacidad de tu caso. Minimiza los datos enviados, anonimiza cuando sea viable y no uses información confidencial de clientes en una cuenta personal.
Si ya trabajas en automatizaciones visuales, puedes comparar esta integración con el flujo de Gemini en n8n. Para aplicar modelos a tareas de comunicación y estrategia, consulta también el curso de IA para marketing: la ficha presenta usos profesionales de marketing, no una promesa de formación en programación o integración de APIs.
Preguntas frecuentes
¿La API de Gemini es gratis?
Hay un nivel gratuito para ciertos modelos y usos, con límites y condiciones. Otros casos pueden requerir facturación. Comprueba el modelo y el proyecto en AI Studio y consulta los precios oficiales; no supongas que tener una API key implica acceso gratuito universal.
¿Necesito una API key?
Sí, las solicitudes deben autenticarse. Gestiona la clave mediante una variable de entorno en pruebas o un gestor de secretos en producción. No la compartas ni la publiques.
¿En qué se diferencia AI Studio de la API?
AI Studio es una interfaz de Google para gestionar proyectos y claves y probar modelos. La API es el servicio al que se conecta el programa para enviar solicitudes. La clave es una credencial, no la interfaz ni el modelo.
¿Qué hago ante un error 429?
Comprueba el código, el mensaje, el modelo y el proyecto; después revisa sus límites activos. Reduce el ritmo o el tamaño de las solicitudes y añade espera progresiva con un máximo de intentos. No cambies de clave suponiendo que eso reiniciará la cuota del proyecto.
¿Puedo enviar datos de clientes?
Solo después de que tu organización compruebe las condiciones de la cuenta y autorice el tratamiento para ese caso. Mientras desarrollas, usa ejemplos ficticios o anonimizados y minimiza la información compartida.