Completions de chat con cURL en varios modelos de IA

Puedes aprender más sobre una pasarela de IA con un solo comando de terminal que con una larga lista de funciones. Si la pasarela es realmente compatible con OpenAI, la misma solicitud curl debería funcionar en las familias de modelos compatibles mientras la URL base, el encabezado de autorización, el formato del mensaje y el análisis de la respuesta se mantienen estables.

Este tutorial muestra el patrón práctico con Flatkey: comienza con una solicitud de chat-completions, mueve el nombre del modelo a una variable y prueba varias familias de modelos actuales sin reescribir la integración. Está diseñado para desarrolladores que quieren validar una API desde una terminal antes de añadir un SDK o comprometer código de la aplicación.

Nota sobre la selección de modelos: Los catálogos de modelos cambian. Los ID de modelo de abajo reflejan la documentación pública de Flatkey comprobada el 24 de julio de 2026. Confirma la fila del modelo y la disponibilidad actuales antes de usar un ID en producción.

The shortest working chat-completions cURL request

Crea una clave de API de Flatkey, expórtala en tu shell y envía una solicitud al endpoint de chat-completions compatible con OpenAI:

export FLATKEY_API_KEY="your-flatkey-api-key"

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Write a one-sentence product description for a waterproof daypack."
      }
    ]
  }'

Cuatro partes importan:

Para modelos de chat compatibles, el campo principal que cambias es model.

Use the same cURL shape across model families

Pon el ID del modelo en una variable de shell para que el cuerpo de la solicitud no tenga que cambiar:

export FLATKEY_API_KEY="your-flatkey-api-key"
export MODEL="gpt-4o-mini"

curl -sS https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"Return concise ecommerce copy.\"
      },
      {
        \"role\": \"user\",
        \"content\": \"Write a product title for a lightweight waterproof daypack.\"
      }
    ],
    \"temperature\": 0.2
  }" | jq -r '.choices[0].message.content'

Ahora vuelve a ejecutar el comando con otro ID de modelo documentado:

export MODEL="claude-sonnet-4-6"

export MODEL="gemini-2.5-flash"

export MODEL="deepseek-v3.1"

La solicitud sigue usando el mismo endpoint, los mismos encabezados, los mismos mensajes y el analizador jq. Esa forma estable de la llamada es la ventaja operativa: puedes comparar familias de modelos compatibles sin mantener un script de terminal distinto para cada proveedor.

Nota sobre la selección de modelo: Una forma de solicitud compartida no significa que todos los modelos se comporten de la misma manera. Los parámetros admitidos, los límites de contexto, el comportamiento de las herramientas, el comportamiento de seguridad, la latencia y el estilo de salida pueden diferir. Trata la compatibilidad como una superficie de integración más simple, no como prueba de que los modelos sean intercambiables.

Ejecuta un pequeño bucle de prueba con varios modelos

Para una comparación rápida en terminal, define una lista corta y envía el mismo prompt a cada modelo:

#!/usr/bin/env bash
set -euo pipefail

: "${FLATKEY_API_KEY:?Set FLATKEY_API_KEY first}"

MODELS=(
  "gpt-4o-mini"
  "claude-sonnet-4-6"
  "gemini-2.5-flash"
  "deepseek-v3.1"
)

PROMPT="Write three benefit-led bullet points for a waterproof commuter backpack."

for MODEL in "${MODELS[@]}"; do
  echo
  echo "=== $MODEL ==="

  jq -n \
    --arg model "$MODEL" \
    --arg prompt "$PROMPT" \
    '{
      model: $model,
      messages: [
        {role: "system", content: "You write concise ecommerce copy."},
        {role: "user", content: $prompt}
      ],
      temperature: 0.2
    }' |
  curl -sS https://router.flatkey.ai/v1/chat/completions \
    -H "Authorization: Bearer $FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -r '.choices[0].message.content // .error.message'
done

Usar jq -n para construir JSON es más seguro que escapar manualmente una cadena larga de shell. También hace que el script sea más fácil de ampliar con variables, mensajes adicionales o parámetros opcionales.

Guarda el script como compare-models.sh, hazlo ejecutable y ejecútalo:

chmod +x compare-models.sh
./compare-models.sh

Qué comparar en la salida

Una prueba con varios modelos solo es útil cuando el prompt y el método de evaluación son consistentes. Para una tarea de texto comercial de ecommerce, compara:

Añade campos de temporización de cURL cuando la latencia importe:

curl -sS -o response.json \
  -w 'estado=%{http_code} total=%{time_total}s\n' \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Escribe un eslogan de producto de cinco palabras."}
    ]
  }'

jq . response.json

Esto separa las mediciones de transporte de la salida del modelo. La terminal muestra el estado HTTP y el tiempo total de la solicitud, mientras que la respuesta JSON permanece disponible para su inspección.

Nota sobre la selección de modelos: No elijas un modelo de producción a partir de una sola respuesta. Ejecuta un conjunto representativo de prompts, repite las solicitudes y puntúa las salidas según los requisitos que importan a tu aplicación.

Mantén la solicitud comparable

