Bramka AI (chat i generate)

Brama AI

Brama AI umożliwia wdrożonemu projektowi FloopFloopwywoływanie zarządzanego punktu końcowego LLM bez konieczności posiadania poświadczeń podmiotów trzecich. FloopFloop kieruje żądanie do odpowiedniego dostawcy, obsługuje ponowne próby i wyłączanie obwodów, odejmuje kredyty od właściciela projektu i rejestruje użycie na potrzeby panelu.

To właśnie zasila funkcje AI wewnątrz projektów budowanych na FloopFloop. Możesz wywoływać je bezpośrednio z kodu po stronie serwera swojego projektu.

Większość projektów nie musi używać tego surowego API HTTP.Każdy wygenerowany projekt jest dostarczany z preinstalowanym SDK@floopfloop/ai, który opakowuje wszystko udokumentowane poniżej:

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

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

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

Skorzystaj z tego przewodnika, gdy musisz wywoływać bramę spoza projektu FloopFloop (niestandardowy backend, skrypt do debugowania lub środowisko uruchomieniowe inne niż Node), albo gdy potrzebujesz dokładnego formatu transmisji dla niestandardowego klienta.

Uwierzytelnianie: klucze AI projektu

Brama używa klucza o zakresie projektu z prefiksemflp_sk_, oddzielnego od kluczy flp_na poziomie użytkownika używanych przez resztę API. Jeden aktywny klucz istnieje na projekt i jest automatycznie udostępniany podczas tworzenia projektu.

• Znajdź lub zrotuj klucz w panelu w sekcji Ustawienia projektu → AI. Rotacja generuje nową wartośćflp_sk_, unieważnia starą i uruchamia ponowne wdrożenie, aby działający projekt ją odebrał.
• FloopFloop wbudowuje aktywny klucz do pakietu kompilacji projektu jako zmienną środowiskowąFLOOPFLOOP_AI_KEY, dzięki czemu kod po stronie serwera może odczytać go przez process.env.FLOOPFLOOP_AI_KEYbez dodatkowego wywołania.
• Wszystkie żądania używają standardowego schematu Bearer:

  Authorization: Bearer flp_sk_…

• Tylko po stronie serwera.Nigdy nie osadzaj klucza w kodzie po stronie klienta — każdy, kto ma dostęp do źródła strony, może opróżnić kredyty projektu.

Uzupełnienia czatu

POST /api/v1/ai/chat

Czat w stylu OpenAI/Anthropic z ustrukturyzowaną listą wiadomości.

Treść żądania:

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

Odpowiedź (200, bez strumieniowania):

{
  "content": "...",
  "model":   "auto",
  "usage": {
    "input_tokens":      123,
    "output_tokens":     45,
    "total_tokens":      168,
    "credits_used":      0.21,
    "credits_remaining": 4837.79
  },
  "finishReason": "end_turn"
}

Gdy model ma wartość "auto", brama klasyfikuje złożoność żądania i wybiera model odpowiedniego rozmiaru. Pozostałe obsługiwane aliasy to:

Preferowane jest przypisanie do aliasu zamiast twardego kodowania identyfikatora modelu dostawcy — platforma przekierowuje przez aliasy w miarę pojawiania się i znikania dostawców, ale twardo zakodowany identyfikator przestanie działać w dniu, gdy dany model zostanie wycofany przez dostawcę.

Generowanie z pojedynczego polecenia

POST /api/v1/ai/generate

To samo kierowanie modelu co w przypadku /chat, ale przyjmuje pojedynczy prompt w postaci zwykłego tekstu zamiast tablicy wiadomości. Wygodne do przypadków użycia w stylu uzupełniania.

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

Kształt odpowiedzi pasuje do /chat.

Strumieniowanie (SSE)

Przekaż "stream": true w którymkolwiek punkcie końcowym, aby otrzymać odpowiedź text/event-stream. Każda ramka to JSON w linii 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]

Końcowa ramka usage jest wysyłana przed[DONE], dzięki czemu wywołujący mogą rejestrować koszty bez dodatkowego żądania. Jeśli upstream napotka błąd w trakcie strumieniowania, strumień emituje data: {"error": "..."}a następnie [DONE]— tokeny już wyprodukowane są nadal rozliczane.

Osadzenia (jeszcze niedostępne)

POST /api/v1/ai/embed

Dziś zwraca 501 NOT_IMPLEMENTED. Punkt końcowy jest zarezerwowany, aby SDK mogły z wyprzedzeniem opracować metodę przed uruchomieniem bramy; na razie nie polegaj na nim.

Limity i budżety

Każdy klucz AI projektu ma dwie warstwy ograniczania powyżej salda kredytów:

• Żądania na minutę— konfigurowalne wUstawienia projektu → AI, domyślnie 10 RPM. Nadmiar zwraca 429 RATE_LIMITED z nagłówkiemRetry-After.
• Dzienny budżet tokenów— resetuje się o północy UTC, domyślnie 10 000 tokenów/dzień. Nadmiar zwraca429 BUDGET_EXCEEDED.
• Rozmiar danych wejściowych na żądanie jest ograniczony przez limit kontekstu planu. Zbyt duże dane wejściowe zwracają 400 INPUT_TOO_LARGEz wartością limitu w komunikacie.

Oprócz tego każde wywołanie odejmuje kredyty wycenione na podstawie (wejście + wyjście) tokenów według skonfigurowanej stawki modelu. Gdy saldo kredytów właściciela projektu osiągnie zero, żądania zwracają402 INSUFFICIENT_CREDITS.

Kody błędów specyficzne dla bramy

Każda odpowiedź bramy — pomyślna lub błędna — zawiera nagłówek X-Request-Id. Podaj go podczas zgłaszania problemów, aby pomoc techniczna mogła znaleźć ślad w dzienniku użycia AI projektu.