IA

Tu primera llamada a un LLM (Claude/GPT) desde ColdFusion

Tutorial paso a paso para hacer tu primera llamada a OpenAI o Claude desde ColdFusion, con cfhttp y con el nuevo framework de IA nativo de CF2025 Update 8.

Juan Carlos Cardoso Riveroll

Juan Carlos Cardoso Riveroll

— 5 min read
Share
Desarrollador escribiendo código ColdFusion para conectar con una API de inteligencia artificial
Foto: Safar Safarov / Unsplash

Para llamar a la API de OpenAI o Claude desde ColdFusion tienes dos caminos: usar cfhttp para hacer la petición REST manualmente (funciona en cualquier versión de CFML), o usar el nuevo framework de IA nativo de ColdFusion 2025 Update 8, que integra LLMs con unas pocas líneas de código. En este tutorial vas a hacer tu primera llamada real a un modelo de lenguaje desde CFML paso a paso.

¿Qué necesitas antes de empezar?

  • Una cuenta en platform.openai.com (o en console.anthropic.com para Claude) con una API key generada.
  • ColdFusion 2021, 2023 o 2025 corriendo localmente o en un servidor con salida a internet (puerto 443 abierto).
  • Si quieres usar el framework nativo de IA, necesitas ColdFusion 2025 Update 8 o superior.

¿Cómo llamar a OpenAI desde ColdFusion con cfhttp?

Este método funciona en cualquier versión moderna de CFML, incluido BoxLang. Es la forma más portable de hacer la integración.

  1. Guarda tu API key en una variable de aplicación o, mejor, en una variable de entorno del servidor. Nunca la escribas directo en el código que vas a subir a un repositorio.
  2. Construye el body de la petición como un struct que luego conviertes a JSON con serializeJSON().
  3. Haz la llamada con cfhttp apuntando al endpoint /v1/chat/completions.
  4. Parsea la respuesta con deserializeJSON() y extrae el texto generado.
<cfset apiKey = server.system.environment.OPENAI_API_KEY />

<cfset payload = {
    "model": "gpt-4o-mini",
    "messages": [
        { "role": "user", "content": "Explica qué es CFML en una frase" }
    ],
    "temperature": 0.7
} />

<cfhttp url="https://api.openai.com/v1/chat/completions"
        method="post"
        result="httpResponse">
    <cfhttpparam type="header" name="Authorization" value="Bearer #apiKey#" />
    <cfhttpparam type="header" name="Content-Type" value="application/json" />
    <cfhttpparam type="body" value="#serializeJSON(payload)#" />
</cfhttp>

<cfset resultData = deserializeJSON(httpResponse.fileContent) />
<cfset respuesta = resultData.choices[1].message.content />

<cfoutput>#respuesta#</cfoutput>

Este bloque envía un mensaje simple al modelo gpt-4o-mini y muestra la respuesta en pantalla. Fíjate que resultData.choices[1] usa índice 1 porque los arreglos en CFML empiezan en 1, no en 0 como en JavaScript o Python.

¿Cómo llamar a Claude (Anthropic) desde ColdFusion?

La estructura es casi idéntica, solo cambian el endpoint, el header de autenticación y el formato de la respuesta.

<cfset apiKey = server.system.environment.ANTHROPIC_API_KEY />

<cfset payload = {
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 500,
    "messages": [
        { "role": "user", "content": "Explica qué es CFML en una frase" }
    ]
} />

<cfhttp url="https://api.anthropic.com/v1/messages"
        method="post"
        result="httpResponse">
    <cfhttpparam type="header" name="x-api-key" value="#apiKey#" />
    <cfhttpparam type="header" name="anthropic-version" value="2023-06-01" />
    <cfhttpparam type="header" name="Content-Type" value="application/json" />
    <cfhttpparam type="body" value="#serializeJSON(payload)#" />
</cfhttp>

<cfset resultData = deserializeJSON(httpResponse.fileContent) />
<cfset respuesta = resultData.content[1].text />

<cfoutput>#respuesta#</cfoutput>

La diferencia clave es que Claude usa el header x-api-key en vez de Authorization: Bearer, y devuelve el texto dentro de un arreglo content, no dentro de choices.

