| --- |
| title: HTTP API 参考 |
| --- |
| |
| # HTTP API 参考 |
|
|
| Koharu 在本地暴露 HTTP API： |
|
|
| ```text |
| http://127.0.0.1:<PORT>/api/v1 |
| ``` |
|
|
| 桌面 UI 与 headless Web UI 使用的就是这套 API。 |
|
|
| ## 运行时模型 |
|
|
| 当前实现中的重要行为： |
|
|
| - API 与 GUI 或 headless 运行时由同一个进程提供 |
| - 服务器默认绑定到 `127.0.0.1`；使用 `--host` 可绑定到其他地址 |
| - API 与 MCP 服务器共享同一个已加载的项目、模型和管线状态 |
| - 没有提供 `--port` 时，Koharu 会选择一个随机本地端口 |
| - 在应用完成启动之前，除 `/api/v1/downloads`、`/api/v1/operations` 与 `/api/v1/events` 之外的所有路由都会返回 `503 Service Unavailable` |
|
|
| ## 资源模型 |
|
|
| API 是以项目为中心的。同一时间只会打开一个项目，它包含： |
|
|
| - 一组 `Pages`，按 `PageId` 索引 |
| - 每个页面下的 `Nodes`（图像图层、掩码、文本块），通过 `NodeId` 引用 |
| - 一个内容寻址的 `Blob` 存储，按 Blake3 哈希保存原始图像字节 |
| - 由这些组件构建出的 `Scene` 快照，并通过 `epoch` 计数器递进 |
| - 一段 `Op` 修改历史，可以撤销与重做 |
|
|
| 所有修改都必须经过历史层（`POST /history/apply`），以保证场景、自动保存和事件订阅者都保持同步。 |
|
|
| ## 常见响应类型 |
|
|
| 高频返回结构包括： |
|
|
| - `MetaInfo`：应用版本与 ML 设备 |
| - `EngineCatalog`：每个管线阶段可安装的引擎 id |
| - `ProjectSummary`：id、名称、路径、页数、最近一次打开时间 |
| - `SceneSnapshot`：`{ epoch, scene }` |
| - `LlmState`：当前 LLM 加载状态（status、target、error） |
| - `LlmCatalog`：按系列分组的本地 + 提供商模型 |
| - `JobSummary`：`{ id, kind, status, error }` |
| - `DownloadProgress`：包 id、字节数、状态 |
|
|
| ## 端点 |
|
|
| ### 元信息 |
|
|
| | 方法 | 路径 | 用途 | |
| | ----- | ---------- | ------------------------------- | |
| | `GET` | `/meta` | 获取应用版本与当前 ML 后端 | |
| | `GET` | `/engines` | 列出每个管线阶段已注册的引擎 | |
|
|
| ### 字体 |
|
|
| | 方法 | 路径 | 用途 | |
| | ------ | --------------------------------- | --------------------------------------------- | |
| | `GET` | `/fonts` | 系统字体 + Google Fonts 的合并目录，用于渲染 | |
| | `GET` | `/google-fonts` | 单独列出 Google Fonts 目录 | |
| | `POST` | `/google-fonts/{family}/fetch` | 下载并缓存某个 Google Fonts 字体族 | |
| | `GET` | `/google-fonts/{family}/{file}` | 提供已缓存的 TTF/WOFF 文件 | |
|
|
| ### 项目 |
|
|
| 每个项目都位于受管理的 `{data.path}/projects/` 目录下；客户端永远不需要传入文件系统路径。 |
|
|
| | 方法 | 路径 | 用途 | |
| | -------- | ----------------------------- | ------------------------------------------------- | |
| | `GET` | `/projects` | 列出受管理的项目 | |
| | `POST` | `/projects` | 创建新项目（请求体 `{ name }`） | |
| | `POST` | `/projects/import` | 把一个 `.khr` 归档解压到新目录并打开 | |
| | `PUT` | `/projects/current` | 通过 `id` 打开一个受管理项目 | |
| | `DELETE` | `/projects/current` | 关闭当前会话 | |
| | `POST` | `/projects/current/export` | 导出当前项目；返回二进制字节 | |
|
|
| `POST /projects/current/export` 接受 `{ format, pages? }`，其中 `format` 是 `khr`、`psd`、`rendered`、`inpainted` 之一。当某种格式会产生多个文件时，响应类型是 `application/zip`。 |
|
|
| ### 页面 |
|
|
| | 方法 | 路径 | 用途 | |
| | ------ | --------------------------------------- | --------------------------------------------------- | |
| | `POST` | `/pages` | 通过 multipart 上传 N 张图片创建页面 | |
| | `POST` | `/pages/from-paths` | Tauri 专用的快速通道，按绝对路径导入 | |
| | `POST` | `/pages/{id}/image-layers` | 从上传文件添加一个 Custom 图像节点 | |
| | `PUT` | `/pages/{id}/masks/{role}` | 用原始 PNG 字节 upsert 一个掩码节点 | |
| | `GET` | `/pages/{id}/thumbnail` | 获取页面缩略图（以 WebP 缓存） | |
|
|
| `role` 是 `segment` 或 `brushInpaint`。`POST /pages` 接受可选字段 `replace=true`；导入时会按文件名自然顺序排序。 |
|
|
| ### Scene 与 blobs |
|
|
| | 方法 | 路径 | 用途 | |
| | ----- | ------------------ | ----------------------------------------------------------------- | |
| | `GET` | `/scene.json` | 完整的场景快照，供 web/UI 客户端使用 | |
| | `GET` | `/scene.bin` | postcard 编码的 `Snapshot { epoch, scene }`，供 Tauri 客户端使用 | |
| | `GET` | `/blobs/{hash}` | 按 Blake3 哈希返回 blob 的原始字节 | |
|
|
| `/scene.bin` 会在 `x-koharu-epoch` 响应头里附带当前 epoch。 |
|
|
| ### 历史（修改） |
|
|
| 所有场景修改都从这里走。每个响应都返回 `{ epoch }`。 |
|
|
| | 方法 | 路径 | 用途 | |
| | ------ | ------------------- | ------------------------------------- | |
| | `POST` | `/history/apply` | 应用一个 `Op`（包括 `Op::Batch`） | |
| | `POST` | `/history/undo` | 撤销上一次应用的 op | |
| | `POST` | `/history/redo` | 重新应用上一次撤销的 op | |
|
|
| `Op` 是一个带判别字段的联合类型，覆盖添加/删除/更新节点、添加/删除页面、批量操作以及其他场景过渡。请求体是带 JSON tag 的变体。 |
|
|
| ### 管线 |
|
|
| | 方法 | 路径 | 用途 | |
| | ------ | ------------- | --------------------------------- | |
| | `POST` | `/pipelines` | 以 operation 形式启动一次管线运行 | |
|
|
| 请求体字段： |
|
|
| - `steps`：按顺序执行的引擎 id（会与注册表校验） |
| - `pages`：可选的 `PageId` 子集；省略时处理整个项目 |
| - `region`：可选的 inpainter 边界框（修复笔刷流程使用） |
| - `targetLanguage`、`systemPrompt`、`defaultFont`：每次运行可覆盖的可选参数 |
|
|
| 响应携带 `operationId`。进度与完成事件会通过 `/events` 以 `JobStarted`、`JobProgress`、`JobWarning`、`JobFinished` 推送。 |
|
|
| ### Operations |
|
|
| `/operations` 是正在运行和最近完成的任务（管线 + 下载）的统一登记表。 |
|
|
| | 方法 | 路径 | 用途 | |
| | -------- | --------------------- | ---------------------------------------------------- | |
| | `GET` | `/operations` | 所有正在运行或最近的 operation 的快照 | |
| | `DELETE` | `/operations/{id}` | 取消一次管线运行；对下载尽力而为地清理 | |
|
|
| ### Downloads |
|
|
| | 方法 | 路径 | 用途 | |
| | ------ | ------------- | ----------------------------------------------- | |
| | `GET` | `/downloads` | 所有正在进行或最近的下载快照 | |
| | `POST` | `/downloads` | 启动一次模型包下载（`{ modelId }`） | |
|
|
| `modelId` 是通过 `declare_hf_model_package!` 声明的包 id（例如 `"model:comic-text-detector:yolo-v5"`）。响应是 `{ operationId }`，其值复用包 id。 |
|
|
| ### LLM 控制 |
|
|
| 已加载模型是位于 `/llm/current` 的单例资源。 |
|
|
| | 方法 | 路径 | 用途 | |
| | -------- | ---------------- | --------------------------------------------- | |
| | `GET` | `/llm/current` | 当前状态（status、target、error） | |
| | `PUT` | `/llm/current` | 加载指定的 target（local 或 provider） | |
| | `DELETE` | `/llm/current` | 卸载 / 释放当前模型 | |
| | `GET` | `/llm/catalog` | 列出可用的本地模型 + 提供商支持的模型 | |
|
|
| `PUT /llm/current` 接受 `LlmLoadRequest`： |
|
|
| - provider target：`{ kind: "provider", providerId, modelId }` |
| - local target：`{ kind: "local", modelId }` |
| - 可选的 `options { temperature, maxTokens, customSystemPrompt }` |
|
|
| `PUT /llm/current` 在加载任务入队后立即返回 `204`。实际就绪状态会作为 `LlmLoaded` 事件发布到 `/events`。 |
|
|
| ### 配置 |
|
|
| | 方法 | 路径 | 用途 | |
| | -------- | --------------------------------- | ----------------------------------------------- | |
| | `GET` | `/config` | 读取当前 `AppConfig` | |
| | `PATCH` | `/config` | 应用 `ConfigPatch`；持久化并广播变更 | |
| | `PUT` | `/config/providers/{id}/secret` | 保存（或覆盖）某个 provider 的 API key | |
| | `DELETE` | `/config/providers/{id}/secret` | 清除某个 provider 已保存的 API key | |
|
|
| `AppConfig` 暴露顶层的 `data`、`http`、`pipeline` 与 `providers`： |
|
|
| - `data.path`：本地数据目录，用于运行时、模型缓存与项目 |
| - `http { connectTimeout, readTimeout, maxRetries }`：下载与 provider 请求共用的 HTTP 客户端 |
| - `pipeline { detector, fontDetector, segmenter, bubbleSegmenter, ocr, translator, inpainter, renderer }`：每个阶段选用的引擎 id |
| - `providers[] { id, baseUrl?, apiKey? }`：保存的 API key 在往返中始终以遮蔽占位符 `"[REDACTED]"` 出现，绝不返回原始密钥 |
|
|
| 内置 provider id： |
|
|
| - `openai` |
| - `gemini` |
| - `claude` |
| - `deepseek` |
| - `deepl` |
| - `google-translate` |
| - `caiyun` |
| - `openai-compatible` |
|
|
| API key 保存在平台凭据存储中，而不是 `config.toml` 里。PATCH `apiKey: ""` 会清除已保存的 key；PATCH `"[REDACTED]"` 表示保持原值不变。专门的 `/config/providers/{id}/secret` 路由是显式管理某个 provider 密钥的非 PATCH 方式。 |
|
|
| ## 事件流 |
|
|
| Koharu 通过以下地址暴露 Server-Sent Events： |
|
|
| ```text |
| GET /events |
| ``` |
|
|
| 行为： |
|
|
| - 全新连接（不带 `Last-Event-ID` 请求头）会先收到一个 `Snapshot` 事件，包含当前的任务和下载登记表 |
| - 重连时，服务器会按顺序回放缓冲区中 `seq > Last-Event-ID` 的事件；如果请求的 id 已经从环形缓冲区中滚出，则会重新发送一个 `Snapshot` |
| - 每个实时事件都会用其 `seq` 作为 SSE `id:` 字段 |
| - 维持 15 秒的 keep-alive |
|
|
| 当前事件变体包括： |
|
|
| - `Snapshot`：用于全新客户端与延迟恢复客户端的完整状态种子 |
| - `JobStarted`、`JobProgress`、`JobWarning`、`JobFinished`：管线任务生命周期 |
| - `DownloadProgress`：包下载进度 |
| - `ConfigChanged`：通过 `PATCH /config` 或 secret 路由应用了配置变更 |
| - `LlmLoaded`、`LlmUnloaded`：LLM 生命周期切换 |
| - `SceneAdvanced`：场景修改使 epoch 推进时触发 |
|
|
| ## 典型工作流 |
|
|
| 新建一个项目时常见的 API 调用顺序： |
|
|
| 1. `POST /projects`：创建项目 |
| 2. `POST /pages`（或 Tauri 下的 `/pages/from-paths`）：导入图片 |
| 3. `PUT /llm/current`：加载翻译模型（本地或 provider） |
| 4. `POST /pipelines`：启动 `detect → ocr → translate → inpaint → render` |
| 5. 监听 `GET /events` 直到 `JobFinished` |
| 6. `POST /projects/current/export`，`format = "rendered"` 或 `"psd"` |
|
|
| 如果你需要更精细的控制，可以直接 `POST /history/apply` 携带显式 `Op` 负载，而不是运行整条管线。 |
|
|
| 如果你更想用面向 Agent 的接口，而不是手动编排 HTTP 端点，请参见 [MCP 工具参考](mcp-tools.md)。 |
|
|
