Flujo de trabajo arquitectónico con Gemini API: primera solicitud de texto en Python

¿Qué aprenderás en este tutorial?

Esta guía está dirigida a equipos de arquitectura, diseño de interiores y visualización que quieran enviar su primera solicitud de texto a Gemini API desde Python. Mostraremos cómo crear un prompt con la interfaz Interactions API de Google, leer la respuesta de texto y recibirla en streaming. Los ejemplos se centran en tareas de texto que pueden surgir durante el proceso de diseño, como pedir sugerencias para el salón de una vivienda pequeña o prepararse para una reunión sobre el concepto de una cafetería.

Los ejemplos de código de este tutorial están preparados para obtener respuestas de texto. Gemini API no se limita a eso: la guía de inicio de Google también incluye entre los temas que se pueden abordar con la API la comprensión multimodal, la generación de imágenes, las salidas estructuradas y el uso de herramientas. Sin embargo, las respuestas de texto mostradas aquí no sustituyen los planos, los renders ni la validación técnica; el equipo debe revisar las decisiones del proyecto.

Requisitos: cuenta, clave y software

Para empezar, obtén una clave de API en Google AI Studio. Según la guía de Google, AI Studio puede crear automáticamente un proyecto y una clave para los nuevos usuarios; quienes ya tienen una cuenta pueden crear una nueva combinación de clave y proyecto desde la página de claves de API. También se indica que los proyectos adicionales importados desde Google Cloud pueden requerir verificación para utilizar el nivel gratuito.

En este tutorial se utiliza el SDK de Python. El comando de instalación que aparece en la fuente instala o actualiza el paquete google-genai. Como la guía no especifica un requisito de versión de Python, aquí no se establece ninguna condición adicional sobre la versión. En lugar de escribir la clave de API directamente en el código fuente, defínela como variable de entorno:

export GEMINI_API_KEY="YOUR_API_KEY"

Sustituye YOUR_API_KEY por tu propia clave. Este comando define la clave con el nombre GEMINI_API_KEY en el entorno donde se ejecuta. Para mantener el acceso bajo control, es importante no incluirla en repositorios de código públicos ni en archivos accesibles para personas ajenas al equipo.

Quienes quieran pasar al nivel de pago deben configurar Cloud Billing, añadir un método de pago y realizar un prepago de al menos 5 dólares o su equivalente en créditos de pago. Google indica que el nivel de pago aumenta los límites de velocidad. Puedes consultar el uso de la API en la pantalla de uso de Google AI Studio.

Envía tu primera solicitud paso a paso

1. Instala el SDK. Ejecuta el siguiente comando en tu entorno de Python:

pip install -U google-genai

El comando instala el paquete google-genai mediante pip o actualiza la instalación existente. Si utilizas varios entornos de Python, asegúrate de ejecutar el comando en el entorno donde se ejecutará el código.

1. Prepara la primera solicitud de texto. Añade el siguiente ejemplo a un archivo de Python. El prompt pide recomendaciones por escrito para el salón de una vivienda pequeña:

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Küçük bir konut salonu için gün ışığını ve dolaşımı gözeten üç tasarım önerisi yaz. Her öneride tasarım kararını ve gerekçesini belirt."
)
print(interaction.output_text)

La solicitud se envía al modelo gemini-3.8-flash mediante la Interactions API; en el ejemplo, el resultado se muestra en pantalla con interaction.output_text. Puedes adaptar el texto del prompt a la tarea concreta de tu flujo de trabajo. Por ejemplo, puedes pedir una descripción conceptual para una presentación, un borrador que compare opciones de materiales o una lista de preguntas para una reunión con el cliente. Describir con claridad el alcance y el formato esperados facilita la evaluación del texto recibido.

1. Ajusta el prompt al contexto del proyecto. En lugar de dar una instrucción genérica, especifica el tipo de espacio y el resultado que necesitas. El siguiente ejemplo es un prompt original preparado para organizar una reunión de diseño de interiores:

