Gateway IA (chat e generate)

AI Gateway

O AI Gateway permite que o teu projeto FloopFloop publicadochame um endpoint LLM gerido sem teres de guardar quaisquer credenciais de terceiros. O FloopFloop encaminha o pedido para o fornecedor correto, trata de retries e circuit-breaking, deduz dos créditos do proprietário do projeto e regista o uso no painel.

É isto que alimenta as funcionalidades de IA nos projetos que constróis no FloopFloop. Podes chamá-lo diretamente a partir do código do lado do servidor do teu projeto.

A maioria dos projetos não precisa de usar esta API HTTP diretamente.Cada projeto gerado inclui o SDK@floopfloop/ai pré-instalado, que encapsula tudo o que está documentado abaixo:

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

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

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

Utiliza esta referência quando precisares de chamar o gateway a partir de fora de um projeto FloopFloop (um backend personalizado, um script de depuração ou um runtime não-Node), ou quando quiseres o formato exato dos dados para um cliente personalizado.

Autenticação: chaves de IA do projeto

O gateway utiliza uma chave com âmbito de projetocom o prefixo flp_sk_, separada das chaves ao nível do utilizador flp_ usadas pelo resto da API. Existe uma chave ativa por projeto, provisionada automaticamente quando o projeto é criado.

• Encontra ou roda a tua chave no painel em Project settings → AI. A rotação gera um novo valorflp_sk_, revoga o antigo e desencadeia uma republicação para que o projeto em execução o receba.
• O FloopFloop incorpora a chave ativa no bundle de build do teu projeto como a variável de ambienteFLOOPFLOOP_AI_KEY, para que o código do lado do servidor a possa ler via process.env.FLOOPFLOOP_AI_KEYsem uma viagem adicional a um serviço de segredos.
• Todos os pedidos usam o esquema Bearer padrão:

  Authorization: Bearer flp_sk_…

• Apenas do lado do servidor.Nunca incorpores a chave em código do lado do cliente — qualquer pessoa com acesso ao código fonte da página pode esgotar os créditos do projeto.

Completações de chat

POST /api/v1/ai/chat

Chat no estilo OpenAI/Anthropic com uma lista de mensagens estruturada.

Corpo do pedido:

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

Resposta (200, sem 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", o gateway classifica a complexidade do pedido e escolhe um modelo de dimensão adequada. Os outros aliases suportados são:

Usar um alias é preferível a fixar um id de modelo do fornecedor — a plataforma redireciona através dos aliases à medida que os fornecedores chegam e partem, mas um id fixo começará a falhar no dia em que esse modelo for descontinuado pelo fornecedor.

Geração com prompt único

POST /api/v1/ai/generate

O mesmo encaminhamento de modelos que /chat, mas recebe um único prompt em texto simples em vez de um array de mensagens. Conveniente para casos de uso no estilo de completação.

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

O formato da resposta é idêntico ao de /chat.

Streaming (SSE)

Passa "stream": true em qualquer dos endpoints para receber uma resposta text/event-stream. Cada frame é JSON numa linha 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]

O frame final de usage é enviado antes de[DONE] para que os chamadores possam registar o custo sem um pedido separado. Se o upstream falhar a meio do stream, o stream emite data: {"error": "..."} seguido de[DONE]— os tokens já produzidos continuam a ser faturados.

Embeddings (ainda não disponível)

POST /api/v1/ai/embed

Devolve 501 NOT_IMPLEMENTED atualmente. O endpoint está reservado para que os SDKs possam implementar o método antes de o gateway ser lançado; não dependa dele ainda.

Limites e orçamentos

Cada chave de IA de projeto tem duas camadas de throttling para além do saldo de créditos:

• Pedidos por minuto— configurável emProject settings → AI, predefinição de 10 RPM. O excesso devolve 429 RATE_LIMITED com um cabeçalho Retry-After.
• Orçamento diário de tokens— reinicia à meia-noite UTC, predefinição de 10 000 tokens/dia. O excesso devolve 429 BUDGET_EXCEEDED.
• O tamanho de entrada por pedido está limitado ao limite de contexto do plano. Entradas demasiado grandes devolvem400 INPUT_TOO_LARGE com o limite na mensagem.

Para além disso, cada chamada deduz créditos calculados por token (entrada + saída) à taxa configurada do modelo. Quando o saldo de créditos do proprietário do projeto chega a zero, os pedidos devolvem 402 INSUFFICIENT_CREDITS.

Códigos de erro específicos do gateway

Todas as respostas do gateway — com sucesso ou com erro — incluem um cabeçalho X-Request-Id. Menciona-o quando reportares problemas para que o suporte possa encontrar o rastreio no registo de utilização de IA por projeto.