La configuración de la URL base del proveedor personalizado del Vercel AI SDK es más que un simple reemplazo de cadena. La parte útil es apuntar el proveedor del AI SDK a Flatkey, pero el trabajo seguro de producción es verificar los alias de los modelos, la familia de endpoints, el comportamiento del streaming, las llamadas a herramientas, la evidencia de uso, los controles de cuota y la reversión antes de que se mueva el tráfico de usuarios.
Esta guía es para desarrolladores, equipos de productos de IA, ingenieros de plataforma, creadores de automatización, operadores financieros y revisores de adquisiciones que utilizan el AI SDK en una ruta de Next.js, una acción de servidor, un worker, una cola o un bucle de agente. Fue actualizada el 29 de junio de 2026 a partir de la documentación actual del AI SDK, una verificación de tipos con los paquetes actuales del AI SDK y las páginas públicas de Flatkey en vivo. Los fragmentos de código son plantillas. No se dispuso de una clave de API de Flatkey en vivo para esta tarea, así que ejecuta las pruebas de humo con tu propia clave, la URL base actual de la consola de Flatkey y los alias de modelo habilitados para tu cuenta.
Respuesta rápida: URL base del proveedor personalizado del Vercel AI SDK
Para una configuración de URL base de proveedor personalizado del Vercel AI SDK con Flatkey, comienza con el paquete de proveedor oficial compatible con OpenAI. Crea un proveedor con createOpenAICompatible, establece baseURL a la URL base actual de Flatkey desde tu consola, establece apiKey a tu clave de Flatkey y utiliza los alias de modelo de Flatkey en generateText o streamText.
npm install ai @ai-sdk/openai-compatible zodexport FLATKEY_API_KEY="fk_your_key"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1" # Copia el valor actual de Flatkey
export FLATKEY_MODEL="your-flatkey-model-alias"import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';
function requiredEnv(name: string): string {
const value = process.env[name];
if (!value) {
throw new Error(`Falta ${name}`);
}
return value;
}
const flatkey = createOpenAICompatible({
name: 'flatkey',
apiKey: requiredEnv('FLATKEY_API_KEY'),
baseURL: requiredEnv('FLATKEY_BASE_URL'),
includeUsage: true,
});
const result = await generateText({
model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
prompt: 'Responde con una breve comprobación de enrutamiento del AI SDK de Flatkey.',
});
console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);
console.log(result.warnings);Esa es la forma mínima de funcionamiento para una migración de URL base de proveedor personalizado del Vercel AI SDK. No te detengas ahí. Una respuesta de texto exitosa solo demuestra que una forma de solicitud llegó a un alias de modelo. No demuestra el uso de streaming, herramientas, salida estructurada, visibilidad de costos, comportamiento de cuotas o reversión.
¿Qué admiten los documentos actuales del AI SDK?
La documentación actual del AI SDK tiene dos rutas relevantes. El paquete de proveedor compatible con OpenAI está diseñado para proveedores que implementan la API de OpenAI. Expone createOpenAICompatible con opciones que incluyen name, apiKey, baseURL, headers, queryParams, fetch personalizado, includeUsage, supportsStructuredOutputs, transformaciones del cuerpo de la solicitud y extracción de metadatos.
El paquete de proveedor de OpenAI también admite createOpenAI({ baseURL }) para configuraciones personalizadas, incluidos los servidores proxy. El proveedor compatible con OpenAI es la opción predeterminada más limpia para una URL base de proveedor personalizado del Vercel AI SDK porque su nombre de proveedor, la extracción de metadatos personalizados, las opciones específicas del proveedor y los nombres de fábrica de modelos están diseñados para rutas compatibles con OpenAI que no son de OpenAI.
| Patrón de proveedor | Cuándo usarlo | Punto de revisión de Flatkey |
|---|---|---|
createOpenAICompatible |
Quieres un proveedor Flatkey con nombre para modelos de chat, streaming, herramientas, embeddings, imágenes o finalización compatibles con OpenAI. | Punto de partida preferido para una integración con Flatkey porque name: 'flatkey' hace que las opciones específicas del proveedor y los metadatos sean más fáciles de razonar. |
createOpenAI({ baseURL }) |
Tu base de código ya está estandarizada en @ai-sdk/openai y solo necesitas una URL base personalizada de estilo proxy. |
Sé explícito sobre el comportamiento de .chat(...) frente a Responses; no asumas que los valores predeterminados del proveedor de OpenAI coinciden con todas las rutas de Flatkey. |
| Wrapper de fetch sin procesar | Necesitas una transformación de cuerpo no estándar o un endpoint que el proveedor del AI SDK no cubre. | Mantén esto como una excepción. Pierdes la forma de resultado normalizada del SDK, los ayudantes de herramientas y los ayudantes de stream con tipo. |
Evidencia reciente de Flatkey para usar con cuidado
La página de inicio de Flatkey, consultada el 29 de junio de 2026, tiene el título One API gateway for production AI teams y una meta descripción que dice que Flatkey unifica el acceso a modelos, el enrutamiento, la facturación, el análisis de uso y los controles operativos. La API de precios en vivo devolvió 633 filas de modelos, 23 proveedores y familias de endpoints para /v1/chat/completions, /v1/responses, /v1/messages, /v1beta/models/{model}:generateContent, /v1/images/generations y /v1/video/generations.
Usa esos datos como evidencia pública fechada para el posicionamiento y la forma del catálogo, no como prueba de que cada cuenta puede llamar a cada ruta, que cada alias de modelo está disponible o que cada característica está habilitada. Antes del tráfico de producción, tus comprobaciones de URL base de proveedor personalizado del Vercel AI SDK deben usar la clave, la URL base, el alias de modelo, la familia de endpoints y la ruta de características exactas que enviará tu aplicación.
URL base y configuración del entorno
Mantén la URL base, la clave y el alias del modelo en variables de entorno. Eso hace que un despliegue de URL base de proveedor personalizado para Vercel AI SDK sea revisable en la configuración de implementación en lugar de estar oculto dentro de los manejadores de rutas, archivos de prompts y workers.
function requiredEnv(name: string): string {
const value = process.env[name];
if (!value) {
throw new Error(`Missing ${name}`);
}
return value;
}
const flatkey = createOpenAICompatible({
name: 'flatkey',
apiKey: requiredEnv('FLATKEY_API_KEY'),
baseURL: requiredEnv('FLATKEY_BASE_URL'),
includeUsage: true,
});Luego, mantén el enrutamiento de la carga de trabajo separado de la configuración de transporte. La URL base le dice al SDK a dónde enviar las solicitudes. El alias del modelo decide qué ruta de Flatkey y qué modelo upstream estás solicitando.
const MODEL_ROUTES = {
supportTriage: 'FLATKEY_SUPPORT_MODEL',
workflowPlanning: 'FLATKEY_PLANNING_MODEL',
codeReview: 'FLATKEY_CODE_MODEL',
fallback: 'FLATKEY_FALLBACK_MODEL',
} as const;
function modelFor(routeName: keyof typeof MODEL_ROUTES) {
return flatkey.chatModel(requiredEnv(MODEL_ROUTES[routeName]));
}Este patrón evita que los equipos dispersen nombres de proveedores, alias de modelos y URL base por todo el código base. También proporciona a los equipos de finanzas y operaciones un conjunto estable de nombres de carga de trabajo para comparar con las filas de uso.
Prueba de humo primero con texto sin streaming
Comienza con generateText. Te proporciona un objeto de resultado directo con texto, motivo de finalización, uso, advertencias, pasos y metadatos de respuesta. Úsalo para probar la autenticación, la forma de la URL base, el alias del modelo y la visibilidad del uso antes de probar el streaming o las herramientas.
import { generateText } from 'ai';
const result = await generateText({
model: modelFor('supportTriage'),
prompt: 'Reply with one short migration readiness check.',
});
console.log({
text: result.text,
finishReason: result.finishReason,
usage: result.usage,
warnings: result.warnings,
});Aprueba esta primera verificación de URL base de proveedor personalizado para Vercel AI SDK solo si los campos de texto generado, alias del modelo, motivo de finalización y uso son suficientes para las necesidades de registro y revisión de tu aplicación. Si la llamada devuelve texto pero el uso no se puede encontrar en los registros de Flatkey, la migración no está lista para producción.
Prueba el streaming por separado
El streaming tiene una superficie de fallo diferente. Afecta a la transmisión de respuestas, los tiempos de espera sin servidor, la cancelación de la interfaz de usuario, el manejo de errores y la contabilidad del uso. La documentación del AI SDK muestra streamText, result.textStream, una devolución de llamada onError y promesas de resultado como result.usage. El proveedor compatible con OpenAI también tiene includeUsage para los metadatos de respuesta de streaming cuando el proveedor lo admite.
import { streamText } from 'ai';
const stream = streamText({
model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
prompt: 'Stream three short setup checks.',
onError({ error }) {
console.error(error);
},
});
for await (const textPart of stream.textStream) {
process.stdout.write(textPart);
}
const usage = await stream.usage;
console.log({ usage });Mantén el streaming habilitado solo después de que el alias del modelo de Flatkey seleccionado demuestre ser estable bajo la forma de tu solicitud real. Si el texto transmitido funciona pero el uso está incompleto, decide si tu equipo puede recopilar el uso de los registros de Flatkey en lugar de la respuesta del stream antes de que se mueva el tráfico de usuarios.
Verifica las llamadas a herramientas con el mismo alias
La API de herramientas del AI SDK utiliza un objeto tools, el ayudante tool, un inputSchema y una función execute opcional. Una pasada de chat simple no aprueba la llamada a herramientas. Prueba primero un esquema pequeño y luego amplía al conjunto de herramientas que tus agentes realmente utilizan.
import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';
const result = await generateText({
model: flatkey.chatModel(requiredEnv('FLATKEY_TOOL_MODEL')),
tools: {
routeReadiness: tool({
description: 'Return the readiness state for a Flatkey route.',
inputSchema: z.object({
routeName: z.string().describe('Internal route name to inspect'),
}),
execute: async ({ routeName }) => ({
routeName,
checked: true,
}),
}),
},
stopWhen: isStepCount(2),
prompt: 'Use the tool for route supportTriage.',
});
console.log(result.toolCalls);
console.log(result.toolResults);
console.log(result.usage);Para el tráfico de agentes, registra si el modelo llamó a la herramienta esperada, si la entrada se validó, si el resultado de la herramienta se devolvió limpiamente y si la fila de uso de Flatkey se puede vincular a la misma ruta. Si los esquemas estrictos, los flujos de aprobación o las llamadas a herramientas en paralelo son importantes, prueba esas características con el alias exacto del modelo.
Cuándo usar createOpenAI en su lugar
Si tu aplicación ya usa @ai-sdk/openai en todas partes, la opción baseURL del proveedor de OpenAI puede ser una ruta de migración con menos diferencias. Esto sigue siendo una configuración de URL base de proveedor personalizado para Vercel AI SDK, pero debes ser más explícito sobre la selección de la API del modelo.
import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
const flatkeyViaOpenAIProvider = createOpenAI({
name: 'flatkey',
apiKey: requiredEnv('FLATKEY_API_KEY'),
baseURL: requiredEnv('FLATKEY_BASE_URL'),
});
const result = await generateText({
model: flatkeyViaOpenAIProvider.chat(requiredEnv('FLATKEY_MODEL')),
prompt: 'Reply with one short OpenAI-provider base URL check.',
});La documentación actual del proveedor de OpenAI dice que Responses es la API predeterminada para el proveedor de OpenAI desde el AI SDK 5, a menos que especifiques una ruta como .chat(...). Es por eso que el ejemplo anterior usa .chat(...) explícitamente. Si tienes la intención de probar la familia de endpoints /v1/responses de Flatkey, trátala como una verificación de ruta separada con un alias de modelo y una ruta de reversión (rollback) distintos.
Lista de verificación de configuración
| Verificación | Qué capturar | Por qué es importante |
|---|---|---|
| URL base | Valor actual de la consola de Flatkey, incluido el prefijo /v1 cuando sea necesario. |
Los segmentos de ruta faltantes y los hosts obsoletos crean confusos errores 404. |
| Elección del proveedor | createOpenAICompatible o createOpenAI({ baseURL }). |
La elección del proveedor afecta los valores predeterminados, los metadatos, las opciones específicas del proveedor y las fábricas de modelos. |
| Alias del modelo | La cadena de modelo exacta de Flatkey para cada ruta de carga de trabajo. | El nombre de una familia de proveedores no es suficiente para una solicitud de producción. |
| Ruta de la característica | Texto sin formato, streaming, herramientas, salida estructurada, imágenes o Responses. | La aprobación de una característica no aprueba la ruta de otra característica. |
| Registro de uso | Marca de tiempo, clave, ruta, alias del modelo, motivo de finalización, tokens, unidad de costo y metadatos del propietario donde estén disponibles. | Los revisores de operaciones y finanzas necesitan encontrar la solicitud sin tener que adivinar. |
| Reversión (Rollback) | Clave anterior, URL base, modelo, indicador de implementación y umbral de error. | La reversión debe ser un cambio de configuración, no una reescritura de código durante un incidente. |
Modos de fallo comunes
| Síntoma | Causa probable | Solución |
|---|---|---|
| 404 desde la solicitud del AI SDK | A la URL base le falta /v1, apunta al host incorrecto o utiliza la familia de endpoints equivocada. |
Copia el valor actual de la consola de Flatkey y vuelve a ejecutar la verificación más pequeña de generateText. |
| 401 o 403 | El proceso cargó la clave incorrecta o mezcló OPENAI_API_KEY y FLATKEY_API_KEY. |
Registra solo los nombres de las variables de entorno cargadas, nunca los valores secretos, y confirma el acceso a la clave de Flatkey. |
| El chat simple funciona pero las llamadas a herramientas fallan | El alias o la familia de endpoints seleccionados no son compatibles con tu esquema de herramientas. | Prueba primero el esquema de Zod más pequeño, luego agrega rigurosidad, aprobación y bucles de varios pasos. |
| El texto en streaming funciona pero el uso está vacío | La ruta transmite contenido pero no devuelve metadatos de uso transmitidos. | Verifica los registros de uso de Flatkey y decide si el uso de la respuesta de streaming es necesario para el lanzamiento. |
| Las opciones específicas del proveedor desaparecen | La solicitud utiliza el nombre de proveedor incorrecto o una opción personalizada no compatible. | Usa name: 'flatkey' y prueba cualquier campo providerOptions.flatkey antes de depender de él. |
Dónde encaja esto con otras guías de Flatkey
Si necesitas una ruta de migración más amplia, comienza con la guía de migración de API compatibles con OpenAI. Para patrones de configuración de herramientas adyacentes, revisa la guía de configuración de la API de Cherry Studio y la guía de cc-switch Claude Code Flatkey. Usa los precios de Flatkey para inspeccionar el catálogo de modelos actual, y luego obtén una clave cuando estés listo para ejecutar las pruebas de humo en tu propia cuenta.
Preguntas frecuentes
¿Cómo configuro una URL base de proveedor personalizado del Vercel AI SDK para Flatkey?
Crea un proveedor compatible con OpenAI con createOpenAICompatible, establece baseURL en la URL base actual de Flatkey, establece apiKey en tu clave de Flatkey y pasa un alias de modelo de Flatkey a generateText o streamText.
¿Debería usar @ai-sdk/openai-compatible o @ai-sdk/openai?
Usa @ai-sdk/openai-compatible para una nueva configuración de Flatkey porque está diseñado para proveedores compatibles con OpenAI. Usa @ai-sdk/openai con createOpenAI({ baseURL }) cuando tu aplicación ya esté estandarizada en el proveedor de OpenAI y quieras una diferencia de código más pequeña.
¿La URL base necesita incluir /v1?
Usa el valor que se muestra en tu consola de Flatkey actual. En la mayoría de los patrones de SDK compatibles con OpenAI, la URL base incluye el prefijo de la versión para que las llamadas del SDK puedan agregar rutas como /chat/completions correctamente.
¿Puede una URL base de Flatkey enrutar múltiples modelos?
El posicionamiento público de Flatkey es ser una puerta de enlace única para el acceso a modelos, enrutamiento, facturación, análisis de uso y controles operativos. En tu aplicación, aun así, asigna cada carga de trabajo a un alias de modelo explícito de Flatkey y prueba el alias real antes de mover el tráfico.
¿Se probaron estos fragmentos del AI SDK?
Los fragmentos fueron verificados por tipo el 29 de junio de 2026 con ai@7.0.4, @ai-sdk/openai-compatible@3.0.1, @ai-sdk/openai@4.0.2, TypeScript y Zod. No se ejecutaron contra Flatkey porque no había una clave de API de Flatkey activa disponible en este entorno de ejecución.
En resumen
Una migración de la URL base de proveedor personalizado para Vercel AI SDK debería ser un pequeño cambio de proveedor con una rigurosa lista de verificación. Utiliza createOpenAICompatible para el proveedor Flatkey, mantén la URL base y los alias de modelo en la configuración, prueba primero el texto sin streaming, prueba el streaming y las llamadas a herramientas por separado, confirma la evidencia de uso en Flatkey y ten lista la reversión hasta que el tráfico de producción sea estable. Cuando las comprobaciones estén listas, obtén una clave y ejecuta las pruebas de humo con tus propios alias de modelo.
