Integrar un asistente de IA Gemini en una página de Webflow es pan comido si tu sitio cuenta con Webflow Cloud. La clave se mantiene en el servidor, el endpoint comparte tu dominio y no hace falta configurar CORS.
Si has intentado añadir una función de IA, probablemente te hayas topado con dos muros: la clave de la API de Gemini no puede estar en el código frontend, donde cualquier visitante puede verla en la pestaña de red, y configurar un servicio proxy aparte implica lidiar con cabeceras CORS antes de poder escribir una sola línea de lógica de chat.
Un Worker de terceros soluciona el problema de la clave, pero saca la infraestructura del ecosistema de Webflow, y cada respuesta de Gemini tiene que cruzar un límite de origen para volver a la página.
Webflow Cloud toma otro camino. Tu proxy de Gemini se ejecuta como un endpoint de Next.js en el dominio de tu sitio Webflow. El frontend llama a /app/gemini (una ruta relativa, mismo origen), así que no hay nada de CORS que configurar.
Tu clave se queda en el servidor, la integración vive totalmente dentro del ecosistema de Webflow y tus visitantes disfrutan de un asistente de IA interactivo sin complicaciones de infraestructura.
Esta guía construye ese asistente de principio a fin: la aplicación Cloud gestiona la autenticación, el historial de la conversación y el prompt del sistema; la página de Webflow se encarga de la interfaz.
3 formas de añadir Gemini a un sitio de Webflow
Existen tres caminos para conectar Gemini con Webflow. Webflow Cloud mantiene todo en el mismo dominio y dentro del ecosistema de Webflow. Un proxy de Cloudflare Worker funciona si tu equipo ya usa Cloudflare y se siente cómodo configurando CORS manualmente.
Las plataformas de automatización como Zapier o Make gestionan flujos de trabajo backend que se activan con eventos, en lugar de ofrecer respuestas en tiempo real a los visitantes.
El enfoque adecuado depende de si necesitas respuestas en tiempo real para los visitantes o flujos de trabajo backend basados en eventos:
Los tres comparten un requisito: la clave de API nunca debe exponerse al navegador.
Esta guía cubre por completo la ruta de Webflow Cloud. Te brinda control total sobre el prompt del sistema, el historial de la conversación y la forma en que se muestran las respuestas.
¿Qué necesitas para añadir Gemini a un sitio de Webflow con Webflow Cloud?
Necesitas cuatro cosas: una clave de API de Gemini, un sitio de Webflow con acceso a Cloud, una cuenta de GitHub para el despliegue y Node.js 20 o superior en tu equipo.
Una vez confirmados los cuatro elementos, la configuración solo toma unos minutos. Aquí tienes los detalles de cada uno.
Una clave de API de Gemini de Google AI Studio
Ve a Google AI Studio e inicia sesión con tu cuenta de Google. En la barra lateral izquierda, haz clic en API Keys y luego en Create API key. Selecciona un proyecto de Google Cloud existente o crea uno nuevo. Copia la clave de inmediato y guárdala en un gestor de contraseñas. La añadirás al almacén de variables de entorno de Webflow Cloud, no a ningún código accesible desde el navegador.
Sobre el plan gratuito: los límites de uso gratuito de Gemini se han ajustado varias veces. Antes de comprometerte con el plan gratuito para una función en producción, verifica tus límites actuales en AI Studio. El plan de pago desbloquea límites considerablemente más altos.
Un sitio de Webflow con acceso a Webflow Cloud
Webflow Cloud es la plataforma de alojamiento de Webflow para aplicaciones full-stack desplegadas junto a tu sitio de Webflow. Está disponible en todos los planes de pago de sitios de Webflow. Consulta la página de precios de Webflow para conocer los detalles actuales del plan y la facturación basada en el uso.
La ventaja clave de este caso de uso es que tu aplicación Cloud se despliega en una ruta de montaje dentro del dominio de tu sitio de Webflow (yoursite.webflow.io/app o tu dominio personalizado). Sin solicitudes de origen cruzado, sin configuración de CORS.
Una cuenta de GitHub
Webflow Cloud utiliza GitHub para CI/CD. Cada envío (push) a tu repositorio conectado activa un despliegue. No necesitas experiencia en GitHub más allá de realizar commits y pushes básicos.
Crea una cuenta gratuita en github.com si aún no tienes una. Durante la configuración, conectarás Webflow Cloud a un repositorio y rama específicos. A partir de ahí, cada commit en esa rama activará automáticamente un nuevo despliegue. También puedes activar despliegues manualmente desde el panel de control de Webflow Cloud.
Node.js 20 o superior
Verifica tu versión con node --version. El sitio web de Node.js tiene los instaladores actuales. Node.js se ejecuta en tu máquina local para las herramientas de CLI y la vista previa de desarrollo local. Webflow Cloud, por su parte, se ejecuta en el entorno de ejecución Workers de Cloudflare, no en Node.js, por lo que la compatibilidad con Node en tu equipo y en el despliegue en la nube son cuestiones independientes.
La estructura de la CLI, el servidor de vista previa local (webflow cloud dev) y el paso de compilación requieren una instalación local de Node 20 o superior.
Una vez que tengas los cuatro elementos listos, la configuración te llevará menos de 30 minutos. Aquí tienes el tutorial completo.
5 pasos para añadir un asistente de IA Gemini con Webflow Cloud
La construcción se divide en dos partes: una aplicación de Webflow Cloud que actúa como proxy para las solicitudes a Gemini (pasos 1 a 4) y una interfaz de chat en tu página de Webflow que se comunica con ella (paso 5). El proxy gestiona la autenticación y el formato de la conversación; la interfaz se encarga de la visualización.
Los pasos 1 a 3 se ejecutan en tu terminal. Los pasos 4 y 5 ocurren dentro de Webflow.
1. Obtén tu clave de API de Gemini y configura tu proyecto
Si aún no lo has hecho, el primer paso es recuperar tu clave de API de Gemini en la barra lateral izquierda y hacer clic en Crear clave de API.
Una decisión importante: el proyecto de Google Cloud al que vinculas la clave determina qué cuenta de facturación recibe los cargos y dónde se aplican tus límites de uso. Utiliza un proyecto dedicado para cada integración de Webflow en lugar de un proyecto compartido que ya ejecute otros servicios. Mezclar claves de diferentes proyectos bajo una misma cuenta de facturación hace que depurar los límites de tasa sea mucho más difícil.
2. Inicializa una aplicación de Webflow Cloud
Instala la CLI de Webflow y crea la estructura de una nueva aplicación Cloud.
Ejecuta estos comandos en tu terminal:
npm install -g @webflow/webflow-cli
webflow cloud initDurante webflow cloud init, la CLI te pedirá que:
- Selecciones un framework: elige Next.js (Webflow Cloud requiere Next.js 15 (o superior) o Astro)
- Establezcas una ruta de montaje: usa
/app(esto hace que tu endpoint esté disponible enyoursite.webflow.io/app/gemini) - Autentícate con tu cuenta de Webflow y selecciona tu sitio
La CLI crea la estructura del proyecto con webflow.json, next.config.js, open-next.config.ts y la estructura de directorios necesaria.
La ruta de montaje se establece en next.config.js:
// next.config.js (generated by CLI — verify basePath matches your mount path)
module.exports = {
basePath: '/app',
assetPrefix: '/app',
};Confirma que basePath coincide con la ruta de montaje que ingresaste durante la inicialización. Si no coinciden, las referencias a los recursos y las llamadas a la API se dirigirán a rutas incorrectas después del despliegue.
Inicializa tu repositorio de Git
Inicializa un repositorio de Git y súbelo a un nuevo repositorio de GitHub:
git init
git add .
git commit -m "init webflow cloud app"Crea un repositorio en GitHub y súbelo. Luego, conecta el repositorio en el panel de control de Webflow Cloud yendo a la pestaña Cloud de tu sitio, haciendo clic en Crear nuevo proyecto y siguiendo las instrucciones para vincular tu repositorio de GitHub y establecer la ruta de montaje.
Una vez conectado, despliega con la CLI:
webflow auth login
webflow cloud deployO simplemente haz push a tu rama de GitHub conectada. Webflow Cloud detecta el push y realiza el despliegue automáticamente.
Resultado esperado: Tu aplicación Cloud se despliega correctamente. El registro de despliegue en el panel de control de Webflow muestra un estado en verde.
3. Escribe el endpoint del proxy de Gemini
En el directorio app de tu proyecto, crea un nuevo archivo de Route Handler:
app/
gemini/
route.js ← create this filePega lo siguiente en route.js:
export const runtime = 'edge';
export async function POST(request) {
const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
const SYSTEM_PROMPT =
process.env.SYSTEM_PROMPT ||
'You are a helpful assistant on this website. Answer visitor questions accurately and concisely.';
if (!GEMINI_API_KEY) {
return Response.json({ error: 'API key not configured' }, { status: 500 });
}
let body;
try {
body = await request.json();
} catch {
return Response.json({ error: 'Invalid request body' }, { status: 400 });
}
const { message, history } = body;
if (!message) {
return Response.json({ error: 'No message provided' }, { status: 400 });
}
// Gemini uses role: "user" | "model" — not "assistant"
const contents = [
...(history || []),
{ role: 'user', parts: [{ text: message }] },
];
const geminiResponse = await fetch(
'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent',
{
method: 'POST',
headers: {
'x-goog-api-key': GEMINI_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
system_instruction: {
parts: [{ text: SYSTEM_PROMPT }],
},
contents,
}),
}
);
const data = await geminiResponse.json();
if (!data.candidates?.[0]) {
console.error('Gemini error:', JSON.stringify(data));
return Response.json(
{ error: data.error?.message || 'Unexpected response from Gemini' },
{ status: 500 }
);
}
const reply = data.candidates[0].content.parts[0].text;
return Response.json({ reply });
}Tres cosas que hace este endpoint y que una implementación mínima no hace:
- Combina toda la matriz de
historyconversación en cada solicitud, para que Gemini mantenga el contexto entre turnos. Sin esto, cada mensaje se trata como una conversación nueva. - Lee el prompt del sistema desde una variable de entorno, así puedes personalizar el comportamiento del asistente por sitio sin tocar el código.
- Protege contra respuestas mal formadas de Gemini antes de acceder a propiedades anidadas. A veces, Gemini devuelve objetos de error en lugar de candidatos.
Nota que no hay cabeceras CORS en este código. No son necesarias. El frontend de Webflow y este endpoint comparten el mismo dominio, por lo que el navegador lo trata como una solicitud de mismo origen.
Confirma tus cambios
Haz commit y push para activar un nuevo despliegue:
git add .
git commit -m "add gemini route handler"
git pushResultado esperado: El despliegue se completa en el panel de control de Webflow. Puedes probar el endpoint con una solicitud POST a https://yoursite.webflow.io/app/gemini desde una herramienta como Bruno o Postman.
4. Añade tus claves de API como variables de entorno secretas
En el panel de control de Webflow, navega a la pestaña de configuración Cloud de tu sitio. Selecciona tu entorno de despliegue y abre las Variables de entorno.
Añade dos variables:
Configura GEMINI_API_KEY como Secreto para cifrar y ocultar el valor. Cualquier persona con acceso a tu sitio de Webflow puede ver las variables de entorno normales en el panel, así que los secretos son la opción correcta para las credenciales de API.
Las variables de entorno en Webflow Cloud solo están disponibles durante la ejecución, no durante la compilación. process.env.GEMINI_API_KEY en el controlador de ruta accede al valor en el momento de la solicitud, lo cual es correcto para este caso de uso.
Después de añadir las variables, inicia un nuevo despliegue desde el panel de control. Los cambios en las variables de entorno requieren un nuevo despliegue para surtir efecto.
Resultado esperado: Vuelve a probar tu endpoint. El error 500 "API key not configured" debería desaparecer y Gemini debería devolver una respuesta real.
5. Añade la interfaz de chat a tu página de Webflow
En la página de Webflow donde residirá el asistente, añade un elemento Code Embed desde el panel de añadir (el icono + en la barra lateral izquierda). Este elemento contiene el HTML y CSS de la interfaz de chat de forma integrada.
Dentro del Code Embed, pega este marcado:
<div id="gemini-chat" style="
font-family: inherit;
max-width: 480px;
border: 1px solid #e5e7eb;
border-radius: 12px;
overflow: hidden;
display: flex;
flex-direction: column;
height: 480px;
">
<div id="chat-messages" style="
flex: 1;
overflow-y: auto;
padding: 16px;
display: flex;
flex-direction: column;
gap: 12px;
background: #f9fafb;
"></div>
<div style="
display: flex;
gap: 8px;
padding: 12px 16px;
background: #fff;
border-top: 1px solid #e5e7eb;
">
<input
id="chat-input"
type="text"
placeholder="Ask a question..."
style="
flex: 1;
padding: 8px 12px;
border: 1px solid #d1d5db;
border-radius: 8px;
font-size: 14px;
outline: none;
"
/>
<button
id="chat-send"
style="
padding: 8px 16px;
background: #1a1a2e;
color: #fff;
border: none;
border-radius: 8px;
font-size: 14px;
cursor: pointer;
"
>Send</button>
</div>
</div>Los estilos están integrados para evitar conflictos con la hoja de estilos de Webflow. Ajusta los colores y el tamaño para que coincidan con tu sistema de diseño. Los IDs (gemini-chat, chat-messages, chat-input, chat-send) son referenciados por el JavaScript de abajo. No los cambies.
En Site Settings → Custom Code → Footer Code, pega este script:
<script>
(function() {
// Relative path — no CORS, same domain as your Webflow site
const ENDPOINT = '/app/gemini';
const messagesEl = document.getElementById('chat-messages');
const inputEl = document.getElementById('chat-input');
const sendBtn = document.getElementById('chat-send');
if (!messagesEl || !inputEl || !sendBtn) return;
// In-memory conversation history (resets on page reload)
let history = [];
function appendMessage(role, text) {
const isUser = role === 'user';
const wrapper = document.createElement('div');
wrapper.style.cssText = `display:flex;justify-content:${isUser ? 'flex-end' : 'flex-start'};`;
const bubble = document.createElement('div');
bubble.style.cssText = `
max-width:80%;padding:10px 14px;
border-radius:${isUser ? '12px 12px 2px 12px' : '12px 12px 12px 2px'};
background:${isUser ? '#1a1a2e' : '#fff'};
color:${isUser ? '#fff' : '#111'};
font-size:14px;line-height:1.5;
border:${isUser ? 'none' : '1px solid #e5e7eb'};
white-space:pre-wrap;
`;
bubble.textContent = text;
wrapper.appendChild(bubble);
messagesEl.appendChild(wrapper);
messagesEl.scrollTop = messagesEl.scrollHeight;
}
async function sendMessage() {
const userText = inputEl.value.trim();
if (!userText) return;
inputEl.value = '';
sendBtn.disabled = true;
sendBtn.textContent = '...';
appendMessage('user', userText);
// Typing indicator
const typingId = 'typing-' + Date.now();
const typingEl = document.createElement('div');
typingEl.id = typingId;
typingEl.style.cssText = 'color:#6b7280;font-size:13px;padding:4px 0;';
typingEl.textContent = 'Thinking…';
messagesEl.appendChild(typingEl);
messagesEl.scrollTop = messagesEl.scrollHeight;
try {
const response = await fetch(ENDPOINT, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message: userText, history }),
});
const indicator = document.getElementById(typingId);
if (indicator) indicator.remove();
if (!response.ok) {
const err = await response.json().catch(() => ({}));
appendMessage('model', 'Error: ' + (err.error || response.statusText));
} else {
const data = await response.json();
appendMessage('model', data.reply);
// Update history for multi-turn context
history.push({ role: 'user', parts: [{ text: userText }] });
history.push({ role: 'model', parts: [{ text: data.reply }] });
}
} catch (err) {
const indicator = document.getElementById(typingId);
if (indicator) indicator.remove();
appendMessage('model', 'Connection error. Check your internet connection and try again.');
console.error('Fetch error:', err);
} finally {
sendBtn.disabled = false;
sendBtn.textContent = 'Send';
inputEl.focus();
}
}
sendBtn.addEventListener('click', sendMessage);
inputEl.addEventListener('keydown', function(e) {
if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); sendMessage(); }
});
})();
</script>Publica tu sitio. Ábrelo en tu URL publicada (no en la vista previa del Diseñador, ya que el código personalizado no se ejecuta en el lienzo) y escribe un mensaje. Gemini debería responder. Haz una pregunta de seguimiento que haga referencia a la primera respuesta para confirmar que el contexto de múltiples turnos funciona.
Resultado esperado: El widget de chat aparece en la página. El primer mensaje devuelve una respuesta de Gemini. Un segundo mensaje que hace referencia al primero confirma que el contexto de múltiples turnos funciona correctamente.
¿Qué causa que la integración de Gemini falle en Webflow Cloud?
La mayoría de los fallos tras la configuración inicial se deben a tres causas: que el endpoint no detecte la clave de API, límites de tasa en el plan gratuito y que el formato de mensaje de Gemini se confunda con la estructura de OpenAI.
Cada fallo produce un síntoma distinto. Empieza por el síntoma que estás observando.
El endpoint devuelve un 500 tras el despliegue: clave de API no encontrada
El controlador de ruta lee process.env.GEMINI_API_KEY durante la ejecución. Si el endpoint devuelve un 500 con "API key not configured", ha ocurrido una de estas dos cosas: la variable de entorno no se configuró antes del despliegue, o se añadió después del último despliegue y no se ha vuelto a desplegar.
En el panel de control de Webflow Cloud, confirma que GEMINI_API_KEY aparece en Environment Variables con el tipo Secret. Luego, inicia un nuevo despliegue. Los cambios en las variables de entorno requieren un nuevo despliegue completo. No se recargan automáticamente.
Errores 429 durante el desarrollo
Estás alcanzando el límite de tasa de Gemini en el plan gratuito. Este plan tiene límites por minuto y por día que varían según el modelo. Durante el desarrollo, estos se alcanzan rápidamente si envías mensajes de prueba de forma consecutiva.
Opciones: añade una breve pausa entre las llamadas de prueba, cambia a un plan de pago o comprueba tus límites actuales en Google AI Studio dentro del proyecto de la clave de API. El tráfico de producción en un sitio público debería estar en el plan de pago para evitar que los visitantes vean errores de límite de tasa durante los picos de uso.
La conversación pierde el contexto después de la primera respuesta
Gemini no almacena el estado de la sesión. Cada solicitud debe incluir el historial completo de la conversación para que el contexto de múltiples turnos funcione. Si Gemini responde pero luego trata el segundo mensaje como una conversación nueva, es que el history array en el JavaScript del frontend no se está actualizando correctamente.
Revisa las history.push(...) llamadas al final de la sendMessage función. Tanto el mensaje del usuario como la respuesta del modelo deben añadirse después de cada respuesta exitosa.
La estructura debe ser:
{ role: 'user', parts: [{ text: userText }] }
{ role: 'model', parts: [{ text: data.reply }] }Ten en cuenta que Gemini utiliza el role "model", no el "assistant" como OpenAI. Este es el error más común al adaptar una integración de OpenAI existente.
Las instrucciones del prompt del sistema se ignoran parcialmente o son inconsistentes
Gemini sigue las instrucciones del sistema, pero las instrucciones vagas producen resultados inconsistentes. "Sé útil y conciso" es demasiado general.
Patrones más efectivos:
- Asígnale una personalidad: "Eres un asistente de soporte para [Empresa]. Solo respondes preguntas sobre nuestros productos".
- Establece límites explícitos: "Mantén todas las respuestas por debajo de las 120 palabras. No especules sobre temas fuera de tu contexto".
- Define qué hacer cuando no sepas la respuesta: "Si no sabes la respuesta, dilo directamente en lugar de adivinar".
Prueba el prompt del sistema con una variedad de entradas de usuario, incluyendo casos límite, antes de publicar. La SYSTEM_PROMPT variable de entorno te permite iterar sobre esto sin tocar el código: actualiza la variable, vuelve a desplegar y prueba de nuevo.
Qué construir a continuación con Webflow Cloud
Esta guía cubrió el patrón principal: un manejador de rutas de Webflow Cloud que actúa como proxy para las solicitudes a Gemini, sin necesidad de configurar CORS porque el endpoint comparte el dominio de tu sitio.
El mismo patrón funciona para cualquier API externa que requiera una clave del lado del servidor: OpenAI, Anthropic (Claude), APIs de clima y procesadores de pago.
Explora Webflow + Gemini para ver casos de uso, ejemplos de la comunidad e integraciones relacionadas que combinan bien con esta configuración.
Preguntas frecuentes
¿Es el nivel gratuito de Gemini adecuado para un sitio de Webflow en producción?
Probablemente no si tienes un volumen de tráfico considerable. Los límites del nivel gratuito varían según el modelo y cambian con frecuencia. Un puñado de visitantes simultáneos enviando mensajes puede agotar rápidamente los límites por minuto. Para producción, utiliza el nivel de pago y establece un límite de presupuesto en Google Cloud. Consulta los límites actuales en AI Studio antes del lanzamiento.
¿En qué se diferencia el formato de solicitud de la API de Gemini del de OpenAI?
Gemini utiliza el role "model," mientras que OpenAI utiliza el role "assistant". Gemini también envuelve el texto en parts: [{ text: "..." }] en lugar de una cadena content plana. Intercambiar directamente el array de mensajes de OpenAI en una solicitud de Gemini fallará silenciosamente. La estructura se analiza sin errores, pero Gemini devuelve una respuesta inesperada.
¿El asistente de IA conserva la memoria entre sesiones o recargas de página?
No. La history matriz reside en la memoria y se borra al recargar la página. Dentro de una misma sesión, el contexto de varios turnos funciona porque el historial completo se envía con cada solicitud. Para una memoria persistente entre sesiones, guarda y recupera el historial de la conversación desde SQLite de Webflow Cloudo el almacenamiento de clave-valor.
¿Puedo usar Astro en lugar de Next.js para la aplicación Cloud?
Sí. Webflow Cloud es compatible con ambos frameworks. El equivalente en Astro utiliza la sintaxis de endpoints del servidor, con un export async function POST({ request, locals }) que accede a las variables de entorno mediante locals.runtime.env.GEMINI_API_KEY. Nuestra entrada de blog de Webflow sobre wrappers de API con Webflow Cloud utiliza Astro y es una excelente referencia de configuración.
¿Puede el asistente Gemini leer colecciones de CMS de Webflow?
No directamente. Gemini solo conoce lo que envías en el prompt del sistema o en el historial de la conversación. Obtén los elementos de la colección CMS a través de la API de datos de Webflow en tu manejador de rutas e insértalos en el prompt del sistema antes de llamar a Gemini. Requiere un plan CMS o superior para acceder a la API de datos.
