URL base do provedor personalizado do Vercel AI SDK: Notas de Configuração do Flatkey

A configuração da URL base do provedor personalizado do Vercel AI SDK é mais do que uma substituição de string. A parte útil é apontar o provedor do AI SDK para o Flatkey, mas o trabalho seguro de produção é verificar aliases de modelo, família de endpoints, comportamento de streaming, chamadas de ferramentas, evidências de uso, controles de cota e reversão antes que o tráfego do usuário seja movido.

Este guia é para desenvolvedores, equipes de produtos de IA, engenheiros de plataforma, criadores de automação, operadores financeiros e revisores de aquisições que usam o AI SDK em uma rota Next.js, ação de servidor, worker, fila ou loop de agente. Foi atualizado em 29 de junho de 2026 a partir da documentação atual do AI SDK, uma verificação de tipo em relação aos pacotes atuais do AI SDK e páginas públicas ativas do Flatkey. Os trechos de código são modelos. Nenhuma chave de API do Flatkey ativa estava disponível nesta tarefa, então execute os testes de fumaça (smoke tests) com sua própria chave, a URL base atual do console do Flatkey e os aliases de modelo habilitados para sua conta.

Resposta Rápida: URL Base do Provedor Personalizado do Vercel AI SDK

Para uma configuração de URL base do provedor personalizado do Vercel AI SDK com o Flatkey, comece com o pacote oficial do provedor compatível com OpenAI. Crie um provedor com createOpenAICompatible, defina baseURL para a URL base atual do Flatkey do seu console, defina apiKey para sua chave do Flatkey e use os aliases de modelo do Flatkey em generateText ou streamText.

npm install ai @ai-sdk/openai-compatible zod

export FLATKEY_API_KEY="fk_your_key"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1" # Copie o valor atual do 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(`Missing ${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: 'Responda com uma verificação curta de roteamento do Flatkey AI SDK.',
});

console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);
console.log(result.warnings);

Essa é a forma mínima de funcionamento para uma migração da URL base do provedor personalizado do Vercel AI SDK. Não pare por aí. Uma resposta de texto bem-sucedida prova apenas que uma forma de solicitação alcançou um alias de modelo. Isso não prova o uso de streaming, ferramentas, saída estruturada, visibilidade de custos, comportamento de cota ou reversão.

O Que a Documentação Atual do AI SDK Suporta

A documentação atual do AI SDK tem dois caminhos relevantes. O pacote do provedor Compatível com OpenAI é construído para provedores que implementam a API da OpenAI. Ele expõe createOpenAICompatible com opções que incluem name, apiKey, baseURL, headers, queryParams, fetch personalizado, includeUsage, supportsStructuredOutputs, transformações do corpo da solicitação e extração de metadados.

O pacote do provedor OpenAI também suporta createOpenAI({ baseURL }) para configurações personalizadas, incluindo servidores proxy. O provedor Compatível com OpenAI é o padrão mais limpo para uma URL base do provedor personalizado do Vercel AI SDK porque seu nome de provedor, extração de metadados personalizados, opções específicas do provedor e nomes de fábrica de modelos são projetados para rotas compatíveis com OpenAI que não são da OpenAI.

Padrão do Provedor	Use Quando	Ponto de Revisão do Flatkey
createOpenAICompatible	Você quer um provedor Flatkey nomeado para modelos de chat, streaming, ferramentas, embeddings, imagens ou conclusão compatíveis com OpenAI.	Ponto de partida preferido para uma integração com o Flatkey porque name: 'flatkey' torna as opções específicas do provedor e os metadados mais fáceis de entender.
createOpenAI({ baseURL })	Sua base de código já está padronizada em @ai-sdk/openai e você só precisa de uma URL base personalizada no estilo de proxy.	Seja explícito sobre o comportamento de .chat(...) versus Respostas; não presuma que os padrões do provedor OpenAI correspondem a todas as rotas do Flatkey.
Wrapper de fetch bruto	Você precisa de uma transformação de corpo não padrão ou de um endpoint que o provedor do AI SDK não cobre.	Mantenha isso como uma exceção. Você perde a forma de resultado normalizada do SDK, os auxiliares de ferramentas e os auxiliares de stream tipados.

Evidências Recentes do Flatkey Para Usar com Cuidado

A página inicial do Flatkey, verificada em 29 de junho de 2026, tem o título One API gateway for production AI teams e uma meta descrição dizendo que o Flatkey unifica o acesso a modelos, roteamento, faturamento, análise de uso e controles operacionais. A API de preços em tempo real retornou 633 linhas de modelos, 23 fornecedores e famílias de endpoints para /v1/chat/completions, /v1/responses, /v1/messages, /v1beta/models/{model}:generateContent, /v1/images/generations e /v1/video/generations.

