AI Gateway (chat & generate)

AI Gateway

De AI Gateway laat je gedeployde FloopFloop-projecteen beheerd LLM-endpoint aanroepen zonder dat je zelf third-party credentials nodig hebt. FloopFloop routeert het verzoek naar de juiste provider, verwerkt retries en circuit-breaking, trekt kosten af van de credits van de projecteigenaar en registreert het gebruik in het dashboard.

Dit is wat de AI-functies aandrijft in de projecten die je bouwt op FloopFloop. Je kunt het rechtstreeks aanroepen vanuit de server-side code van je project.

De meeste projecten hoeven deze ruwe HTTP-API niet te gebruiken.Elk gegenereerd project wordt geleverd met de@floopfloop/ai SDK vooraf geïnstalleerd, die alles wat hieronder gedocumenteerd staat omhult:

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

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

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

Gebruik deze referentie wanneer je de gateway wilt aanroepen vanuit een omgeving buiten een FloopFloop-project (een eigen backend, een debugscript of een niet-Node-runtime), of wanneer je het exacte wire-formaat wilt voor een eigen client.

Authenticatie: project AI-sleutels

De gateway gebruikt een project-scoped sleutel met het voorvoegsel flp_sk_, afzonderlijk van de gebruikersniveau-flp_-sleutels die door de rest van de API worden gebruikt. Er bestaat één actieve sleutel per project die automatisch wordt aangemaakt bij het aanmaken van het project.

• Vind of roteer je sleutel in het dashboard bij Project settings → AI. Rotatie genereert een nieuweflp_sk_-waarde, trekt de oude in en triggert een redeploy zodat het lopende project hem oppikt.
• FloopFloop bakt de actieve sleutel in de buildbundel van je project als de omgevingsvariabeleFLOOPFLOOP_AI_KEY, zodat server-side code hem kan lezen via process.env.FLOOPFLOOP_AI_KEYzonder een extra round-trip voor een secret.
• Alle verzoeken gebruiken het standaard Bearer-schema:

  Authorization: Bearer flp_sk_…

• Alleen server-side.Sluit de sleutel nooit in client-side code in — iedereen met de paginabron kan dan de credits van het project uitputten.

Chat-completions

POST /api/v1/ai/chat

OpenAI/Anthropic-stijl chat met een gestructureerde berichtenlijst.

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, niet-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"
}

Wanneer model "auto" is, classificeert de gateway de complexiteit van het verzoek en kiest een passend model. De andere ondersteunde aliassen zijn:

Vastzetten op een alias heeft de voorkeur boven het hardcoden van een provider-model-id — het platform herroutes via aliassen naarmate providers komen en gaan, maar een hardgecodeerd id zal gaan falen op de dag dat dat model door de upstream wordt beëindigd.

Generatie met één prompt

POST /api/v1/ai/generate

Dezelfde modelroutering als /chat, maar neemt een enkelepromptals platte tekst in plaats van een berichtenarray. Handig voor completion-achtige gebruiksscenario's.

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

De responsstructuur komt overeen met die van /chat.

Streaming (SSE)

Geef "stream": true mee bij elk endpoint om een text/event-stream-response te ontvangen. Elk frame is JSON in een data:-regel:

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]

Het laatste usage-frame wordt verzonden vóór[DONE] zodat aanroepers kosten kunnen registreren zonder een afzonderlijk verzoek. Als de upstream halverwege de stream een fout geeft, verzendt de stream data: {"error": "..."} gevolgd door [DONE]— al geproduceerde tokens worden nog steeds in rekening gebracht.

Embeddings (nog niet beschikbaar)

POST /api/v1/ai/embed

Geeft vandaag 501 NOT_IMPLEMENTEDterug. Het endpoint is gereserveerd zodat SDK's de methode alvast kunnen toevoegen voordat de gateway live gaat; vertrouw er nog niet op.

Limieten en budgetten

Elke project-AI-sleutel heeft twee lagen van beperking bovenop het creditsaldo:

• Verzoeken per minuut— instelbaar bijProject settings → AI, standaard 10 RPM. Overschrijding geeft 429 RATE_LIMITED terug met eenRetry-After-header.
• Dagelijks tokenbudget— wordt gereset om UTC middernacht, standaard 10.000 tokens/dag. Overschrijding geeft429 BUDGET_EXCEEDED terug.
• De invoergrootte per verzoek is beperkt tot de contextlimiet van het plan. Te grote invoer geeft 400 INPUT_TOO_LARGEterug met de limiet in de melding.

Bovenop die limieten trekt elke aanroep credits af, geprijsd per (invoer + uitvoer) token tegen het geconfigureerde tarief van het model. Zodra het creditsaldo van de projecteigenaar nul bereikt, geven verzoeken 402 INSUFFICIENT_CREDITS terug.

Foutcodes specifiek voor de gateway

Elke gateway-response — geslaagd of mislukt — bevat een X-Request-Id-header. Vermeld hem bij het melden van problemen zodat support de trace kan vinden in het per-project AI-gebruikslogboek.