AI Gateway (chat & generate)

AI Gateway

AI Gateway memungkinkan proyek FloopFloop yang di-deploymemanggil endpoint LLM terkelola tanpa Anda menyimpan kredensial pihak ketiga apa pun. FloopFloop meneruskan permintaan ke provider yang tepat, menangani percobaan ulang dan circuit-breaking, mengurangi dari kredit pemilik proyek, dan mencatat penggunaan untuk dasbor.

Inilah yang menggerakkan fitur AI di dalam proyek yang Anda buat di FloopFloop. Anda dapat memanggilnya langsung dari kode sisi server proyek Anda.

Sebagian besar proyek tidak perlu menggunakan API HTTP mentah ini.Setiap proyek yang dihasilkan sudah dilengkapi dengan SDK@floopfloop/ai yang mengemas semua yang didokumentasikan di bawah ini:

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

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

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

Gunakan referensi ini saat Anda perlu memanggil gateway dari luar proyek FloopFloop (backend kustom, skrip debugging, atau runtime non-Node), atau saat Anda memerlukan format wire yang tepat untuk klien kustom.

Autentikasi: project AI key

Gateway menggunakan key bercakupan proyek dengan prefiks flp_sk_, terpisah dari key tingkat penggunaflp_ yang digunakan oleh bagian API lainnya. Satu key aktif ada per proyek dan disediakan secara otomatis saat proyek dibuat.

• Temukan atau rotasi key Anda di dasbor di Project settings → AI. Rotasi menghasilkan nilaiflp_sk_ baru, mencabut yang lama, dan memicu redeploy agar proyek yang berjalan mengambilnya.
• FloopFloop menyematkan key aktif ke dalam bundle build proyek Anda sebagai variabel lingkunganFLOOPFLOOP_AI_KEY, sehingga kode sisi server dapat membacanya melalui process.env.FLOOPFLOOP_AI_KEYtanpa perlu mengambil secret.
• Semua permintaan menggunakan skema Bearer standar:

  Authorization: Bearer flp_sk_…

• Hanya sisi server.Jangan pernah menyematkan key di kode sisi klien — siapa pun dengan sumber halaman dapat menguras kredit proyek.

Chat completions

POST /api/v1/ai/chat

Chat bergaya OpenAI/Anthropic dengan daftar pesan terstruktur.

Request body:

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

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

Saat model adalah "auto", gateway mengklasifikasikan kompleksitas permintaan dan memilih model yang berukuran tepat. Alias lain yang didukung adalah:

Lebih diutamakan menggunakan alias daripada hard-coding ID model provider — platform mengalihkan melalui alias saat provider datang dan pergi, tetapi ID yang di-hardcode akan mulai gagal saat model tersebut dihentikan oleh provider.

Pembuatan satu-prompt

POST /api/v1/ai/generate

Routing model yang sama dengan /chat, tetapi mengambilprompt teks biasa tunggal alih-alih array pesan. Nyaman untuk kasus penggunaan gaya 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
}

Bentuk respons cocok dengan /chat.

Streaming (SSE)

Teruskan "stream": true pada salah satu endpoint untuk menerima respons text/event-stream. Setiap frame adalah JSON dalam baris 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]

Frame usage terakhir dikirim sebelum[DONE] sehingga pemanggil dapat mencatat biaya tanpa permintaan terpisah. Jika upstream mengalami error di tengah stream, stream memancarkan data: {"error": "..."} diikuti oleh [DONE]— token yang sudah dihasilkan tetap ditagih.

Embeddings (belum tersedia)

POST /api/v1/ai/embed

Mengembalikan 501 NOT_IMPLEMENTED saat ini. Endpoint dicadangkan agar SDK dapat menstub metode sebelum gateway dikirimkan; jangan mengandalkannya dulu.

Batas dan anggaran

Setiap project AI key memiliki dua lapisan throttling di atas saldo kredit:

• Permintaan per menit— dapat dikonfigurasi diProject settings → AI, default 10 RPM. Kelebihan mengembalikan 429 RATE_LIMITED dengan headerRetry-After.
• Anggaran token harian— direset pada tengah malam UTC, default 10.000 token/hari. Kelebihan mengembalikan429 BUDGET_EXCEEDED.
• Ukuran input per permintaan dibatasi pada batas konteks paket. Input yang terlalu besar mengembalikan 400 INPUT_TOO_LARGEdengan batas dalam pesan.

Di atas itu, setiap panggilan mengurangi kredit yang dihargai per token (input + output) pada tarif yang dikonfigurasi model. Setelah saldo kredit pemilik proyek mencapai nol, permintaan mengembalikan 402 INSUFFICIENT_CREDITS.

Kode error khusus gateway

Setiap respons gateway — sukses atau gagal — membawa header X-Request-Id. Sebutkan saat melaporkan masalah agar support dapat menemukan jejak di log penggunaan AI per proyek.