Vercel AI SDK benutzerdefinierte Anbieter-Basis-URL: Flatkey Einrichtungsnotizen

Die Einrichtung einer benutzerdefinierten Anbieter-Basis-URL für das Vercel AI SDK ist mehr als nur das Ersetzen einer Zeichenkette. Der nützliche Teil besteht darin, den AI-SDK-Anbieter auf Flatkey zu verweisen, aber die sichere Produktionsarbeit besteht darin, Modell-Aliase, Endpunktfamilie, Streaming-Verhalten, Tool-Aufrufe, Nutzungsnachweise, Quotensteuerungen und Rollback zu überprüfen, bevor der Benutzerverkehr umgeleitet wird.

Dieser Leitfaden richtet sich an Entwickler, KI-Produktteams, Plattform-Ingenieure, Automatisierungsentwickler, Finanzverantwortliche und Beschaffungsprüfer, die das AI SDK in einer Next.js-Route, Server-Aktion, einem Worker, einer Warteschlange oder einer Agentenschleife verwenden. Er wurde am 29. Juni 2026 auf der Grundlage der aktuellen AI-SDK-Dokumentation, einer Typüberprüfung mit den aktuellen AI-SDK-Paketen und den öffentlichen Live-Seiten von Flatkey aktualisiert. Die Code-Schnipsel sind Vorlagen. Für diese Aufgabe war kein Live-API-Schlüssel von Flatkey verfügbar. Führen Sie die Smoke-Tests daher mit Ihrem eigenen Schlüssel, der aktuellen Basis-URL der Flatkey-Konsole und den für Ihr Konto aktivierten Modell-Aliasen durch.

Schnelle Antwort: Vercel AI SDK benutzerdefinierte Anbieter-Basis-URL

Für eine Einrichtung mit einer benutzerdefinierten Anbieter-Basis-URL für das Vercel AI SDK mit Flatkey beginnen Sie mit dem offiziellen OpenAI-kompatiblen Anbieterpaket. Erstellen Sie einen Anbieter mit createOpenAICompatible, setzen Sie baseURL auf die aktuelle Flatkey-Basis-URL aus Ihrer Konsole, setzen Sie apiKey auf Ihren Flatkey-Schlüssel und verwenden Sie Flatkey-Modell-Aliase in generateText oder 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" # Kopieren Sie den aktuellen Wert von 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(`Fehlendes ${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: 'Antworte mit einer kurzen Flatkey AI SDK Routing-Prüfung.',
});

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

Das ist die minimale funktionierende Form für eine Migration einer benutzerdefinierten Anbieter-Basis-URL für das Vercel AI SDK. Hören Sie hier nicht auf. Eine erfolgreiche Textantwort beweist nur, dass eine Anfrageform einen Modell-Alias erreicht hat. Sie beweist nicht die Nutzung von Streaming, Tools, strukturierter Ausgabe, Kostentransparenz, Quotenverhalten oder Rollback.

Was die aktuelle AI-SDK-Dokumentation unterstützt

Die aktuelle AI-SDK-Dokumentation bietet zwei relevante Wege. Das OpenAI-kompatible Anbieterpaket ist für Anbieter konzipiert, die die OpenAI-API implementieren. Es stellt createOpenAICompatible mit Optionen wie name, apiKey, baseURL, headers, queryParams, benutzerdefiniertem fetch, includeUsage, supportsStructuredOutputs, Transformationen des Anfrage-Bodys und Metadaten-Extraktion zur Verfügung.

Das OpenAI-Anbieterpaket unterstützt auch createOpenAI({ baseURL }) für angepasste Setups, einschließlich Proxy-Servern. Der OpenAI-kompatible Anbieter ist die sauberere Standardeinstellung für eine benutzerdefinierte Anbieter-Basis-URL für das Vercel AI SDK, da sein Anbietername, die benutzerdefinierte Metadaten-Extraktion, anbieterspezifische Optionen und die Namen der Modellfabriken für nicht-OpenAI OpenAI-kompatible Routen konzipiert sind.

