Cómo usar un proxy para generar imágenes de OpenAI en Webflow Cloud sin exponer tu clave API

Una de las peticiones más comunes que recibo al añadir IA a un proyecto de Webflow es permitir que los usuarios generen imágenes a partir de sus propios prompts.

Sin embargo, no puedes llamar a OpenAI desde el navegador sin exponer tu clave API en el código fuente de la página. Cualquiera que abra las herramientas de desarrollo puede copiarla y, a partir de ese momento, tu cuota será suya. La solución que la mayoría de los equipos elige (una función serverless alojada por separado) funciona, pero fragmenta el stack y añade un despliegue que debes gestionar independientemente del sitio de Webflow.

Con Webflow Cloud Apps, puedes ejecutar un Route Handler de Next.js en el servidor mediante Cloudflare Workers, usar un proxy para la solicitud de OpenAI con tu clave almacenada como variable de entorno y devolver la imagen generada al navegador. La clave API nunca llega al cliente. Todo se despliega junto a tu sitio de Webflow con un solo comando de CLI.

Esta guía cubre cómo construir una herramienta completa de generación de imágenes con IA en Webflow Cloud, desde la estructura inicial hasta el despliegue, usando el modelo gpt-image-1 de OpenAI.

¿Qué necesitas para crear un generador de imágenes con IA en Webflow?

Necesitas una clave API de OpenAI, una Webflow Cloud App y evitar la exposición de la API en el lado del cliente. La arquitectura consiste en un proxy de servidor. El navegador se comunica con tu Route Handler, que a su vez se comunica con OpenAI.

Estos son los requisitos clave:

No se requieren paquetes npm adicionales para las llamadas a la API. El Route Handler utiliza la fetch() API estándar, que está disponible de forma nativa en Cloudflare Workers.

Una vez que hayas confirmado el acceso a estos cinco requisitos, estarás listo para estructurar la aplicación y escribir el Route Handler que mantendrá tu clave API fuera del alcance del cliente.

5 pasos para crear un generador de imágenes con IA en Webflow Cloud

La construcción consta de dos partes. Los pasos 1 y 2 preparan la estructura de la aplicación de Webflow Cloud y configuran la clave de API de OpenAI. Los pasos 3 y 4 crean el gestor de rutas (Route Handler) del lado del servidor y el formulario del lado del cliente. El paso 5 despliega todo.

La decisión de diseño clave en esta arquitectura es dónde reside la llamada a OpenAI. Siempre la coloco en el gestor de rutas, nunca en el cliente. Incluso una clave de API de solo lectura puede generar miles de imágenes en tu cuota si se filtra. El gestor de rutas ofrece un punto central para añadir límites de velocidad, validación de prompts o filtrado de contenido antes de que la solicitud llegue a OpenAI.

Los pasos del 1 al 5 se construyen de forma secuencial. No te saltes el paso de las variables de entorno, ya que una clave faltante es la causa más común de errores 500 tras el despliegue.

1. Crear el esqueleto de la aplicación de Webflow Cloud

Empieza instalando la CLI de Webflow de forma global y ejecutando el comando init. Esto crea la estructura de un proyecto Next.js, autentica tu cuenta de Webflow y vincula la aplicación a un sitio específico, todo en un mismo flujo.

Instala la CLI de Webflow de forma global y luego ejecuta webflow cloud init para crear el esqueleto del proyecto:

npm install -g @webflow/webflow-cli
webflow cloud init

La CLI te pedirá que elijas un framework (selecciona Next.js), establezcas una ruta de montaje para la aplicación (por ejemplo, ), y te autentiques con tu cuenta de Webflow. La autenticación ocurre durante . No se requiere ningún comando de autenticación adicional en esta etapa./generatorinit

Tras la autenticación, selecciona el sitio de Webflow al que deseas vincular la aplicación.

La CLI genera una estructura con cinco archivos preconfigurados:

your-app/
├── next.config.js          # basePath + assetPrefix set to your mount path
├── open-next.config.ts     # OpenNext adapter for Cloudflare Workers
├── cloudflare.env.ts       # TypeScript types for env vars and bindings
├── wrangler.json           # Cloudflare Workers config — do not edit
└── webflow.json            # Webflow project metadata

Yo no toco en ningún proyecto. Webflow Cloud lo regenera en cada despliegue basándose en . Editarlo manualmente provoca conflictos silenciosos.wrangler.jsonwebflow.json

Resultado esperado: Un proyecto Next.js estructurado y vinculado a tu sitio de Webflow, con conteniendo tu ruta de montaje tanto en como en .next.config.jsbasePathassetPrefix

