API 概览 - FIM One

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 字段，指示其内容：

事件类型	描述
`step`	ReAct 推理步骤（工具调用、思考）。对于具有扩展思考能力的模型（Claude、o-series、DeepSeek-R1），在工具决策阶段包括实时 `thinking_delta` 内容
`step_progress`	DAG 步骤进度（已启动/迭代/已完成）。当底层智能体流式传输推理 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 状态	含义
`unauthorized`	401	无效或缺失身份验证
`forbidden`	403	用户缺少此资源的权限
`not_found`	404	资源不存在
`bad_request`	400	无效的请求参数
`rate_limit_exceeded`	429	请求过于频繁（计划中）
`internal_error`	500	服务器错误

API 游乐场

每个端点页面都包含一个交互式 API 游乐场，您可以：

直接从浏览器测试请求
查看真实响应
复制多种语言的请求代码
使用您的 API 密钥进行身份验证

API 游乐场从您的浏览器运行请求，因此请确保您的 API 密钥具有适当的 CORS 权限（通常对同源请求默认启用）。

SDK 可用性

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

Python：即将推出
JavaScript/TypeScript：即将推出
Go：即将推出

版本控制

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

支持

如有 API 问题或疑问：

文档: 查看每个端点的详细指南
GitHub Issues: 在 https://github.com/fim-ai/fim-one/issues 报告错误
Discord 社区: 加入我们的社区进行讨论

​基础 URL

​身份验证

​使用 API 密钥

​使用 JWT 令牌

​响应格式

​成功响应

​错误响应

​分页响应

​流式传输 (Server-Sent Events)

​SSE 流示例

​基于游标的恢复

​速率限制

​分页

​时间戳

​错误代码

​API 游乐场

​SDK 可用性

​版本控制

​支持

基础 URL

身份验证

使用 API 密钥

使用 JWT 令牌

响应格式

成功响应

错误响应

分页响应

流式传输 (Server-Sent Events)

SSE 流示例

基于游标的恢复

速率限制

分页

时间戳

错误代码

API 游乐场

SDK 可用性

版本控制

支持