Pequeños cambios en el prompt o en los parámetros pueden hacer que una prueba de modelo sea engañosa. Usa estos controles:

1. Mantén idénticos los mensajes. No mejores el prompt para un modelo y no para los demás.
2. Usa la misma temperatura. Los valores más bajos suelen facilitar la revisión de las ejecuciones comparativas.
3. Captura el JSON sin procesar. Almacena la respuesta completa, no solo el texto renderizado.
4. Registra el ID del modelo. Un nombre visible no es lo suficientemente preciso para pruebas reproducibles.
5. Separa los errores de las respuestas incorrectas. Un error de transporte o disponibilidad no es una puntuación de calidad de salida.
6. Comprueba la disponibilidad actual. Un modelo documentado aún puede tener un estado operativo cambiante.

Añade manejo básico de fallos

Usa --fail-with-body para que cURL salga en errores HTTP mientras conserva el cuerpo de la respuesta:

HTTP_BODY=$(mktemp)

if ! curl --fail-with-body -sS \
  -o "$HTTP_BODY" \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Devuelve la palabra listo."}
    ]
  }'; then
  jq -r '.error.message // "La solicitud falló"' "$HTTP_BODY" >&2
  rm -f "$HTTP_BODY"
  exit 1
fi

jq -r '.choices[0].message.content' "$HTTP_BODY"
rm -f "$HTTP_BODY"

En el código de la aplicación, añade también tiempos de espera explícitos, reintentos limitados para fallos reintentables y un registro que no exponga claves secretas ni contenido sensible de los prompts.

Una política práctica de selección de modelos

La política más sencilla es seleccionar según la carga de trabajo y no por el nombre del proveedor:

Empieza con el modelo más pequeño que supere de forma fiable tu umbral de calidad. Escala a un modelo más potente cuando la tarea lo necesite. Si añades enrutamiento de respaldo, prueba el respaldo con el mismo contrato de respuesta en lugar de asumir que puede reemplazar al modelo principal sin cambios en la aplicación.

Puedes revisar el acceso actual a los modelos y los precios en la página de precios de Flatkey antes de seleccionar los ID para una prueba de producción.

Cuándo pasar de cURL a un SDK

cURL es ideal para confirmar rápidamente cuatro cosas:

• la clave de API funciona
• la URL base es correcta
• el modelo seleccionado acepta la solicitud
• la forma de la respuesta coincide con tu analizador

Pasa a un SDK cuando necesites asistentes de streaming, lógica de reintentos estructurada, respuestas tipadas, clientes reutilizables u observabilidad a nivel de aplicación. Mantén la solicitud de cURL que funcionó en tu runbook: sigue siendo la forma más rápida de separar los problemas de acceso al gateway de los problemas de configuración del SDK.

Lista de verificación final de implementación

• Exporta la clave de API en lugar de colocarla directamente en los scripts.
• Usa https://router.flatkey.ai/v1 como URL base.
• Envía solicitudes de chat compatibles a /chat/completions.
• Mueve el ID del modelo a la configuración.
• Genera JSON con jq cuando el escape en la shell se vuelva complejo.
• Captura el estado HTTP, la latencia, el contenido de la respuesta y los datos de uso.
• Compara modelos con indicaciones y parámetros idénticos.
• Verifica la disponibilidad actual del catálogo antes del despliegue en producción.
• Añade tiempos de espera, reintentos limitados y registro seguro de secretos en el código de la aplicación.

Una solicitud cURL estable te da un punto de partida claro. Una vez que funciona, cambiar el campo model convierte esa solicitud en un banco de pruebas práctico para varias familias de modelos de IA, sin cambiar cada vez la autenticación, la URL base ni el analizador de respuestas.

Preguntas frecuentes

¿Puedo usar la misma solicitud cURL de chat completions para todos los modelos de IA?

Úsala para los modelos que Flatkey expone a través de la ruta compatible de chat completions. Otras modalidades o funciones específicas de un protocolo pueden requerir diferentes endpoints o campos de solicitud.

¿Cuál es el conjunto mínimo de campos para una solicitud de chat completions?

Para una solicitud básica, proporciona un model compatible y un array messages. También necesitas el encabezado de autorización Bearer y el tipo de contenido JSON.

¿Por qué poner el nombre del modelo en una variable de entorno?

Mantiene estable la forma de la solicitud, reduce los errores de edición y facilita la ejecución de scripts en configuraciones de staging, evaluación y producción.

¿Debería usar cURL en producción?

cURL es excelente para verificación, scripts y runbooks. La mayoría de las aplicaciones de producción se benefician de un SDK o cliente HTTP con soporte explícito para tiempo de espera, reintentos, telemetría y manejo de tipos.

¿Cómo elijo entre los modelos GPT, Claude, Gemini y DeepSeek?

Elija con un conjunto de evaluación representativo. Compare el seguimiento de instrucciones, la calidad de la salida, la latencia, el uso de tokens, el comportamiento ante errores y las funciones específicas que requiere su carga de trabajo. Confirme la disponibilidad actual antes de la implementación.