Anbietermuster	Verwenden, wenn	Flatkey-Prüfpunkt
createOpenAICompatible	Sie einen benannten Flatkey-Anbieter für OpenAI-kompatible Chat-, Streaming-, Tool-, Einbettungs-, Bild- oder Vervollständigungsmodelle wünschen.	Bevorzugter Ausgangspunkt für eine Flatkey-Integration, da name: 'flatkey' anbieterspezifische Optionen und Metadaten leichter verständlich macht.
createOpenAI({ baseURL })	Ihre Codebasis bereits auf @ai-sdk/openai standardisiert ist und Sie nur eine proxy-artige benutzerdefinierte Basis-URL benötigen.	Seien Sie explizit bezüglich des Verhaltens von .chat(...) im Vergleich zu Responses; gehen Sie nicht davon aus, dass die Standardeinstellungen des OpenAI-Anbieters mit jeder Flatkey-Route übereinstimmen.
Roher Fetch-Wrapper	Sie eine nicht standardmäßige Body-Transformation oder einen Endpunkt benötigen, den der AI-SDK-Anbieter nicht abdeckt.	Behalten Sie dies als Ausnahme bei. Sie verlieren die normalisierte Ergebnisform des SDKs, die Tool-Helfer und die typisierten Stream-Helfer.

Aktuelle Flatkey-Informationen zur vorsichtigen Verwendung

Die am 29. Juni 2026 überprüfte Homepage von Flatkey hat den Titel One API gateway for production AI teams und eine Meta-Beschreibung, die besagt, dass Flatkey den Modellzugriff, das Routing, die Abrechnung, die Nutzungsanalyse und die betrieblichen Kontrollen vereinheitlicht. Die Live-Preis-API lieferte 633 Modellzeilen, 23 Anbieter und Endpunktfamilien für /v1/chat/completions, /v1/responses, /v1/messages, /v1beta/models/{model}:generateContent, /v1/images/generations und /v1/video/generations zurück.

Verwenden Sie diese Fakten als datierte öffentliche Belege für die Positionierung und die Katalogstruktur, nicht als Beweis dafür, dass jedes Konto jede Route aufrufen kann, jeder Modell-Alias verfügbar ist oder jede Funktion aktiviert ist. Vor dem Produktionsverkehr sollten Ihre Überprüfungen der benutzerdefinierten Anbieter-Basis-URL für das Vercel AI SDK genau den Schlüssel, die Basis-URL, den Modell-Alias, die Endpunktfamilie und den Funktionspfad verwenden, den Ihre App senden wird.

Basis-URL und Umgebungseinrichtung

Bewahren Sie die Basis-URL, den Schlüssel und den Modell-Alias in Umgebungsvariablen auf. Dadurch wird ein Rollout mit einer benutzerdefinierten Anbieter-Basis-URL des Vercel AI SDK in der Bereitstellungskonfiguration überprüfbar, anstatt in Route-Handlern, Prompt-Dateien und Workern vergraben zu sein.

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

Halten Sie dann das Workload-Routing von der Transporteinrichtung getrennt. Die Basis-URL teilt dem SDK mit, wohin Anfragen gesendet werden sollen. Der Modell-Alias entscheidet, welche Flatkey-Route und welches Upstream-Modell Sie anfordern.

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

Dieses Muster verhindert, dass Teams Anbieternamen, Modell-Aliase und Basis-URLs über die gesamte Codebasis verstreuen. Es gibt auch den Finanz- und Betriebsteams einen stabilen Satz von Workload-Namen, die sie mit den Nutzungszeilen abgleichen können.

Zuerst Nicht-Streaming-Text mit einem Smoke-Test prüfen

Beginnen Sie mit generateText. Es liefert Ihnen ein unkompliziertes Ergebnisobjekt mit Text, Beendigungsgrund, Nutzung, Warnungen, Schritten und Antwort-Metadaten. Verwenden Sie es, um die Authentifizierung, die Form der Basis-URL, den Modell-Alias und die Sichtbarkeit der Nutzung zu überprüfen, bevor Sie Streaming oder Tools testen.

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

Genehmigen Sie diese erste Überprüfung der benutzerdefinierten Anbieter-Basis-URL des Vercel AI SDK nur, wenn der generierte Text, der Modell-Alias, der Beendigungsgrund und die Nutzungsfelder für die Protokollierungs- und Überprüfungsanforderungen Ihrer Anwendung ausreichen. Wenn der Aufruf Text zurückgibt, die Nutzung aber nicht in den Flatkey-Datensätzen gefunden werden kann, ist die Migration nicht für die Produktion bereit.

Streaming separat testen

Streaming hat eine andere Fehleranfälligkeit. Es betrifft das Streamen von Antworten, serverseitige Zeitüberschreitungen, UI-Abbrüche, Fehlerbehandlung und die Nutzungsabrechnung. Die AI SDK-Dokumentation zeigt streamText, result.textStream, einen onError-Callback und Ergebnis-Promises wie result.usage. Der OpenAI-kompatible Anbieter hat auch includeUsage für das Streamen von Antwort-Metadaten, wenn der Anbieter dies unterstützt.

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

