Gateway IA (chat e generate)

AI Gateway

L'AI Gateway permette al tuo progetto FloopFloop distribuitodi chiamare un endpoint LLM gestito senza che tu debba detenere credenziali di terze parti. FloopFloop instrada la richiesta al provider corretto, gestisce i tentativi e il circuit-breaking, deduce dai crediti del proprietario del progetto e registra l'utilizzo per la dashboard.

Questo è ciò che alimenta le funzionalità AI nei progetti che costruisci su FloopFloop. Puoi chiamarlo direttamente dal codice lato server del tuo progetto.

La maggior parte dei progetti non ha bisogno di usare questa API HTTP grezza.Ogni progetto generato viene fornito con l'SDK @floopfloop/aipre-installato, che racchiude tutto ciò che è documentato di seguito:

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

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

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

Usa questo riferimento quando hai bisogno di chiamare il gateway dall'esterno di un progetto FloopFloop (un backend personalizzato, uno script di debug o un runtime non Node), oppure quando vuoi il formato wire esatto per un client personalizzato.

Autenticazione: chiavi AI del progetto

Il gateway usa una chiave con scope a livello di progetto con prefisso flp_sk_, separata dalle chiavi flp_a livello utente usate dal resto dell'API. Esiste una chiave attiva per progetto, che viene fornita automaticamente alla creazione del progetto.

• Trova o ruota la tua chiave nella dashboard su Impostazioni progetto → AI. La rotazione genera un nuovo valoreflp_sk_, revoca il vecchio e avvia un ridistribuzione affinché il progetto in esecuzione lo recepisca.
• FloopFloop incorpora la chiave attiva nel bundle di build del tuo progetto come variabile d'ambiente FLOOPFLOOP_AI_KEY, in modo che il codice lato server possa leggerla tramiteprocess.env.FLOOPFLOOP_AI_KEY senza un viaggio di andata e ritorno per i segreti.
• Tutte le richieste usano lo schema Bearer standard:

  Authorization: Bearer flp_sk_…

• Solo lato server.Non incorporare mai la chiave nel codice lato client — chiunque abbia accesso al sorgente della pagina può prosciugare i crediti del progetto.

Completamenti chat

POST /api/v1/ai/chat

Chat in stile OpenAI/Anthropic con un elenco strutturato di messaggi.

Corpo della richiesta:

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

Risposta (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"
}

Quando model è "auto", il gateway classifica la complessità della richiesta e sceglie un modello di dimensioni adeguate. Gli altri alias supportati sono:

È preferibile fissare un alias piuttosto che hard-codare un id di modello del provider — la piattaforma reindirizza tramite gli alias man mano che i provider cambiano, ma un id hard-codato inizierà a fallire il giorno in cui quel modello viene dismesso dall'upstream.

Generazione a prompt singolo

POST /api/v1/ai/generate

Stesso routing del modello di /chat, ma accetta un singolo promptin testo semplice invece di un array di messaggi. Comodo per i casi d'uso di tipo completion.

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

La forma della risposta corrisponde a /chat.

Streaming (SSE)

Passa "stream": true su entrambi gli endpoint per ricevere una risposta text/event-stream. Ogni frame è JSON in una riga data::

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]

L'ultimo frame usage viene inviato prima di[DONE]in modo che i chiamanti possano registrare il costo senza una richiesta separata. Se l'upstream va in errore a metà stream, lo stream emettedata: {"error": "..."} seguito da [DONE]— i token già prodotti vengono comunque addebitati.

Embedding (non ancora disponibile)

POST /api/v1/ai/embed

Restituisce 501 NOT_IMPLEMENTEDattualmente. L'endpoint è riservato in modo che gli SDK possano implementare il metodo in anticipo rispetto alla distribuzione del gateway; non farci affidamento ancora.

Limiti e budget

Ogni chiave AI del progetto ha due livelli di throttling oltre al saldo dei crediti:

• Richieste al minuto— configurabile inImpostazioni progetto → AI, predefinito a 10 RPM. Le eccedenze restituiscono 429 RATE_LIMITEDcon un header Retry-After.
• Budget giornaliero di token— si azzera a mezzanotte UTC, predefinito a 10 000 token/giorno. Le eccedenze restituiscono 429 BUDGET_EXCEEDED.
• La dimensione dell'input per richiesta è limitata al limite di contesto del piano. Gli input troppo grandi restituiscono400 INPUT_TOO_LARGE con il limite nel messaggio.

Oltre a questi, ogni chiamata deduce crediti calcolati per token (input + output) al tasso configurato per il modello. Una volta che il saldo dei crediti del proprietario del progetto raggiunge zero, le richieste restituiscono 402 INSUFFICIENT_CREDITS.

Codici di errore specifici del gateway

Ogni risposta del gateway — successo o errore — include un header X-Request-Id. Citalo quando segnali problemi in modo che il supporto possa trovare la traccia nel log di utilizzo AI per progetto.