Flatkey API Schnellstart: So machst du deinen ersten Aufruf über router.flatkey.ai

Wenn du bereits das OpenAI SDK verwendest, ist der kürzeste Weg zu einem ersten Flatkey-API-Aufruf ganz einfach: Erstelle einen Flatkey-Key, richte deinen Client auf https://router.flatkey.ai/v1 aus, sende eine Chat-Completions-Anfrage und bestätige den Aufruf in der Konsole.

Dieser Schnellstart führt dich durch den gesamten Ablauf. Er zeigt außerdem, wie du nach dem ersten funktionierenden Modell eine einfache Fallback-Sequenz hinzufügst, ohne Fehler zu verbergen oder eine unbegrenzte Retry-Kette zu erzeugen.

Was du erledigen wirst

Am Ende dieser Anleitung wirst du Folgendes haben:

1. Ein Flatkey-Konto und einen API-Schlüssel.
2. Einen OpenAI-kompatiblen Client, der den Flatkey-Router verwendet.
3. Eine erfolgreiche Anfrage und eine lesbare Antwort.
4. Einen Console-Prüfpunkt für Nutzung, Kosten und Fehlerbehebung bei Anfragen.
5. Ein kleines Fallback-Muster, das du vor der Produktion testen kannst.

Für diesen Smoke Test musst du deine Anwendung nicht um ein neues SDK herum neu aufbauen. Die öffentlichen Flatkey-Dokumente stellen einen OpenAI-kompatiblen Endpunkt unter https://router.flatkey.ai/v1 bereit, sodass gängige Workflows für Chat, Tools, Streaming und strukturierte Ausgaben die vertraute Client-Form beibehalten können.

Bevor du beginnst

Du benötigst:

• Ein Flatkey-Konto.
• Einen Flatkey-API-Schlüssel, der mit sk-fk- beginnt.
• Python 3.9+ oder Node.js 18+, wenn du ein SDK-Beispiel verwenden möchtest.
• Einen Modellnamen, der aktuell für dein Konto verfügbar ist.

Modellkataloge und Verfügbarkeit können sich ändern. Verwende den aktuellen Modellkatalog oder die Konsole, statt einen alten Modellnamen in die Produktion zu übernehmen.

Schritt 1: Erstelle dein Flatkey-Konto

Öffne den Flatkey-Anmeldeprozess und erstelle ein Konto. Nachdem du dich angemeldet hast, verwende die Konsole, um die Anmeldeinformationen zu erstellen, die deine Anwendung bei jeder Anfrage sendet.

Konsole-Referenz

Gehe zu Konsole → API-Schlüssel.

Erstelle für diesen Schnellstart einen Schlüssel und kopiere ihn sofort. Behandle den Schlüssel wie ein Passwort: Füge ihn nicht in clientseitigen Code ein, committe ihn nicht in Git, nimm ihn nicht in Screenshots auf und sende ihn nicht in Support-Nachrichten.

Für eine Teamumgebung solltest du getrennte Schlüssel für verschiedene Entwickler oder Dienste erstellen. Die Dokumentation von Flatkey beschreibt außerdem Schlüssel-spezifische Kontrollen wie ein monatliches Limit und eine optionale Modell-Whitelist. Diese Kontrollen erleichtern es, einen Test zu isolieren, eine Anmeldeinformation zu rotieren oder einen einzelnen Workload zu stoppen, ohne jede Anwendung zu beeinflussen.

Setze den Schlüssel in deiner Shell:

export FLATKEY_API_KEY="sk-fk-your-key-here"

Wenn du eine .env-Datei verwendest, halte sie außerhalb der Versionskontrolle:

FLATKEY_API_KEY=sk-fk-your-key-here

Schritt 2: Ändere die Base-URL

Die OpenAI-kompatible Flatkey-Base-URL lautet:

https://router.flatkey.ai/v1

Dies ist die wichtigste Konfigurationsänderung im Schnellstart. Dein API-Schlüssel authentifiziert die Anfrage, während die Base-URL sie über den Flatkey-Router statt direkt an einen anderen Anbieter-Endpunkt sendet.

Halte beide Werte in der Umgebungs-Konfiguration, damit du sie ändern kannst, ohne die Anwendungslogik zu bearbeiten:

export OPENAI_API_KEY="$FLATKEY_API_KEY"
export OPENAI_BASE_URL="https://router.flatkey.ai/v1"