Lassen Sie das Streaming nur aktiviert, nachdem sich der ausgewählte Flatkey-Modell-Alias unter Ihrer realen Anforderungsform als stabil erwiesen hat. Wenn gestreamter Text funktioniert, die Nutzung aber unvollständig ist, entscheiden Sie, ob Ihr Team die Nutzung aus den Flatkey-Datensätzen anstelle der Stream-Antwort erfassen kann, bevor der Benutzerverkehr umgeleitet wird.

Tool-Aufrufe mit demselben Alias überprüfen

Die AI SDK Tool-API verwendet ein tools-Objekt, den tool-Helfer, ein inputSchema und eine optionale execute-Funktion. Ein einfacher Chat-Durchlauf genehmigt keine Tool-Aufrufe. Testen Sie zuerst ein kleines Schema und erweitern Sie es dann auf das Tool-Set, das Ihre Agenten tatsächlich verwenden.

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

Zeichnen Sie für den Agentenverkehr auf, ob das Modell das erwartete Tool aufgerufen hat, ob die Eingabe validiert wurde, ob das Tool-Ergebnis sauber zurückgegeben wurde und ob die Flatkey-Nutzungszeile derselben Route zugeordnet werden kann. Wenn strikte Schemata, Genehmigungsabläufe oder parallele Tool-Aufrufe wichtig sind, testen Sie diese Funktionen mit dem exakten Modell-Alias.

Wann stattdessen createOpenAI verwendet werden sollte

Wenn Ihre App bereits überall @ai-sdk/openai verwendet, kann die baseURL-Option des OpenAI-Anbieters ein einfacherer Migrationspfad sein. Dies ist immer noch eine Einrichtung mit einer benutzerdefinierten Anbieter-Basis-URL des Vercel AI SDK, aber Sie sollten bei der Auswahl der Modell-API expliziter sein.

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

Die aktuellen Dokumente des OpenAI-Anbieters besagen, dass Responses seit AI SDK 5 die Standard-API für den OpenAI-Anbieter ist, es sei denn, Sie geben eine Route wie .chat(...) an. Aus diesem Grund verwendet das obige Beispiel explizit .chat(...). Wenn Sie beabsichtigen, die Endpunktfamilie /v1/responses von Flatkey zu testen, behandeln Sie dies als separate Routenprüfung mit einem separaten Modellalias und Rollback-Pfad.

Einrichtungs-Checkliste

Prüfung	Was zu erfassen ist	Warum es wichtig ist
Basis-URL	Aktueller Wert der Flatkey-Konsole, einschließlich des /v1-Präfixes, falls erforderlich.	Fehlende Pfadsegmente und veraltete Hosts führen zu verwirrenden 404-Fehlern.
Anbieterwahl	createOpenAICompatible oder createOpenAI({ baseURL }).	Die Wahl des Anbieters beeinflusst Standardeinstellungen, Metadaten, anbieterspezifische Optionen und Modellfabriken.
Modell-Alias	Die genaue Flatkey-Modellzeichenfolge für jede Workload-Route.	Ein Name einer Anbieterfamilie ist für eine Produktionsanfrage nicht ausreichend.
Funktionspfad	Klartext, Streaming, Tools, strukturierte Ausgabe, Bilder oder Responses.	Ein bestandener Funktionstest genehmigt nicht einen anderen Funktionspfad.
Nutzungsdatensatz	Zeitstempel, Schlüssel, Route, Modell-Alias, Beendigungsgrund, Tokens, Kosteneinheit und Eigentümer-Metadaten, sofern verfügbar.	Betriebs- und Finanzprüfer müssen die Anfrage finden können, ohne raten zu müssen.
Rollback	Vorheriger Schlüssel, Basis-URL, Modell, Bereitstellungs-Flag und Fehlerschwelle.	Ein Rollback sollte eine Konfigurationsänderung sein, keine Code-Umschreibung während eines Vorfalls.

Häufige Fehlermodi

