# 知识花园 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配额计算费用
* 计费周期：实时计算使用量并从账户余额中扣除


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.flowith.io/cn/knowledge-garden/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.