Use esses fatos como evidência pública datada para posicionamento e forma do catálogo, não como prova de que toda conta pode chamar toda rota, todo alias de modelo está disponível ou todo recurso está habilitado. Antes do tráfego de produção, suas verificações da URL base do provedor personalizado do Vercel AI SDK devem usar a chave, URL base, alias de modelo, família de endpoint e caminho de recurso exatos que seu aplicativo enviará.

URL Base e Configuração do Ambiente

Mantenha a URL base, a chave e o alias do modelo em variáveis de ambiente. Isso torna a implementação de uma URL base do provedor personalizado do Vercel AI SDK revisável na configuração de implantação, em vez de ficar escondida dentro de manipuladores de rota, arquivos de prompt e 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,
});

Em seguida, mantenha o roteamento da carga de trabalho separado da configuração de transporte. A URL base informa ao SDK para onde enviar as solicitações. O alias do modelo decide qual rota do Flatkey e qual modelo upstream você está 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 padrão evita que as equipes espalhem nomes de provedores, aliases de modelos e URLs base por todo o código-fonte. Ele também fornece às equipes de finanças e operações um conjunto estável de nomes de carga de trabalho para corresponder às linhas de uso.

Primeiro, Teste o Texto Sem Streaming

Comece com generateText. Ele fornece um objeto de resultado direto com texto, motivo da finalização, uso, avisos, etapas e metadados de resposta. Use-o para comprovar a autenticação, o formato da URL base, o alias do modelo e a visibilidade do uso antes de testar streaming ou ferramentas.

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,
});

Aprove esta primeira verificação da URL base do provedor personalizado do Vercel AI SDK somente se os campos de texto gerado, alias do modelo, motivo da finalização e uso forem suficientes para as necessidades de registro e revisão da sua aplicação. Se a chamada retornar texto, mas o uso não puder ser encontrado nos registros do Flatkey, a migração não está pronta para produção.

Teste o Streaming Separadamente

O streaming tem uma superfície de falha diferente. Ele afeta o streaming de respostas, timeouts sem servidor, cancelamento na interface do usuário, tratamento de erros e contabilização de uso. A documentação do AI SDK mostra streamText, result.textStream, um callback onError e promessas de resultado como result.usage. O provedor compatível com OpenAI também possui includeUsage para metadados de resposta de streaming quando o provedor o suporta.

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 });

Mantenha o streaming ativado somente depois que o alias do modelo Flatkey selecionado se mostrar estável sob o formato real da sua solicitação. Se o texto transmitido funcionar, mas o uso estiver incompleto, decida se sua equipe pode coletar o uso dos registros do Flatkey em vez da resposta do stream antes que o tráfego do usuário seja movido.

Verifique as Chamadas de Ferramentas com o Mesmo Alias

A API de ferramentas do AI SDK usa um objeto tools, o auxiliar tool, um inputSchema e uma função execute opcional. Uma passagem de chat simples não aprova a chamada de ferramentas. Teste primeiro um esquema pequeno e, em seguida, expanda para o conjunto de ferramentas que seus agentes realmente usam.

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 o tráfego de agentes, registre se o modelo chamou a ferramenta esperada, se a entrada foi validada, se o resultado da ferramenta retornou sem erros e se a linha de uso do Flatkey pode ser associada à mesma rota. Se esquemas rigorosos, fluxos de aprovação ou chamadas de ferramentas paralelas forem importantes, teste esses recursos com o alias exato do modelo.

Quando Usar createOpenAI em Vez Disso

Se seu aplicativo já usa @ai-sdk/openai em todos os lugares, a opção baseURL do provedor OpenAI pode ser um caminho de migração com menos alterações. Esta ainda é uma configuração de URL base do provedor personalizado do Vercel AI SDK, mas você deve ser mais explícito sobre a seleção da API do 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.',
});

A documentação atual do provedor OpenAI diz que Responses é a API padrão para o provedor OpenAI desde o AI SDK 5, a menos que você especifique uma rota como .chat(...). É por isso que o exemplo acima usa .chat(...) explicitamente. Se você pretende testar a família de endpoints /v1/responses do Flatkey, trate isso como uma verificação de rota separada com um alias de modelo e caminho de reversão separados.

Lista de Verificação de Configuração