¿Cómo usar el framework de IA nativo de ColdFusion 2025 Update 8?

Desde Update 8, Adobe ColdFusion incluye un framework de IA integrado que abstrae los detalles de cada proveedor (OpenAI, Claude, Gemini, Mistral, Azure OpenAI y hasta modelos locales con Ollama). Esto significa que puedes cambiar de proveedor sin reescribir tu lógica de negocio.

  1. Configura el proveedor en el CF Administrator, en la nueva sección de AI Services, o directamente en código con un objeto de configuración.
  2. Usa la función nativa para crear un cliente de IA apuntando al proveedor que quieras.
  3. Envía tu prompt y recibe la respuesta ya parseada, sin lidiar con headers ni JSON manual.
<cfscript>
    aiConfig = {
        provider: "openai",
        apiKey: server.system.environment.OPENAI_API_KEY,
        model: "gpt-4o-mini"
    };

    aiClient = getAIService(aiConfig);

    respuesta = aiClient.chat("Explica qué es CFML en una frase");

    writeOutput(respuesta.getText());
</cfscript>

Con este enfoque, si mañana quieres migrar a Claude o Gemini, solo cambias el valor de provider en aiConfig. El resto del código sigue igual, lo cual es enorme si estás construyendo una app que necesita flexibilidad entre modelos.

¿Cómo manejar errores en la llamada a la API?

  • Revisa siempre httpResponse.statusCode antes de intentar parsear el JSON; un 401 significa API key inválida y un 429 significa que llegaste al límite de rate limit.
  • Envuelve la llamada en un bloque try/catch para capturar timeouts de red, especialmente si el servidor está en Latinoamérica y el endpoint en EE.UU.
  • Define un timeout explícito en el cfhttp (por ejemplo, 30 segundos) para que tu app no se quede colgada esperando respuesta del modelo.
<cftry>
    <cfhttp url="https://api.openai.com/v1/chat/completions"
            method="post"
            result="httpResponse"
            timeout="30">
        <cfhttpparam type="header" name="Authorization" value="Bearer #apiKey#" />
        <cfhttpparam type="header" name="Content-Type" value="application/json" />
        <cfhttpparam type="body" value="#serializeJSON(payload)#" />
    </cfhttp>

    <cfif httpResponse.statusCode contains "200">
        <cfset resultData = deserializeJSON(httpResponse.fileContent) />
    <cfelse>
        <cfthrow message="Error de la API: #httpResponse.statusCode#" />
    </cfif>

<cfcatch type="any">
    <cfoutput>Ocurrió un error al llamar la API: #cfcatch.message#</cfoutput>
</cfcatch>
</cftry>

Preguntas frecuentes

¿Necesito una librería especial para llamar a OpenAI desde CFML?

No, para el método clásico solo necesitas cfhttp, que viene integrado en ColdFusion desde hace años. Si usas ColdFusion 2025 Update 8, tienes además el framework nativo de IA que simplifica aún más el proceso.

¿Esto funciona igual en BoxLang?

Sí, BoxLang es compatible con CFML, así que el código con cfhttp, serializeJSON() y deserializeJSON() funciona prácticamente igual, con la ventaja de correr sobre la JVM moderna y con ColdBox 8 si usas ese framework.

¿Es seguro guardar la API key directamente en el código?

No. Siempre usa variables de entorno del servidor o el CF Administrator para almacenar claves sensibles. Nunca subas una API key a un repositorio Git público.

¿Puedo usar modelos locales como Ollama en vez de pagar por OpenAI?

Sí, el framework de IA nativo de ColdFusion 2025 Update 8 soporta Ollama local como proveedor, ideal para pruebas sin costo o para datos sensibles que no quieres enviar a la nube.

Si quieres dominar estas integraciones de IA junto con los fundamentos sólidos de ColdFusion (CFCs, bases de datos, seguridad y despliegue), te invito a inscribirte en el curso Aprende a Desarrollar en Adobe ColdFusion, donde vemos estos casos con ejemplos completos y aplicables a proyectos reales.

Read more