> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-recommend-assets-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 路由

## 路由

服务器定义了一系列 `get` 和 `post` 方法，
这些方法可以通过在 `server.py` 中搜索 `@routes` 找到。当你在网页客户端提交工作流时，
它会被发送到 `/prompt` 端点，该端点会验证提示并将其添加到执行队列中，
返回 `prompt_id` 和 `number`（队列中的位置），如果验证失败则返回 `error` 和 `node_errors`。
提示队列定义在 `execution.py` 中，该文件还定义了 `PromptExecutor` 类。

### 内置路由

`server.py` 定义了以下路由：

#### 核心 API 路由

| 路径                             | get/post/ws | 用途                                                |
| ------------------------------ | ----------- | ------------------------------------------------- |
| `/`                            | get         | 加载 Comfy 网页                                       |
| `/ws`                          | websocket   | 用于与服务器进行实时通信的 WebSocket 端点                        |
| `/embeddings`                  | get         | 获取可用的嵌入模型名称列表                                     |
| `/extensions`                  | get         | 获取注册了 `WEB_DIRECTORY` 的扩展列表                       |
| `/features`                    | get         | 获取服务器功能和能力                                        |
| `/models`                      | get         | 获取可用模型类型列表                                        |
| `/models/{folder}`             | get         | 获取特定文件夹中的模型                                       |
| `/workflow_templates`          | get         | 获取自定义节点模块及其关联模板工作流的映射                             |
| `/api/assets`                  | get         | 列出资产，支持过滤和分页（推荐）                                  |
| `/api/assets`                  | post        | 上传新资产，支持标签和元数据（推荐）                                |
| `/api/assets/{id}`             | get         | 按 ID 获取资产详情（推荐）                                   |
| `/api/assets/{id}/content`     | get         | 下载资产内容                                            |
| `/api/tags`                    | get         | 列出所有标签                                            |
| `/upload/image`                | post        | 上传图片（旧版）                                          |
| `/upload/mask`                 | post        | 上传蒙版（旧版）                                          |
| `/view`                        | get         | 查看图片（旧版）。参见 `server.py` 中的 `@routes.get("/view")` |
| `/view_metadata`/{folder_name} | get         | 获取模型的元数据                                          |
| `/system_stats`                | get         | 获取系统信息（Python 版本、设备、显存等）                          |
| `/prompt`                      | get         | 获取当前队列状态和执行信息                                     |
| `/prompt`                      | post        | 提交提示到队列                                           |
| `/object_info`                 | get         | 获取所有节点类型的详细信息                                     |
| `/object_info/{node_class}`    | get         | 获取特定节点类型的详细信息                                     |
| `/history`                     | get         | 获取队列历史记录                                          |
| `/history/{prompt_id}`         | get         | 获取特定提示的队列历史记录                                     |
| `/history`                     | post        | 清除历史记录或删除历史记录项                                    |
| `/queue`                       | get         | 获取执行队列的当前状态                                       |
| `/queue`                       | post        | 管理队列操作（清除待处理/运行中的任务）                              |
| `/interrupt`                   | post        | 停止当前工作流执行                                         |
| `/free`                        | post        | 通过卸载指定模型释放内存                                      |
| `/userdata`                    | get         | 列出指定目录中的用户数据文件                                    |
| `/v2/userdata`                 | get         | 增强版本，以结构化格式列出文件和目录                                |
| `/userdata/{file}`             | get         | 获取特定的用户数据文件                                       |
| `/userdata/{file}`             | post        | 上传或更新用户数据文件                                       |
| `/userdata/{file}`             | delete      | 删除特定的用户数据文件                                       |
| `/userdata/{file}/move/{dest}` | post        | 移动或重命名用户数据文件                                      |
| `/users`                       | get         | 获取用户信息                                            |
| `/users`                       | post        | 创建新用户（仅限多用户模式）                                    |

### Assets API

Assets API (`/api/assets`) 提供了一个统一的、基于标签的文件管理系统（图片、模型、输出），支持内容寻址存储和元数据。这是上传、组织和检索文件的推荐方式。

