Gateway IA (chat et generate)

AI Gateway

L'AI Gateway permet à votre projet FloopFloop déployéd'appeler un endpoint LLM géré sans que vous déteniez de justificatifs tiers. FloopFloop achemine la requête vers le bon fournisseur, gère les nouvelles tentatives et le disjoncteur, déduit des crédits du propriétaire du projet et enregistre l'utilisation pour le tableau de bord.

C'est ce qui alimente les fonctionnalités IA dans les projets que vous construisez sur FloopFloop. Vous pouvez l'appeler directement depuis le code côté serveur de votre projet.

La plupart des projets n'ont pas besoin d'utiliser cette API HTTP brute.Chaque projet généré est livré avec le SDK@floopfloop/ai préinstallé, qui encapsule tout ce qui est documenté ci-dessous :

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

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

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

Utilisez cette référence lorsque vous devez appeler la gateway depuis l'extérieur d'un projet FloopFloop (un backend personnalisé, un script de débogage ou un runtime non-Node), ou lorsque vous souhaitez connaître le format exact du fil pour un client personnalisé.

Authentification : clés AI de projet

La gateway utilise une clé à portée projet avec le préfixe flp_sk_, distincte des clésflp_au niveau utilisateur utilisées par le reste de l'API. Une seule clé active existe par projet et est provisionnée automatiquement lors de la création du projet.

• Trouvez ou faites tourner votre clé dans le tableau de bord sous Paramètres du projet → IA. La rotation génère une nouvelle valeur flp_sk_, révoque l'ancienne et déclenche un redéploiement afin que le projet en cours la récupère.
• FloopFloop intègre la clé active dans le bundle de build de votre projet comme variable d'environnementFLOOPFLOOP_AI_KEY, afin que le code côté serveur puisse la lire via process.env.FLOOPFLOOP_AI_KEYsans aller-retour de secret.
• Toutes les requêtes utilisent le schéma Bearer standard :

  Authorization: Bearer flp_sk_…

• Côté serveur uniquement.N'intégrez jamais la clé dans du code côté client — n'importe qui ayant accès au code source de la page pourrait alors drainer les crédits du projet.

Complétions de chat

POST /api/v1/ai/chat

Chat de style OpenAI/Anthropic avec une liste de messages structurée.

Corps de la requête :

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

Réponse (200, sans 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"
}

Lorsque model vaut "auto", la gateway classifie la complexité de la requête et choisit un modèle de taille appropriée. Les autres alias supportés sont :

Il est préférable d'épingler à un alias plutôt que de coder en dur un id de modèle fournisseur — la plateforme redirige via les alias lorsque les fournisseurs évoluent, mais un id codé en dur commencera à échouer le jour où ce modèle sera retiré en amont.

Génération à prompt unique

POST /api/v1/ai/generate

Même routage de modèle que /chat, mais prend un seulprompten texte brut au lieu d'un tableau de messages. Pratique pour les cas d'usage de style complétion.

{
  "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 forme de la réponse correspond à /chat.

Streaming (SSE)

Passez "stream": truesur l'un ou l'autre endpoint pour recevoir une réponse text/event-stream. Chaque trame est du JSON dans une ligne 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]

La trame usage finale est envoyée avant[DONE] afin que les appelants puissent enregistrer le coût sans requête supplémentaire. Si le fournisseur en amont rencontre une erreur en cours de stream, le flux émet data: {"error": "..."} suivi de[DONE]— les tokens déjà produits sont toujours facturés.

Embeddings (pas encore disponible)

POST /api/v1/ai/embed

Retourne 501 NOT_IMPLEMENTEDaujourd'hui. L'endpoint est réservé afin que les SDK puissent implémenter la méthode en avance sur le déploiement de la gateway ; ne vous en servez pas encore.

Limites et budgets

Chaque clé AI de projet dispose de deux couches de limitation au-dessus du solde de crédits :

• Requêtes par minute— configurable dansParamètres du projet → IA, par défaut 10 RPM. L'excédent retourne 429 RATE_LIMITED avec un en-tête Retry-After.
• Budget de tokens quotidien— se réinitialise à minuit UTC, par défaut 10 000 tokens/jour. L'excédent retourne429 BUDGET_EXCEEDED.
• La taille d'entrée par requête est limitée au contexte du plan. Les entrées trop grandes retournent 400 INPUT_TOO_LARGEavec la limite dans le message.

En plus de cela, chaque appel déduit des crédits facturés par token (entrée + sortie) au taux configuré du modèle. Une fois que le solde de crédits du propriétaire du projet atteint zéro, les requêtes retournent 402 INSUFFICIENT_CREDITS.

Codes d'erreur spécifiques à la gateway

Chaque réponse de la gateway — succès ou échec — porte un en-tête X-Request-Id. Citez-le lorsque vous signalez des problèmes afin que le support puisse retrouver la trace dans le journal d'utilisation IA par projet.