KI-Gateway (Chat & Generate)

AI Gateway

Das AI Gateway ermöglicht es Ihrem bereitgestellten FloopFloop-Projekt, einen verwalteten LLM-Endpunkt aufzurufen, ohne dass Sie Drittanbieter-Anmeldeinformationen benötigen. FloopFloop leitet die Anfrage an den richtigen Anbieter weiter, übernimmt Wiederholungen und Circuit-Breaking, zieht vom Credit-Guthaben des Projekteigentümers ab und protokolliert die Nutzung für das Dashboard.

Dies ermöglicht die KI-Funktionen in den Projekten, die Sie auf FloopFloop erstellen. Sie können es direkt aus dem serverseitigen Code Ihres Projekts aufrufen.

Die meisten Projekte müssen diese rohe HTTP-API nicht verwenden.Jedes generierte Projekt wird mit dem vorinstallierten@floopfloop/ai-SDK geliefert, das alles unten Dokumentierte einschließt:

import { FloopAI } from "@floopfloop/ai";

const ai = new FloopAI({ apiKey: process.env.FLOOPFLOOP_AI_KEY! });

const reply = await ai.chat({ messages, model: "smart" });

Verwenden Sie diese Referenz, wenn Sie das Gateway von außerhalb eines FloopFloop-Projekts aufrufen müssen (ein benutzerdefiniertes Backend, ein Debug-Skript oder eine Nicht-Node-Laufzeit), oder wenn Sie das genaue Wire-Format für einen benutzerdefinierten Client benötigen.

Authentifizierung: Projekt-KI-Schlüssel

Das Gateway verwendet einen projektbezogenen Schlüssel mit dem Präfix flp_sk_, der von den benutzerebenenflp_-Schlüsseln der restlichen API getrennt ist. Pro Projekt existiert ein aktiver Schlüssel, der automatisch bei der Projekterstellung bereitgestellt wird.

• Finden oder rotieren Sie Ihren Schlüssel im Dashboard unter Project settings → AI. Die Rotation generiert einen neuenflp_sk_-Wert, widerruft den alten und löst ein Neu-Deployment aus, damit das laufende Projekt ihn aufnimmt.
• FloopFloop baut den aktiven Schlüssel in das Build-Bundle Ihres Projekts als Umgebungsvariable FLOOPFLOOP_AI_KEY ein, sodass serverseitiger Code ihn über process.env.FLOOPFLOOP_AI_KEY lesen kann, ohne einen Secret-Round-Trip zu benötigen.
• Alle Anfragen verwenden das Standard-Bearer-Schema:

  Authorization: Bearer flp_sk_…

• Nur serverseitig.Betten Sie den Schlüssel niemals in clientseitigen Code ein — jeder mit dem Seitenquellcode kann dann die Credits des Projekts aufbrauchen.

Chat-Vervollständigungen

POST /api/v1/ai/chat

OpenAI/Anthropic-Stil-Chat mit einer strukturierten Nachrichtenliste.

Request body:

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user",   "content": "Summarise this in one sentence: ..." }
  ],
  "model":       "auto",   // optional alias; default "auto" picks the best fit
  "system":      "...",    // optional, alternative to a system role message
  "temperature": 0.7,      // optional, 0-2
  "max_tokens":  1024,     // optional, clamped to plan limit
  "stream":      false     // optional, default false (see streaming below)
}

Response (200, non-streaming):

{
  "content": "...",
  "model":   "auto",
  "usage": {
    "input_tokens":      123,
    "output_tokens":     45,
    "total_tokens":      168,
    "credits_used":      0.21,
    "credits_remaining": 4837.79
  },
  "finishReason": "end_turn"
}

Wenn model "auto" ist, klassifiziert das Gateway die Anfragekomplexität und wählt ein angemessen großes Modell aus. Die anderen unterstützten Aliase sind:

Das Festlegen auf einen Alias wird dem Hard-Coding einer Provider-Modell-ID vorgezogen — die Plattform leitet durch Aliase um, wenn Anbieter kommen und gehen, aber eine hard-kodierte ID beginnt zu scheitern, sobald dieses Modell beim Upstream eingestellt wird.

Einzelne-Prompt-Generierung

POST /api/v1/ai/generate

Gleiche Modell-Weiterleitung wie /chat, nimmt aber einen einzelnen Klartext-prompt anstatt eines Nachrichten-Arrays an. Praktisch für Completion-Anwendungsfälle.

{
  "prompt":      "Write a haiku about the moon",   // required, ≤ 500_000 chars
  "system":      "...",                            // optional
  "model":       "auto",                           // optional
  "temperature": 0.7,                              // optional
  "max_tokens":  1024,                             // optional
  "stream":      false                             // optional
}

Die Antwortstruktur entspricht der von /chat.

Streaming (SSE)

Übergeben Sie "stream": true an einem der Endpunkte, um eine text/event-stream-Antwort zu erhalten. Jeder Frame ist JSON in einer data:-Zeile:

data: {"text": "Once "}

data: {"text": "upon "}

data: {"text": "a time"}

data: {"usage": { "input_tokens": 14, "output_tokens": 47, "total_tokens": 61, "credits_used": 0.07, "credits_remaining": 4837.93 }, "finishReason": "end_turn"}

data: [DONE]

Der letzte usage-Frame wird vor[DONE] gesendet, damit Aufrufer die Kosten ohne eine separate Anfrage aufzeichnen können. Wenn der Upstream mitten im Stream einen Fehler zurückgibt, sendet der Stream data: {"error": "..."} gefolgt von [DONE]— bereits produzierte Tokens werden dennoch berechnet.

Embeddings (noch nicht verfügbar)

POST /api/v1/ai/embed

Gibt heute 501 NOT_IMPLEMENTED zurück. Der Endpunkt ist reserviert, damit SDKs die Methode vorab implementieren können, bevor das Gateway ausgeliefert wird; verlassen Sie sich noch nicht darauf.

Limits und Budgets

Jeder Projekt-KI-Schlüssel hat zwei Drosselungsebenen zusätzlich zum Credit-Guthaben:

• Anfragen pro Minute— konfigurierbar unterProject settings → AI, standardmäßig 10 RPM. Überschreitung gibt 429 RATE_LIMITED mit einemRetry-After-Header zurück.
• Tägliches Token-Budget— setzt um UTC-Mitternacht zurück, standardmäßig 10 000 Tokens/Tag. Überschreitung gibt429 BUDGET_EXCEEDED zurück.
• Die Eingabegröße pro Anfrage ist auf das Kontextlimit des Plans begrenzt. Zu große Eingaben geben 400 INPUT_TOO_LARGEmit dem Limit in der Meldung zurück.

Zusätzlich zieht jeder Aufruf Credits ab, die pro (Eingabe + Ausgabe) Token zum konfigurierten Satz des Modells berechnet werden. Sobald das Credit-Guthaben des Projekteigentümers null erreicht, geben Anfragen 402 INSUFFICIENT_CREDITS zurück.

Für das Gateway spezifische Fehlercodes

Jede Gateway-Antwort — Erfolg oder Fehler — enthält einen X-Request-Id-Header. Geben Sie ihn an, wenn Sie Probleme melden, damit der Support die Spur im Pro-Projekt-KI-Nutzungsprotokoll finden kann.