2. Configura tu clave de API de OpenAI como variable de entorno

Antes de escribir cualquier código para el gestor de rutas, guarda la clave de API de OpenAI en un lugar donde el cliente no pueda leerla.

Crea un archivo en la raíz del proyecto y añade tu clave de API de OpenAI:.env.local

OPENAI_API_KEY=sk-...your-key-here

No añadas el prefijo . Ese prefijo expone el valor en el paquete de JavaScript del lado del cliente. Eso es exactamente lo que intentamos evitar. Una variable sin solo es accesible en los gestores de rutas y en los componentes de servidor, que se ejecutan en el servidor.NEXT_PUBLIC_NEXT_PUBLIC_

Añade a tu si aún no está ahí. He revisado proyectos donde el archivo se subió a un repositorio público de GitHub. La clave fue revocada a las pocas horas de que alguien la encontrara mediante una búsqueda en GitHub. No confíes en la seguridad por oscuridad..env.local.gitignore.env.local

# .gitignore
.env.local
.env*.local

También añadirás esta clave a tu entorno de Webflow Cloud antes del despliegue. Eso se explica en el paso 5.

OPENAI_API_KEYResultado esperado: disponible en tiempo de ejecución en tu gestor de rutas mediante , invisible para el navegador.process.env.OPENAI_API_KEY

3. Crea el gestor de rutas del lado del servidor

El gestor de rutas es el núcleo de esta arquitectura. Se sitúa entre el navegador y OpenAI, recibe el prompt del usuario, realiza la llamada a la API con tu clave almacenada en el servidor y devuelve los datos de la imagen al cliente.

Crea un gestor de rutas en . Este archivo recibe el prompt del navegador, llama a la API de imágenes de OpenAI y devuelve la imagen codificada en base64.app/api/generate/route.ts

Aquí tienes el gestor de rutas completo. Cópialo en app/api/generate/route.ts. Los comentarios en el código explican las decisiones que vale la pena entender antes de desplegar:

// app/api/generate/route.ts
export async function POST(request: Request) {
  const OPENAI_API_KEY = process.env.OPENAI_API_KEY;

  if (!OPENAI_API_KEY) {
    return Response.json(
      { error: "OpenAI API key not configured" },
      { status: 500 }
    );
  }

  const { prompt } = await request.json();

  if (!prompt || typeof prompt !== "string" || prompt.trim().length === 0) {
    return Response.json(
      { error: "A prompt is required" },
      { status: 400 }
    );
  }

  const openaiResponse = await fetch(
    "https://api.openai.com/v1/images/generations",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${OPENAI_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        model: "gpt-image-1",
        prompt: prompt.trim(),
        size: "1024x1024",
        quality: "medium",
        n: 1,
      }),
    }
  );

  if (!openaiResponse.ok) {
    const error = await openaiResponse.json();
    return Response.json(
      { error: error.error?.message ?? "Image generation failed" },
      { status: openaiResponse.status }
    );
  }

  const data = await openaiResponse.json();
  const imageBase64 = data.data?.[0]?.b64_json;

  if (!imageBase64) {
    return Response.json(
      { error: "No image returned from OpenAI" },
      { status: 500 }
    );
  }

  return Response.json({ image: imageBase64 });
}

Hay algo que este controlador no hace: no autentica ni limita la tasa de solicitudes del emisor. Tal como está escrito, cualquiera que encuentre el endpoint puede gastar tu saldo de OpenAI. Antes de publicar esto en un sitio público, añade un límite de tasa basado en IP respaldado por el Almacén de Clave-Valor, limita la longitud del prompt y establece un presupuesto mensual en tu panel de control de OpenAI.

Tres cosas más a tener en cuenta en esta implementación.

(1) Primero, no añadas export const runtime = "edge". El adaptador OpenNext de Cloudflare que utiliza Webflow Cloud no es compatible con el runtime edge de Next.js, y dejar la directiva ahí rompe la compilación. Los Route Handlers ya se ejecutan en el runtime de Workers.

(2) Segundo, valido el prompt antes de la llamada a la API. OpenAI devolverá un error 400 si el prompt está vacío, pero gestionarlo por nuestra parte significa una respuesta más rápida y un mensaje de error más útil para el cliente.

(3) Tercero, la respuesta es b64_json (una cadena PNG codificada en base64), no una URL. Los modelos de imagen GPT de OpenAI devuelven los datos de la imagen directamente, no un enlace alojado.