Verwende die Variablennamen, die dein Framework erwartet. Einige Bibliotheken lesen OPENAI_BASE_URL; andere erfordern eine base_url- oder baseURL-Option, wenn der Client erstellt wird.

Schritt 3: Sende deine erste Anfrage

Beginne mit einer kurzen, deterministischen Eingabeaufforderung. Das Ziel ist es, Authentifizierung, Konnektivität, Modellzugriff und das Parsen der Antwort zu bestätigen, bevor du Streaming, Tools, strukturierte Ausgabe oder Fallback-Verhalten hinzufügst.

Option A: cURL

Ersetze YOUR_CURRENT_MODEL durch ein Modell, das im aktuellen Flatkey-Katalog verfügbar ist:

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
  }'

Option B: Python

Installiere den OpenAI-Client:

pip install openai

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

Führe es aus:

python quickstart.py

Option C: JavaScript

Installiere den Client:

npm install openai

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

Führe es aus:

node quickstart.mjs

Schritt 4: Lese die Antwort

Bei einer standardmäßigen Chat-Completions-Anfrage beginne mit vier Feldern:

Eine vereinfachte Antwort sieht so aus:

{
  "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
  }
}

Die genauen Kennungen und Token-Zahlen werden abweichen. Dein Erfolgskriterium für den ersten Aufruf ist kein exakter Byte-für-Byte-Abgleich; es ist eine gültige HTTP-Antwort, eine parsebare Assistant-Nachricht und Nutzungsinformationen, die deine Anwendung erfassen kann.

Schritt 5: Nutzung nach dem Aufruf prüfen

Bleib nicht bei 200 OK stehen. Ein hilfreicher Schnellstart zeigt auch, dass die Anfrage für die Personen sichtbar ist, die die Integration betreiben werden.

Console-Referenz

Öffne nach der Anfrage Console → Usage & Logs.

Suche den neuen Aufruf und bestätige die für dein Konto verfügbaren Details, wie zum Beispiel:

• Anfragezeit.
• Modell oder Route.
• Status.
• Token-Nutzung.
• Kosten oder Auswirkung auf das Guthaben.
• Fehlerdetails, wenn eine Anfrage fehlschlägt.

Wenn die Anwendung eine Antwort erhalten hat, der erwartete Logeintrag jedoch fehlt, prüfe zuerst, ob du dasselbe Konto, denselben Workspace und denselben API-Schlüssel ansiehst, die für die Anfrage verwendet wurden. Notiere außerdem die Antwort-ID und die Anfragezeit, bevor du es erneut versuchst; diese beiden Details machen die Fehlersuche deutlich einfacher.

Sieh dir die aktuelle Flatkey-Preisseite an, bevor du von einem Smoke-Test zu einer dauerhaften Workload übergehst. Vergleiche das Modell, das Anfragevolumen, die Token-Zusammensetzung und das Fallback-Verhalten, das du verwenden willst – nicht nur die Kosten eines einzelnen erfolgreichen Aufrufs.

Schritt 6: Eine sichere Fallback-Sequenz hinzufügen

Fallback-Routing sollte erst kommen, nachdem das erste Modell funktioniert. Andernfalls kann eine Backup-Route das eigentliche Problem verdecken: ein ungültiger Schlüssel, eine falsche Basis-URL, ein nicht verfügbares Modell, eine fehlerhafte Anfrage oder ein Kontolimit.

Beginne mit einer kurzen geordneten Liste von Modellen, die du für dieselbe Aufgabe getestet hast:

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": "Gib JSON mit einem Schlüssel namens status und dem Wert ok zurück",
                }
            ],
            temperature=0,
        )
        print(model, response.choices[0].message.content)
        break
    except Exception as error:
        last_error = error
        print(f"Route fehlgeschlagen: {model}")
else:
    raise RuntimeError("Alle freigegebenen Modellrouten sind fehlgeschlagen") from last_error

Dieses Beispiel ist absichtlich klein gehalten. Bevor du es in der Produktion verwendest, füge hinzu:

• Eine eng gefasste Liste von erneut versuchbaren Fehlern.
• Ein Timeout pro Versuch und eine Gesamtdauer für die Anfrage.
• Backoff für vorübergehende Fehler.
• Strukturierte Logs mit dem versuchten Modell und der Response-ID.
• Ausgabevalidierung für JSON, Tool-Aufrufe oder andere erforderliche Schemas.
• Eine Kostenobergrenze, damit ein Fallback nicht unbemerkt eine ungeeignete Route auswählt.

