Inicio rápido de la API de Flatkey: haz tu primera llamada a través de router.flatkey.ai
Si ya usas el SDK de OpenAI, la ruta más corta para hacer tu primera llamada a la API de Flatkey es simple: crea una clave de Flatkey, apunta tu cliente a https://router.flatkey.ai/v1, envía una solicitud de chat completions y confirma la llamada en la consola.
Este inicio rápido recorre ese flujo completo. También muestra cómo añadir una secuencia básica de fallback después de que funcione el primer modelo, sin ocultar errores ni crear una cadena de reintentos ilimitada.
Lo que completarás
Al final de esta guía, habrás tenido:
- Una cuenta de Flatkey y una clave API.
- Un cliente compatible con OpenAI que usa el router de Flatkey.
- Una solicitud exitosa y una respuesta legible.
- Un punto de control en la consola para uso, coste y resolución de problemas de las solicitudes.
- Un pequeño patrón de fallback que puedes probar antes de producción.
No necesitas reescribir tu aplicación alrededor de un nuevo SDK para esta prueba rápida. La documentación pública de Flatkey expone un endpoint compatible con OpenAI en https://router.flatkey.ai/v1, por lo que los flujos habituales de chat, herramientas, streaming y salida estructurada pueden conservar la misma forma familiar del cliente.
Antes de empezar
Necesitas:
- Una cuenta de Flatkey.
- Una clave API de Flatkey que empiece con
sk-fk-. - Python 3.9+ o Node.js 18+ si quieres usar un ejemplo de SDK.
- Un nombre de modelo actualmente disponible para tu cuenta.
Los catálogos de modelos y la disponibilidad pueden cambiar. Usa el catálogo de modelos actual o la consola en lugar de copiar un nombre de modelo antiguo en producción.
Paso 1: Crea tu cuenta de Flatkey
Abre el flujo de registro de Flatkey y crea una cuenta. Después de iniciar sesión, usa la consola para crear la credencial que tu aplicación enviará con cada solicitud.
Referencia de la consola
Ve a Console → API Keys.
Crea una clave para este inicio rápido y cópiala inmediatamente. Trata la clave como una contraseña: no la pegues en código del lado del cliente, no la confirmes en Git, no la incluyas en capturas de pantalla ni la envíes en mensajes de soporte.
Para un entorno de equipo, crea claves separadas para desarrolladores o servicios distintos. La documentación de Flatkey también describe controles por clave, como un límite mensual y una lista de अनुमति de modelos opcional. Esos controles facilitan aislar una prueba, rotar una credencial o detener una carga de trabajo sin afectar a todas las aplicaciones.
Define la clave en tu shell:
export FLATKEY_API_KEY="sk-fk-your-key-here"
Si usas un archivo .env, mantenlo fuera del control de versiones:
FLATKEY_API_KEY=sk-fk-your-key-here
Paso 2: Cambia la URL base
La URL base de Flatkey compatible con OpenAI es:
https://router.flatkey.ai/v1
Este es el cambio de configuración más importante en el inicio rápido. Tu clave API autentica la solicitud, mientras que la URL base la envía a través del router de Flatkey en lugar de directamente a otro endpoint de proveedor.
Mantén ambos valores en la configuración del entorno para que puedas cambiarlos sin editar la lógica de la aplicación:
export OPENAI_API_KEY="$FLATKEY_API_KEY"
export OPENAI_BASE_URL="https://router.flatkey.ai/v1"
Usa los nombres de variables que espera tu framework. Algunas bibliotecas leen OPENAI_BASE_URL; otras requieren una opción base_url o baseURL cuando se crea el cliente.
Paso 3: Envía tu primera solicitud
Empieza con un prompt corto y determinista. El objetivo es demostrar autenticación, conectividad, acceso al modelo y análisis de la respuesta antes de añadir streaming, herramientas, salida estructurada o comportamiento de fallback.
Opción A: cURL
Reemplaza YOUR_CURRENT_MODEL con un modelo disponible en el catálogo actual de Flatkey:
curl https://router.flatkey.ai/v1/chat/completions \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_CURRENT_MODEL",
"messages": [
{
"role": "user",
"content": "Reply with exactly: flatkey quickstart connected"
}
],
"temperature": 0
}'
Opción B: Python
Instala el cliente de OpenAI:
pip install openai
Crea quickstart.py:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url="https://router.flatkey.ai/v1",
)
response = client.chat.completions.create(
model="YOUR_CURRENT_MODEL",
messages=[
{
"role": "user",
"content": "Reply with exactly: flatkey quickstart connected",
}
],
temperature=0,
)
print(response.choices[0].message.content)
print(response.usage)
Ejecuta:
python quickstart.py
Opción C: JavaScript
Instala el cliente:
npm install openai
Crea quickstart.mjs:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: "YOUR_CURRENT_MODEL",
messages: [
{
role: "user",
content: "Reply with exactly: flatkey quickstart connected",
},
],
temperature: 0,
});
console.log(response.choices[0].message.content);
console.log(response.usage);
Ejecuta:
node quickstart.mjs
Paso 4: Lee la respuesta
Para una solicitud estándar de chat-completions, empieza con cuatro campos:
| Campo | Qué te indica | Comprobación de la primera llamada |
|---|---|---|
id |
El identificador de la respuesta | Guárdalo temporalmente para la resolución de problemas |
model |
El modelo asociado con la respuesta | Confirma que coincide con la ruta que querías probar |
choices[0].message.content |
La salida del asistente | Confirma que tu aplicación puede extraer el texto |
usage |
El recuento de tokens devuelto con la llamada | Regístralo para comprobaciones de coste y regresión |
Una respuesta simplificada se ve así:
{
"id": "chatcmpl-example",
"model": "YOUR_CURRENT_MODEL",
"choices": [
{
"message": {
"role": "assistant",
"content": "flatkey quickstart connected"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 5,
"total_tokens": 17
}
}
Los identificadores exactos y los recuentos de tokens diferirán. Tu condición de éxito en la primera llamada no es una coincidencia byte a byte; es una respuesta HTTP válida, un mensaje del asistente que se pueda analizar y la información de uso que tu aplicación pueda registrar.
Paso 5: Revisa el uso después de la llamada
No te detengas en 200 OK. Un quickstart útil también demuestra que la solicitud es visible para las personas que operarán la integración.
Referencia de consola
Abre Consola → Uso & Registros después de la solicitud.
Busca la nueva llamada y confirma los detalles disponibles para tu cuenta, como:
- Hora de la solicitud.
- Modelo o ruta.
- Estado.
- Uso de tokens.
- Impacto en el coste o en el saldo.
- Detalles del error cuando una solicitud falla.
Si la aplicación recibió una respuesta pero falta la entrada de registro esperada, primero comprueba que estás viendo la misma cuenta, espacio de trabajo y clave API utilizados por la solicitud. También registra el ID de la respuesta y la hora de la solicitud antes de reintentar; esos dos detalles facilitan mucho la resolución de problemas.
Revisa la página de precios de Flatkey actual antes de pasar de una prueba de humo a una carga de trabajo sostenida. Compara el modelo, el volumen de solicitudes, la mezcla de tokens y el comportamiento de respaldo que esperas usar, no solo el coste de una sola llamada exitosa.
Paso 6: Añade una secuencia de respaldo segura
El enrutamiento de respaldo debe ir después de que funcione el primer modelo. De lo contrario, una ruta de respaldo puede ocultar el problema real: una clave inválida, una URL base incorrecta, un modelo no disponible, una solicitud mal formada o un límite de cuenta.
Empieza con una lista corta ordenada de modelos que hayas probado para el mismo trabajo:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url="https://router.flatkey.ai/v1",
)
models = [
"PRIMARY_CURRENT_MODEL",
"FALLBACK_CURRENT_MODEL",
]
last_error = None
for model in models:
try:
response = client.chat.completions.create(
model=model,
messages=[
{
"role": "user",
"content": "Return JSON with one key named status and value ok",
}
],
temperature=0,
)
print(model, response.choices[0].message.content)
break
except Exception as error:
last_error = error
print(f"Route failed: {model}")
else:
raise RuntimeError("All approved model routes failed") from last_error
Este ejemplo es intencionalmente pequeño. Antes de usarlo en producción, añade:
- Una lista limitada de errores reintentables.
- Un tiempo de espera por intento y una fecha límite total de la solicitud.
- Backoff para fallos transitorios.
- Registros estructurados que contengan el modelo intentado y el ID de respuesta.
- Validación de salida para JSON, llamadas a herramientas u otros esquemas requeridos.
- Un techo de coste para que el fallback no seleccione silenciosamente una ruta inadecuada.
No reintentes errores de autenticación con varios modelos. No reintentes solicitudes mal formadas hasta que la solicitud se corrija. No trates todos los modelos como intercambiables solo porque acepten un payload de chat completions.
Una política práctica de fallback
Usa esta tabla de decisiones como punto de partida:
| Fallo | ¿Reintentar el mismo modelo? | ¿Probar un fallback aprobado? | Acción |
|---|---|---|---|
| Tiempo de espera de red | Una vez, dentro del plazo | Sí | Conserva el ID de solicitud original y registra ambos intentos |
| Límite de tasa | Después del backoff | Sí | Respeta la guía de reintentos y limita la demora total |
| Error temporal del servidor | Una vez | Sí | Detente después de agotar la lista de rutas aprobadas |
| Clave de API no válida | No | No | Rota o corrige las credenciales |
| Modelo desconocido/no disponible | No | Sí | Actualiza la elección del modelo; no hagas bucles con el mismo nombre |
| Esquema de solicitud no válido | No | No | Corrige y valida el payload |
| La salida falla la validación | Quizás | Sí | Reintenta solo cuando el flujo de trabajo defina una regla de validación |
La regla principal es simple: reintenta fallos transitorios de transporte; corrige errores de configuración y de esquema; usa un fallback solo cuando el fallback esté aprobado para el mismo trabajo de producto.
Errores comunes en la primera llamada
401 o fallo de autenticación
Confirma que la solicitud usa Authorization: Bearer <key>, que la clave está activa y que no se copió espacio en blanco adicional. Verifica que la aplicación esté leyendo la variable de entorno esperada.
404 o endpoint incorrecto
Usa la URL base compatible con OpenAI https://router.flatkey.ai/v1 y la ruta de chat /chat/completions. Evita añadir accidentalmente /v1 dos veces.
No se encuentra el modelo o no está disponible
Elige un modelo actualmente disponible del catálogo en vivo o de la consola. No asumas que el nombre de un modelo de un tutorial antiguo sigue habilitado para tu cuenta.
Respuesta HTTP correcta pero error de aplicación
Registra la respuesta sin procesar una vez en un entorno de desarrollo seguro. Confirma que tu código lea choices[0].message.content para chat completions y no espere el esquema de respuesta de otro endpoint.
Gasto inesperado durante el fallback
Registra el modelo intentado en cada llamada, limita la lista de rutas y revisa Usage & Logs. Una política de fallback sin un plazo límite ni un límite de coste puede convertir una acción de usuario en varias solicitudes facturables.
Lista de verificación de producción
Antes de enviar tráfico real a través de la integración, confirma:
- [ ] La clave de API se almacena en un gestor de secretos o en un entorno del lado del servidor.
- [ ] Desarrollo, staging y producción usan claves separadas.
- [ ] La URL base es una configuración, no está codificada en toda la base de código.
- [ ] El modelo seleccionado está disponible y probado para la carga de trabajo real.
- [ ] Los timeouts, los errores reintentables y los plazos totales están definidos explícitamente.
- [ ] Los modelos de fallback usan el mismo contrato de salida requerido.
- [ ] Los registros de uso y errores son visibles para el equipo de operaciones.
- [ ] Las expectativas de coste se verificaron con los precios actuales.
- [ ] Los límites de clave o las listas de अनुमति están configurados cuando corresponde.
- [ ] Un camino de rollback puede restaurar rápidamente la ruta anterior.
Haz la primera llamada, luego optimiza
La forma más rápida de evaluar Flatkey es mantener la primera prueba acotada. Crea una clave, cambia una URL base, envía una solicitud, lee una respuesta y encuentra la misma llamada en Uso & Logs.
Una vez que ese flujo esté verificado, añade el enrutamiento de fallback como una política observable en lugar de un bucle de reintento oculto. Mantén corta la lista de modelos aprobados, conserva la evidencia de los errores, valida la salida y revisa los precios actuales antes de aumentar el tráfico.
Cuando estés listo, crea una cuenta de Flatkey, haz la primera llamada a través de router.flatkey.ai y usa el registro de la consola como prueba de aceptación de tu integración.