Para nuevas compilaciones, usa "gpt-image-2", el modelo de imagen actual de OpenAI. No inicies un proyecto con "gpt-image-1.5" o "gpt-image-1-mini": OpenAI los retiró ambos el 2 de junio de 2026, con su cierre el 1 de diciembre de 2026 y "gpt-image-2" como el reemplazo designado. Todos comparten la misma interfaz de API, por lo que el valor del modelo es el único cambio necesario.

Resultado esperado: Un Route Handler en /generator/api/generate (relativo a tu ruta de montaje) que acepte solicitudes POST con un { prompt: string } cuerpo y devuelva { image: string } que contenga el PNG en base64.

4. Crea el formulario del generador de imágenes del lado del cliente

Con el Route Handler listo, la página del lado del cliente necesita hacer tres cosas: capturar un prompt de texto, enviarlo mediante POST al controlador y renderizar la imagen en base64 que recibe de vuelta.

Crea un Client Component con un campo de entrada de texto para el prompt, un botón de envío y un área para mostrar la imagen. El componente envía los datos al Route Handler y renderiza la cadena base64 devuelta como una etiqueta <img> .

Aquí tienes el componente completo. Gestiona el estado de carga, la visualización de errores y el renderizado de la imagen, y envía los datos al Route Handler usando la ruta de montaje completa:

// app/page.tsx
"use client";

import { useState } from "react";

export default function ImageGeneratorPage() {
  const [prompt, setPrompt] = useState("");
  const [imageBase64, setImageBase64] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function handleGenerate() {
    if (!prompt.trim()) return;

    setLoading(true);
    setError(null);
    setImageBase64(null);

    try {
      const response = await fetch("/generator/api/generate", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ prompt }),
      });

      const data = await response.json();

      if (!response.ok) {
        setError(data.error ?? "Something went wrong. Try again.");
        return;
      }

      setImageBase64(data.image);
    } catch {
      setError("Network error. Check your connection and try again.");
    } finally {
      setLoading(false);
    }
  }

  return (
    <main style={{ maxWidth: 640, margin: "0 auto", padding: "2rem" }}>
      <h1>AI Image Generator</h1>
      <p>Describe an image and generate it instantly with OpenAI.</p>

      <textarea
        value={prompt}
        onChange={(e) => setPrompt(e.target.value)}
        placeholder="A minimalist product photo of a white ceramic mug on a marble surface..."
        rows={3}
        style={{ width: "100%", fontSize: "1rem", padding: "0.75rem" }}
      />

      <button
        onClick={handleGenerate}
        disabled={loading || !prompt.trim()}
        style={{ marginTop: "1rem", padding: "0.75rem 1.5rem" }}
      >
        {loading ? "Generating..." : "Generate Image"}
      </button>

      {error && (
        <p style={{ color: "red", marginTop: "1rem" }}>{error}</p>
      )}

      {imageBase64 && (
        <div style={{ marginTop: "2rem" }}>
          <img
            src={`data:image/png;base64,${imageBase64}`}
            alt={prompt}
            style={{ width: "100%", borderRadius: 8 }}
          />
          <a
            href={`data:image/png;base64,${imageBase64}`}
            download="generated-image.png"
            style={{ display: "block", marginTop: "0.5rem" }}
          >
            Download image
          </a>
        </div>
      )}
    </main>
  );
}

Algo con lo que me he topado en casi todos los proyectos de generadores de imágenes: la carga útil en base64 es grande.

Un PNG de 1024x1024 regresa como una cadena base64 varias veces más grande que la imagen binaria. Eso está dentro del rango normal para una sola imagen, pero si planeas permitir que los usuarios generen múltiples imágenes y las muestren en una cuadrícula, almacena cada resultado en el estado y evita volver a realizar la solicitud.

La imageBase64 variable de estado aquí solo contiene la última imagen. Amplíala a un array si necesitas una galería.

La URL de fetch usa la ruta de montaje completa: /generator/api/generate. Actualiza esto para que coincida con la ruta de montaje que estableciste durante webflow cloud init. Siempre escribo la ruta completa en el código en lugar de derivarla dinámicamente, lo que evita casos extremos de enrutamiento en Cloudflare Workers.

Resultado esperado: La página en your-site.com/generator renderiza un formulario de prompt. Al enviar un prompt, se llama al Route Handler y la imagen generada aparece en la página en un plazo de 10 a 20 segundos, dependiendo del modelo y los ajustes de calidad.

5. Añade la variable de entorno y despliega

En la configuración de tu sitio en Webflow, navega a Webflow Cloud, abre el entorno de tu proyecto y añade OPENAI_API_KEY en Variables de Entorno.

A continuación, autentícate y despliega desde la CLI:

webflow auth login
webflow cloud deploy