#### 列出资产

`GET /api/assets` 返回一个分页的资产列表，支持可选的过滤：

| 参数              | 类型      | 描述                                               |
| --------------- | ------- | ------------------------------------------------ |
| `include_tags`  | string  | 过滤包含所有这些标签的资产（逗号分隔）                              |
| `exclude_tags`  | string  | 排除包含任何这些标签的资产（逗号分隔）                              |
| `name_contains` | string  | 按名称子字符串过滤（不区分大小写）                                |
| `sort`          | string  | 排序字段：`name`、`created_at`（默认）、`updated_at`、`size` |
| `order`         | string  | 排序方向：`asc`、`desc`（默认）                            |
| `limit`         | integer | 返回的最大条目数（1-500，默认：20）                            |
| `offset`        | integer | 跳过的条目数（默认：0）                                     |

**响应：**

```json theme={null}
{
  "assets": [
    {
      "id": "asset-uuid",
      "name": "my-image.png",
      "hash": "blake3:abc123...",
      "size_bytes": 102400,
      "mime_type": "image/png",
      "tags": ["output", "image"],
      "created_at": "2024-01-29T12:00:00Z",
      "preview_url": "/api/assets/asset-uuid/content"
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 20
}
```

#### 上传资产

`POST /api/assets` 上传新资产（multipart/form-data）：

| 字段              | 类型     | 描述                            |
| --------------- | ------ | ----------------------------- |
| `file`          | file   | 要上传的文件（必需）                    |
| `name`          | string | 资产的显示名称                       |
| `tags`          | string | 逗号分隔的标签（例如 `input,reference`） |
| `user_metadata` | string | 自定义 JSON 元数据                  |

#### 获取资产详情

`GET /api/assets/{id}` 返回特定资产的完整详情。

#### 下载资产内容

`GET /api/assets/{id}/content` 下载资产文件，带有适当的 Content-Type 和 Content-Disposition 头。

<Note>
  Assets API 使用 Blake3 哈希的内容寻址存储，这意味着相同的文件会自动去重。标签提供了灵活的组织方式，无需严格的文件夹层次结构。
</Note>

### WebSocket 通信

`/ws` 端点提供客户端与服务器之间的实时双向通信。用于：

* 接收执行进度更新
* 实时获取节点执行状态
* 接收错误消息和调试信息
* 队列状态变化时的实时更新

WebSocket 连接发送不同类型的 JSON 消息，例如：

* `status` - 整体系统状态更新
* `execution_start` - 当提示执行开始时
* `execution_cached` - 当使用缓存结果时
* `executing` - 节点执行期间的更新
* `progress` - 长时间运行操作的进度更新
* `executed` - 当节点完成执行时

### 自定义路由

如果你想在执行过程中从客户端向服务器发送消息，你需要在服务器中添加一个自定义路由。
对于复杂的情况，你需要深入研究 [aiohttp 框架文档](https://docs.aiohttp.org/)，但大多数情况可以按以下方式处理：

```Python theme={null}
from server import PromptServer
from aiohttp import web
routes = PromptServer.instance.routes
@routes.post('/my_new_path')
async def my_function(request):
    the_data = await request.post()
    # the_data now holds a dictionary of the values sent
    MyClass.handle_my_message(the_data)
    return web.json_response({})
```

<Tip>
  除非你确切知道自己在做什么，否则不要尝试在类中定义 `my_function`。
  `@routes.post` 装饰器做了很多工作！相反，应该像上面那样定义函数，
  然后调用一个类方法。
</Tip>

<Tip>
  如果你不需要修改任何内容，也可以定义 `@routes.get`。
</Tip>

客户端可以通过发送 `FormData` 对象来使用这个新路由，代码如下所示，
这将导致上面代码中的 `the_data` 包含 `message` 和 `node_id` 键：

```Javascript theme={null}
import { api } from "../../scripts/api.js";
function send_message(node_id, message) {
    const body = new FormData();
    body.append('message',message);
    body.append('node_id', node_id);
    api.fetchApi("/my_new_path", { method: "POST", body, });
}
```