Gateway de IA (chat y generate)

AI Gateway

El AI Gateway permite a tu proyecto de FloopFloop implementadollamar a un endpoint de LLM gestionado sin necesidad de tener credenciales de terceros. FloopFloop enruta la solicitud al proveedor adecuado, gestiona los reintentos y el circuit-breaking, deduce los créditos del propietario del proyecto y registra el uso en el panel.

Esto es lo que impulsa las funciones de IA dentro de los proyectos que construyes en FloopFloop. Puedes llamarlo directamente desde el código del lado del servidor de tu proyecto.

La mayoría de los proyectos no necesitan usar esta API HTTP directamente.Cada proyecto generado viene con el SDK@floopfloop/ai preinstalado, que envuelve todo lo documentado a continuación:

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

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

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

Usa esta referencia cuando necesites llamar al gateway desde fuera de un proyecto de FloopFloop (un backend personalizado, un script de depuración o un entorno de ejecución que no sea Node), o cuando quieras conocer el formato exacto de transferencia para un cliente personalizado.

Autenticación: claves de IA del proyecto

El gateway usa una clave de alcance por proyecto con el prefijo flp_sk_, separada de las claves a nivel de usuarioflp_ que usa el resto de la API. Existe una clave activa por proyecto y se aprovisiona automáticamente cuando se crea el proyecto.

• Encuentra o rota tu clave en el panel en Configuración del proyecto → IA. La rotación genera un nuevo valorflp_sk_, revoca el anterior y activa una reimplementación para que el proyecto en ejecución lo adopte.
• FloopFloop incorpora la clave activa en el paquete de compilación de tu proyecto como la variable de entornoFLOOPFLOOP_AI_KEY, para que el código del lado del servidor pueda leerla mediante process.env.FLOOPFLOOP_AI_KEYsin una vuelta adicional a los secretos.
• Todas las solicitudes usan el esquema Bearer estándar:

  Authorization: Bearer flp_sk_…

• Solo del lado del servidor.Nunca incluyas la clave en código del lado del cliente — cualquiera con el código fuente de la página puede agotar los créditos del proyecto.

Completaciones de chat

POST /api/v1/ai/chat

Chat al estilo OpenAI/Anthropic con una lista estructurada de mensajes.

Cuerpo de la solicitud:

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

Respuesta (200, sin 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"
}

Cuando model es "auto", el gateway clasifica la complejidad de la solicitud y elige un modelo del tamaño adecuado. Los otros alias admitidos son:

Se prefiere fijar un alias antes que codificar de forma fija un id de modelo del proveedor — la plataforma redirige a través de los alias cuando los proveedores entran y salen, pero un id codificado de forma fija comenzará a fallar el día en que ese modelo quede en desuso en el proveedor.

Generación con un solo prompt

POST /api/v1/ai/generate

Mismo enrutamiento de modelos que /chat, pero recibe un únicoprompt de texto plano en lugar de un array de mensajes. Conveniente para casos de uso de estilo completación.

{
  "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 de la respuesta coincide con la de /chat.

Streaming (SSE)

Pasa "stream": true en cualquiera de los endpoints para recibir una respuesta text/event-stream. Cada frame es JSON en una línea 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]

El frame final de usage se envía antes de[DONE] para que los solicitantes puedan registrar el costo sin una solicitud adicional. Si el proveedor da error a mitad del stream, el stream emite data: {"error": "..."} seguido de [DONE]— los tokens ya producidos se siguen facturando.

Embeddings (aún no disponible)

POST /api/v1/ai/embed

Devuelve 501 NOT_IMPLEMENTED hoy. El endpoint está reservado para que los SDK puedan crear el stub del método antes de que el gateway lo implemente; no dependas de él todavía.

Límites y presupuestos

Cada clave de IA de proyecto tiene dos capas de regulación además del saldo de créditos:

• Solicitudes por minuto— configurable enConfiguración del proyecto → IA, por defecto 10 RPM. El exceso devuelve 429 RATE_LIMITED con un encabezado Retry-After.
• Presupuesto diario de tokens— se restablece a medianoche UTC, por defecto 10 000 tokens/día. El exceso devuelve429 BUDGET_EXCEEDED.
• El tamaño de entrada por solicitud está limitado al contexto del plan. Las entradas demasiado grandes devuelven 400 INPUT_TOO_LARGEcon el límite en el mensaje.

Además de eso, cada llamada deduce créditos según el precio por (tokens de entrada + salida) a la tasa configurada del modelo. Una vez que el saldo de créditos del propietario del proyecto llega a cero, las solicitudes devuelven 402 INSUFFICIENT_CREDITS.

Códigos de error específicos del gateway

Cada respuesta del gateway — éxito o error — lleva un encabezado X-Request-Id. Cítalo al reportar problemas para que el soporte pueda encontrar el rastro en el registro de uso de IA por proyecto.