webflow auth login abre una ventana del navegador para autenticar tu cuenta de Webflow. Después de conceder el acceso, webflow cloud deploy envía el proyecto. Alternativamente, haz push a tu rama de GitHub conectada y Webflow Cloud se desplegará automáticamente.

Monitorea el progreso de la compilación y los registros en el panel de control de Webflow Cloud bajo Historial de Despliegue. La duración de la compilación varía según el tamaño del proyecto; observa el Historial de Despliegue para ver el resultado.

Resultado esperado: El generador de imágenes está activo en your-site.webflow.io/generator. Al ingresar un prompt y hacer clic en Generar, se obtiene una imagen generada por IA de 1024x1024 en un plazo de 10 a 20 segundos. La clave de API no es visible en el código fuente de la página ni en la pestaña de red.

¿Qué causa que la generación de imágenes falle en Webflow Cloud con OpenAI?

La mayoría de los fallos se agrupan en cuatro categorías: clave de API faltante o mal configurada, rechazos por políticas de contenido, límites de velocidad excedidos o una directiva runtime = "edge" residual que interrumpe la compilación.

Cada tipo de fallo que se detalla a continuación incluye el error específico que verás, la causa más probable y la solución, ordenados según su frecuencia de aparición en la práctica.

La API devuelve un error 401 o "Invalid API key"

Causa: La variable de entorno OPENAI_API_KEY no está configurada en el entorno de Webflow Cloud, o la clave se añadió solo a .env.local y no al panel de entorno de Cloud.

Solución: Abre Webflow Cloud → Variables de entorno y confirma que OPENAI_API_KEY existe con el valor correcto. Los cambios en las variables de entorno requieren un nuevo despliegue para surtir efecto. Ejecuta webflow cloud deploy o haz un push a GitHub para iniciar uno.

La API devuelve un error 400 con un mensaje de política de contenido

Causa: OpenAI rechazó el prompt por infringir su política de uso. Esto sucede con prompts que incluyen nombres específicos, descripciones violentas o contenido que activa el sistema de seguridad. El mensaje de error de OpenAI suele describir la categoría de la infracción.

Solución: Muestra el mensaje de error de OpenAI al usuario para que pueda modificar el prompt. El manejador de rutas (Route Handler) en el paso 3 ya devuelve error.error?.message al cliente. Asegúrate de que el frontend lo renderice de forma visible en lugar de ignorarlo silenciosamente.

He tenido clientes que reportaron un generador "roto" que en realidad estaba rechazando todos sus prompts por incluir nombres de marcas. Capturar y mostrar el mensaje de error habría hecho que esto fuera evidente de inmediato.

Las imágenes se generan localmente, pero no después del despliegue

Causa: Existe una directiva export const runtime = "edge" en route.ts. El adaptador OpenNext de Cloudflare no es compatible con el tiempo de ejecución edge (edge runtime), por lo que la compilación falla o la ruta nunca se ejecuta.

Solución: Añade export const runtime = "edge" como la primera exportación en app/generate/route.ts. Vuelve a desplegar tras realizar el cambio.

La respuesta es lenta o se agota el tiempo de espera

Causa: La generación de imágenes con gpt-image-1 en calidad medium tarda entre 10 y 20 segundos. En calidad high, puede llegar a los 30-40 segundos. Webflow Cloud mide el tiempo de CPU del Worker, pero ese presupuesto contabiliza el cómputo activo, no el tiempo de espera de la respuesta de OpenAI. El fallo más común es que el navegador o un proxy intermedio abandonen una solicitud que ha permanecido abierta demasiado tiempo.

Solución: Reduce la calidad a "low" durante las pruebas. Yo realizo prototipos en quality: "low" para mantener el ciclo de iteración rápido y económico, y luego aumento la calidad antes de la demostración al cliente. Evita usar gpt-image-1-mini, que OpenAI desactivará el 1 de diciembre de 2026.

Si los tiempos de espera persisten en calidad high, considera poner la solicitud en cola de forma asíncrona y consultar el resultado mediante sondeo (polling) en lugar de esperar una única petición de larga duración.

Crea más herramientas de IA en Webflow Cloud

Esta guía cubre un generador de imágenes de un solo prompt como punto de partida. El mismo patrón de manejador de rutas funciona para la edición de imágenes (llama al endpoint /v1/images/edits con "gpt-image-2" y pasa una imagen de entrada junto con el prompt), la generación por lotes o para enviar la imagen generada a un elemento del CMS mediante la API de datos de Webflow.

Explora Webflow + OpenAI para conectar las funciones de texto y chat de OpenAI con la generación de imágenes, además de toda la gama de patrones de integración.