Symptom	Wahrscheinliche Ursache	Lösung
404 von der AI SDK-Anfrage	Der Basis-URL fehlt /v1, verweist auf den falschen Host oder verwendet die falsche Endpunktfamilie.	Kopieren Sie den aktuellen Wert der Flatkey-Konsole und führen Sie die kleinste generateText-Prüfung erneut aus.
401 oder 403	Der Prozess hat den falschen Schlüssel geladen oder OPENAI_API_KEY und FLATKEY_API_KEY vermischt.	Protokollieren Sie nur die geladenen Namen der Umgebungsvariablen, niemals geheime Werte, und bestätigen Sie den Zugriff auf den Flatkey-Schlüssel.
Einfacher Chat funktioniert, aber Tool-Aufrufe schlagen fehl	Der ausgewählte Alias oder die Endpunktfamilie unterstützt Ihr Tool-Schema nicht.	Testen Sie zuerst das kleinste Zod-Schema und fügen Sie dann Strenge, Genehmigung und mehrstufige Schleifen hinzu.
Streaming-Text funktioniert, aber die Nutzung ist leer	Die Route streamt Inhalte, gibt aber keine gestreamten Nutzungsmetadaten zurück.	Überprüfen Sie die Flatkey-Nutzungsdatensätze und entscheiden Sie, ob die Nutzung der Stream-Antwort für den Start erforderlich ist.
Anbieterspezifische Optionen verschwinden	Die Anfrage verwendet den falschen Anbieternamen oder eine nicht unterstützte benutzerdefinierte Option.	Verwenden Sie name: 'flatkey' und testen Sie jedes providerOptions.flatkey-Feld, bevor Sie sich darauf verlassen.

Wo dies zu anderen Flatkey-Anleitungen passt

Wenn Sie den umfassenderen Migrationspfad benötigen, beginnen Sie mit der Anleitung zur Migration von OpenAI-kompatiblen APIs. Für angrenzende Muster zur Einrichtung von Tools lesen Sie die Anleitung zur Einrichtung der Cherry Studio API und die Anleitung zu cc-switch Claude Code Flatkey. Verwenden Sie die Flatkey-Preise, um den aktuellen Modellkatalog zu prüfen, und holen Sie sich dann einen Schlüssel, wenn Sie bereit sind, die Smoke-Tests in Ihrem eigenen Konto durchzuführen.

Häufig gestellte Fragen

Wie richte ich eine benutzerdefinierte Anbieter-Basis-URL des Vercel AI SDK für Flatkey ein?

Erstellen Sie einen OpenAI-kompatiblen Anbieter mit createOpenAICompatible, setzen Sie baseURL auf die aktuelle Flatkey-Basis-URL, setzen Sie apiKey auf Ihren Flatkey-Schlüssel und übergeben Sie einen Flatkey-Modell-Alias an generateText oder streamText.

Sollte ich @ai-sdk/openai-compatible oder @ai-sdk/openai verwenden?

Verwenden Sie @ai-sdk/openai-compatible für eine neue Flatkey-Einrichtung, da es für OpenAI-kompatible Anbieter konzipiert ist. Verwenden Sie @ai-sdk/openai mit createOpenAI({ baseURL }), wenn Ihre App bereits auf den OpenAI-Anbieter standardisiert ist und Sie einen kleineren Code-Unterschied wünschen.

Muss die Basis-URL /v1 enthalten?

Verwenden Sie den in Ihrer aktuellen Flatkey-Konsole angezeigten Wert. In den meisten Mustern für OpenAI-kompatible SDKs enthält die Basis-URL das Versionspräfix, damit SDK-Aufrufe Pfade wie /chat/completions korrekt anhängen können.

Kann eine Flatkey-Basis-URL mehrere Modelle routen?

Flatkeys öffentliche Positionierung ist ein Gateway für Modellzugriff, Routing, Abrechnung, Nutzungsanalysen und Betriebskontrollen. Ordnen Sie in Ihrer App dennoch jeden Workload einem expliziten Flatkey-Modell-Alias zu und testen Sie den tatsächlichen Alias, bevor der Traffic verschoben wird.

Wurden diese AI SDK-Snippets getestet?

Die Snippets wurden am 29. Juni 2026 gegen ai@7.0.4, @ai-sdk/openai-compatible@3.0.1, @ai-sdk/openai@4.0.2, TypeScript und Zod typgeprüft. Sie wurden nicht gegen Flatkey ausgeführt, da in dieser Laufzeitumgebung kein Live-API-Schlüssel für Flatkey verfügbar war.

Fazit

Eine Migration der benutzerdefinierten Anbieter-Basis-URL des Vercel AI SDK sollte eine kleine Anbieteränderung sein, die mit einer sorgfältigen Verifizierungs-Checkliste einhergeht. Verwenden Sie createOpenAICompatible für den Flatkey-Anbieter, behalten Sie die Basis-URL und die Modell-Aliase in der Konfiguration, testen Sie zuerst nicht-streamenden Text, testen Sie Streaming und Tool-Aufrufe separat, bestätigen Sie die Nutzungsnachweise in Flatkey und halten Sie ein Rollback bereit, bis der Produktionsverkehr stabil ist. Wenn die Prüfungen abgeschlossen sind, holen Sie sich einen Schlüssel und führen Sie die Smoke-Tests mit Ihren eigenen Modell-Aliasen durch.