API 参考

AI 网关（chat 和 generate）

从您部署的项目调用 FloopFloop 的托管 LLM 网关 — 聊天完成、单提示生成、流式 SSE、自动模型路由。

最后更新： 2026年4月29日

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_ 密钥分开。每个项目存在一个有效密钥，在项目创建时自动生成。

在控制台的 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" 时，网关将对请求复杂度进行分类，并选择合适规模的模型。其他支持的别名如下：

Alias	Use case
`"auto"`	默认 — 平台根据请求复杂度自动选择
`"fast"`	简单任务，低延迟（翻译、摘要、分类）
`"smart"`	复杂任务（代码生成、分析、推理）
`"reason"`	多步推理、规划、深度分析（扩展思考）

优先使用别名，而非硬编码服务商的模型 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]— 已生成的令牌仍会计费。

Embeddings（尚未开放）

POST /api/v1/ai/embed

目前返回 501 NOT_IMPLEMENTED。该端点已预留，以便 SDK 可在网关正式上线前提前存根该方法；请勿依赖此端点。

限额与预算

在积分余额之外，每个项目 AI 密钥还有两层限流机制：

每分钟请求数— 可在Project settings → AI 中配置，默认为 10 RPM。超出限额返回 429 RATE_LIMITED，并附带Retry-After 响应头。
每日令牌预算— 每天 UTC 零点重置，默认为 10,000 个令牌/天。超出限额返回429 BUDGET_EXCEEDED。
单次请求的输入大小受计划上下文限制约束。超出限制的输入返回400 INPUT_TOO_LARGE，消息中包含上限值。

此外，每次调用均按（输入 + 输出）令牌数以模型配置的费率扣减积分。一旦项目所有者的积分余额为零，请求将返回402 INSUFFICIENT_CREDITS。

网关专用错误代码

HTTP	Code	Meaning
400	`INVALID_BODY`	请求体不是有效的 JSON
400	`VALIDATION_ERROR`	字段缺失、类型错误或超出范围
400	`INPUT_TOO_LARGE`	预估输入令牌数超出计划限制
400	`INVALID_MODEL`	未知的模型别名
402	`INSUFFICIENT_CREDITS`	项目所有者积分不足
429	`RATE_LIMITED`	每密钥 RPM 超限
429	`BUDGET_EXCEEDED`	每日令牌预算已耗尽
501	`NOT_IMPLEMENTED`	端点已预留（目前仅 embed）
502	`PROVIDER_ERROR`	上游 LLM 服务商故障，请稍后重试
503	`SERVICE_UNAVAILABLE`	所有服务商均触发熔断；`Retry-After: 60`

每个网关响应 — 无论成功还是失败 — 均携带X-Request-Id 响应头。报告问题时请提供该值，以便支持团队在每项目 AI 使用日志中找到对应的追踪记录。