Wiederhole Authentifizierungsfehler nicht mit mehreren Modellen. Wiederhole fehlerhafte Anfragen nicht, bis die Anfrage behoben ist. Behandle nicht jedes Modell als austauschbar, nur weil es eine Chat-Completions-Nutzlast akzeptiert.

Eine praktische Fallback-Richtlinie

Verwende diese Entscheidungstabelle als Ausgangspunkt:

Die Kernregel ist einfach: vorübergehende Transportfehler erneut versuchen; Konfigurations- und Schemafehler beheben; einen Fallback nur verwenden, wenn der Fallback für denselben Produkt-Job genehmigt ist.

Häufige Fehler beim ersten Aufruf

401 oder Authentifizierungsfehler

Stelle sicher, dass die Anfrage Authorization: Bearer <key> verwendet, der Schlüssel aktiv ist und kein zusätzliches Leerzeichen kopiert wurde. Verifiziere, dass die Anwendung die erwartete Umgebungsvariable liest.

404 oder falscher Endpunkt

Verwende die OpenAI-kompatible Basis-URL https://router.flatkey.ai/v1 und den Chat-Pfad /chat/completions. Vermeide es, versehentlich /v1 doppelt anzuhängen.

Modell nicht gefunden oder nicht verfügbar

Wähle ein aktuell verfügbares Modell aus dem Live-Katalog oder der Konsole. Gehe nicht davon aus, dass ein Modellname aus einem alten Tutorial für dein Konto noch aktiviert ist.

Erfolgreiche HTTP-Antwort, aber Anwendungsfehler

Protokolliere die Rohantwort einmal in einer sicheren Entwicklungsumgebung. Vergewissere dich, dass dein Code für Chat-Completions choices[0].message.content liest und nicht ein Antwortschema eines anderen Endpunkts erwartet.

Unerwartete Kosten während des Fallbacks

Protokolliere bei jedem Aufruf das versuchte Modell, begrenze die Route-Liste und prüfe Usage & Logs. Eine Fallback-Richtlinie ohne Frist und Kostenbegrenzung kann aus einer Benutzeraktion mehrere abrechenbare Anfragen machen.

Checkliste für die Produktion

Bevor du echten Traffic über die Integration sendest, bestätige:

• [ ] Der API-Schlüssel wird in einem Secret Manager oder in serverseitigen Umgebungsvariablen gespeichert.
• [ ] Entwicklung, Staging und Produktion verwenden getrennte Schlüssel.
• [ ] Die Basis-URL ist eine Konfiguration und nicht im gesamten Codebase fest verdrahtet.
• [ ] Das ausgewählte Modell ist verfügbar und für die tatsächliche Arbeitslast getestet.
• [ ] Timeouts, wiederholbare Fehler und Gesamt-Deadlines sind explizit definiert.
• [ ] Fallback-Modelle verwenden denselben erforderlichen Ausgabevertrag.
• [ ] Nutzungs- und Fehlerprotokolle sind für das Betriebsteam sichtbar.
• [ ] Kostenerwartungen wurden anhand der aktuellen Preisgestaltung überprüft.
• [ ] Schlüssel-Limits oder Allowlists sind dort konfiguriert, wo es sinnvoll ist.
• [ ] Ein Rollback-Pfad kann die vorherige Route schnell wiederherstellen.

Führe den ersten Aufruf aus, dann optimiere

Der schnellste Weg, Flatkey zu evaluieren, besteht darin, den ersten Test eng zu halten. Erstelle einen Schlüssel, ändere eine Basis-URL, sende eine Anfrage, lies eine Antwort und finde denselben Aufruf in Usage & Logs.

Nachdem dieser Pfad verifiziert ist, füge Fallback-Routing als beobachtbare Richtlinie hinzu statt als versteckte Retry-Schleife. Halte die Liste der freigegebenen Modelle kurz, bewahre Fehlernachweise auf, validiere die Ausgabe und prüfe die aktuellen Preise, bevor du den Traffic erhöhst.

Wenn du bereit bist, erstelle ein Flatkey-Konto, führe den ersten Aufruf über router.flatkey.ai aus und verwende den Datensatz in der Konsole als Abnahmetest für deine Integration.