Verificação	O que Capturar	Por que é Importante
URL Base	Valor atual do console Flatkey, incluindo o prefixo /v1 quando necessário.	Segmentos de caminho ausentes e hosts desatualizados criam erros 404 confusos.
Escolha do provedor	createOpenAICompatible ou createOpenAI({ baseURL }).	A escolha do provedor afeta padrões, metadados, opções específicas do provedor e fábricas de modelos.
Alias do modelo	A string exata do modelo Flatkey para cada rota de carga de trabalho.	O nome da família de um fornecedor não é suficiente para uma solicitação de produção.
Caminho do recurso	Texto simples, streaming, ferramentas, saída estruturada, imagens ou Responses.	A aprovação de um recurso não aprova outro caminho de recurso.
Registro de uso	Timestamp, chave, rota, alias do modelo, motivo da finalização, tokens, unidade de custo e metadados do proprietário, quando disponíveis.	Revisores de operações e finanças precisam encontrar a solicitação sem adivinhações.
Reversão	Chave anterior, URL base, modelo, flag de implantação e limite de erro.	A reversão deve ser uma mudança de configuração, não uma reescrita de código durante um incidente.

Modos de Falha Comuns

Sintoma	Causa Provável	Correção
404 da solicitação do AI SDK	A URL base está sem /v1, aponta para o host errado ou usa a família de endpoints errada.	Copie o valor atual do console Flatkey e execute novamente a menor verificação generateText.
401 ou 403	O processo carregou a chave errada ou misturou OPENAI_API_KEY e FLATKEY_API_KEY.	Registre apenas os nomes das variáveis de ambiente carregadas, nunca os valores secretos, e confirme o acesso à chave Flatkey.
O chat simples funciona, mas as chamadas de ferramentas falham	O alias ou a família de endpoints selecionada não suporta o seu esquema de ferramentas.	Teste primeiro o menor esquema Zod, depois adicione rigor, aprovação e loops de múltiplos passos.
O streaming de texto funciona, mas o uso está vazio	A rota transmite conteúdo, mas não retorna metadados de uso transmitidos.	Verifique os registros de uso do Flatkey e decida se o uso da resposta de stream é necessário para o lançamento.
Opções específicas do provedor desaparecem	A solicitação usa o nome do provedor errado ou uma opção personalizada não suportada.	Use name: 'flatkey' e teste qualquer campo providerOptions.flatkey antes de depender dele.

Onde Isso se Encaixa com Outros Guias do Flatkey

Se você precisa de um caminho de migração mais amplo, comece com o guia de migração de API compatível com OpenAI. Para padrões de configuração de ferramentas adjacentes, revise o guia de configuração da API do Cherry Studio e o guia cc-switch Claude Code Flatkey. Use os preços do Flatkey para inspecionar o catálogo de modelos atual e, em seguida, obtenha uma chave quando estiver pronto para executar os testes de fumaça em sua própria conta.

Perguntas frequentes

Como defino uma URL base de provedor personalizado do Vercel AI SDK para o Flatkey?

Crie um provedor compatível com OpenAI com createOpenAICompatible, defina baseURL para a URL base atual do Flatkey, defina apiKey para sua chave Flatkey e passe um alias de modelo Flatkey para generateText ou streamText.

Devo usar @ai-sdk/openai-compatible ou @ai-sdk/openai?

Use @ai-sdk/openai-compatible para uma nova configuração do Flatkey, pois ele foi projetado para provedores compatíveis com OpenAI. Use @ai-sdk/openai com createOpenAI({ baseURL }) quando seu aplicativo já padroniza o provedor OpenAI e você deseja uma diferença de código menor.

A URL base precisa incluir /v1?

Use o valor exibido no seu console Flatkey atual. Na maioria dos padrões de SDK compatíveis com OpenAI, a URL base inclui o prefixo da versão para que as chamadas do SDK possam anexar caminhos como /chat/completions corretamente.

Uma única URL base do Flatkey pode rotear vários modelos?

O posicionamento público do Flatkey é de um gateway único para acesso a modelos, roteamento, faturamento, análise de uso e controles operacionais. Em seu aplicativo, ainda mapeie cada carga de trabalho para um alias de modelo explícito do Flatkey e teste o alias real antes de mover o tráfego.

Esses trechos do AI SDK foram testados?

Os trechos foram verificados por tipo em 29 de junho de 2026 em relação a ai@7.0.4, @ai-sdk/openai-compatible@3.0.1, @ai-sdk/openai@4.0.2, TypeScript e Zod. Eles não foram executados no Flatkey porque nenhuma chave de API do Flatkey ativa estava disponível neste ambiente de execução.

Conclusão

Uma migração da URL base do provedor personalizado do Vercel AI SDK deve ser uma pequena alteração no provedor com uma lista de verificação rigorosa. Use createOpenAICompatible para o provedor Flatkey, mantenha a URL base e os aliases de modelo na configuração, teste primeiro o texto sem streaming, teste o streaming e as chamadas de ferramenta separadamente, confirme as evidências de uso no Flatkey e mantenha o rollback pronto até que o tráfego de produção esteja estável. Quando as verificações estiverem prontas, obtenha uma chave e execute os smoke tests com seus próprios aliases de modelo.