--- title: "REST API" description: "服务器 AI 工具包 REST API 端点的完整参考。" canonical_url: "https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api" --- # REST API 服务器 AI 工具包 REST API 端点的完整参考。 Server AI Toolkit REST API 包含用于获取可用工具和执行工具调用的端点 > **Postman collection:** > > 浏览用于 Server AI Toolkit REST API 的 [Postman > collection](https://www.postman.com/tiptap-platform/tiptap-workspace/collection/42722929-6a366c4c-10e4-4674-93c3-da35b70357a7?action=share\&source=copy-link\&creator=42722929)。 > **Legacy endpoints:** > > V4 是 Server AI Toolkit 端点当前使用的 API 版本。V3 端点已弃用；新开发请使用 > v4。v4 还将工具定义端点重命名为 `/v4/ai/toolkit/fetch-tools`； > `/v3/ai/toolkit/tools` 等旧名称属于 v3 API。有关旧版 > 端点，请参阅 [v3 REST API > reference](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api-v3.md)。 ## 如何提供文档 Tiptap Cloud 的基础 URL 为： ```sh BASE_URL=https://api.tiptap.dev ``` 在本地部署中，基础 URL 可能会有所不同。 在下面的示例中，请求写作 `BASE_URL/v4/ai/toolkit/...`。 ## 身份验证 所有请求都必须包含以下身份验证头： - `Authorization: Bearer JWT`，其中 `JWT` 是一个 Tiptap 访问控制 JWT。 请使用以下设置在服务器端签名令牌： - Audience: `AI` - Permissions: `AI:Toolkit` 要自动获取并保存 Tiptap Cloud 文档，请添加 `Documents` audience 和 `Documents:Write` permission。`Documents:Write` 包含读和评论访问权限。 有关如何创建密钥对并签名令牌，请参阅 [Authentication](https://tiptap.zhcndoc.com/authentication.md)；完整设置请参阅 [authorization guide](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/install.md#set-up-authorization)。 ```ts import { SignJWT, importPKCS8 } from 'jose' const privateKey = await importPKCS8(process.env.TIPTAP_PRIVATE_KEY, 'ES256') const JWT_TOKEN = await new SignJWT({ permissions: [ { action: 'AI:Toolkit', resource: '*' }, { action: 'Documents:Write', resource: 'your-document-id' }, ], }) .setProtectedHeader({ alg: 'ES256' }) .setIssuer(process.env.TIPTAP_ENVIRONMENT_ID) .setAudience(['AI', 'Documents']) .setExpirationTime('30m') .sign(privateKey) ``` 之前的 App ID + secret 身份验证流程记录在 [Legacy authentication](https://tiptap.zhcndoc.com/authentication/legacy.md) 中。 ## 可选字段 可选字段可以省略、`null` 或 `undefined`。 ## 端点 ### 获取工具定义 ```txt POST /v4/ai/toolkit/fetch-tools ``` 返回你传递给 AI 提供商的提示词和工具定义。 请求体： - `editorContext` (`object`, required): 由 `getEditorContext` 返回的编辑器上下文。 - `tools` (`Record`, optional, default: `{}`): 启用、禁用或 配置工具。默认情况下工具是禁用的。 - `format` (`'json' | 'shorthand'`, optional, default: `'json'`): 工具 定义和模型输出使用的文档格式。参见 [Tiptap Shorthand](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/advanced-guides/tiptap-shorthand.md)。 `tools` 可以包含以下键： - `tiptapRead` (`boolean`, optional) - `tiptapEdit` (`boolean | { meta?: string }`, optional): 当你希望 AI 在每次编辑操作中 包含一个额外的元数据字段时设置 `meta`，例如简短说明。 - `getThreads` (`boolean`, optional) - `editThreads` (`boolean`, optional) - `readDocument` (`boolean`, optional) - `proofread` (`boolean | { meta?: string }`, optional): 当你希望 AI 在每次校对编辑中 包含一个额外的元数据字段时设置 `meta`，例如简短说明。 响应： - `systemPrompt` (`string`): 将其添加到你 AI 请求的 system prompt 中。它会教会 AI Tiptap 文档如何工作、编辑器支持哪些元素，以及应使用哪种文档格式。 - `tools` (`array`): AI 或开发者可以调用的工具定义。每个数组元素包含： - `name` (`string`): 工具名称。 - `description` (`string`): 工具描述。 - `inputSchema` (`object`): AI 生成的工具输入的 JSON schema。 示例： ```curl curl --location 'BASE_URL/v4/ai/toolkit/fetch-tools' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_JWT' \ --data '{ "editorContext": { /* editor context data */ }, "tools": { "tiptapRead": true, "tiptapEdit": { "meta": "简要解释此次编辑。" } }, "format": "shorthand" }' ``` ### 执行工具 ```txt POST /v4/ai/toolkit/execute-tool ``` 执行一个工具。在 AI 模型生成工具调用后使用此端点。 请求体： - `editorContext` (`object`, required): 由 `getEditorContext` 返回的编辑器上下文。 - `document` (`object`, required): 要对其执行工具的文档。使用 `{ "type": "cloud", "id": "your-document-id" }`，当 API 应该从 Tiptap Cloud 文档读取和写入时。使用 `{ "type": "inline", "content": { /* Tiptap JSON document */ } }`，当你想在请求体中提供 Tiptap JSON 文档时。 - `user` (`string`, optional): 由 AI 执行的编辑所归属的标识符。 - `field` (`string`, optional, default: `"default"`): 用于定位云 文档内部协作字段。文档存储多个可编辑字段时使用，例如标题和正文。 - `tool` (`object`, required): 要执行的工具调用。 - `name` (`string`, required): 工具名称，例如 `"tiptapRead"`。 - `input` (`object`, required): 由 AI 生成的工具输入。这是一个与 该工具的 schema 和工具定义相匹配的对象。每个工具的 schema 和工具定义可通过 `/v4/ai/toolkit/fetch-tools` 端点获取。 - `config` (`unknown`, optional): 开发者提供的、工具特定的配置。 - `format` (`'json' | 'shorthand'`, optional, default: `'json'`): 工具输入和 输出使用的文档格式。参见 [Tiptap Shorthand](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/advanced-guides/tiptap-shorthand.md)。 - `reviewOptions` ([`ReviewOptions`](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md), optional, default: `{ mode: 'disabled' }`): 控制编辑是直接应用还是作为可审阅的更改。 响应： - `tool` (`object`): 已执行的工具及其输出。 - `name` (`string`): 工具名称。 - `output` (`object`): 提供给 AI 的工具输出。 - `docChanged` (`boolean`): 文档是否发生了变化。 - `document` (`object | null`): 更新后的文档；如果文档未更改则为 `null`。 示例： ```curl curl --location 'BASE_URL/v4/ai/toolkit/execute-tool' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_JWT' \ --data '{ "editorContext": { /* editor context data */ }, "document": { "type": "cloud", "id": "your-document-id" }, "user": "ai-assistant", "tool": { "name": "tiptapRead", "input": { "from": 0 } }, "format": "shorthand" }' ``` ### 流式执行工具 > **Alpha feature:** > > 流式传输目前处于 alpha 阶段 ```txt POST /v4/ai/toolkit/stream-tool ``` 以流式方式执行工具。`tiptapEdit` 可以逐步应用编辑，以实现打字效果。其他工具会在接收到完整输入后 运行，并返回一个最终事件，就像 `execute-tool` 一样。 请求分批发送。第一部分包含： - `editorContext` (`object`, required): 由 `getEditorContext` 返回的编辑器上下文。 - `document` (`object`, required): 要对其执行工具的云文档： `{ "type": "cloud", "id": "your-document-id" }`。流式传输不支持内联文档。 - `user` (`string`, optional): 由 AI 执行的编辑所归属的标识符。 - `field` (`string`, optional, default: `"default"`): 用于定位云 文档内部协作字段。 - `tool` (`object`, required): 要执行的工具调用，不包含 `tool.input`。 - `name` (`string`, required): 工具名称，例如 `"tiptapEdit"`。 - `config` (`unknown`, optional): 开发者提供的、工具特定的配置。 - `format` (`'json' | 'shorthand'`, optional, default: `'json'`): 工具输入和 输出使用的文档格式。参见 [Tiptap Shorthand](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/advanced-guides/tiptap-shorthand.md)。 - `reviewOptions` ([`ReviewOptions`](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md), optional, default: `{ mode: 'disabled' }`): 控制编辑是直接应用还是作为可审阅的更改。 - `delayMs` (`number`, optional, default: `5`): 增量 `tiptapEdit` 输出中每个字符的延迟时间，单位为毫秒。必须介于 `0` 和 `1000` 之间。使用 `0` 可尽快应用编辑。 然后发送： - 后续部分：`tool.input` 的值，在 AI 生成时以流式方式发送。 响应： - `tiptapEdit`：在编辑被应用时返回增量事件，随后返回一个包含 更新后 `document` 的最终事件。 - 其他工具：返回一个最终事件，结果结构与 `execute-tool` 相同。 ## 可用工具 这些工具可以提供给 AI 代理。代理决定调用哪个工具。 所有工具默认都处于禁用状态。我们建议先使用 `tiptapRead` 和 `tiptapEdit`，然后 根据需要启用其他工具。 你也可以直接从应用程序代码中调用这些工具，以构建自定义工作流。 ### `tiptapRead` 分块读取文档，以避免上下文窗口溢出。 工具配置（`tool.config`）： - `chunkSize`（`number`，可选）：每次工具调用中读取的最大字符数。默认值：`32000` 工具输出（`tool.output`）： 成功响应： - `success`（`true`）：表示读取请求成功。 - `totalNodeCount`（`number`）：文档中顶层节点的总数。 - `nodeRange`（`[number, number]`）：读取的顶层节点范围。 - `content`（`JSONContent[] | string`）：所返回范围内的文档内容。当 `format` 为 `json` 时，这是一个 Tiptap JSON 片段。当 `format` 为 `shorthand` 时，这是一个 Tiptap Shorthand 字符串。 错误响应： - `success`（`false`）：表示读取请求失败。 - `error`（`string`）：错误信息。 - `totalNodeCount?`（`number`）：顶层节点总数。 ### `tiptapEdit` 编辑文档内容。 工具配置（`tool.config`）： - `threadData`（`object`，可选）：添加到新建线程的元数据。 - `commentData`（`object`，可选）：添加到新建评论的元数据。 工具输出（`tool.output`）： 成功或部分成功响应： - `success`（`boolean`）：所有操作是否都已成功完成。 - `operationResults`（`array`）：每个操作的结果。 - `success`（`boolean`）：该操作是否已成功完成。 - `target`（`string`）：操作所针对元素的字符串标识符。 - `error`（`string | null`）：失败原因；如果操作成功则为 `null`。 错误响应： - `success`（`false`）：表示编辑请求失败。 - `reason`（`'validationError' | 'unexpectedError'`）：错误类别。 - `error`（`string`）：错误信息。 ### `getThreads` 从云文档中读取评论线程。 工具配置（`tool.config`）： - `chunkSize`（`number`，可选）：每次工具调用中读取的最大字符数。默认值：`32000` 工具输出（`tool.output`）： 成功响应： - `success`（`true`）：表示读取请求成功。 - `totalThreadCount`（`number`）：文档中的线程总数。 - `threadRange`（`[number, number]`）：读取的线程范围，格式为 `[from, to)`。 - `threads`（`array`）：返回的线程对象。 - `id`（`string`）：唯一线程标识符。 - `nodeRange`（`[number, number] | null`）：线程所在的节点范围；如果线程未在文档中标注，则为 `null`。 - `content`（`JSONContent[] | string | null`）：线程标记的内容。当 `format` 为 `json` 时，这是一个 Tiptap JSON 片段。当 `format` 为 `shorthand` 时，这是一个 Tiptap Shorthand 字符串。`null` 表示线程未在文档中标注。 - `comments`（`array`）：线程中的评论。 - `id`（`string`）：唯一评论标识符。 - `content`（`string`）：评论文本。 - `userId`（`string`）：创建该评论的用户 ID。 - `createdAt`（`string`）：评论创建时的 ISO 时间戳。 - `updatedAt`（`string`）：评论最后更新时间的 ISO 时间戳。 - `resolvedAt?`（`string | null`）：线程被解决时的 ISO 时间戳；如果未解决，则为 `null`。 - `createdAt`（`string`）：线程创建时的 ISO 时间戳。 - `updatedAt`（`string`）：线程最后更新时间的 ISO 时间戳。 - `data?`（`Record`）：公开线程元数据。 错误响应： - `success`（`false`）：表示读取请求失败。 - `error`（`string`）：错误信息。 - `totalThreadCount?`（`number`）：已持久化线程的总数（如已知）。 ### `editThreads` 创建和更新评论线程。 工具配置（`tool.config`）： - `threadData`（`object`，可选）：添加到新建线程的元数据。 - `commentData`（`object`，可选）：添加到新建评论的元数据。 工具输出（`tool.output`）： 成功或部分成功响应： - `success`（`boolean`）：表示所有操作是否都已成功完成。 - `operations`（`array`）：每个操作的结果。 - `type`（`string`）：已执行的操作类型。 - `success`（`boolean`）：该操作是否已成功完成。 - `message`（`string`）：人类可读的操作结果。 - `threadId?`（`string`）：用于创建或引用线程的操作对应的线程 ID。 错误响应： - `success`（`false`）：表示请求在处理操作之前就已失败。 - `error`（`string`）：错误信息。 ### `readDocument` 读取整个文档。 > **可能会溢出上下文窗口:** > > `readDocument` 会返回完整文档。对于大型文档，请改用 `tiptapRead`。 工具配置（`tool.config`）： `null` 工具输出（`tool.output`）： 成功响应： - `success`（`true`）：表示文档读取成功。 - `content`（`JSONContent[] | string`）：整个有效文档内容。当 `format` 为 `json` 时， 这是一个 Tiptap JSON 片段。当 `format` 为 `shorthand` 时，这是一个 Tiptap Shorthand 字符串。 ### `proofread` 应用校对编辑。 工具配置（`tool.config`）： - `threadData`（`object`，可选）：添加到新建线程的元数据。 - `commentData`（`object`，可选）：添加到新建评论的元数据。 工具输出（`tool.output`）： 成功或部分成功响应： - `success`（`boolean`）：表示所有操作是否都已成功完成。 - `operationResults`（`array`）：每个操作的结果。 - `target`（`string`）：操作所针对元素的字符串标识符。 - `success`（`boolean`）：该操作是否已成功完成。 - `error`（`string | null`）：失败原因；如果操作成功则为 `null`。 ## 相关页面 - [审查选项](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md) - [编辑器上下文](https://tiptap.zhcndoc.com/content-ai/capabilities/server-ai-toolkit/api-reference/editor-context.md)