Si tu aplicación ya usa una API compatible con OpenAI, pasar a Flatkey no debería empezar con una reescritura. La ruta controlada es más pequeña: consigue una clave de Flatkey, apunta tu SDK compatible con OpenAI a https://router.flatkey.ai/v1, elige un ID de modelo del catálogo de Flatkey y verifica la primera solicitud en los registros, las cuotas y la facturación antes de enviar tráfico real.
Ese es el valor práctico de una API compatible con OpenAI. Permite que un equipo mantenga el mismo modelo mental para solicitudes comunes mientras mueve el acceso al proveedor detrás de una única puerta de enlace. El texto público del producto de Flatkey está construido alrededor de ese movimiento: una clave de API, una URL base, precios claros, facturación unificada y un único panel para claves, uso y enrutamiento.
Esta guía muestra el runbook de migración. Cubre el cambio de URL base, ejemplos de SDK, el mapeo de IDs de modelo, pruebas de humo, verificaciones de endpoints, revisión de registros de uso, configuración de cuotas, verificación de facturación y reversión. Úsala cuando estés moviendo un flujo de trabajo existente estilo Chat Completions a Flatkey o estandarizando una pila multimodelo detrás de un único endpoint de API compatible con OpenAI.
Respuesta rápida: ¿Qué cambia en una migración a una API compatible con OpenAI?
Para la mayoría de los clientes de chat existentes compatibles con OpenAI, la primera migración es un cambio de configuración, no una reescritura de la aplicación.
| Configuración | Antes | Con Flatkey |
|---|---|---|
| Clave de API | Clave específica del proveedor de OpenAI, Gemini, DeepSeek o proxy | Clave de API de Flatkey |
| URL base | Predeterminada del proveedor u otra URL base compatible con OpenAI | https://router.flatkey.ai/v1 |
| Endpoint de chat | /v1/chat/completions |
/v1/chat/completions a través de Flatkey |
| Modelo | ID de modelo del proveedor existente | ID de modelo de Flatkey seleccionado desde precios/panel |
| Validación | Solo una respuesta exitosa | Respuesta + registro de uso + coste + cuota + reversión |
La palabra importante es "compatible". Una API compatible con OpenAI no garantiza que cada proveedor, modelo, endpoint y parámetro se comporte exactamente como OpenAI. Significa que la API sigue lo suficiente del patrón de solicitud y respuesta de OpenAI para que las llamadas comunes del cliente funcionen cuando la URL base, la clave y el modelo son correctos. Tu lista de verificación de migración debe demostrar las funciones exactas que usa tu aplicación.
Por qué los endpoints compatibles con OpenAI se están convirtiendo en la capa de migración
Los resultados de búsqueda para OpenAI compatible API son, en su mayoría, referencias oficiales, documentación de proveedores, plugins, documentación de servidores locales y preguntas de la comunidad. Eso tiene sentido. Los desarrolladores no solo están preguntando «¿qué es compatible?». Están intentando mover código entre proveedores de modelos sin cambiar cada punto de llamada.
La documentación de Gemini de Google muestra ejemplos de la biblioteca OpenAI que configuran una base URL compatible con OpenAI de Gemini y llaman a completions de chat. La documentación oficial de la API de DeepSeek muestra ejemplos del SDK de OpenAI con la base URL de DeepSeek y IDs de modelo como deepseek-chat y deepseek-reasoner. El patrón es claro: muchos proveedores se encuentran con los desarrolladores allí donde ya están sus SDKs existentes.
Flatkey usa la misma idea de migración para un objetivo diferente. En lugar de apuntar la OpenAI compatible API de un proveedor a la cuenta de un proveedor, Flatkey ofrece a los equipos una única base URL compatible con OpenAI para acceso multi-modelo, facturación unificada y visibilidad en el panel.
Paso 1: Inventaria el cliente que ya tienes
Antes de cambiar la URL base, anota lo que realmente usa tu app actual. Una migración limpia de OpenAI compatible API empieza con la forma de la llamada en producción, no con una nueva app de ejemplo.
| Comprobar | Qué registrar |
|---|---|
| SDK | Python, Node, HTTP directo, LangChain, LiteLLM, Vercel AI SDK u otro wrapper. |
| Endpoint | Chat Completions, Responses, embeddings, imágenes, video o endpoint nativo del proveedor. |
| ID del modelo | Cadena exacta usada en producción y cualquier modelo de respaldo. |
| Forma del mensaje | Prompts del sistema, mensajes del desarrollador, mensajes de herramientas, contenido multimodal o solo texto plano. |
| Parámetros | Streaming, temperature, max tokens, tool calls, salida JSON, formato de respuesta, seed, timeout, reintentos. |
| Observabilidad | Dónde ves hoy la latencia, el uso de tokens, los IDs de solicitud, los errores y el coste. |
| Rollback | Con qué rapidez puedes restaurar la clave API, la URL base o el modelo antiguos. |
Este inventario mantiene honesta la migración. Si tu app solo envía mensajes simples de chat, la primera prueba de Flatkey puede seguir siendo pequeña. Si tu app depende de streaming, tool calls, modo JSON, imágenes, video o la API de Responses, trata cada función como una prueba de humo separada.
Paso 2: Coloca la URL base detrás de una sola capa de configuración
No disperses la nueva URL base compatible con OpenAI por todo el código base. Ponla en una sola variable de entorno o en una sola fábrica del SDK.
Variables de entorno recomendadas:
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="replace-with-publish-day-model-id"
ROLLBACK_OPENAI_BASE_URL="https://api.openai.com/v1"
ROLLBACK_MODEL="your-previous-model-id"Usar OPENAI_BASE_URL suele ser conveniente porque muchos wrappers de SDK ya admiten esa convención. Usar FLATKEY_API_KEY y FLATKEY_MODEL mantiene explícita la nueva credencial y la elección del modelo.
Aquí es donde Flatkey encaja con la intención de búsqueda openai compatible base url. La migración debería poder revisarse en un solo diff: URL base, clave, modelo y pasos de verificación.
Paso 3: Ejecuta una prueba de humo con Curl
Comienza con una solicitud HTTP directa antes de cambiar tu aplicación. Esto aísla problemas de clave, URL base, endpoint e ID de modelo.
Solo plantilla: el revisor debe ejecutarlo con una clave Flatkey válida y un ID de modelo confirmado del día de publicación.
curl -sS "https://router.flatkey.ai/v1/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{
"role": "user",
"content": "Responde con una sola frase confirmando que esta prueba de humo de Flatkey funcionó."
}
]
}'Una prueba de humo útil demuestra más que 200 OK. Para una migración de API compatible con OpenAI, verifica:
- La respuesta tiene un mensaje de asistente utilizable.
- El nombre del modelo es el que pretendías probar.
- El uso aparece en el panel de Flatkey o en los registros de uso.
- El recuento de tokens y el costo son visibles lo suficiente para la revisión de facturación.
- Los mensajes de error son comprensibles si el ID del modelo o la clave son incorrectos.
- La URL base y el modelo anteriores aún se pueden restaurar rápidamente.
Paso 4: Cambiar la configuración del SDK de OpenAI para Python
Si tu aplicación Python ya usa el SDK de OpenAI, mantén centralizada la construcción del cliente.
Solo plantilla: el revisor debe ejecutar antes de la publicación.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_MODEL"],
messages=[
{
"role": "user",
"content": "Confirm this OpenAI compatible API request is routed through Flatkey.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)El detalle de Python que importa es base_url. En una migración limpia de OpenAI compatible API, el código de la aplicación no debería saber si la URL base apunta directamente a OpenAI, a un endpoint compatible de un proveedor o a Flatkey. Debe llamar al cliente compartido y dejar que la configuración elija la ruta.
Paso 5: Cambiar la configuración del SDK de Node OpenAI
Para aplicaciones Node, la configuración equivalente usa baseURL.
Solo plantilla: el revisor debe ejecutarlo antes de la publicación.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_MODEL,
messages: [
{
role: "user",
content: "Confirma que esta solicitud de API compatible con OpenAI se enruta a través de Flatkey.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);Este es el mismo patrón de migración que se ve en la documentación de los proveedores: mantén el SDK, establece una base URL diferente, proporciona una clave API compatible y elige un ID de modelo que exista en la plataforma de destino.
Paso 6: Asigna los IDs de modelo de forma deliberada
La cadena del modelo es donde fallan muchas migraciones de API compatible con OpenAI. Una URL base puede ser compatible mientras que los IDs de modelo siguen siendo específicos del proveedor.
No asumas:
- Que el nombre de tu modelo anterior exista en Flatkey.
- Que el alias de modelo de un proveedor apunte a la misma versión detrás de una puerta de enlace.
- Que todos los modelos compatibles admitan la misma familia de endpoints.
- Que un modelo que funciona para chat también funcione para visión, herramientas, imágenes, video o Responses.
En su lugar, usa esta tabla de mapeo antes de la primera prueba a nivel de aplicación:
| Uso actual de la aplicación | Verificación en Flatkey |
|---|---|
| Chat de texto | Elige un modelo de Flatkey que admita el endpoint de chat de OpenAI. |
| Chat en streaming | Prueba el streaming por separado con el mismo prompt y margen de tiempo de espera. |
| Llamada a herramientas/funciones | Verifica que el modelo y el endpoint seleccionados admitan la estructura de tool-call que envía tu aplicación. |
| Salida JSON | Prueba tu response_format exacto o el patrón de salida estructurada. |
| Entrada de visión/imagen | Confirma que el modelo seleccionado acepte el formato de entrada de imagen que envía tu SDK. |
| API de Responses | Confirma que el endpoint/modelo de Flatkey admita /v1/responses para tu caso de uso. |
| Generación de imágenes o video | Trátalo como una migración de endpoint separada, no como una migración de chat-completions. |
La instantánea de precios de Flatkey del 11 de junio de 2026 mostró familias de endpoints para completions de chat de OpenAI, Responses de OpenAI, mensajes de Anthropic, Gemini, generación de imágenes y video de OpenAI. Eso es una prueba útil para revisores, pero el artículo aún debería empujar a los lectores a confirmar el modelo exacto y la función que planean usar el día de la publicación.
Paso 7: Verificar registros, cuotas y facturación
Una respuesta exitosa de OpenAI compatible API es solo el primer punto de control. La razón para migrar a través de Flatkey no es solo la forma de la solicitud; es la superficie operativa alrededor del acceso al modelo.
Después de la prueba de humo, verifique:
| Área | Qué inspeccionar |
|---|---|
| Registro de uso | La solicitud aparece con marca de tiempo, modelo, uso de tokens, estado y detalles de error, si los hay. |
| Facturación | El costo es visible y coincide con la unidad de modelo/precio esperada. |
| Cuota | Se puede establecer una cuota pequeña para la nueva clave o ruta de prueba antes de una implementación más amplia. |
| Enrutamiento | La solicitud se enruta a través de la ruta de Flatkey prevista, no a través de una configuración antigua y directa del proveedor. |
| Comportamiento de error | Los errores de clave incorrecta, modelo incorrecto y parámetro no compatible son lo suficientemente claros para soporte. |
| Reversión | Restaurar la URL base/modelo anterior funciona sin cambios de código. |
Aquí es donde una puerta de enlace OpenAI compatible API resulta más útil que un endpoint de proveedor sin procesar. El cambio de la URL base debería traducirse en una mejor visibilidad, no solo en un upstream diferente.
Paso 8: Despliegue por etapas
No mueva todos los flujos de trabajo a la vez. Use un despliegue por etapas:
- Ejecute una prueba de humo directa con curl.
- Ejecute una prueba de humo de un SDK en local o staging.
- Reproduzca un pequeño conjunto de prompts conocidos y compare la forma de la salida.
- Habilite streaming o parámetros avanzados solo después de que pase la llamada básica.
- Establezca una cuota baja en la clave de prueba.
- Envíe un pequeño porcentaje del tráfico no crítico.
- Compare errores, latencia, uso de tokens y coste.
- Aumente el tráfico solo después de que los registros y la facturación coincidan con las expectativas.
Este flujo mantiene la promesa de API compatible con OpenAI vinculada a la realidad de producción. La compatibilidad no es un eslogan; es un resultado de prueba para las llamadas que su aplicación envía realmente.
Lista de verificación de migración
Úselo como el recurso de la página de publicación.
| Paso | ¿Hecho? | Notas |
|---|---|---|
| El SDK y el endpoint actuales están documentados | Python, Node, HTTP, wrapper, chat, respuestas, imagen, video, etc. | |
| Se crea la clave Flatkey | Use una clave de prueba separada cuando sea posible. | |
| La URL base está centralizada | https://router.flatkey.ai/v1 debe vivir en la configuración, no dispersa en el código. |
|
| El ID del modelo se selecciona desde Flatkey | Confirme el ID del modelo del día de publicación desde precios o el panel. | |
| La prueba rápida con Curl pasa | La plantilla debe ser probada por un revisor antes de publicar. | |
| La prueba rápida con el SDK de Python o Node pasa | Use el SDK que su aplicación realmente ejecuta. | |
| Las funciones de streaming/herramientas/JSON/visión se prueban | Pruebe solo las funciones que usa. | |
| El registro de uso es visible | Confirme el modelo, el estado, los tokens y los errores en el panel. | |
| Se revisan la facturación y la unidad de precios | No asuma que las unidades de precios del proveedor son idénticas. | |
| El límite de cuota está configurado | Mantenga acotado el tráfico de migración. | |
| Las variables de entorno para rollback están listas | La URL base y el modelo antiguos pueden restaurarse sin cambios de código. |
Errores comunes
El error de migración más común de una API compatible con OpenAI es cambiar la URL base y asumir que todo lo demás es idéntico. Evita estas trampas:
- Codificar la URL base de Flatkey en varios archivos.
- Mantener un ID de modelo antiguo del proveedor que Flatkey no enruta.
- Probar solo sin streaming cuando producción usa streaming.
- Omitir las pruebas de llamadas a herramientas o de salida JSON.
- Mover endpoints de imagen/vídeo como si fueran endpoints de chat-completions.
- Olvidar actualizar reintentos, presupuestos de tiempo de espera y análisis de errores.
- Dar por terminada la migración antes de que el uso y la facturación sean visibles.
Flatkey reduce la dispersión de cuentas de proveedor y de enrutamiento, pero no elimina la necesidad de una prueba de migración cuidadosa.
Cuando Flatkey es una buena opción
Flatkey encaja bien cuando tu equipo quiere una sola URL base de API compatible con OpenAI para acceso a múltiples modelos en lugar de cuentas de proveedor, claves, facturación y comprobaciones de enrutamiento separadas.
Usa Flatkey cuando:
- Tu aplicación ya usa un SDK compatible con OpenAI.
- Quieres una sola clave para modelos de proveedores como GPT, Claude, Gemini, DeepSeek, Qwen, Seedance 2.0 y GPT Image.
- Quieres ver el uso, la facturación, las claves y el enrutamiento en un solo panel.
- Quieres límites de cuota antes de que aumente el tráfico.
- Quieres que el cambio de modelo y el comportamiento de balanceo de carga sean gestionados por la capa de gateway.
- Quieres que la ruta de migración sea "cambiar la URL base, verificar el modelo, supervisar el uso" en lugar de "reescribir la integración del modelo".
Usa una cuenta directa del proveedor o un proxy autohospedado cuando necesites contratos específicos del proveedor, lógica de enrutamiento totalmente personalizada o control del gateway local a la infraestructura.
FAQ
¿Es una API compatible con OpenAI lo mismo que OpenAI?
No. Una API compatible con OpenAI sigue el patrón de solicitudes y respuestas al estilo OpenAI para los endpoints compatibles, pero el proveedor, los IDs de modelo, la autenticación, el soporte de funciones, los precios y el comportamiento de errores pueden diferir.
¿Necesito reemplazar mi SDK para usar Flatkey?
Normalmente no para las migraciones comunes de chat-completions. Si tu SDK admite una URL base personalizada, a menudo puedes conservar el SDK y cambiar la configuración. Esa es la principal ventaja de una migración a una API compatible con OpenAI.
¿Cuál es la URL base compatible con OpenAI de Flatkey?
Usa https://router.flatkey.ai/v1 como URL base compatible con OpenAI. Para completions de chat, el endpoint completo es https://router.flatkey.ai/v1/chat/completions.
¿Puedo conservar el nombre de mi modelo existente?
Solo si ese ID de modelo está disponible y es compatible a través de Flatkey. Revisa pricing o el panel, y luego prueba el ID exacto del modelo antes de desplegar.
¿Debo migrar primero Chat Completions o Responses?
Migra el endpoint que usa tu aplicación actual. Las aplicaciones existentes de Chat Completions pueden comenzar con /v1/chat/completions. Si tu aplicación usa la API de Responses, prueba /v1/responses por separado y confirma que el modelo seleccionado admite las funciones que necesitas.
¿Cómo revierto los cambios?
Mantén la URL base antigua, la clave de API y el modelo en la configuración hasta que se verifiquen los registros, el costo, la cuota y el comportamiento de la aplicación en Flatkey. La reversión debería ser un cambio de variables de entorno, no una reescritura del código.
Obtener una clave
Si ya tienes una aplicación construida alrededor de una API compatible con OpenAI, Flatkey mantiene la migración pequeña: obtén una clave, cambia la URL base, elige un modelo, ejecuta la prueba de humo y supervisa el uso en un solo panel.
Obtener una clave, luego usa https://router.flatkey.ai/v1 como la URL base para tu primera prueba de migración con Flatkey.
