AI ゲートウェイ（chat と generate）

AI Gateway

AI Gateway を使用すると、デプロイ済みの FloopFloop プロジェクトがサードパーティの認証情報を保持せずにマネージド LLM エンドポイントを呼び出せます。FloopFloop がリクエストを適切なプロバイダーにルーティングし、再試行とサーキットブレーキングを処理し、プロジェクトオーナーのクレジットから差し引き、ダッシュボードの使用状況を記録します。

これは FloopFloop 上に構築したプロジェクト内の AI 機能を動かすものです。プロジェクトのサーバーサイドコードから直接呼び出すことができます。

ほとんどのプロジェクトはこのロー HTTP API を使用する必要はありません。生成されたすべてのプロジェクトには、以下のすべてをラップする @floopfloop/ai SDK がプリインストールされています：

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

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

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

FloopFloop プロジェクト外（カスタムバックエンド、デバッグスクリプト、または非 Node ランタイム）からゲートウェイを呼び出す必要がある場合、またはカスタムクライアント向けの正確なワイヤーフォーマットが必要な場合は、このリファレンスを使用してください。

認証：プロジェクト AI キー

ゲートウェイはプレフィックス flp_sk_ を持つプロジェクトスコープのキーを使用します。これは API の残りの部分で使用されるユーザーレベルの flp_ キーとは別です。プロジェクトごとに 1 つのアクティブなキーが存在し、プロジェクト作成時に自動的にプロビジョニングされます。

• ダッシュボードの Project settings → AI でキーを確認またはローテーションします。ローテーションすると新しい flp_sk_ 値が生成され、古い値が失効し、実行中のプロジェクトが新しいキーを取得するよう再デプロイがトリガーされます。
• FloopFloop はアクティブなキーを環境変数 FLOOPFLOOP_AI_KEY としてプロジェクトのビルドバンドルに組み込むため、サーバーサイドコードはシークレットのラウンドトリップなしに process.env.FLOOPFLOOP_AI_KEY で読み取ることができます。
• すべてのリクエストは標準の Bearer スキームを使用します：

  Authorization: Bearer flp_sk_…

• サーバーサイドのみ。クライアントサイドコードにキーを埋め込まないでください — ページソースにアクセスできる人誰でもプロジェクトのクレジットを消費できてしまいます。

チャット補完

POST /api/v1/ai/chat

構造化されたメッセージリストによる OpenAI/Anthropic スタイルのチャット。

リクエストボディ：

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

レスポンス (200、非ストリーミング):

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

model が "auto" の場合、ゲートウェイはリクエストの複雑さを分類し、適切なサイズのモデルを選択します。その他のサポートされるエイリアスは以下のとおりです：

プロバイダーモデル id をハードコードするよりエイリアスへのピン留めが推奨されます — プロバイダーが入れ替わってもプラットフォームはエイリアスを通じて再ルーティングしますが、ハードコードされた id はそのモデルが上流で廃止された日に失敗し始めます。

シングルプロンプト生成

POST /api/v1/ai/generate

/chat と同じモデルルーティングですが、メッセージ配列の代わりに単一のプレーンテキスト prompt を受け取ります。補完スタイルのユースケースに便利です。

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

レスポンスの形式は /chat と同じです。

ストリーミング (SSE)

どちらのエンドポイントでも "stream": true を渡すと、text/event-stream レスポンスを受け取ります。各フレームは data: 行内の JSON です：

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]

最終の usage フレームは [DONE] の前に送信されるため、呼び出し元は別のリクエストなしにコストを記録できます。上流がストリーム中にエラーになった場合、ストリームは data: {"error": "..."} に続いて [DONE]を送信します — すでに生成されたトークンは引き続き課金されます。

埋め込み（未提供）

POST /api/v1/ai/embed

現在は 501 NOT_IMPLEMENTED を返します。SDK がゲートウェイのリリース前にメソッドをスタブできるよう、エンドポイントは予約されています。まだ依存しないでください。

制限とバジェット

各プロジェクト AI キーには、クレジット残高に加えて 2 層のスロットリングがあります：

• 1 分あたりのリクエスト数 — Project settings → AI で設定可能、デフォルトは 10 RPM。超過すると Retry-After ヘッダー付きの 429 RATE_LIMITED を返します。
• 1 日のトークンバジェット — UTC 深夜にリセット、デフォルトは 1 日 10,000 トークン。超過すると 429 BUDGET_EXCEEDED を返します。
• リクエストごとの入力サイズはプランのコンテキスト制限でキャップされます。サイズ超過の入力は 400 INPUT_TOO_LARGE とともにメッセージ内の上限を返します。

これらに加えて、すべての呼び出しはモデルの設定レートで（入力 + 出力）トークンごとに価格設定されたクレジットを差し引きます。 プロジェクトオーナーのクレジット残高がゼロになると、リクエストは 402 INSUFFICIENT_CREDITS を返します。

ゲートウェイ固有のエラーコード

すべてのゲートウェイレスポンス — 成功または失敗 — には X-Request-Id ヘッダーが含まれます。サポートがプロジェクトごとの AI 使用ログでトレースを見つけられるよう、問題を報告する際はこれを引用してください。