Bir kafe iç mekânı için konsept geliştirme toplantısına hazırlanıyorum. Tasarım ekibinin tartışması için üç farklı atmosfer yönü öner. Her yönü kısa bir başlık, mekânsal yaklaşım ve müşteriye sorulacak iki net soruyla açıkla. Proje verisi verilmediğinde varsayım üretme; eksik bilgileri ayrıca belirt.

Este prompt solicita un borrador escrito para debatir en una reunión, no un resultado visual o técnico. Pedir que se indiquen por separado los datos desconocidos puede ayudar a evitar que la respuesta se confunda con información del proyecto; aun así, el equipo debe revisar el texto generado.

1. Recibe la respuesta en streaming. Si la aplicación necesita procesar la respuesta por partes mientras se genera, puedes utilizar stream=True en la solicitud. El siguiente ejemplo recorre los eventos devueltos por la API y los muestra en pantalla:

from google import genai

client = genai.Client()
stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Bir mimari konsept sunumu için kısa bir açılış metni yaz.",
    stream=True
)
for event in stream:
    print(event)

Al usar el streaming, la respuesta llega en forma de eventos en lugar de recibirse como un único texto. La guía de Google explica que los eventos step.delta pueden contener fragmentos de texto mientras se genera la respuesta. En este ejemplo, cada evento se imprime directamente; al desarrollar una aplicación, también habrá que decidir cómo se mostrarán al usuario.

Uso en flujos de trabajo de arquitectura y visualización

Estos ejemplos pueden servir como punto de partida para tareas centradas en texto, como preparar descripciones conceptuales, generar preguntas que ayuden a definir el orden del día de una reunión, comparar por escrito distintas opciones de diseño y redactar textos para presentaciones. Un equipo puede elegir una tarea recurrente y bien delimitada para evaluar cuánto trabajo de edición requieren los resultados. Este enfoque no permite sacar conclusiones sobre la capacidad de la API para generar imágenes o validar proyectos; solo sirve para comprobar si las solicitudes de texto mostradas aquí se adaptan al flujo de trabajo.

Estos ejemplos no miden el rendimiento de renderizado local de una estación de trabajo. Como la fuente no especifica requisitos de GPU ni recomendaciones de hardware para este uso, no conviene decidir si es necesario actualizar el equipo basándose en ellos. En cuanto a la cuenta, es importante gestionar la clave de API, supervisar el uso y, si corresponde, evaluar el coste del nivel de pago. Para pasar al uso de pago se necesitan Cloud Billing y un prepago; conviene definir de antemano quién será responsable del uso y del seguimiento del presupuesto.

Errores frecuentes y próximos pasos

• La clave no está definida: ejecuta el archivo de Python desde el entorno donde está definida la variable GEMINI_API_KEY.

• El paquete se instaló en otro entorno: comprueba que el entorno de Python que ejecuta el código tenga instalado google-genai.

• El prompt es demasiado genérico: especifica el tipo de espacio, el propósito del texto solicitado y el formato de la respuesta.

• Considerar la respuesta como información aprobada del proyecto: no tomes el texto como una decisión de diseño ni como una validación técnica; debe revisarlo el equipo.

• Iniciar el uso de pago sin planificación: revisa los requisitos de Cloud Billing y del prepago antes de pasar al uso de pago.

Cuando funcione tu primera solicitud, en vez de crear de inmediato una automatización compleja, elige una tarea de texto frecuente y bien delimitada dentro del equipo. Mejora el prompt poco a poco y haz seguimiento de la utilidad de los resultados, las correcciones necesarias y el uso de la API. La guía de Google también explica el uso de los SDK para desarrollar aplicaciones y la opción Gemini API CLI para que un script o una tarea de línea de comandos realice llamadas directas a la API. En este tutorial, los ejemplos de código se limitan al SDK de Python y a la Interactions API.

Fuente y licencia

Este tutorial se ha adaptado al turco a partir de la guía “Getting started” (K1), publicada por Google para Gemini API. La fuente se publica bajo la licencia CC BY 4.0. Los prompts de ejemplo centrados en arquitectura y diseño de interiores se han creado específicamente para este tutorial.