# 知识花园 API 调用指南

## 请求地址

```
POST /external/use/seek-knowledge/seek HTTP/1.1
```

### 获取可⽤模型列表<br>

```
GET /external/use/seek-knowledge/models HTTP/1.1
```

## 请求头

| Header          | Value                 | 说明                                                                                   |
| --------------- | --------------------- | ------------------------------------------------------------------------------------ |
| `Authorization` | `Bearer <your_token>` | 认证令牌，用于验证用户身份。请替换 `<your_token>` 为您的实际令牌。可在<https://flowith.io/setting> 中获取你的 Token。 |
| `Content-Type`  | `application/json`    | 表明请求体为 JSON 格式。                                                                      |
| `Host`          | `edge.flowith.net`    | API 服务器地址。                                                                           |
| `User-Agent`    | `HTTPie`              | （可选）客户端标识。                                                                           |

## 请求体（JSON）

| 参数         | 类型    | 说明                                           |
| ---------- | ----- | -------------------------------------------- |
| `messages` | 数组    | 对话消息列表。每个消息对象包含 `role`（角色）和 `content`（内容）字段。 |
| `model`    | 字符串   | 模型名称。例如：`"gpt-4o-mini"`                      |
| `stream`   | 布尔值   | 是否启用流式响应。`true` 为启用，`false` 为禁用。             |
| `kb_list`  | 字符串数组 | 知识库 ID 列表。用于指定检索知识的范围。                       |

### **`messages` 字段说明**

* `role`: 消息角色，可以是 `"assistant"`（助手）或 `"user"`（用户）。
* `content`: 消息内容，如复杂的查询或指令。

## 响应

### **当 `stream` 为 `true` 时（流式响应）**

* 响应状态码: `200 OK`
* 响应头: 包含标准的 HTTP 头信息，如 `Content-Type: text/plain; charset=UTF-8` 等。
* 响应体: 以 `data:` 开头的文本流。每个 `data:` 块包含一个 JSON 对象，可能有以下 `tag` 值：
  * `searching`: 表示正在搜索，`content` 字段包含搜索进度更新。
  * `seeds`: 中间搜索结果，`content` 是一个 JSON 数组，每个元素是一条独立知识，包含 `id`、`tokens`、`content`、`order`、`source_id`、`source_title` 和 `nip`。
  * `final`: 表示最终结果，`content` 包含完整的响应文本。

### **当 `stream` 为 `false` 时**

* 响应状态码: `200 OK`
* 响应头: 包含标准的 HTTP 头信息，如 `Content-Type: application/json` 等。
* 响应体: 一个 JSON 对象，包含 `tag` 和 `content` 字段。
  * `tag`: 始终为 `"final"`。
  * `content`: 完整的响应文本。

## `curl` 示例

### **流式响应 (stream = true)**

```bash
curl -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [
      {"role": "assistant", "content": "我想探讨有效的社交动态和人际关系"},
      {"role": "user", "content": "分享你在专业场合建立真诚连接和融洽关系的最佳策略"}
    ],
    "model": "gpt-4.1-mini",
    "stream": true,
    "kb_list": ["<knowledge_base_id>"]
  }'
```

### **非流式响应 (stream = false)**

```bash
curl -X POST "https://edge.flowith.net/external/use/knowledge-base/seek" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -H "Host: edge.flowith.net" \
  -d '{
    "messages": [
      {"role": "assistant", "content": "我想探讨有效的社交动态和人际关系"},
      {"role": "user", "content": "分享你在专业场合建立真诚连接和融洽关系的最佳策略"}
    ],
    "model": "gpt-4.1-mini",
    "stream": false,
    "kb_list": ["<knowledge_base_id>"]
  }' 
```

请记得将 `<your_token>` 和 `<knowledge_base_id>` 替换为您的实际值。

## 速率限制

* 请求限制：每分钟 12 次请求(RPM)
* 注意事项：超过此限制将返回 HTTP 429 错误(请求过多)

## 计费说明

* 配额使用：调用时候，按次数根据对应 Flowith 账户的Credits配额计算费用
* 计费周期：实时计算使用量并从账户余额中扣除