跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.fim.ai/llms.txt

Use this file to discover all available pages before exploring further.

API 参考文档目前仅提供英文版本。如果您正在查看其他语言版本的此页面，请切换到英文版本 — 完整的 API 端点列表将显示在左侧边栏中。
FIM One 提供 REST API，用于以编程方式访问 AI 智能体、对话、知识库等。

​
基础 URL

https://your-domain.com/api

​
身份验证

所有 API 请求都需要通过 API 密钥或 JWT 令牌进行身份验证。

​
使用 API 密钥

在 Authorization 标头中包含您的 API 密钥： 
curl -H "Authorization: Bearer fim_your_api_key_here" \
  https://your-domain.com/api/agents

​
使用 JWT 令牌

对于 SSE 流式端点（/api/react 和 /api/dag），你可以在请求体中传递令牌： 
{
  "q": "What's the weather today?",
  "token": "your_jwt_token_here"
}
有关详细的设置说明，请参阅身份验证。

​
响应格式

​
成功响应

所有成功的 API 响应遵循以下结构： 
{
  "success": true,
  "data": {
    "id": "conv_123abc",
    "title": "My Conversation",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

​
错误响应

错误响应包括错误代码和人类可读的消息： 
{
  "success": false,
  "error": "conversation_not_found",
  "message": "The conversation does not exist or has been deleted"
}

​
分页响应

列表端点返回分页结果： 
{
  "items": [
    { "id": "item_1", "name": "First Item" },
    { "id": "item_2", "name": "Second Item" }
  ],
  "total": 42,
  "page": 1,
  "size": 20,
  "pages": 3
}

​
流式传输 (Server-Sent Events)

聊天端点 (POST /api/react 和 POST /api/dag) 返回 Server-Sent Events 以实现实时流式传输。每个事件都有一个 type 字段，指示其内容：
事件类型描述
stepReAct 推理步骤（工具调用、思考）。对于具有扩展思考能力的模型（Claude、o-series、DeepSeek-R1），在工具决策阶段包括实时 thinking_delta 内容
step_progressDAG 步骤进度（已启动/迭代/已完成）。当底层智能体流式传输推理 token 时，可能包括 thinking_delta 内容
phase管道阶段转换（规划/执行/分析）
compact上下文压缩已发生
answer流式答案文本（开始/增量/完成）
done最终结果负载
suggestions建议的后续问题
title自动生成的对话标题
end流终止符（始终为最后）

​
SSE 流示例

event: step
data: {"type": "tool_call", "tool": "search", "input": "Paris weather"}

event: answer
data: {"type": "delta", "text": "Based on current data, "}

event: answer
data: {"type": "delta", "text": "Paris has pleasant weather."}

event: done
data: {"answer": "Based on current data, Paris has pleasant weather.", "tokens": 128}

event: suggestions
data: ["What about tomorrow's forecast?", "Compare with other European cities"]

event: end
data: {}

​
基于游标的恢复

每个 SSE 事件都携带一个限定于对话的单调递增 cursor 整数。客户端应跟踪看到的最高游标。当连接在转向中断时（网络错误、代理超时、服务器重启），客户端可以重新订阅而无需重新运行智能体： 
POST /api/chat/resume
Content-Type: application/json
Authorization: Bearer <jwt>

{
  "conversation_id": "<uuid>",
  "cursor": 42
}
响应是一个 SSE 流，重放 cursor > 42 的缓存事件，并以终端 event: resume_done 帧结束。传递 cursor: -1 以请求从头开始的完整重放。 错误响应：
  • 404 conversation_not_found — 对话 id 无效或不由已认证用户拥有
  • 404 no_recent_assistant_message — 对话没有可恢复的持久化助手转向（例如，没有用户消息的全新对话）
  • 400 invalid_cursor — 游标不是非负整数或 -1
参考前端实现（playground 中的 useSseResume hook）使用指数退避（300ms → 1s → 3s，最多 3 次尝试）自动重试网络断开连接，并区分用户主动中止和网络错误以避免意外重连。有关完整模式，请参阅 playground-page.tsx 集成。
恢复是无状态的 — 它从助手消息的存储 sse_events 数组重放。如果智能体的转向在任何助手消息被持久化之前被中断（例如，在 done 之前崩溃），悬空的 tool_use 块会在下一个转向由 DbMemory._repair_dangling_tool_calls 自动修复。合成 tool_result 行使用 metadata_.synthetic=true 和 metadata_.reason="interrupted" 持久化以供审计。

​
速率限制

计划在未来版本中实现按密钥的速率限制。目前没有强制的按密钥请求限制，但请负责任地使用 API。

​
分页

列表端点支持通过查询参数进行分页： 
curl "https://your-domain.com/api/conversations?page=2&size=50" \
  -H "Authorization: Bearer fim_your_api_key_here"
参数：
  • page（默认值：1）— 页码，从 1 开始
  • size（默认值：20）— 每页项目数，最多 100

​
时间戳

所有时间戳均采用 ISO 8601 格式，使用 UTC 时区： 
{
  "created_at": "2024-01-15T10:30:45.123456Z",
  "updated_at": "2024-01-15T14:22:10.654321Z"
}

​
错误代码

常见错误代码及其含义：
错误代码HTTP 状态含义
unauthorized401无效或缺失身份验证
forbidden403用户缺少此资源的权限
not_found404资源不存在
bad_request400无效的请求参数
rate_limit_exceeded429请求过于频繁（计划中）
internal_error500服务器错误

​
API 游乐场

每个端点页面都包含一个交互式 API 游乐场，您可以：
  • 直接从浏览器测试请求
  • 查看真实响应
  • 复制多种语言的请求代码
  • 使用您的 API 密钥进行身份验证
API 游乐场从您的浏览器运行请求，因此请确保您的 API 密钥具有适当的 CORS 权限（通常对同源请求默认启用）。

​
SDK 可用性

虽然 FIM One API 完全基于 REST，但流行语言的 SDK 已可用（或即将推出）：
  • Python：即将推出
  • JavaScript/TypeScript：即将推出
  • Go：即将推出

​
版本控制

当前 API 版本为 v0.8.0。版本号不包含在 URL 路径中；重大变更将通过主版本号升级和迁移期来通知。

​
支持

如有 API 问题或疑问：