{ "openapi": "3.0.1", "info": { "title": "Dify 服务 API", "description": "用于 Dify 应用与知识库的 REST API。应用类接口使用应用 API 密钥认证，知识库类接口使用知识库 API 密钥认证。", "version": "1.0.0" }, "servers": [ { "url": "https://{api_base_url}", "description": "Dify 服务 API 的基础 URL。自部署时，替换为你的 API 基础 URL。", "variables": { "api_base_url": { "default": "api.dify.ai/v1", "description": "API 基础 URL 的主机与路径，不含 `https://` 前缀。" } } } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "对话消息", "description": "与聊天消息和交互相关的操作。" }, { "name": "文件操作", "description": "文件上传和预览操作。" }, { "name": "终端用户", "description": "终端用户信息相关操作。" }, { "name": "消息反馈", "description": "用户反馈操作。" }, { "name": "会话管理", "description": "与管理会话相关的操作。" }, { "name": "语音与文字转换", "description": "文字转语音和语音转文字操作。" }, { "name": "应用配置", "description": "获取应用设置和信息的操作。" }, { "name": "标注管理", "description": "与管理标注直接回复相关的操作。" }, { "name": "人工介入", "description": "暂停等待人工输入的工作流恢复操作。" }, { "name": "工作流运行", "description": "用于执行和管理工作流的操作。" }, { "name": "文本生成消息", "description": "文本生成相关操作。" }, { "name": "知识库", "description": "用于管理知识库的操作，包括创建、配置和检索。" }, { "name": "文档", "description": "用于在知识库中创建、更新和管理文档的操作。" }, { "name": "分段", "description": "用于管理分段和子分段的操作。" }, { "name": "元数据", "description": "用于管理知识库元数据字段和文档元数据值的操作。" }, { "name": "标签", "description": "用于管理知识库标签和标签绑定的操作。" }, { "name": "模型", "description": "用于获取可用模型的操作。" }, { "name": "知识流水线", "description": "用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。" } ], "paths": { "/chat-messages": { "post": { "summary": "发送对话消息", "description": "**适用于**：Chatflow、新 Agent、聊天助手、Agent。\n\n向对话型应用发送一条消息并返回助手的回复。流式响应中的事件因应用类型而异。", "operationId": "sendBasicChatMessageCn", "tags": [ "对话消息" ], "requestBody": { "description": "发送对话消息的请求体。", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" }, "examples": { "streaming_example": { "summary": "请求示例 - 流式模式", "value": { "inputs": { "city": "San Francisco" }, "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", "conversation_id": "", "user": "abc-123", "files": [ { "type": "image", "transfer_method": "remote_url", "url": "https://cloud.dify.ai/logo/logo-site.png" } ] } }, "blocking_example": { "summary": "请求示例 - 阻塞模式", "value": { "inputs": {}, "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "blocking", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "user": "abc-123" } } } } } }, "responses": { "200": { "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `ChatCompletionResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和服务器发送事件流。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" }, "examples": { "blockingResponse": { "summary": "响应示例 - 阻塞模式", "value": { "event": "message", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "mode": "chat", "answer": "iPhone 13 Pro Max specs are listed here:...", "metadata": { "usage": { "prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 128, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002560", "total_tokens": 1161, "total_price": "0.0012890", "currency": "USD", "latency": 0.7682376249867957 }, "retriever_resources": [ { "position": 1, "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", "dataset_name": "iPhone", "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", "document_name": "iPhone List", "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", "score": 0.98457545, "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" } ] }, "created_at": 1705407629 } } } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events (SSE) 流。按 [SSE 流式传输指南](/zh/api-reference/guides/streaming) 解析：读取 `data:` 行，根据 `event` 字段分派，忽略 `ping`（每 10 秒保持连接）。\n\n**按应用类型划分的事件**（先是回复事件，再是流的结束方式）：\n\n- **聊天助手**：`message` 片段（按顺序拼接）→ `message_end`。\n- **Agent**：`agent_thought` 推理与工具调用步骤，与 `agent_message` 片段并行 → `message_end`。\n- **新 Agent**：`agent_message` 片段与并行的 `agent_thought` 步骤 → 一个收尾的 `message` 携带完整回答（将其视为最终回答，而非要追加的额外文本）→ `message_end`。其 `message_end` 的 `metadata` 包含 `usage`（命中标注回复时还包含 `annotation_reply`），不含 `retriever_resources`。\n- **Chatflow**：`workflow_started` → 节点事件（`node_started`、`node_finished`，以及迭代和循环的相应变体）与 `message` 片段并行 → 随后按运行结果：\n - **成功**：`message_end`，随后 `workflow_finished`\n - **失败**：`workflow_finished`（状态为 `failed`），随后 `error`；不发送 `message_end`\n - **暂停**：`human_input_required`，随后 `workflow_paused`（流到此结束，运行将另行恢复）\n\n**附加事件**：\n\n- 文本转语音自动播放：`tts_message` 音频片段会穿插其间，`tts_message_end` 跟随在结束事件之后。\n- 设置 `reasoning_format: separated` 的 Chatflow LLM 节点还会发送 `reasoning_chunk` 增量，承载模型的推理内容。\n\n**通用字段**：除 `ping` 外，每个事件都包含 `conversation_id`、`message_id` 和 `created_at`（Unix 纪元秒）；除 `error` 外，其余事件还包含 `task_id`。工作流、节点和人工介入事件（Chatflow 应用）会将载荷嵌套在 `data` 中，且除 `agent_log` 外都带有顶层 `workflow_run_id`。\n\n**回复事件**\n\n| 事件 | 应用 | 触发时机 | 关键字段 |\n|:---|:---|:---|:---|\n| `message` | 聊天助手、Chatflow、新 Agent | 每个回答片段（按顺序拼接）；新 Agent 为携带完整回答的收尾片段 | `answer` |\n| `agent_message` | Agent、新 Agent | 每个回答片段（按顺序拼接） | `answer` |\n| `agent_thought` | Agent、新 Agent | 每个推理或工具调用步骤 | `position`、`thought`、`tool`、`tool_input`（JSON）、`observation`、`message_files` |\n| `message_replace` | 全部 | 内容审核替换已生成的回答 | `answer`；Chatflow 应用还包含 `reason` |\n| `reasoning_chunk` | Chatflow | 每个推理内容增量，当 LLM 节点使用 `reasoning_format: separated` 时（按顺序拼接；`is_final: true` 的事件标志推理结束，且 `reasoning` 可能为空） | `data.message_id`、`data.reasoning`、`data.node_id`、`data.is_final` |\n| `message_file` | 聊天助手、Agent | 助手返回文件 | `type`、`belongs_to`、`url` |\n| `message_end` | 全部 | 回答完成 | `metadata`（`usage`、`retriever_resources`） |\n| `tts_message`、`tts_message_end` | 聊天助手、Agent、Chatflow | 音频片段/结束，开启 TTS 自动播放时 | `audio` |\n\n**工作流与节点事件**（仅 Chatflow 应用）\n\n每个事件都将载荷嵌套在 `data` 对象中。\n\n| 事件 | 触发时机 | 关键 `data` 字段 |\n|:---|:---|:---|\n| `workflow_started` | 运行开始 | `inputs` |\n| `node_started` | 节点开始 | `node_id`、`node_type`、`title` |\n| `node_finished` | 节点结束 | `status`、`outputs`、`execution_metadata` |\n| `node_retry` | 节点失败后重试 | `retry_index` |\n| `iteration_started`、`iteration_next`、`iteration_completed` | 迭代节点进度（信息性，可不处理） | `data` |\n| `loop_started`、`loop_next`、`loop_completed` | 循环节点进度（信息性，可不处理） | `data` |\n| `agent_log` | Agent 节点步骤日志（信息性，可不处理；无 `workflow_run_id`） | `data` |\n| `workflow_finished` | 运行结束 | `status`（`succeeded`、`failed`、`partial-succeeded`、`stopped`）、`outputs`、`total_tokens` |\n| `workflow_paused` | 运行暂停 | `paused_nodes`、`reasons` |\n| `human_input_required` | 运行到达人工介入节点 | `form_token`、`form_content`、`expiration_time` |\n\n暂停后，本流在 `workflow_paused` 处结束。通过 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form) 提交表单，或等待其超时；恢复后的运行（包括从 `human_input_form_filled`/`human_input_form_timeout` 到 `workflow_finished` 的事件）由 [流式获取工作流事件](/zh/api-reference/workflow-runs/stream-workflow-events) 流式返回。\n\n**传输事件**\n\n| 事件 | 触发时机 | 关键字段 |\n|:---|:---|:---|\n| `error` | 失败导致流结束；HTTP 仍为 `200` | `status`（如 `400`）、`code`（如 `invalid_param`）、`message` |\n| `ping` | 每 10 秒保持连接 | 无 |" }, "examples": { "streamingResponseBasic": { "summary": "Response Example - Streaming (Basic)", "value": "data: {\"event\": \"message\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\": \"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"created_at\": 1679586595, \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" }, "streamingResponseAgent": { "summary": "Response Example - Streaming (Agent)", "value": "data: {\"event\": \"agent_thought\", \"id\": \"agent_thought_id_1\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"position\": 1, \"thought\": \"Thinking about calling a tool...\", \"tool\": \"dalle3\", \"tool_input\": \"{\\\"dalle3\\\": {\\\"prompt\\\": \\\"a cute cat\\\"}}\", \"created_at\": 1705395332} data: {\"event\": \"message_file\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"created_at\": 1705395332} data: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333} data: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}" }, "streamingResponseWorkflow": { "summary": "Response Example - Streaming (工作流)", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395332, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"The user greeted me, so\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395333, \"data\": {\"message_id\": \"msg123\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395334, \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"created_at\": 1705395335, \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}" }, "humanInputPause": { "summary": "响应示例 - 人工介入暂停", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"请审阅草稿。\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"批准\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407629, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"paused_nodes\": [\"approval_node\"], \"outputs\": {}, \"reasons\": [{\"TYPE\": \"human_input_required\", \"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_content\": \"请审阅草稿。\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"批准\", \"button_style\": \"primary\"}], \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"resolved_default_values\": {\"comment\": \"\"}, \"form_token\": \"tok_abc123\", \"expiration_time\": 1705494029}], \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5, \"total_tokens\": 0, \"total_steps\": 1}}" } } } } }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `not_chat_app` : App mode does not match the API route.\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 文本生成失败。\n- `bad_request` : Cannot use draft 工作流 version.\n- `bad_request` : Invalid `workflow_id` format.\n- `bad_request` : 新 Agent 应用使用了 `blocking` 响应模式。\n- `invalid_param` : 新 Agent 应用未绑定 Agent。\n- `agent_not_published` : 绑定的 Agent 尚未发布。（新 Agent 应用）\n- `conversation_completed` : 会话已结束，省略 `conversation_id` 以开启新会话。", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "is_draft_workflow": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. " } }, "workflow_id_format_error": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Invalid workflow_id format: 'not-a-valid-id'. " } }, "new_agent_streaming_only": { "summary": "bad_request", "value": { "code": "bad_request", "message": "Agent App only supports streaming response mode.", "status": 400 } }, "new_agent_not_bound": { "summary": "invalid_param", "value": { "code": "invalid_param", "message": "Agent App has no bound Agent", "status": 400 } }, "new_agent_not_published": { "summary": "agent_not_published", "value": { "code": "agent_not_published", "message": "Agent has not been published. Please publish the Agent before using the API.", "status": 400 } }, "conversation_completed": { "summary": "conversation_completed", "value": { "status": 400, "code": "conversation_completed", "message": "The conversation has ended. Please start a new conversation." } } } } } }, "403": { "description": "`workflow_version_execution_not_allowed` : Chatflow 请求在 Dify Cloud Sandbox 套餐下通过 `workflow_id` 指定了工作流版本。", "content": { "application/json": { "examples": { "workflow_version_execution_not_allowed": { "summary": "workflow_version_execution_not_allowed", "value": { "status": 403, "code": "workflow_version_execution_not_allowed", "message": "Workflow version execution is not available on your current plan. Please upgrade to a paid plan." } } } } } }, "404": { "description": "- `not_found` : Conversation does not exist.\n- `not_found` : 工作流 not found with the specified `workflow_id`.", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } }, "workflow_not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab" } } } } } }, "429": { "description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 工作空间在 Dify Cloud 的工作流执行配额已用尽。", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chat-messages/send-chat-message", "metadata": { "title": "发送对话消息", "sidebarTitle": "发送对话消息" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/chat-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"query\": \"What are the specs of the iPhone 13 Pro Max?\", \"inputs\": {}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'" } ] } }, "/chat-messages/{task_id}/stop": { "post": { "summary": "停止响应", "description": "**适用于**：Chatflow、新 Agent、聊天助手、Agent。\n\n停止聊天消息生成任务。仅在 `streaming` 模式下支持。", "operationId": "stopBasicChatMessageGenerationCn", "tags": [ "对话消息" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "任务 ID，来自 [发送对话消息](/zh/api-reference/chat-messages/send-chat-message) 的流式事件。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。必须与发送原始消息时的 `user` 一致；不一致时停止不会生效，但仍返回成功。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" } } }, "examples": { "example": { "summary": "请求示例", "value": { "user": "abc-123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `invalid_param` : 缺少必填的 `user` 字段。", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chat-messages/stop-chat-message-generation", "metadata": { "title": "停止响应", "sidebarTitle": "停止响应" } } } }, "/messages/{message_id}/suggested": { "get": { "summary": "获取下一轮建议问题列表", "description": "**适用于**：Chatflow、新 Agent、聊天助手、Agent。\n\n返回为某条消息推荐的追问问题。", "operationId": "getBasicChatSuggestedQuestionsCn", "tags": [ "对话消息" ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "要获取建议问题的消息 ID。可从对话响应或 [获取会话历史消息](/zh/api-reference/conversations/list-conversation-messages) 获取。", "schema": { "type": "string", "format": "uuid" } }, { "name": "user", "in": "query", "required": true, "description": "终端用户标识，由你的应用定义，需在应用内唯一。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功获取建议问题。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponse" }, "examples": { "suggestedQuestions": { "summary": "响应示例", "value": { "result": "success", "data": [ "What colors does the iPhone 13 Pro Max come in?", "How does the battery compare to iPhone 12?", "What is the price range?" ] } } } } } }, "400": { "description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `bad_request` : 建议问题功能已禁用。", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } }, "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Suggested Questions Is Disabled." } } } } } }, "404": { "description": "`not_found` : 消息不存在。", "content": { "application/json": { "examples": { "message_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Message Not Exists." } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://{api_base_url}/messages/{message_id}/suggested?user={user}' \\\n --header 'Authorization: Bearer {api_key}'" } ], "x-mint": { "href": "/zh/api-reference/chat-messages/get-next-suggested-questions", "metadata": { "title": "获取下一轮建议问题列表", "sidebarTitle": "获取下一轮建议问题列表" } } } }, "/files/upload": { "post": { "summary": "上传文件", "description": "**适用于**：Chatflow、Workflow、新 Agent、聊天助手、Agent、文本生成应用。\n\n上传文件并返回其 `id`，供后续请求引用。文件归上传它的终端用户所有：只有携带相同 `user` 的请求才能引用该文件。\n\n应用实际能使用哪些文件类型，取决于它的文件上传设置；可通过 [获取应用参数](/zh/api-reference/applications/get-app-parameters) 读取。", "operationId": "uploadBasicChatFileCn", "tags": [ "文件操作" ], "requestBody": { "description": "文件上传请求。需要 multipart/form-data 格式。", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "要上传的文件，作为 `multipart/form-data` 的一个部分。文件名不能包含 `/` 或 `\\`。\n\n除部署安全黑名单（`UPLOAD_FILE_EXTENSION_BLACKLIST`，默认为空）中的扩展名外，任何文件类型都可上传。\n\n文件大小按类别限制：图片 10 MB、音频 50 MB、视频 100 MB、其他文件 15 MB（默认值，Dify Cloud 使用默认值）。自部署可通过 `UPLOAD_*_FILE_SIZE_LIMIT` [环境变量](/zh/self-host/deploy/configuration/environments) 调整。" }, "user": { "type": "string", "description": "该上传所属的终端用户标识，由你的应用定义，需在应用内唯一。省略时上传归属于共享的 `DEFAULT-USER`。只有携带相同 `user` 的后续请求才能引用该文件。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" } } } } } }, "responses": { "201": { "description": "文件上传成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" }, "examples": { "uploadSuccess": { "summary": "响应示例", "value": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "reference": null, "name": "product-photo.png", "size": 204800, "extension": "png", "mime_type": "image/png", "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "created_at": 1705407629, "preview_url": null, "source_url": "https://upload.dify.ai/files/a1b2c3d4-5678-90ab-cdef-1234567890ab/file-preview?timestamp=1705407629&nonce=8b3e26a5&sign=rN5DXW3xkVGwGE5MSvptu_BhQVXpMbXWmVJ0ib0LMzI=", "original_url": null, "user_id": null, "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "conversation_id": null, "file_key": null } } } } } }, "400": { "description": "- `no_file_uploaded` : 请求中未提供文件。\n- `too_many_files` : 每次请求仅允许上传一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。\n- `invalid_param` : 文件名包含 `/` 或 `\\`，或文件扩展名在部署的黑名单中。", "content": { "application/json": { "examples": { "no_file_uploaded": { "summary": "no_file_uploaded", "value": { "status": 400, "code": "no_file_uploaded", "message": "Please upload your file." } }, "too_many_files": { "summary": "too_many_files", "value": { "status": 400, "code": "too_many_files", "message": "Only one file is allowed." } }, "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "status": 400, "code": "filename_not_exists_error", "message": "The specified filename does not exist." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "File extension '.exe' is not allowed for security reasons" } } } } } }, "413": { "description": "`file_too_large` : 文件超过其类别的大小限制（见 `file` 字段）。目前运行时返回的 `message` 为空字符串（已知的后端问题），请以 `code` 和状态码为准。", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "" } } } } } }, "415": { "description": "`unsupported_file_type` : 上传的 `file` 部分未声明 MIME 类型。", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "x-mint": { "href": "/zh/api-reference/files/upload-file", "metadata": { "title": "上传文件", "sidebarTitle": "上传文件" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/files/upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@product-photo.png' \\\n --form 'user={user}'" } ] } }, "/files/{file_id}/preview": { "get": { "summary": "下载文件", "description": "**适用于**：Chatflow、聊天助手、Agent、文本生成应用。\n\n返回此前由 [上传文件](/zh/api-reference/files/upload-file) 返回的文件的原始字节。文件仅可通过引用它的消息所属的应用访问。", "operationId": "previewBasicChatFileCn", "tags": [ "文件操作" ], "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "要下载的文件 ID，来自上传文件的响应。", "schema": { "type": "string", "format": "uuid" } }, { "name": "as_attachment", "in": "query", "required": false, "description": "为 `true` 时，文件以附件形式下载，而不是在浏览器中内联渲染。", "schema": { "type": "boolean", "default": false } }, { "name": "user", "in": "query", "required": false, "description": "终端用户标识，由你的应用定义，需在应用内唯一。此处对文件访问没有影响，文件访问按应用和消息（而非 `user`）限定。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "返回原始文件内容。`Content-Type` 头设置为文件的 MIME 类型。如果 `as_attachment` 为 `true`，文件将以 `Content-Disposition: attachment` 方式作为下载返回。", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "`file_access_denied` : 文件存在，但属于其他应用或工作空间。", "content": { "application/json": { "examples": { "file_access_denied": { "summary": "file_access_denied", "value": { "status": 403, "code": "file_access_denied", "message": "Access to the requested file is denied." } } } } } }, "404": { "description": "`file_not_found` : 此 ID 对应的文件无法通过本应用的消息访问。", "content": { "application/json": { "examples": { "file_not_found": { "summary": "file_not_found", "value": { "status": 404, "code": "file_not_found", "message": "The requested file was not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/files/download-file", "metadata": { "title": "下载文件", "sidebarTitle": "下载文件" } } } }, "/end-users/{end_user_id}": { "get": { "summary": "获取终端用户信息", "description": "**适用于**：Chatflow、Workflow、新 Agent、聊天助手、Agent、文本生成应用。\n\n根据 ID 返回终端用户的详细信息。当需要解析其他接口返回的终端用户 ID（例如 [上传文件](/zh/api-reference/files/upload-file) 响应中的 `created_by`）时很有用。", "operationId": "getEndUserChatCn", "tags": [ "终端用户" ], "parameters": [ { "name": "end_user_id", "in": "path", "required": true, "description": "要查询的终端用户 ID。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功获取终端用户。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserDetail" }, "examples": { "endUserDetail": { "summary": "响应示例", "value": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "type": "service-api", "external_user_id": "abc-123", "name": null, "is_anonymous": false, "session_id": "abc-123", "created_at": "2024-01-16T12:00:29Z", "updated_at": "2024-01-16T12:00:29Z" } } } } } }, "404": { "description": "`end_user_not_found` : 未找到终端用户。", "content": { "application/json": { "examples": { "end_user_not_found": { "summary": "end_user_not_found", "value": { "status": 404, "code": "end_user_not_found", "message": "End user not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/end-users/get-end-user-info", "metadata": { "title": "获取终端用户信息", "sidebarTitle": "获取终端用户信息" } } } }, "/messages/{message_id}/feedbacks": { "post": { "summary": "提交消息反馈", "description": "**适用于**：Chatflow、聊天助手、Agent、文本生成应用。\n\n为消息记录 `like` 或 `dislike` 评价，并可附带可选评论。将 `rating` 设为 `null` 可撤销该消息的已有反馈。", "operationId": "postBasicChatMessageFeedbackCn", "tags": [ "消息反馈" ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "要反馈的消息 ID。消息 ID 从 [获取会话历史消息](/zh/api-reference/conversations/list-conversation-messages) 获取。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFeedbackRequest" }, "examples": { "likeFeedback": { "summary": "请求示例", "value": { "rating": "like", "user": "abc-123", "content": "This answer was very helpful!" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "`invalid_param` : 缺少必填的 `user` 字段，或 `rating` 为 `null` 但没有可撤销的已有反馈。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "404": { "description": "`not_found` : 消息不存在。", "content": { "application/json": { "examples": { "message_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Message Not Exists." } } } } } } }, "x-mint": { "href": "/zh/api-reference/feedback/submit-message-feedback", "metadata": { "title": "提交消息反馈", "sidebarTitle": "提交消息反馈" } } } }, "/app/feedbacks": { "get": { "summary": "获取应用的消息反馈", "description": "**适用于**：Chatflow、聊天助手、Agent、文本生成应用。\n\n返回此应用所有消息反馈的分页列表，包括终端用户和管理员提交的反馈。", "operationId": "getBasicChatAppFeedbacksCn", "tags": [ "消息反馈" ], "parameters": [ { "name": "page", "in": "query", "description": "页码。", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "每页反馈条数。", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 101 } } ], "responses": { "200": { "description": "应用反馈列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppFeedbacksResponse" }, "examples": { "feedbacksList": { "summary": "响应示例", "value": { "data": [ { "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "rating": "like", "content": "The response accurately answered my question about product specifications.", "from_source": "user", "from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "from_account_id": null, "created_at": "2025-01-16T14:30:29Z", "updated_at": "2025-01-16T14:30:29Z" }, { "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603", "message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1", "rating": "dislike", "content": "The answer was too vague and did not address the specific pricing question.", "from_source": "user", "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", "from_account_id": null, "created_at": "2025-01-15T09:12:45Z", "updated_at": "2025-01-15T09:12:45Z" } ] } } } } } } }, "x-mint": { "href": "/zh/api-reference/feedback/list-app-feedbacks", "metadata": { "title": "获取应用的消息反馈", "sidebarTitle": "获取应用的消息反馈" } } } }, "/conversations": { "get": { "summary": "获取会话列表", "description": "**适用于**：Chatflow、新 Agent、聊天助手、Agent。\n\n列出某个终端用户的会话，按最近活跃时间排序。", "operationId": "getBasicChatConversationsListCn", "tags": [ "会话管理" ], "parameters": [ { "name": "user", "in": "query", "required": false, "description": "终端用户标识，由你的应用定义，需在应用内唯一。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。", "schema": { "type": "string" } }, { "name": "last_id", "in": "query", "required": false, "description": "分页游标：当前页最后一个会话的 `id`。省略则获取第一页。", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "返回的记录数。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "sort_by", "in": "query", "required": false, "description": "排序字段。加 `-` 前缀表示降序。", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-updated_at" } } ], "responses": { "200": { "description": "成功获取会话列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsListResponse" }, "examples": { "conversationsList": { "summary": "响应示例", "value": { "limit": 20, "has_more": false, "data": [ { "id": "45701982-8118-4bc5-8e9b-64562b4555f2", "name": "iPhone Specs Chat", "inputs": { "city": "San Francisco" }, "status": "normal", "introduction": "Welcome! How can I help you today?", "created_at": 1705407629, "updated_at": 1705411229 } ] } } } } } }, "400": { "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : 上一个会话不存在（无效的 `last_id`）。", "content": { "application/json": { "examples": { "last_conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Last Conversation Not Exists." } } } } } } }, "x-mint": { "href": "/zh/api-reference/conversations/list-conversations", "metadata": { "title": "获取会话列表", "sidebarTitle": "获取会话列表" } } } }, "/messages": { "get": { "summary": "获取会话历史消息", "description": "**适用于**：Chatflow、新 Agent、聊天助手、Agent。\n\n返回会话的消息历史，按时间倒序（最新在前）。传入 `first_id` 可向前翻页获取更早的消息。", "operationId": "getBasicChatConversationHistoryCn", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "query", "required": true, "description": "要读取的会话 ID。会话 ID 从 [获取会话列表](/zh/api-reference/conversations/list-conversations) 获取。", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "终端用户标识，由你的应用定义，需在应用内唯一。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。", "schema": { "type": "string" } }, { "name": "first_id", "in": "query", "required": false, "description": "分页游标：当前页第一条消息的 `id`。传入它可获取上一页（更早的消息）；省略则获取最新消息。", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "每次请求返回的聊天历史消息数量。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "成功获取会话历史。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationHistoryResponse" }, "examples": { "conversationHistory": { "summary": "响应示例", "value": { "limit": 20, "has_more": false, "data": [ { "id": "9da23599-e713-473b-982c-4328d4f5c78a", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "parent_message_id": null, "inputs": { "city": "San Francisco" }, "query": "What are the specs of the iPhone 13 Pro Max?", "answer": "iPhone 13 Pro Max specs are listed here:...", "status": "normal", "error": null, "message_files": [], "feedback": { "rating": "like" }, "retriever_resources": [], "agent_thoughts": [], "created_at": 1705407629, "extra_contents": [], "message_tokens": 100, "answer_tokens": 58, "total_tokens": 158, "provider_response_latency": 1.234, "total_price": "0.0012825", "currency": "USD" } ] } } } } } }, "400": { "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "- `not_found` : 会话不存在。\n- `not_found` : 第一条消息不存在（`first_id` 无效）。", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } }, "first_message_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "First Message Not Exists." } } } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://{api_base_url}/messages?conversation_id={conversation_id}&user={user}' \\\n --header 'Authorization: Bearer {api_key}'" } ], "x-mint": { "href": "/zh/api-reference/conversations/list-conversation-messages", "metadata": { "title": "获取会话历史消息", "sidebarTitle": "获取会话历史消息" } } } }, "/conversations/{conversation_id}/variables": { "get": { "summary": "获取对话变量", "description": "**适用于**：Chatflow、聊天助手、Agent。\n\n列出会话中存储的变量。", "operationId": "getBasicChatConversationVariablesCn", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "要列出变量的会话 ID。会话 ID 从 [获取会话列表](/zh/api-reference/conversations/list-conversations) 获取。", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "终端用户标识，由你的应用定义，需在应用内唯一。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。", "schema": { "type": "string" } }, { "name": "last_id", "in": "query", "required": false, "description": "分页游标：当前页最后一个变量的 `id`。省略则获取第一页。", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "返回的记录数。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "variable_name", "in": "query", "required": false, "description": "按指定名称筛选变量。", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "成功获取会话变量。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariablesResponse" }, "examples": { "conversationVariables": { "summary": "响应示例", "value": { "limit": 20, "has_more": false, "data": [ { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "name": "user_preference", "value_type": "string", "value": "dark_mode", "description": "用户偏好设置", "created_at": 1705407629, "updated_at": 1705411229 } ] } } } } } }, "400": { "description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `invalid_param` : `last_id` 未匹配到此会话中的任何变量。", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } }, "invalid_last_id": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "" } } } } } }, "404": { "description": "`not_found` : 会话不存在。", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } } } } } } }, "x-mint": { "href": "/zh/api-reference/conversations/list-conversation-variables", "metadata": { "title": "获取对话变量", "sidebarTitle": "获取对话变量" } } } }, "/conversations/{conversation_id}/name": { "post": { "summary": "重命名会话", "description": "**适用于**：Chatflow、新 Agent、聊天助手、Agent。\n\n重命名会话；当 `auto_generate` 为 `true` 时，根据会话消息自动生成名称。该名称用于客户端的多会话列表显示。", "operationId": "renameBasicChatConversationCn", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "要重命名的会话 ID。会话 ID 从 [获取会话列表](/zh/api-reference/conversations/list-conversations) 获取。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequest" }, "examples": { "renameExample": { "summary": "请求示例", "value": { "name": "iPhone Specs Chat", "user": "abc-123" } } } } } }, "responses": { "200": { "description": "会话重命名成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationListItem" }, "examples": { "renamedConversation": { "summary": "响应示例", "value": { "id": "45701982-8118-4bc5-8e9b-64562b4555f2", "name": "iPhone Specs Chat", "inputs": { "city": "San Francisco" }, "status": "normal", "introduction": "Welcome! How can I help you today?", "created_at": 1705407629, "updated_at": 1705411229 } } } } } }, "400": { "description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `invalid_param` : `auto_generate` 为 `true`，但会话中没有可用于生成名称的消息。", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } }, "no_messages": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "" } } } } } }, "404": { "description": "`not_found` : 会话不存在。", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } } } } } } }, "x-mint": { "href": "/zh/api-reference/conversations/rename-conversation", "metadata": { "title": "重命名会话", "sidebarTitle": "重命名会话" } } } }, "/conversations/{conversation_id}/variables/{variable_id}": { "put": { "summary": "更新对话变量", "description": "**适用于**：Chatflow、聊天助手、Agent。\n\n更新会话变量的值。新值必须与该变量的现有类型匹配。", "operationId": "updateChatConversationVariableZh", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "变量所属的会话 ID。会话 ID 从 [获取会话列表](/zh/api-reference/conversations/list-conversations) 获取。", "schema": { "type": "string", "format": "uuid" } }, { "name": "variable_id", "in": "path", "required": true, "description": "要更新的变量 ID。变量 ID 从 [获取对话变量](/zh/api-reference/conversations/list-conversation-variables) 获取。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariableUpdateRequest" }, "examples": { "updateStringVariable": { "summary": "请求示例", "value": { "value": "new value", "user": "abc-123" } } } } } }, "responses": { "200": { "description": "变量更新成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariableItem" }, "examples": { "updatedVariable": { "summary": "响应示例", "value": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "name": "user_preference", "value_type": "string", "value": "new value", "description": "用户偏好设置", "created_at": 1705407629, "updated_at": 1705411229 } } } } } }, "400": { "description": "- `not_chat_app` : 应用模式与 API 路由不匹配。\n- `bad_request` : 变量值类型不匹配。", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } }, "type_mismatch": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Type mismatch: variable 'user_preference' expects string, but got number type" } } } } } }, "404": { "description": "- `not_found` : 会话不存在。\n- `not_found` : 会话变量不存在。", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } }, "variable_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Variable Not Exists." } } } } } } }, "x-mint": { "href": "/zh/api-reference/conversations/update-conversation-variable", "metadata": { "title": "更新对话变量", "sidebarTitle": "更新对话变量" } } } }, "/conversations/{conversation_id}": { "delete": { "summary": "删除会话", "description": "**适用于**：Chatflow、新 Agent、聊天助手、Agent。\n\n删除会话。", "operationId": "deleteBasicChatConversationCn", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "要删除的会话 ID。会话 ID 从 [获取会话列表](/zh/api-reference/conversations/list-conversations) 获取。", "schema": { "type": "string" } } ], "requestBody": { "description": "JSON 请求体始终必填；不传 `user` 时发送 `{}`。", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" } } }, "examples": { "deleteExample": { "value": { "user": "abc-123" }, "summary": "请求示例" } } } } }, "responses": { "204": { "description": "会话删除成功。无返回内容。" }, "400": { "description": "`not_chat_app` : 应用模式与 API 路由不匹配。", "content": { "application/json": { "examples": { "not_chat_app": { "summary": "not_chat_app", "value": { "status": 400, "code": "not_chat_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : 会话不存在。", "content": { "application/json": { "examples": { "conversation_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Conversation Not Exists." } } } } } } }, "x-mint": { "href": "/zh/api-reference/conversations/delete-conversation", "metadata": { "title": "删除会话", "sidebarTitle": "删除会话" } } } }, "/audio-to-text": { "post": { "summary": "语音转文字", "description": "**适用于**：Chatflow、Workflow、新 Agent、聊天助手、Agent、文本生成应用。\n\n使用应用配置的语音转文字模型，将上传的音频文件转写为文字。", "operationId": "basicChatAudioToTextCn", "tags": [ "语音与文字转换" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequest" } } } }, "responses": { "200": { "description": "语音转文字成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponse" }, "examples": { "audioToTextSuccess": { "summary": "响应示例", "value": { "text": "Hello, I would like to know more about the iPhone 13 Pro Max." } } } } } }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `speech_to_text_disabled` : 此应用未启用语音转文本。\n- `provider_not_support_speech_to_text` : 模型供应商不支持语音转文字。\n- `provider_not_initialize` : 未配置有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 语音识别请求失败。", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "speech_to_text_disabled": { "summary": "speech_to_text_disabled", "value": { "status": 400, "code": "speech_to_text_disabled", "message": "Speech to text is disabled." } }, "provider_not_support_speech_to_text": { "summary": "provider_not_support_speech_to_text", "value": { "status": 400, "code": "provider_not_support_speech_to_text", "message": "Provider not support speech to text." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "413": { "description": "`audio_too_large` : 音频文件超出 `30 MB` 大小限制。", "content": { "application/json": { "examples": { "audio_too_large": { "summary": "audio_too_large", "value": { "status": 413, "code": "audio_too_large", "message": "Audio size larger than 30 mb" } } } } } }, "415": { "description": "`unsupported_audio_type` : 文件的 MIME 类型不在接受的音频类型之列（见 `file` 字段）。", "content": { "application/json": { "examples": { "unsupported_audio_type": { "summary": "unsupported_audio_type", "value": { "status": 415, "code": "unsupported_audio_type", "message": "Audio type not allowed." } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "x-mint": { "href": "/zh/api-reference/audio/convert-audio-to-text", "metadata": { "title": "语音转文字", "sidebarTitle": "语音转文字" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/audio-to-text' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@meeting-question.mp3' \\\n --form 'user={user}'" } ] } }, "/text-to-audio": { "post": { "summary": "文字转语音", "description": "**适用于**：Chatflow、Workflow、新 Agent、聊天助手、Agent、文本生成应用。\n\n将文本转换为语音音频。传入 `text` 可合成任意文本，或传入 `message_id` 为已有消息的答案配音。", "operationId": "basicChatTextToAudioCn", "tags": [ "语音与文字转换" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToAudioRequest" }, "examples": { "textToAudioExample": { "summary": "请求示例", "value": { "text": "Hello, welcome to our service.", "user": "abc-123", "voice": "alloy", "streaming": false } } } } } }, "responses": { "200": { "description": "返回生成的音频文件。`Content-Type` 头设置为音频 MIME 类型（例如 `audio/wav`、`audio/mp3`）。当配置的 TTS 供应商返回流时，音频以 `audio/mpeg` 分块传输编码方式返回；请求中的 `streaming` 字段不影响这一行为。", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `invalid_param` : 未启用文字转语音、缺少 `text` 或没有可用音色。\n- `provider_not_initialize` : 未配置有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不支持此操作。\n- `completion_request_error` : 文字转语音请求失败。", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "TTS is not enabled" } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "x-mint": { "href": "/zh/api-reference/audio/convert-text-to-audio", "metadata": { "title": "文字转语音", "sidebarTitle": "文字转语音" } } } }, "/info": { "get": { "summary": "获取应用基本信息", "description": "**适用于**：Chatflow、Workflow、新 Agent、聊天助手、Agent、文本生成应用。\n\n返回应用的基本信息：名称、描述、标签、模式和作者。", "operationId": "getBasicChatAppInfoCn", "tags": [ "应用配置" ], "responses": { "200": { "description": "应用的基本信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponse" }, "examples": { "appInfo": { "summary": "响应示例", "value": { "name": "My Chat App", "description": "一个有用的客服聊天机器人。", "tags": [ "customer-service", "chatbot" ], "mode": "chat", "author_name": "Dify Team" } } } } } } }, "x-mint": { "href": "/zh/api-reference/applications/get-app-info", "metadata": { "title": "获取应用基本信息", "sidebarTitle": "获取应用基本信息" } } } }, "/parameters": { "get": { "summary": "获取应用参数", "description": "**适用于**：Chatflow、Workflow、新 Agent、聊天助手、Agent、文本生成应用。\n\n返回应用的前端配置：开场白和建议问题、功能开关、用户输入表单，以及文件上传限制。用它来渲染应用的输入项并应用正确的上传限制。", "operationId": "getBasicChatAppParametersCn", "tags": [ "应用配置" ], "responses": { "200": { "description": "应用参数信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppParametersResponse" }, "examples": { "appParameters": { "summary": "响应示例", "value": { "opening_statement": "Hello! How can I help you today?", "suggested_questions": [ "What can you do?", "Tell me about your features." ], "suggested_questions_after_answer": { "enabled": true }, "speech_to_text": { "enabled": false }, "text_to_speech": { "enabled": false, "voice": "alloy", "language": "en-US", "autoPlay": "disabled" }, "retriever_resource": { "enabled": true }, "annotation_reply": { "enabled": false }, "more_like_this": { "enabled": false }, "sensitive_word_avoidance": { "enabled": false }, "user_input_form": [ { "text-input": { "label": "City", "variable": "city", "required": true, "default": "" } } ], "file_upload": { "image": { "enabled": true, "number_limits": 3, "detail": "high", "transfer_methods": [ "remote_url", "local_file" ] } }, "system_parameters": { "file_size_limit": 15, "image_file_size_limit": 10, "audio_file_size_limit": 50, "video_file_size_limit": 100, "workflow_file_upload_limit": 10 } } } } } } }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `agent_not_published` : 应用的 Agent 尚无已发布版本。（新 Agent 应用）", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "agent_not_published": { "summary": "agent_not_published", "value": { "code": "agent_not_published", "message": "Agent has not been published. Please publish the Agent before using the API.", "status": 400 } } } } } } }, "x-mint": { "href": "/zh/api-reference/applications/get-app-parameters", "metadata": { "title": "获取应用参数", "sidebarTitle": "获取应用参数" } } } }, "/meta": { "get": { "summary": "获取应用元数据", "description": "**适用于**：Chatflow、Workflow、新 Agent、聊天助手、Agent、文本生成应用。\n\n返回此应用所用工具的展示图标，以工具名为键。", "operationId": "getBasicChatAppMetaCn", "tags": [ "应用配置" ], "responses": { "200": { "description": "成功获取应用元数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponse" }, "examples": { "appMeta": { "summary": "响应示例", "value": { "tool_icons": { "dalle3": "https://example.com/icons/dalle3.png", "calculator": { "background": "#4A90D9", "content": "🧮" } } } } } } } } }, "x-mint": { "href": "/zh/api-reference/applications/get-app-meta", "metadata": { "title": "获取应用元数据", "sidebarTitle": "获取应用元数据" } } } }, "/site": { "get": { "summary": "获取应用 WebApp 设置", "description": "**适用于**：Chatflow、Workflow、新 Agent、聊天助手、Agent、文本生成应用。\n\n返回应用托管 WebApp 的品牌与展示设置，如标题、图标、主题色和默认语言。", "operationId": "getBasicChatWebAppSettingsCn", "tags": [ "应用配置" ], "responses": { "200": { "description": "应用的 WebApp 设置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" }, "examples": { "webAppSettings": { "summary": "响应示例", "value": { "title": "My Chat App", "chat_color_theme": "#4A90D9", "chat_color_theme_inverted": false, "icon_type": "emoji", "icon": "🤖", "icon_background": "#FFFFFF", "icon_url": null, "description": "一个有用的客服聊天机器人。", "copyright": "2025 Dify", "privacy_policy": "https://example.com/privacy", "input_placeholder": "有任何关于我们产品的问题都可以问我……", "custom_disclaimer": "", "default_language": "en-US", "show_workflow_steps": false, "use_icon_as_answer_icon": true } } } } } }, "403": { "description": "`forbidden` : 未找到此应用的站点或工作空间已归档。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden", "value": { "status": 403, "code": "forbidden", "message": "You don't have the permission to access the requested resource. It is either read-protected or not readable by the server." } } } } } } }, "x-mint": { "href": "/zh/api-reference/applications/get-app-webapp-settings", "metadata": { "title": "获取应用 WebApp 设置", "sidebarTitle": "获取应用 WebApp 设置" } } } }, "/apps/annotations": { "post": { "summary": "创建标注", "description": "**适用于**：Chatflow、聊天助手、Agent。\n\n创建标注。标注是预定义的问答对，命中时应用直接返回，而不再生成新回复。", "operationId": "createChatAnnotationZh", "tags": [ "标注管理" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" }, "examples": { "createAnnotation": { "summary": "请求示例", "value": { "question": "What is Dify?", "answer": "Dify is an open-source LLM application development platform." } } } } } }, "responses": { "201": { "description": "标注创建成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" }, "examples": { "createdAnnotation": { "summary": "响应示例", "value": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "question": "What is Dify?", "answer": "Dify is an open-source LLM application development platform.", "hit_count": 0, "created_at": 1705407629 } } } } } } }, "x-mint": { "href": "/zh/api-reference/annotations/create-annotation", "metadata": { "title": "创建标注", "sidebarTitle": "创建标注" } } }, "get": { "summary": "获取标注列表", "description": "**适用于**：Chatflow、聊天助手、Agent。\n\n列出应用的标注，可按关键词筛选。", "operationId": "listChatAnnotationsZh", "tags": [ "标注管理" ], "parameters": [ { "name": "page", "in": "query", "description": "页码。", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "description": "每页条目数。超过 100 的请求会被限制为 100。", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1 } }, { "name": "keyword", "in": "query", "description": "按问题或回答内容筛选标注的关键词。", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功获取标注列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationListResponse" }, "examples": { "annotationList": { "summary": "响应示例", "value": { "data": [ { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "question": "What is Dify?", "answer": "Dify is an open-source LLM application development platform.", "hit_count": 5, "created_at": 1705407629 } ], "has_more": false, "limit": 20, "total": 1, "page": 1 } } } } } } }, "x-mint": { "href": "/zh/api-reference/annotations/list-annotations", "metadata": { "title": "获取标注列表", "sidebarTitle": "获取标注列表" } } } }, "/apps/annotations/{annotation_id}": { "put": { "summary": "更新标注", "description": "**适用于**：Chatflow、聊天助手、Agent。\n\n更新标注的问题和答案。", "operationId": "updateChatAnnotationZh", "tags": [ "标注管理" ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "description": "要更新的标注 ID。标注 ID 从 [获取标注列表](/zh/api-reference/annotations/list-annotations) 获取。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" }, "examples": { "updateAnnotation": { "summary": "请求示例", "value": { "question": "What is Dify?", "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." } } } } } }, "responses": { "200": { "description": "标注更新成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" }, "examples": { "updatedAnnotation": { "summary": "响应示例", "value": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "question": "What is Dify?", "answer": "Dify is an open-source LLM application development platform for building AI-powered apps.", "hit_count": 5, "created_at": 1705407629 } } } } } }, "404": { "description": "`not_found` : 标注不存在。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Annotation not found" } } } } } } }, "x-mint": { "href": "/zh/api-reference/annotations/update-annotation", "metadata": { "title": "更新标注", "sidebarTitle": "更新标注" } } }, "delete": { "summary": "删除标注", "description": "**适用于**：Chatflow、聊天助手、Agent。\n\n删除标注及其关联的命中历史。", "operationId": "deleteChatAnnotationZh", "tags": [ "标注管理" ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "description": "要删除的标注 ID。标注 ID 从 [获取标注列表](/zh/api-reference/annotations/list-annotations) 获取。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "标注删除成功。" }, "404": { "description": "`not_found` : 标注不存在。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Annotation not found" } } } } } } }, "x-mint": { "href": "/zh/api-reference/annotations/delete-annotation", "metadata": { "title": "删除标注", "sidebarTitle": "删除标注" } } } }, "/apps/annotation-reply/{action}": { "post": { "summary": "配置标注回复", "description": "**适用于**：Chatflow、聊天助手、Agent。\n\n为应用启用或禁用标注回复。异步执行；使用 [查询标注回复配置任务状态](/zh/api-reference/annotations/get-annotation-reply-job-status) 跟踪进度。\n\n请求体在执行操作前校验，因此即使是 `disable` 也必须提供 `score_threshold`、`embedding_provider_name` 和 `embedding_model_name`。", "operationId": "setChatAnnotationReplyZh", "tags": [ "标注管理" ], "parameters": [ { "name": "action", "in": "path", "required": true, "description": "启用还是禁用标注回复。", "schema": { "type": "string", "enum": [ "enable", "disable" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" }, "examples": { "enableAnnotationReply": { "summary": "请求示例", "value": { "score_threshold": 0.9, "embedding_provider_name": "openai", "embedding_model_name": "text-embedding-3-small" } } } } } }, "responses": { "200": { "description": "标注回复设置任务已启动。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" }, "examples": { "annotationReplyResponse": { "summary": "响应示例", "value": { "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "job_status": "waiting" } } } } } } }, "x-mint": { "href": "/zh/api-reference/annotations/configure-annotation-reply", "metadata": { "title": "配置标注回复", "sidebarTitle": "配置标注回复" } } } }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { "summary": "查询标注回复配置任务状态", "description": "**适用于**：Chatflow、聊天助手、Agent。\n\n返回由 [配置标注回复](/zh/api-reference/annotations/configure-annotation-reply) 发起的标注回复配置任务的状态。", "operationId": "getChatAnnotationReplyStatusZh", "tags": [ "标注管理" ], "parameters": [ { "name": "action", "in": "path", "required": true, "description": "操作类型，必须与 [配置标注回复](/zh/api-reference/annotations/configure-annotation-reply) 调用中的一致。", "schema": { "type": "string", "enum": [ "enable", "disable" ] } }, { "name": "job_id", "in": "path", "required": true, "description": "由 [配置标注回复](/zh/api-reference/annotations/configure-annotation-reply) 接口返回的任务 ID。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功获取任务状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" }, "examples": { "jobStatus": { "summary": "响应示例", "value": { "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "job_status": "completed", "error_msg": "" } } } } } }, "400": { "description": "`invalid_param` : 指定的任务不存在。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "The job does not exist." } } } } } } }, "x-mint": { "href": "/zh/api-reference/annotations/get-annotation-reply-job-status", "metadata": { "title": "查询标注回复配置任务状态", "sidebarTitle": "查询标注回复配置任务状态" } } } }, "/workflows/run/{workflow_run_id}": { "get": { "summary": "获取工作流执行情况", "description": "**适用于**：Chatflow、Workflow。\n\n获取单次工作流运行的状态、输入、输出和执行指标。", "operationId": "getWorkflowRunDetailCn", "tags": [ "工作流运行" ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "description": "工作流运行 ID，来自 [执行工作流](/zh/api-reference/workflow-runs/run-workflow) 的响应或流式事件，或 Chatflow 应用的消息元数据。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功获取工作流运行详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponse" }, "examples": { "workflowRunDetail": { "summary": "响应示例", "value": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "inputs": "{\"query\": \"Translate this to French\"}", "outputs": { "result": "Traduisez ceci en francais" }, "error": null, "total_steps": 3, "total_tokens": 150, "created_at": 1705407629, "finished_at": 1705407630, "elapsed_time": 1.23 } } } } } }, "400": { "description": "`not_workflow_app` : 应用模式与 API 路由不匹配。", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : 未找到工作流运行记录。", "content": { "application/json": { "examples": { "workflow_run_not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow run not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/workflow-runs/get-workflow-run-detail", "metadata": { "title": "获取工作流执行情况", "sidebarTitle": "获取工作流执行情况" } } } }, "/workflows/logs": { "get": { "summary": "获取工作流日志", "description": "**适用于**：Chatflow、Workflow。\n\n列出过往的工作流运行，支持可选筛选。每条记录是运行级摘要（状态、Token 用量、步数和耗时），而非逐节点的执行日志。\n\n如需跟踪某次运行的节点级事件，请改用流式方式：\n\n- **自行发起的运行**：以流式模式调用 [执行工作流](/zh/api-reference/workflow-runs/run-workflow)，运行执行时会发送 `node_started` 和 `node_finished` 事件。\n- **已在进行中的运行**：调用 [流式获取工作流事件](/zh/api-reference/workflow-runs/stream-workflow-events) 并附带 `include_state_snapshot=true`，先重放各已执行节点的状态，再流式发送其余事件。\n\n已结束运行的节点级日志无法通过服务 API 获取。", "operationId": "getWorkflowLogsCn", "tags": [ "工作流运行" ], "parameters": [ { "name": "keyword", "in": "query", "description": "在日志中搜索的关键词。", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "按执行状态筛选。", "schema": { "type": "string", "enum": [ "succeeded", "failed", "stopped" ] } }, { "name": "page", "in": "query", "description": "页码。", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 99999 } }, { "name": "limit", "in": "query", "description": "每页条目数。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "created_at__before", "in": "query", "description": "筛选在此 ISO 8601 时间戳之前创建的日志。", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at__after", "in": "query", "description": "筛选在此 ISO 8601 时间戳之后创建的日志。", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_by_end_user_session_id", "in": "query", "description": "按终端用户会话 ID 筛选。", "schema": { "type": "string" } }, { "name": "created_by_account", "in": "query", "description": "按创建者的账户邮箱筛选（例如 `name@example.com`）。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "成功获取工作流日志。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponse" }, "examples": { "workflowLogs": { "summary": "响应示例", "value": { "page": 1, "limit": 20, "total": 1, "has_more": false, "data": [ { "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", "workflow_run": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "version": "2025-01-16 12:00:00.000000", "status": "succeeded", "error": null, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630, "exceptions_count": 0, "triggered_from": "app-run" }, "created_from": "service-api", "created_by_role": "end_user", "created_by_account": null, "created_by_end_user": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "type": "service-api", "is_anonymous": false, "session_id": "user_workflow_123" }, "created_at": 1705407629 } ] } } } } } }, "400": { "description": "`invalid_param` : 某个查询参数无效，例如 `created_by_account` 未匹配到任何账户、`created_at__before` 或 `created_at__after` 时间戳格式错误，或 `page`、`limit`、`status` 超出有效范围。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Account not found: name@example.com" } } } } } } }, "x-mint": { "href": "/zh/api-reference/workflow-runs/list-workflow-logs", "metadata": { "title": "获取工作流日志", "sidebarTitle": "获取工作流日志" } } } }, "/form/human_input/{form_token}": { "get": { "tags": [ "人工介入" ], "summary": "获取人工介入表单", "description": "**适用于**：Chatflow、Workflow。\n\n返回暂停中的人工介入表单内容。需要 WebApp 提交方式。\n\n人工介入调用的完整流程，参见 [人工介入流程](/zh/api-reference/guides/human-input-flow)。", "operationId": "getChatflowHumanInputForm", "parameters": [ { "name": "form_token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "暂停表单的访问令牌，由流式模式下执行工作流或发送对话消息接口返回的 `human_input_required` 事件提供。" } ], "responses": { "200": { "description": "表单内容获取成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "form_content": { "type": "string", "description": "已替换工作流变量的预渲染表单正文。" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "表单输入控件类型。可用值：`paragraph`（多行文本输入）、`select`（从列表中单选）、`file`（单个文件上传）和 `file-list`（多个文件上传）。" }, "output_variable_name": { "type": "string", "description": "引用该输入提交值在工作流中使用的变量名。对应提交 `inputs` 对象中的键。" }, "default": { "type": "object", "nullable": true, "description": "`paragraph` 输入的原始默认值配置。客户端不应直接解析此字段，请使用 `resolved_default_values` 来展示默认值。其他输入类型或未配置默认值时，不包含该键。", "properties": { "type": { "type": "string", "description": "默认值来源。`constant` 表示将 `value` 作为字面字符串；`variable` 表示 `selector` 指向工作流变量。" }, "selector": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `variable` 时的变量引用路径（例如 `[\"node_id\", \"var_name\"]`）。至少包含两个元素。" }, "value": { "type": "string", "description": "当 `type` 为 `constant` 时的字面默认值。始终为字符串。" } } }, "option_source": { "type": "object", "description": "`select` 输入的选项来源。仅当 `type` 为 `select` 时出现。", "properties": { "type": { "type": "string", "enum": [ "variable", "constant" ], "description": "选项来源。`constant` 表示 `value` 直接列出选项；`variable` 表示 `selector` 指向提供选项的 `array[string]` 工作流变量。" }, "selector": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `variable` 时的变量引用路径。" }, "value": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `constant` 时的字面选项列表。" } } }, "allowed_file_types": { "type": "array", "items": { "type": "string", "enum": [ "image", "document", "audio", "video", "custom" ] }, "description": "接收人可上传的文件类别。`file` 和 `file-list` 输入会包含此字段。可用值：`image`、`document`、`audio`、`video`、`custom`。" }, "allowed_file_extensions": { "type": "array", "items": { "type": "string" }, "description": "当 `allowed_file_types` 包含 `custom` 时允许的文件扩展名。每个扩展名都需要包含前导 `.`，例如 `.md`。`file` 和 `file-list` 输入会包含此字段。" }, "allowed_file_upload_methods": { "type": "array", "items": { "type": "string", "enum": [ "local_file", "remote_url" ] }, "description": "接收人可使用的上传方式。可用值：`local_file`、`remote_url`。`file` 和 `file-list` 输入会包含此字段。" }, "number_limits": { "type": "integer", "description": "接收人可上传的最大文件数。仅 `file-list` 输入会包含此字段。" } } }, "description": "表单输入字段定义。" }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "用于在表单中展示的预渲染默认值，按输入的 `output_variable_name` 分组。仅当 `paragraph` 输入的默认值可由工作流变量解析时填充；无可解析默认值的输入为空。客户端请直接展示这些值，无需在前端再次解析 `default`。所有值均为字符串。" }, "user_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "操作按钮的标识。当接收人选择该按钮时，作为 `action` 传入 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form)。" }, "title": { "type": "string", "maxLength": 100, "description": "显示给接收人的按钮文本。" }, "button_style": { "type": "string", "description": "按钮的视觉样式。可用值：`primary`、`default`、`accent`、`ghost`。" } } }, "description": "可用的提交操作。" }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix 时间戳（秒），超过该时间后表单将不可提交。", "nullable": true } } }, "examples": { "success": { "summary": "响应示例", "value": { "form_content": "请审阅草稿，设置优先级，然后确认或提出修改。", "inputs": [ { "type": "paragraph", "output_variable_name": "feedback", "default": { "type": "constant", "selector": [], "value": "" } }, { "type": "select", "output_variable_name": "priority", "option_source": { "type": "constant", "selector": [], "value": [ "low", "medium", "high" ] } }, { "type": "file", "output_variable_name": "attachment", "allowed_file_types": [ "image", "document" ], "allowed_file_extensions": [], "allowed_file_upload_methods": [ "local_file", "remote_url" ] }, { "type": "file-list", "output_variable_name": "attachments", "allowed_file_types": [ "image", "document" ], "allowed_file_extensions": [], "allowed_file_upload_methods": [ "local_file", "remote_url" ], "number_limits": 5 } ], "resolved_default_values": { "feedback": "" }, "user_actions": [ { "id": "approve", "title": "批准", "button_style": "primary" }, { "id": "reject", "title": "请求修改", "button_style": "default" } ], "expiration_time": 1745510400 } } } } } }, "404": { "description": "`not_found`：未找到表单。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "未找到表单" } } } } } }, "412": { "description": "- `human_input_form_submitted`：表单已被提交。表单为一次性使用；无论由哪位用户提交，首个响应即生效。\n- `human_input_form_expired`：在提交到达之前表单已过期。", "content": { "application/json": { "examples": { "human_input_form_submitted": { "summary": "human_input_form_submitted", "value": { "status": 412, "code": "human_input_form_submitted", "message": "该表单已被其他用户提交，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "human_input_form_expired": { "summary": "human_input_form_expired", "value": { "status": 412, "code": "human_input_form_expired", "message": "该表单已过期，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } }, "x-mint": { "href": "/zh/api-reference/human-input/get-human-input-form", "metadata": { "title": "获取人工介入表单", "sidebarTitle": "获取人工介入表单" } } }, "post": { "tags": [ "人工介入" ], "summary": "提交人工介入表单", "description": "**适用于**：Chatflow、Workflow。\n\n向暂停中的人工介入表单提交接收人的响应。接受后工作流将恢复；可通过 [流式获取工作流事件](/zh/api-reference/workflow-runs/stream-workflow-events) 跟踪恢复后的运行。需要 WebApp 提交方式。", "operationId": "submitChatflowHumanInputForm", "parameters": [ { "name": "form_token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "暂停表单的访问令牌，由流式模式下执行工作流或发送对话消息接口返回的 `human_input_required` 事件提供。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs", "action", "user" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "按各输入的 `output_variable_name` 作为键提交的值。段落和下拉选项输入为字符串；`file` 输入为单个文件映射；`file-list` 输入为文件映射数组。\n\n文件映射为 `{transfer_method: local_file, upload_file_id, type}` 或 `{transfer_method: remote_url, url, type}`，其中 `type` 为该字段 `allowed_file_types` 中的一种。对于 `local_file`，`upload_file_id` 为 [上传文件](/zh/api-reference/files/upload-file) 返回的 `id`。\n\n在执行、上传和提交各次调用中使用一致的 `user`。" }, "action": { "type": "string", "description": "接收人选择的操作按钮 ID。必须与表单的 `user_actions` 列表（由 [获取人工介入表单](/zh/api-reference/human-input/get-human-input-form) 接口返回）中的某个 `id` 值匹配。" }, "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。Service API 与 WebApp 的用户 ID 相互独立，即使取值相同也不指向同一用户。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" } } }, "examples": { "approve": { "summary": "请求示例", "value": { "inputs": { "feedback": "可以发布", "priority": "high", "attachment": { "transfer_method": "local_file", "upload_file_id": "3c8fa1b2-7d4e-4f9a-b0c1-d2e3f4a5b6c7", "type": "image" }, "attachments": [ { "transfer_method": "local_file", "upload_file_id": "1a77f0df-c0e6-461c-987c-e72526f341ee", "type": "document" }, { "transfer_method": "remote_url", "url": "https://example.com/report.pdf", "type": "document" } ] }, "action": "approve", "user": "abc-123" } } } } } }, "responses": { "200": { "description": "表单提交成功。响应体为空对象。", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "success": { "summary": "响应示例", "value": {} } } } } }, "400": { "description": "- `bad_request`：表单接收人类型无效。\n- `invalid_form_data`：提交内容未通过表单定义的校验。", "content": { "application/json": { "examples": { "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "表单接收人类型无效" } }, "invalid_form_data": { "summary": "invalid_form_data", "value": { "status": 400, "code": "invalid_form_data", "message": "缺少必填输入：feedback" } } } } } }, "404": { "description": "`not_found`：未找到表单。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "未找到表单" } } } } } }, "412": { "description": "- `human_input_form_submitted`：表单已被提交。表单为一次性使用；无论由哪位用户提交，首个响应即生效。\n- `human_input_form_expired`：在提交到达之前表单已过期。", "content": { "application/json": { "examples": { "human_input_form_submitted": { "summary": "human_input_form_submitted", "value": { "status": 412, "code": "human_input_form_submitted", "message": "该表单已被其他用户提交，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "human_input_form_expired": { "summary": "human_input_form_expired", "value": { "status": 412, "code": "human_input_form_expired", "message": "该表单已过期，form_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } }, "x-mint": { "href": "/zh/api-reference/human-input/submit-human-input-form", "metadata": { "title": "提交人工介入表单", "sidebarTitle": "提交人工介入表单" } } } }, "/workflow/{workflow_run_id}/events": { "get": { "tags": [ "工作流运行" ], "summary": "流式获取工作流事件", "description": "**适用于**：Chatflow、Workflow。\n\n在工作流运行暂停或原始 SSE 连接断开后恢复 Server-Sent Events 流。对于已结束的运行，流仅发送单个 `workflow_finished` 事件后关闭。\n\n如需查看进行中运行的节点级状态与进度，可在调用时附带 `include_state_snapshot=true`：流会先重放各已执行节点的状态，再流式发送新事件。", "operationId": "streamWorkflowEvents", "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "要恢复事件流的工作流运行 ID，来自 [执行工作流](/zh/api-reference/workflow-runs/run-workflow) 的响应或流式事件。" }, { "name": "user", "in": "query", "required": true, "schema": { "type": "string" }, "description": "终端用户标识，由你的应用定义，需在应用内唯一。必须与发起该运行的 `user` 一致。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" }, { "name": "include_state_snapshot", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "为 `true` 时，从持久化状态快照重放，在流式发送新事件前附带已执行节点的状态摘要。" }, { "name": "continue_on_pause", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "设为 `true` 时，流会在多次 `workflow_paused` 事件之间保持打开（适用于工作流包含多个连续人工介入节点的场景）。默认在首次暂停时关闭流。" } ], "responses": { "200": { "description": "Server-Sent Events 流。每个事件以 `data: {JSON}\\n\\n` 形式送达。事件载荷结构与原始流式响应一致。", "content": { "text/event-stream": { "schema": { "type": "string", "description": "已恢复工作流运行的事件 SSE 流，格式与 [执行工作流](/zh/api-reference/workflow-runs/run-workflow)（Workflow 应用）或 [发送对话消息](/zh/api-reference/chat-messages/send-chat-message)（Chatflow 应用）相同。当恢复部分运行设置 `reasoning_format: separated` 的 LLM 节点时，本流还会携带 `reasoning_chunk` 事件。" }, "examples": { "resumedRun": { "summary": "响应示例 - 恢复运行（Workflow）", "value": "data: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"请审阅草稿。\", \"action_id\": \"approve\", \"action_text\": \"批准\", \"submitted_data\": {\"comment\": \"没问题，可以发布。\"}}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_2\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Approved, now translating.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour\"}, \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}" }, "resumedRunChatflow": { "summary": "响应示例 - 恢复运行（Chatflow）", "value": "data: {\"event\": \"human_input_form_filled\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"rendered_content\": \"请审阅草稿。\", \"action_id\": \"approve\", \"action_text\": \"批准\", \"submitted_data\": {\"comment\": \"没问题，可以发布。\"}}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"created_at\": 1705407705}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"The reviewer approved the draft.\", \"node_id\": \"node_llm_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407705, \"data\": {\"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"reasoning\": \"\", \"node_id\": \"node_llm_1\", \"is_final\": true}} data: {\"event\": \"message\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"answer\": \"Approved\", \"created_at\": 1705407706} data: {\"event\": \"node_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"ne_002\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 2, \"status\": \"succeeded\", \"elapsed_time\": 1.2, \"created_at\": 1705407705, \"finished_at\": 1705407706}} data: {\"event\": \"message_end\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"metadata\": {\"usage\": {\"total_tokens\": 42, \"latency\": 1.3}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"message_id\": \"2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b\", \"conversation_id\": \"9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7\", \"created_at\": 1705407706, \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"elapsed_time\": 2.1, \"total_tokens\": 42, \"total_steps\": 2, \"created_at\": 1705407629, \"finished_at\": 1705407706}}" } } } } }, "400": { "description": "`not_workflow_app` : Please check if your app mode matches the right API route.", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } } } } } }, "404": { "description": "`not_found` : Workflow run not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow run not found" } } } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "恢复事件流", "source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}' \\\n --header 'Authorization: Bearer {api_key}'" }, { "lang": "bash", "label": "附带状态快照", "source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}&include_state_snapshot=true' \\\n --header 'Authorization: Bearer {api_key}'" } ], "x-mint": { "href": "/zh/api-reference/workflow-runs/stream-workflow-events", "metadata": { "title": "流式获取工作流事件", "sidebarTitle": "流式获取工作流事件" } } } }, "/workflows/run": { "post": { "summary": "执行工作流", "description": "**适用于**：Workflow。\n\n运行应用已发布的工作流并返回其输出，可以是单次 `blocking` 响应，也可以是 `streaming` 的 Server-Sent Events 流。需要已发布的工作流。", "operationId": "executeWorkflowCn", "tags": [ "工作流运行" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { "streaming_example": { "summary": "请求示例 - 流式模式", "value": { "inputs": { "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", "user": "user_workflow_123" } }, "blocking_example": { "summary": "请求示例 - 阻塞模式", "value": { "inputs": { "query": "Translate this to French: Hello world" }, "response_mode": "blocking", "user": "user_workflow_456" } }, "with_file_array_variable": { "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", "transfer_method": "remote_url", "url": "https://example.com/image.jpg" } ] }, "response_mode": "blocking", "user": "user_workflow_789" } } } } } }, "responses": { "200": { "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `WorkflowBlockingResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkWorkflowEvent` 对象流。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" }, "examples": { "blockingResponse": { "summary": "响应示例 - 阻塞模式", "value": { "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": { "result": "Bonjour le monde" }, "error": null, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630 } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events (SSE) 流。按 [SSE 流式传输指南](/zh/api-reference/guides/streaming) 解析：读取 `data:` 行，根据 `event` 字段分派，忽略 `ping`（每 10 秒保持连接）。\n\n**流生命周期**：收到 `workflow_finished`、`workflow_paused` 或 `error` 事件时流关闭。错误以流内 `error` 事件的形式返回，HTTP 状态码始终为 `200`；请检查事件载荷获取详情，不要依赖状态码判断。\n\n**推理事件**：\n- `reasoning_chunk`：来自 `reasoning_format` 为 `separated` 的 LLM 节点的推理内容增量。拼接连续的 `reasoning_chunk` 事件即可还原完整推理内容；`is_final: true` 的事件标志该节点思考结束（且 `reasoning` 可能为空）。载荷位于 `data` 下，与对话应用不同，`message_id` 为 `null`，且不含 `conversation_id`。并行的 `text_chunk` 流不含 `` 标签。\n\n**人工介入事件**：\n- `human_input_required`：工作流到达人工介入节点时与 `workflow_paused` 一同触发。使用载荷中的 `form_token` 通过 [人工介入 API](/zh/api-reference/human-input/get-human-input-form) 处理表单。\n- `human_input_form_filled`：接收者提交了表单，工作流恢复执行。\n- `human_input_form_timeout`：表单超时未响应。如定义了超时回退分支，工作流将沿该分支执行。" }, "examples": { "streamingResponse": { "summary": "响应示例 - 流式模式", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" }, "humanInputPause": { "summary": "响应示例 - 人工介入暂停", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"请审阅草稿。\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"批准\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : 应用模式与 API 路由不匹配。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 工作流执行请求失败。\n- `invalid_param` : 请求参数缺失或无效，例如缺少 `user` 或工作流未发布。", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "429": { "description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 此工作空间在 Dify Cloud 的工作流执行配额已达上限。", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal Server Error." } } } } } } }, "x-mint": { "href": "/zh/api-reference/workflow-runs/run-workflow", "metadata": { "title": "执行工作流", "sidebarTitle": "执行工作流" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -N --request POST \\\n --url 'https://{api_base_url}/workflows/run' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --data '{\"inputs\": {\"query\": \"Summarize this text: The quick brown fox jumps over the lazy dog.\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'" } ] } }, "/workflows/{workflow_id}/run": { "post": { "summary": "按 ID 执行工作流", "description": "**适用于**：Workflow。\n\n运行指定的已发布工作流版本，由路径中的 `workflow_id` 指定。请求体、响应和流式行为与 [执行工作流](/zh/api-reference/workflow-runs/run-workflow) 相同，仅执行的版本不同。", "operationId": "runWorkflowByIdZh", "tags": [ "工作流运行" ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "description": "要运行的已发布工作流版本。在 [执行工作流](/zh/api-reference/workflow-runs/run-workflow) 响应和 [获取工作流运行详情](/zh/api-reference/workflow-runs/get-workflow-run-detail) 的 `workflow_id` 字段中返回。必须指向已发布版本；草稿版本 ID 会返回 `bad_request`。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { "example": { "summary": "请求示例", "value": { "inputs": { "query": "Summarize this article" }, "response_mode": "blocking", "user": "user_workflow_123" } } } } } }, "responses": { "200": { "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `WorkflowBlockingResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkWorkflowEvent` 对象流。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowBlockingResponse" }, "examples": { "blockingResponse": { "summary": "响应示例 - 阻塞模式", "value": { "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": { "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": { "result": "Article summary here" }, "error": null, "elapsed_time": 2.45, "total_tokens": 280, "total_steps": 4, "created_at": 1705407629, "finished_at": 1705407631 } } } } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events (SSE) 流。按 [SSE 流式传输指南](/zh/api-reference/guides/streaming) 解析：读取 `data:` 行，根据 `event` 字段分派，忽略 `ping`（每 10 秒保持连接）。\n\n**流生命周期**：收到 `workflow_finished`、`workflow_paused` 或 `error` 事件时流关闭。错误以流内 `error` 事件的形式返回，HTTP 状态码始终为 `200`；请检查事件载荷获取详情，不要依赖状态码判断。\n\n**推理事件**：\n- `reasoning_chunk`：来自 `reasoning_format` 为 `separated` 的 LLM 节点的推理内容增量。拼接连续的 `reasoning_chunk` 事件即可还原完整推理内容；`is_final: true` 的事件标志该节点思考结束（且 `reasoning` 可能为空）。载荷位于 `data` 下，与对话应用不同，`message_id` 为 `null`，且不含 `conversation_id`。并行的 `text_chunk` 流不含 `` 标签。\n\n**人工介入事件**：\n- `human_input_required`：工作流到达人工介入节点时与 `workflow_paused` 一同触发。使用载荷中的 `form_token` 通过 [人工介入 API](/zh/api-reference/human-input/get-human-input-form) 处理表单。\n- `human_input_form_filled`：接收者提交了表单，工作流恢复执行。\n- `human_input_form_timeout`：表单超时未响应。如定义了超时回退分支，工作流将沿该分支执行。" }, "examples": { "streamingResponse": { "summary": "响应示例 - 流式模式", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"Let me translate that.\", \"node_id\": \"node_1\", \"is_final\": false}} data: {\"event\": \"reasoning_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"reasoning\": \"\", \"node_id\": \"node_1\", \"is_final\": true}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" }, "humanInputPause": { "summary": "响应示例 - 人工介入暂停", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"draft\": \"Hello\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"human_input_required\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"form_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\", \"form_token\": \"tok_abc123\", \"node_id\": \"approval_node\", \"node_title\": \"Approval\", \"form_content\": \"请审阅草稿。\", \"inputs\": [{\"type\": \"paragraph\", \"output_variable_name\": \"comment\", \"default\": null}], \"actions\": [{\"id\": \"approve\", \"title\": \"批准\", \"button_style\": \"primary\"}], \"display_in_ui\": false, \"resolved_default_values\": {\"comment\": \"\"}, \"expiration_time\": 1705494029}} data: {\"event\": \"workflow_paused\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"status\": \"paused\", \"created_at\": 1705407629, \"elapsed_time\": 0.5}}" } } } } }, "400": { "description": "- `not_workflow_app` : 应用模式与 API 路由不匹配。\n- `bad_request` : 工作流为草稿或 ID 格式无效。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 工作流执行请求失败。\n- `invalid_param` : 请求参数缺失或无效，例如缺少 `user`。", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "bad_request": { "summary": "bad_request", "value": { "status": 400, "code": "bad_request", "message": "Cannot use draft workflow version. Workflow ID: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345. Please use a published workflow version or leave workflow_id empty." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "403": { "description": "`workflow_version_execution_not_allowed` : Dify Cloud Sandbox 套餐无法执行指定的工作流版本。", "content": { "application/json": { "examples": { "workflow_version_execution_not_allowed": { "summary": "workflow_version_execution_not_allowed", "value": { "status": 403, "code": "workflow_version_execution_not_allowed", "message": "Workflow version execution is not available on your current plan. Please upgrade to a paid plan." } } } } } }, "404": { "description": "`not_found` : 工作流 not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Workflow not found with id: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345" } } } } } }, "429": { "description": "- `too_many_requests` : 该应用的并发请求过多。\n- `rate_limit_error` : 此工作空间在 Dify Cloud 的工作流执行配额已达上限。", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later." } }, "rate_limit_error": { "summary": "rate_limit_error", "value": { "status": 429, "code": "rate_limit_error", "message": "Rate Limit Error" } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "Internal Server Error." } } } } } } }, "x-mint": { "href": "/zh/api-reference/workflow-runs/run-workflow-by-id", "metadata": { "title": "按 ID 执行工作流", "sidebarTitle": "按 ID 执行工作流" } } } }, "/workflows/tasks/{task_id}/stop": { "post": { "summary": "停止工作流任务", "description": "**适用于**：Workflow。\n\n停止正在运行的工作流任务。仅在 `streaming` 模式下支持。", "operationId": "stopWorkflowTaskGenerationCn", "tags": [ "工作流运行" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "任务 ID，来自 [执行工作流](/zh/api-reference/workflow-runs/run-workflow) 的流式事件。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。无需与发起该运行的 `user` 一致；停止对该任务始终生效。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" } } }, "examples": { "example": { "summary": "请求示例", "value": { "user": "user_workflow_123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "- `not_workflow_app` : 应用模式与 API 路由不匹配。\n- `invalid_param` : 请求参数缺失或无效，例如缺少 `user`。", "content": { "application/json": { "examples": { "not_workflow_app": { "summary": "not_workflow_app", "value": { "status": 400, "code": "not_workflow_app", "message": "Please check if your app mode matches the right API route." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } } }, "x-mint": { "href": "/zh/api-reference/workflow-runs/stop-workflow-task", "metadata": { "title": "停止工作流任务", "sidebarTitle": "停止工作流任务" } } } }, "/completion-messages": { "post": { "summary": "发送消息", "description": "**适用于**：文本生成应用。\n\n向文本生成型应用发送请求并返回生成的文本。", "operationId": "createCompletionMessage", "tags": [ "文本生成消息" ], "requestBody": { "description": "创建文本生成消息的请求体。", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionRequest" }, "examples": { "streaming_example": { "summary": "请求示例 - 流式模式", "value": { "inputs": { "city": "San Francisco" }, "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", "user": "abc-123", "files": [ { "type": "image", "transfer_method": "remote_url", "url": "https://cloud.dify.ai/logo/logo-site.png" } ] } }, "blocking_example": { "summary": "请求示例 - 阻塞模式", "value": { "inputs": { "city": "New York" }, "query": "Summarize the following text: ...", "response_mode": "blocking", "user": "def-456" } } } } } }, "responses": { "200": { "description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `CompletionResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `ChunkCompletionEvent` 对象流。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionResponse" }, "examples": { "blockingResponse": { "summary": "响应示例 - 阻塞模式", "value": { "event": "message", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "mode": "completion", "answer": "Hello World!...", "metadata": { "usage": { "prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 128, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002560", "total_tokens": 1161, "total_price": "0.0012890", "currency": "USD", "latency": 0.7682376249867957 } }, "created_at": 1705407629 } } } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events (SSE) 流。按 [SSE 流式传输指南](/zh/api-reference/guides/streaming) 解析：读取 `data:` 行，根据 `event` 字段分派，忽略 `ping`（每 10 秒保持连接）。事件结构参见 `ChunkCompletionEvent`。\n\n**流生命周期**：回复以 `message` 片段流式返回，并以 `message_end` 结束。`error` 事件会提前结束流；此时 HTTP 状态码仍为 `200`，请检查事件载荷获取详情。" }, "examples": { "streamingResponse": { "summary": "响应示例 - 流式模式", "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n" } } } } }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。\n- `provider_quota_exceeded` : 模型供应商配额已用尽。\n- `model_currently_not_support` : 当前模型不可用。\n- `completion_request_error` : 文本生成失败。\n- `invalid_param` : 缺少必填的 `user` 字段。", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } }, "429": { "description": "`too_many_requests` : 该应用的并发请求过多。", "content": { "application/json": { "examples": { "too_many_requests": { "summary": "too_many_requests", "value": { "status": 429, "code": "too_many_requests", "message": "Too many requests. Please try again later. The current maximum concurrent requests allowed for 5b3d4f2a-1c9e-4a7b-8f6d-2e0c9a1b3d4f is 10." } } } } } }, "500": { "description": "`internal_server_error` : 内部服务器错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application." } } } } } } }, "x-mint": { "href": "/zh/api-reference/completion-messages/send-completion-message", "metadata": { "title": "发送消息", "sidebarTitle": "发送消息" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/completion-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"inputs\": {\"city\": \"San Francisco\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'" } ] } }, "/completion-messages/{task_id}/stop": { "post": { "summary": "停止响应", "description": "**适用于**：文本生成应用。\n\n停止文本生成消息生成任务。仅在 `streaming` 模式下支持。", "operationId": "stopCompletionGeneration", "tags": [ "文本生成消息" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "任务 ID，来自 [发送消息](/zh/api-reference/completion-messages/send-completion-message) 的流式事件。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。必须与发送原始消息时的 `user` 一致；不一致时停止不会生效，但仍返回成功。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" } } }, "examples": { "example": { "summary": "请求示例", "value": { "user": "abc-123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `invalid_param` : 缺少必填的 `user` 字段。", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Arg user must be provided." } } } } } } }, "x-mint": { "href": "/zh/api-reference/completion-messages/stop-completion-message-generation", "metadata": { "title": "停止响应", "sidebarTitle": "停止响应" } } } }, "/datasets": { "post": { "tags": [ "知识库" ], "summary": "创建空知识库", "description": "创建一个空知识库。之后用 [从文本创建文档](/zh/api-reference/documents/create-document-by-text) 或 [从文件创建文档](/zh/api-reference/documents/create-document-by-file) 向其中添加文档。", "operationId": "createDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "知识库名称。" }, "description": { "type": "string", "maxLength": 400, "default": "", "description": "知识库描述。" }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ], "nullable": true, "description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。" }, "permission": { "type": "string", "enum": [ "only_me", "all_team_members", "partial_members" ], "default": "only_me", "description": "控制谁可以访问此知识库。`only_me` 仅限创建者，`all_team_members` 授权整个工作区访问，`partial_members` 授权指定成员访问。" }, "provider": { "type": "string", "enum": [ "vendor", "external" ], "default": "vendor", "description": "`vendor` 为内部知识库，`external` 为外部知识库。" }, "embedding_model": { "type": "string", "description": "嵌入模型名称。使用 [获取可用模型](/zh/api-reference/models/get-available-models) 中 `model_type=text-embedding` 返回的 `model` 字段值。" }, "embedding_model_provider": { "type": "string", "description": "嵌入模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如 `langgenius/openai/openai`）。`openai` 这类简写会展开为 `langgenius//`，仅对 langgenius 发布的插件有效。\n\n有效取值从 [获取可用模型](/zh/api-reference/models/get-available-models) 中 `model_type=text-embedding` 返回的 `provider` 字段获取。" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。" }, "external_knowledge_api_id": { "type": "string", "description": "外部知识库 API 连接的 ID。" }, "external_knowledge_id": { "type": "string", "description": "外部知识库的 ID。" }, "summary_index_setting": { "type": "object", "nullable": true, "description": "摘要索引配置。", "properties": { "enable": { "type": "boolean", "description": "是否启用摘要索引。" }, "model_name": { "type": "string", "description": "用于生成摘要的模型名称。" }, "model_provider_name": { "type": "string", "description": "摘要生成模型的供应商。" }, "summary_prompt": { "type": "string", "description": "用于摘要生成的自定义提示词模板。" } } } } } } } }, "responses": { "200": { "description": "知识库创建成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" }, "examples": { "success": { "summary": "响应示例", "value": { "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "name": "Product Documentation", "description": "产品 API 技术文档", "provider": "vendor", "permission": "only_me", "data_source_type": null, "indexing_technique": "high_quality", "app_count": 0, "document_count": 0, "word_count": 0, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "author_name": "admin", "created_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "updated_at": 1741267200, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "embedding_available": true, "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "", "reranking_model_name": "" }, "weights": null, "top_k": 3, "score_threshold_enabled": false, "score_threshold": null }, "tags": [], "doc_form": "text_model", "external_knowledge_info": null, "external_retrieval_model": null, "doc_metadata": [], "built_in_field_enabled": true, "pipeline_id": null, "runtime_mode": null, "chunk_structure": null, "icon_info": null, "summary_index_setting": null, "is_published": false, "total_documents": 0, "total_available_documents": 0, "enable_api": true, "is_multimodal": false, "maintainer": "admin" } } } } } }, "400": { "description": "`invalid_param` : 指定的嵌入模型或重排序模型未配置或不可用。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } } } } } }, "403": { "description": "`forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "409": { "description": "`dataset_name_duplicate` : 已存在同名知识库。", "content": { "application/json": { "examples": { "dataset_name_duplicate": { "summary": "dataset_name_duplicate", "value": { "status": 409, "code": "dataset_name_duplicate", "message": "The dataset name already exists. Please modify your dataset name." } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-bases/create-an-empty-knowledge-base", "metadata": { "title": "创建空知识库", "sidebarTitle": "创建空知识库" } } }, "get": { "tags": [ "知识库" ], "summary": "获取知识库列表", "description": "返回知识库的分页列表，可按关键词或标签筛选。", "operationId": "listDatasets", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "页码。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 }, "description": "每页条目数。" }, { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "按名称筛选的搜索关键词。" }, { "name": "include_all", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "是否包含所有知识库，无论权限如何。" }, { "name": "tag_ids", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "用于筛选的标签 ID。标签 ID 从 [获取知识库标签列表](/zh/api-reference/tags/list-knowledge-tags) 获取。" } ], "responses": { "200": { "description": "知识库列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "知识库对象数组。", "items": { "$ref": "#/components/schemas/Dataset" } }, "has_more": { "type": "boolean", "description": "下一页是否还有更多项目。" }, "limit": { "type": "integer", "description": "每页条目数。" }, "total": { "type": "integer", "description": "匹配条目的总数。" }, "page": { "type": "integer", "description": "当前页码。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": [ { "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "name": "Product Documentation", "description": "产品 API 技术文档", "provider": "vendor", "permission": "only_me", "data_source_type": null, "indexing_technique": "high_quality", "app_count": 0, "document_count": 0, "word_count": 0, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "author_name": "admin", "created_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "updated_at": 1741267200, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "embedding_available": true, "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "", "reranking_model_name": "" }, "weights": null, "top_k": 3, "score_threshold_enabled": false, "score_threshold": null }, "tags": [], "doc_form": "text_model", "external_knowledge_info": null, "external_retrieval_model": null, "doc_metadata": [], "built_in_field_enabled": true, "pipeline_id": null, "runtime_mode": null, "chunk_structure": null, "icon_info": null, "summary_index_setting": null, "is_published": false, "total_documents": 0, "total_available_documents": 0, "enable_api": true, "is_multimodal": false, "maintainer": "admin" } ], "has_more": false, "limit": 20, "total": 1, "page": 1 } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-bases/list-knowledge-bases", "metadata": { "title": "获取知识库列表", "sidebarTitle": "获取知识库列表" } } } }, "/datasets/{dataset_id}": { "get": { "tags": [ "知识库" ], "summary": "获取知识库详情", "description": "返回知识库的详细信息，包括嵌入模型、检索配置和文档统计信息。", "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "responses": { "200": { "description": "知识库详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" }, "examples": { "success": { "summary": "响应示例", "value": { "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "name": "Product Documentation", "description": "产品 API 技术文档", "provider": "vendor", "permission": "only_me", "data_source_type": null, "indexing_technique": "high_quality", "app_count": 0, "document_count": 0, "word_count": 0, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "author_name": "admin", "created_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "updated_at": 1741267200, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "embedding_available": true, "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "", "reranking_model_name": "" }, "weights": null, "top_k": 3, "score_threshold_enabled": false, "score_threshold": null }, "tags": [], "doc_form": "text_model", "external_knowledge_info": null, "external_retrieval_model": null, "doc_metadata": [], "built_in_field_enabled": true, "pipeline_id": null, "runtime_mode": null, "chunk_structure": null, "icon_info": null, "summary_index_setting": null, "is_published": false, "total_documents": 0, "total_available_documents": 0, "enable_api": true, "is_multimodal": false, "maintainer": "admin" } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 未找到与 `dataset_id` 匹配的知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-bases/get-knowledge-base", "metadata": { "title": "获取知识库详情", "sidebarTitle": "获取知识库详情" } } }, "patch": { "tags": [ "知识库" ], "summary": "更新知识库", "description": "更新知识库。仅更改请求体中包含的字段。", "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "知识库名称。" }, "description": { "type": "string", "maxLength": 400, "description": "知识库描述。" }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ], "nullable": true, "description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。" }, "permission": { "type": "string", "enum": [ "only_me", "all_team_members", "partial_members" ], "description": "控制谁可以访问此知识库。`only_me` 仅限创建者，`all_team_members` 授权整个工作区访问，`partial_members` 授权指定成员访问。" }, "embedding_model": { "type": "string", "description": "嵌入模型名称。使用 [获取可用模型](/zh/api-reference/models/get-available-models) 中 `model_type=text-embedding` 返回的 `model` 字段值。" }, "embedding_model_provider": { "type": "string", "description": "嵌入模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如 `langgenius/openai/openai`）。`openai` 这类简写会展开为 `langgenius//`，仅对 langgenius 发布的插件有效。\n\n有效取值从 [获取可用模型](/zh/api-reference/models/get-available-models) 中 `model_type=text-embedding` 返回的 `provider` 字段获取。" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。" }, "partial_member_list": { "type": "array", "description": "当 `permission` 为 `partial_members` 时有访问权限的团队成员列表。", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "要授予访问权限的团队成员 ID。" } } } }, "external_retrieval_model": { "type": "object", "description": "外部知识库的检索设置。", "properties": { "top_k": { "type": "integer", "description": "返回的最大结果数。" }, "score_threshold": { "type": "number", "description": "用于过滤结果的最低相关性分数阈值。" }, "score_threshold_enabled": { "type": "boolean", "description": "是否启用分数阈值过滤。" } } }, "external_knowledge_id": { "type": "string", "description": "外部知识库的 ID。" }, "external_knowledge_api_id": { "type": "string", "description": "外部知识库 API 连接的 ID。" } } } } } }, "responses": { "200": { "description": "知识库更新成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" }, "examples": { "success": { "summary": "响应示例", "value": { "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", "name": "Product Documentation", "description": "产品 API 技术文档", "provider": "vendor", "permission": "only_me", "data_source_type": null, "indexing_technique": "high_quality", "app_count": 0, "document_count": 0, "word_count": 0, "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "author_name": "admin", "created_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "updated_at": 1741267200, "embedding_model": "text-embedding-3-small", "embedding_model_provider": "langgenius/openai/openai", "embedding_available": true, "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": false, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "", "reranking_model_name": "" }, "weights": null, "top_k": 3, "score_threshold_enabled": false, "score_threshold": null }, "tags": [], "doc_form": "text_model", "external_knowledge_info": null, "external_retrieval_model": null, "doc_metadata": [], "built_in_field_enabled": true, "pipeline_id": null, "runtime_mode": null, "chunk_structure": null, "icon_info": null, "summary_index_setting": null, "is_published": false, "total_documents": 0, "total_available_documents": 0, "enable_api": true, "is_multimodal": false, "maintainer": "admin", "partial_member_list": [] } } } } } }, "400": { "description": "`invalid_param` : 指定的嵌入模型或重排序模型未配置或不可用。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到与 `dataset_id` 匹配的知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-bases/update-knowledge-base", "metadata": { "title": "更新知识库", "sidebarTitle": "更新知识库" } } }, "delete": { "tags": [ "知识库" ], "summary": "删除知识库", "description": "永久删除知识库及其所有文档。", "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "responses": { "204": { "description": "知识库删除成功。" }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到与 `dataset_id` 匹配的知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-bases/delete-knowledge-base", "metadata": { "title": "删除知识库", "sidebarTitle": "删除知识库" } } } }, "/datasets/{dataset_id}/document/create-by-text": { "post": { "tags": [ "文档" ], "summary": "从文本创建文档", "description": "在知识库中通过纯文本创建文档。索引异步进行；使用返回的 `batch` ID 通过 [获取文档嵌入状态（进度）](/zh/api-reference/documents/get-document-indexing-status) 跟踪。", "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "text" ], "properties": { "name": { "type": "string", "description": "文档名称。" }, "text": { "type": "string", "description": "文档文本内容。" }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ], "description": "向知识库添加首个文档时必填。后续文档如果省略此字段，将继承知识库的索引方式。`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。" }, "doc_form": { "type": "string", "enum": [ "text_model", "hierarchical_model", "qa_model" ], "default": "text_model", "description": "`text_model` 为标准文本分段，`hierarchical_model` 为父子分段结构，`qa_model` 为问答对提取。" }, "doc_language": { "type": "string", "default": "English", "description": "用于处理优化的文档语言。" }, "process_rule": { "type": "object", "description": "分块处理规则。", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "automatic", "custom", "hierarchical" ], "description": "`automatic` 使用内置规则，`custom` 允许手动配置，`hierarchical` 启用父子分段结构（配合 `doc_form: hierarchical_model` 使用）。" }, "rules": { "type": "object", "properties": { "pre_processing_rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "remove_stopwords", "remove_extra_spaces", "remove_urls_emails" ], "description": "规则标识符。" }, "enabled": { "type": "boolean", "description": "该预处理规则是否启用。" } } } }, "segmentation": { "type": "object", "properties": { "separator": { "type": "string", "default": "\n", "description": "用于拆分文本的自定义分隔符。" }, "max_tokens": { "type": "integer", "description": "每个分段的最大令牌数。" }, "chunk_overlap": { "type": "integer", "default": 0, "description": "分段之间的令牌重叠数。" } } } } } } }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "控制查询此知识库时如何搜索和排序分段。" }, "embedding_model": { "type": "string", "description": "嵌入模型名称。使用 [获取可用模型](/zh/api-reference/models/get-available-models) 中 `model_type=text-embedding` 返回的 `model` 字段值。" }, "embedding_model_provider": { "type": "string", "description": "嵌入模型供应商。使用 [获取可用模型](/zh/api-reference/models/get-available-models) 中 `model_type=text-embedding` 返回的 `provider` 字段值。" }, "original_document_id": { "type": "string", "description": "用于版本控制的原始文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" } } } } } }, "responses": { "200": { "description": "文档创建成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "用于跟踪索引进度的批次 ID。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 0, "indexing_status": "indexing", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "indexing", "word_count": 0, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "400": { "description": "- `provider_not_initialize` : 工作空间未配置模型供应商凭据。\n- `invalid_param` : 添加首个文档时必须提供 `indexing_technique`，或 `doc_form` 无效。", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "invalid_param_indexing": { "summary": "invalid_param (indexing_technique)", "value": { "status": 400, "code": "invalid_param", "message": "indexing_technique is required." } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 文档数量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (documents limit)", "value": { "status": 403, "code": "forbidden", "message": "The number of documents has reached the limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/create-document-by-text", "metadata": { "title": "从文本创建文档", "sidebarTitle": "从文本创建文档" } } } }, "/datasets/{dataset_id}/document/create-by-file": { "post": { "tags": [ "文档" ], "summary": "从文件创建文档", "description": "在知识库中通过上传文件创建文档。支持 PDF、TXT、DOCX 等常见格式。索引异步进行；使用返回的 `batch` ID 通过 [获取文档嵌入状态（进度）](/zh/api-reference/documents/get-document-indexing-status) 跟踪。", "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "要上传的文件。" }, "data": { "type": "string", "description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/zh/api-reference/documents/create-document-by-text) 相同的字段（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。", "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } } } }, "responses": { "200": { "description": "文档创建成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "用于跟踪索引进度的批次 ID。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 0, "indexing_status": "indexing", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "indexing", "word_count": 0, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "400": { "description": "- `no_file_uploaded` : 请求中未提供文件。\n- `too_many_files` : 每次请求仅允许一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。\n- `provider_not_initialize` : 工作空间未配置模型供应商凭据。\n- `invalid_param` : 该知识库为外部知识库、缺少 `indexing_technique`，或缺少 `process_rule`。", "content": { "application/json": { "examples": { "no_file_uploaded": { "summary": "no_file_uploaded", "value": { "status": 400, "code": "no_file_uploaded", "message": "Please upload your file." } }, "too_many_files": { "summary": "too_many_files", "value": { "status": 400, "code": "too_many_files", "message": "Only one file is allowed." } }, "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "status": 400, "code": "filename_not_exists_error", "message": "The specified filename does not exist." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "invalid_param_external": { "summary": "invalid_param (external)", "value": { "status": 400, "code": "invalid_param", "message": "External datasets are not supported." } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 文档数量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (documents limit)", "value": { "status": 403, "code": "forbidden", "message": "The number of documents has reached the limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/create-document-by-file", "metadata": { "title": "从文件创建文档", "sidebarTitle": "从文件创建文档" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/document/create-by-file' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'" } ] } }, "/datasets/{dataset_id}/documents": { "get": { "tags": [ "文档" ], "summary": "获取知识库的文档列表", "description": "返回知识库中文档的分页列表。", "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "页码。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 }, "description": "每页的项目数量。服务器上限为 `100`。" }, { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "按文档名称筛选的搜索关键词。" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queuing", "indexing", "paused", "error", "available", "disabled", "archived" ] }, "description": "按显示状态筛选。" } ], "responses": { "200": { "description": "文档列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "文档对象数组。", "items": { "$ref": "#/components/schemas/Document" } }, "has_more": { "type": "boolean", "description": "下一页是否还有更多项目。" }, "limit": { "type": "integer", "description": "每页条目数。" }, "total": { "type": "integer", "description": "匹配条目的总数。" }, "page": { "type": "integer", "description": "当前页码。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": [ { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "word_count": 350, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false } ], "has_more": false, "limit": 20, "total": 1, "page": 1 } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 知识库未找到。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/list-documents", "metadata": { "title": "获取知识库的文档列表", "sidebarTitle": "获取知识库的文档列表" } } } }, "/datasets/{dataset_id}/documents/{document_id}": { "get": { "tags": [ "文档" ], "summary": "获取文档详情", "description": "返回单个文档的详细信息。", "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" }, { "name": "metadata", "in": "query", "schema": { "type": "string", "enum": [ "all", "only", "without" ], "default": "all" }, "description": "`all` 返回所有字段（包括元数据）。`only` 仅返回 `id`、`doc_type` 和 `doc_metadata`。`without` 返回除 `doc_metadata` 外的所有字段。" } ], "responses": { "200": { "description": "文档详情。返回的字段取决于 `metadata` 查询参数。", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "文档标识符。" }, "position": { "type": "integer", "description": "在知识库中的位置索引。" }, "data_source_type": { "type": "string", "description": "文档的上传方式。文件上传为 `upload_file`，Notion 导入为 `notion_import`。" }, "data_source_info": { "type": "object", "description": "数据源详情。文件上传时，此详情接口在 `upload_file` 下返回完整的文件对象，而列表接口仅返回 `upload_file_id`。", "properties": { "upload_file": { "type": "object", "description": "上传文件的详情。当 `data_source_type` 为 `upload_file` 时返回。", "properties": { "id": { "type": "string", "description": "文件标识符。" }, "name": { "type": "string", "description": "原始文件名。" }, "size": { "type": "integer", "description": "文件大小（字节）。" }, "extension": { "type": "string", "description": "文件扩展名。" }, "mime_type": { "type": "string", "description": "文件的 MIME 类型。" }, "created_by": { "type": "string", "description": "上传该文件的用户 ID。" }, "created_at": { "type": "integer", "description": "文件上传的 Unix 时间戳。" } } } } }, "dataset_process_rule_id": { "type": "string", "description": "应用于该文档的处理规则 ID。" }, "dataset_process_rule": { "type": "object", "description": "知识库级别的处理规则配置。" }, "document_process_rule": { "type": "object", "description": "文档级别的处理规则配置。" }, "name": { "type": "string", "description": "文档名称。" }, "created_from": { "type": "string", "description": "文档来源。通过 API 创建时为 `api`，通过 UI 创建时为 `web`。" }, "created_by": { "type": "string", "description": "创建该文档的用户 ID。" }, "created_at": { "type": "number", "description": "文档创建的 Unix 时间戳。" }, "tokens": { "type": "integer", "description": "文档中的令牌数。" }, "indexing_status": { "type": "string", "description": "当前索引状态，例如 `waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、`error`、`paused`。" }, "error": { "type": "string", "nullable": true, "description": "索引失败时的错误消息，否则为 `null`。" }, "enabled": { "type": "boolean", "description": "该文档是否启用检索。" }, "disabled_at": { "type": "number", "nullable": true, "description": "文档被禁用的 Unix 时间戳，启用时为 `null`。" }, "disabled_by": { "type": "string", "nullable": true, "description": "禁用该文档的用户 ID，启用时为 `null`。" }, "archived": { "type": "boolean", "description": "文档是否已归档。" }, "display_status": { "type": "string", "description": "适合 UI 显示的索引状态。" }, "hit_count": { "type": "integer", "description": "该文档被检索的次数。" }, "doc_form": { "type": "string", "description": "文档分块模式。`text_model` 表示标准文本，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对。" }, "doc_language": { "type": "string", "description": "文档内容的语言。" }, "doc_type": { "type": "string", "nullable": true, "description": "文档类型分类，未设置时为 `null`。" }, "doc_metadata": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "元数据字段标识符。" }, "name": { "type": "string", "description": "元数据字段名称。" }, "type": { "type": "string", "description": "元数据字段类型。" }, "value": { "type": "string", "description": "此文档的元数据字段值。" } } }, "description": "此文档的自定义元数据键值对。" }, "completed_at": { "type": "number", "nullable": true, "description": "处理完成的 Unix 时间戳，尚未完成时为 `null`。" }, "updated_at": { "type": "number", "nullable": true, "description": "最后更新的 Unix 时间戳，从未更新时为 `null`。" }, "indexing_latency": { "type": "number", "nullable": true, "description": "索引耗时（秒），未完成时为 `null`。" }, "segment_count": { "type": "integer", "description": "文档中的分段数。" }, "average_segment_length": { "type": "number", "description": "分段的平均字符长度。" }, "summary_index_status": { "type": "string", "nullable": true, "description": "摘要索引的状态，未启用摘要索引时为 `null`。" }, "need_summary": { "type": "boolean", "description": "该文档是否需要生成摘要。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "dataset_process_rule": { "id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "mode": "custom" }, "document_process_rule": { "mode": "custom", "rules": { "pre_processing_rules": [], "segmentation": { "separator": "###", "max_tokens": 500, "chunk_overlap": 50 } } }, "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "hit_count": 0, "doc_form": "text_model", "doc_language": "English", "doc_type": null, "doc_metadata": [], "completed_at": 1741267260, "updated_at": 1741267260, "indexing_latency": 60.0, "segment_count": 5, "average_segment_length": 70.0, "summary_index_status": null, "need_summary": false } } } } } }, "400": { "description": "`invalid_metadata` : `metadata` 查询参数的值无效（必须为 `all`、`only` 或 `without`）。", "content": { "application/json": { "examples": { "invalid_metadata": { "summary": "invalid_metadata", "value": { "status": 400, "code": "invalid_metadata", "message": "Invalid metadata value: only" } } } } } }, "403": { "description": "- `forbidden` : 你没有访问此文档的权限。\n- `forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (no permission)", "value": { "status": 403, "code": "forbidden", "message": "No permission." } }, "forbidden_2": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 未找到文档。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/get-document", "metadata": { "title": "获取文档详情", "sidebarTitle": "获取文档详情" } } }, "delete": { "tags": [ "文档" ], "summary": "删除文档", "description": "从知识库中永久删除文档及其所有分段。", "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" } ], "responses": { "204": { "description": "Success." }, "403": { "description": "- `archived_document_immutable` : 已归档的文档不可编辑。\n- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "archived_document_immutable": { "summary": "archived_document_immutable", "value": { "status": 403, "code": "archived_document_immutable", "message": "The archived document is not editable." } }, "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 文档不存在。 知识库本身不存在时，也会返回 \"Dataset not found.\"。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document Not Exists." } }, "not_found_2": { "summary": "not_found_2", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/delete-document", "metadata": { "title": "删除文档", "sidebarTitle": "删除文档" } } }, "patch": { "tags": [ "文档" ], "summary": "更新文档", "description": "通过上传新文件更新文档，然后重新索引。这是基于文件更新文档的规范端点。使用返回的 `batch` ID 通过 [获取文档嵌入状态（进度）](/zh/api-reference/documents/get-document-indexing-status) 跟踪进度。", "operationId": "updateDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "要上传的文件。" }, "data": { "type": "string", "description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/zh/api-reference/documents/create-document-by-text) 相同的字段（`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。", "example": "{\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } } } }, "responses": { "200": { "description": "文档更新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "用于跟踪索引进度的批次 ID。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "word_count": 350, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "400": { "description": "- `too_many_files` : 每次请求仅允许一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。\n- `provider_not_initialize` : 工作空间未配置模型供应商凭据。\n- `invalid_param` : 文档不可用，无法更新（仅可更新处于可用状态的文档）。", "content": { "application/json": { "examples": { "too_many_files": { "summary": "too_many_files", "value": { "status": 400, "code": "too_many_files", "message": "Only one file is allowed." } }, "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "status": 400, "code": "filename_not_exists_error", "message": "The specified filename does not exist." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "invalid_param_not_available": { "summary": "invalid_param (not available)", "value": { "status": 400, "code": "invalid_param", "message": "Document is not available" } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } }, "413": { "description": "`file_too_large` : 上传的文件超出最大大小限制。", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "File size exceeded." } } } } } }, "415": { "description": "`unsupported_file_type` : 上传文件的类型不受支持。", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/update-document", "metadata": { "title": "更新文档", "sidebarTitle": "更新文档" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request PATCH \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/documents/{document_id}' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'" } ] } }, "/datasets/{dataset_id}/documents/{document_id}/download": { "get": { "tags": [ "文档" ], "summary": "下载文档", "description": "返回用于下载文档原始上传文件的签名 URL。", "operationId": "downloadDocumentZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" } ], "responses": { "200": { "description": "下载 URL 生成成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "用于下载原始上传文件的签名 URL。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600" } } } } } }, "403": { "description": "- `forbidden` : 你没有访问此文档的权限。\n- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (no permission)", "value": { "status": 403, "code": "forbidden", "message": "No permission." } }, "forbidden_2": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到文档。 存储文件缺失时也会返回 \"Uploaded file not found.\"；非文件类文档则返回 \"Document does not have an uploaded file to download.\"。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_2": { "summary": "not_found_2", "value": { "status": 404, "code": "not_found", "message": "Uploaded file not found." } }, "not_found_3": { "summary": "not_found_3", "value": { "status": 404, "code": "not_found", "message": "Document does not have an uploaded file to download." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/download-document", "metadata": { "title": "下载文档", "sidebarTitle": "下载文档" } } } }, "/datasets/{dataset_id}/documents/{batch}/indexing-status": { "get": { "tags": [ "文档" ], "summary": "获取文档嵌入状态（进度）", "description": "返回批次中每个文档的索引进度：当前阶段和分段完成计数。轮询直到每个 `indexing_status` 变为 `completed` 或 `error`。状态按 `waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed` 推进。", "operationId": "getDocumentIndexingStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "batch", "in": "path", "required": true, "schema": { "type": "string" }, "description": "创建或更新文档时返回的批次 ID。" } ], "responses": { "200": { "description": "批次中文档的索引状态。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "文档标识符。" }, "indexing_status": { "type": "string", "description": "当前索引状态：`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed` 或 `error`。" }, "processing_started_at": { "type": "number", "nullable": true, "description": "处理开始的 Unix 时间戳。" }, "parsing_completed_at": { "type": "number", "nullable": true, "description": "解析完成的 Unix 时间戳。" }, "cleaning_completed_at": { "type": "number", "nullable": true, "description": "清洗完成的 Unix 时间戳。" }, "splitting_completed_at": { "type": "number", "nullable": true, "description": "拆分完成的 Unix 时间戳。" }, "completed_at": { "type": "number", "nullable": true, "description": "索引完成的 Unix 时间戳。" }, "paused_at": { "type": "number", "nullable": true, "description": "索引暂停的时间戳。未暂停时为 `null`。" }, "error": { "type": "string", "nullable": true, "description": "索引失败时的错误信息。无错误时为 `null`。" }, "stopped_at": { "type": "number", "nullable": true, "description": "索引停止的时间戳。未停止时为 `null`。" }, "completed_segments": { "type": "integer", "description": "已索引的分段数。" }, "total_segments": { "type": "integer", "description": "待索引的分段总数。" } } }, "description": "索引状态条目列表。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": [ { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "indexing_status": "completed", "processing_started_at": 1741267200, "parsing_completed_at": 1741267200, "cleaning_completed_at": 1741267200, "splitting_completed_at": 1741267200, "completed_at": 1741267200, "paused_at": null, "error": null, "stopped_at": null, "completed_segments": 5, "total_segments": 5 } ] } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。", "content": { "application/json": { "examples": { "dataset_not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "documents_not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Documents not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/get-document-indexing-status", "metadata": { "title": "获取文档嵌入状态（进度）", "sidebarTitle": "获取文档嵌入状态（进度）" } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { "post": { "tags": [ "文档" ], "summary": "用文本更新文档", "description": "更新文档的文本内容、名称或处理配置。文本变更时会重新索引文档。", "operationId": "updateDocumentByText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "文档名称。当提供 `text` 时必填。" }, "text": { "type": "string", "description": "文档文本内容。" }, "process_rule": { "type": "object", "description": "分块处理规则。", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "automatic", "custom", "hierarchical" ], "description": "`automatic` 使用内置规则，`custom` 允许手动配置，`hierarchical` 启用父子分段结构（配合 `doc_form: hierarchical_model` 使用）。" }, "rules": { "type": "object", "properties": { "pre_processing_rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "remove_stopwords", "remove_extra_spaces", "remove_urls_emails" ], "description": "规则标识符。" }, "enabled": { "type": "boolean", "description": "该预处理规则是否启用。" } } } }, "segmentation": { "type": "object", "properties": { "separator": { "type": "string", "default": "\n", "description": "用于拆分文本的自定义分隔符。" }, "max_tokens": { "type": "integer", "description": "每个分段的最大令牌数。" }, "chunk_overlap": { "type": "integer", "default": 0, "description": "分段之间的令牌重叠数。" } } } } } } }, "doc_form": { "type": "string", "enum": [ "text_model", "hierarchical_model", "qa_model" ], "default": "text_model", "description": "`text_model` 为标准文本分段，`hierarchical_model` 为父子分段结构，`qa_model` 为问答对提取。" }, "doc_language": { "type": "string", "default": "English", "description": "用于处理优化的文档语言。" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "控制查询此知识库时如何搜索和排序分段。" } } } } } }, "responses": { "200": { "description": "文档更新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "用于跟踪索引进度的批次 ID。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "word_count": 350, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "400": { "description": "- `provider_not_initialize` : 工作空间未配置模型供应商凭据。\n- `invalid_param` : 提供 `text` 时必须提供 `name`，或 `doc_form` 无效。\n- `invalid_param` : 文档不可用，无法更新（仅可更新处于可用状态的文档）。", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "invalid_param_name": { "summary": "invalid_param (name required)", "value": { "status": 400, "code": "invalid_param", "message": "name is required when text is provided." } }, "invalid_param_not_available": { "summary": "invalid_param (not available)", "value": { "status": 400, "code": "invalid_param", "message": "Document is not available" } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/update-document-by-text", "metadata": { "title": "用文本更新文档", "sidebarTitle": "用文本更新文档" } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { "post": { "tags": [ "文档" ], "summary": "用文件更新文档", "description": "已弃用。改用 [更新文档](/zh/api-reference/documents/update-document)。通过上传新文件更新文档，然后重新索引。", "operationId": "updateDocumentByFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "要上传的文件。" }, "data": { "type": "string", "description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/zh/api-reference/documents/create-document-by-text) 相同的字段（`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。", "example": "{\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } } } }, "responses": { "200": { "description": "文档更新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "用于跟踪索引进度的批次 ID。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "position": 1, "data_source_type": "upload_file", "data_source_info": { "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "data_source_detail_dict": { "upload_file": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "guide.txt", "size": 2048, "extension": "txt", "mime_type": "text/plain", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200 } }, "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", "name": "guide.txt", "created_from": "api", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "tokens": 512, "indexing_status": "completed", "error": null, "enabled": true, "disabled_at": null, "disabled_by": null, "archived": false, "display_status": "available", "word_count": 350, "hit_count": 0, "doc_form": "text_model", "doc_metadata": [], "summary_index_status": null, "need_summary": false }, "batch": "20250306150245647595" } } } } } }, "400": { "description": "- `too_many_files` : 每次请求仅允许一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。\n- `provider_not_initialize` : 工作空间未配置模型供应商凭据。\n- `invalid_param` : 文档不可用，无法更新（仅可更新处于可用状态的文档）。", "content": { "application/json": { "examples": { "too_many_files": { "summary": "too_many_files", "value": { "status": 400, "code": "too_many_files", "message": "Only one file is allowed." } }, "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "status": 400, "code": "filename_not_exists_error", "message": "The specified filename does not exist." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "invalid_param_not_available": { "summary": "invalid_param (not available)", "value": { "status": 400, "code": "invalid_param", "message": "Document is not available" } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } }, "413": { "description": "`file_too_large` : 上传的文件超出最大大小限制。", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "File size exceeded." } } } } } }, "415": { "description": "`unsupported_file_type` : 上传文件的类型不受支持。", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "deprecated": true, "x-mint": { "href": "/zh/api-reference/documents/update-document-by-file", "metadata": { "title": "用文件更新文档", "sidebarTitle": "用文件更新文档" } } } }, "/datasets/{dataset_id}/documents/download-zip": { "post": { "tags": [ "文档" ], "summary": "批量下载文档（ZIP）", "description": "将一个或多个文档下载为单个 ZIP 压缩包。仅可包含以文件形式上传的文档。", "operationId": "downloadDocumentsZipZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_ids" ], "properties": { "document_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "uuid" }, "description": "要包含在压缩包中的文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" } } } } } }, "responses": { "200": { "description": "包含所请求文档的 ZIP 压缩包。", "content": { "application/zip": { "schema": { "type": "string", "format": "binary", "description": "ZIP 压缩包二进制流。" } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。\n- `forbidden` : 你没有访问此知识库的权限。\n- `forbidden` : 你对请求的某个文档没有访问权限。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (dataset permission)", "value": { "status": 403, "code": "forbidden", "message": "You do not have permission to access this dataset." } }, "forbidden_4": { "summary": "forbidden (document permission)", "value": { "status": 403, "code": "forbidden", "message": "No permission." } } } } } }, "404": { "description": "- `not_found` : 未找到文档。\n- `not_found` : 未找到知识库。 请求的文档没有已上传的文件时，也会返回 \"Only uploaded-file documents can be downloaded as ZIP.\"。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_3": { "summary": "not_found_3", "value": { "status": 404, "code": "not_found", "message": "Only uploaded-file documents can be downloaded as ZIP." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/download-documents-as-zip", "metadata": { "title": "批量下载文档（ZIP）", "sidebarTitle": "批量下载文档（ZIP）" } } } }, "/datasets/{dataset_id}/documents/status/{action}": { "patch": { "tags": [ "文档" ], "summary": "批量更新文档状态", "description": "在一次请求中批量启用、禁用、归档或取消归档多个文档。", "operationId": "batchUpdateDocumentStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "enable", "disable", "archive", "un_archive" ] }, "description": "`enable` 启用文档以供检索，`disable` 停用，`archive` 移入归档，`un_archive` 从归档中恢复。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_ids" ], "properties": { "document_ids": { "type": "array", "items": { "type": "string" }, "description": "要更新的文档 ID。文档 ID 从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" } } } } } }, "responses": { "200": { "description": "文档更新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "操作结果。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "result": "success" } } } } } }, "400": { "description": "`invalid_action` : 操作无效，或某个文档处于不允许该操作的状态（例如仍在索引中或尚未处理完成）。", "content": { "application/json": { "examples": { "invalid_action": { "summary": "invalid_action", "value": { "status": 400, "code": "invalid_action", "message": "Invalid action." } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 知识库未找到。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/documents/update-document-status-in-batch", "metadata": { "title": "批量更新文档状态", "sidebarTitle": "批量更新文档状态" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments": { "post": { "tags": [ "分段" ], "summary": "向文档添加分段", "description": "在文档中创建一个或多个分段。", "operationId": "createSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "segments" ], "properties": { "segments": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "分段文本内容。", "minLength": 1 }, "answer": { "type": "string", "description": "答案文本。问答模式（`qa_model`）文档必填。" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "分段的关键词。" }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "description": "附件文件 ID。" } }, "required": [ "content" ] }, "description": "要创建的分段对象数组。", "minItems": 1 } } } } } }, "responses": { "200": { "description": "分段创建成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" }, "description": "已创建的分段列表。" }, "doc_form": { "type": "string", "description": "该文档使用的分块模式。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": [ { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 0, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "child_chunks": [], "attachments": [], "summary": null } ], "doc_form": "text_model" } } } } } }, "400": { "description": "- `provider_not_initialize` : 知识库使用高质量索引，但其嵌入模型缺失或配置有误。\n- `invalid_param` : 某个分段字段无效（例如 Q&A 模式的文档要求提供 `answer`），或分段数量超出单次请求上限。\n- 请求体 schema 校验失败（例如 `content` 为空）时返回非标准响应体 `{\"error\": \"<校验详情>\"}`，不含 `code` 或 `status` 字段。", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } }, "invalid_param_limit": { "summary": "invalid_param (segments limit)", "value": { "status": 400, "code": "invalid_param", "message": "Exceeded maximum segments limit of 1000." } }, "validation_error": { "summary": "schema validation (non-standard body)", "value": { "error": "1 validation error for SegmentCreatePayload\nsegments.0.content\n String should have at least 1 character [type=string_too_short, input_value='', input_type=str]" } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (upgrade plan)", "value": { "status": 403, "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 文档尚未处理完成。\n- `not_found` : 文档已被禁用。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document is not completed." } }, "not_found_4": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document is disabled." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chunks/create-chunks", "metadata": { "title": "向文档添加分段", "sidebarTitle": "向文档添加分段" } } }, "get": { "tags": [ "分段" ], "summary": "从文档获取分段", "description": "返回文档内分段的分页列表，可按关键词或索引状态筛选。", "operationId": "listSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "页码。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1 }, "description": "每页的项目数量。服务器上限为 `100`。" }, { "name": "status", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "按索引状态筛选分段，例如 `completed`、`indexing`、`error`。" }, { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "搜索关键词。" } ], "responses": { "200": { "description": "分段列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" }, "description": "分段列表。" }, "doc_form": { "type": "string", "description": "该文档使用的分块模式。" }, "total": { "type": "integer", "description": "匹配的分段总数。" }, "has_more": { "type": "boolean", "description": "下一页是否还有更多项目。" }, "limit": { "type": "integer", "description": "每页条目数。" }, "page": { "type": "integer", "description": "当前页码。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": [ { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 0, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "child_chunks": [], "attachments": [], "summary": null } ], "doc_form": "text_model", "total": 1, "has_more": false, "limit": 20, "page": 1 } } } } } }, "400": { "description": "`provider_not_initialize` : 知识库使用高质量索引，但其嵌入模型缺失或配置有误。", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chunks/list-chunks", "metadata": { "title": "从文档获取分段", "sidebarTitle": "从文档获取分段" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { "get": { "tags": [ "分段" ], "summary": "获取文档中的分段详情", "description": "获取单个分段的完整详情。", "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "分段 ID。来自 [从文档获取分段](/zh/api-reference/chunks/list-chunks)。" } ], "responses": { "200": { "description": "分段详情。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "doc_form": { "type": "string", "description": "该文档使用的分块模式。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 0, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "child_chunks": [], "attachments": [], "summary": null }, "doc_form": "text_model" } } } } } }, "400": { "description": "`invalid_param` : 知识库使用高质量索引，但其嵌入模型缺失或配置有误。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chunks/get-chunk", "metadata": { "title": "获取文档中的分段详情", "sidebarTitle": "获取文档中的分段详情" } } }, "post": { "tags": [ "分段" ], "summary": "更新文档中的分段", "description": "更新分段的字段。更新会为该分段重新触发索引。", "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "分段 ID。来自 [从文档获取分段](/zh/api-reference/chunks/list-chunks)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "segment" ], "properties": { "segment": { "type": "object", "properties": { "content": { "type": "string", "description": "分段文本内容。" }, "answer": { "type": "string", "description": "问答模式（`qa_model`）文档的答案文本。" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "分段的关键词。" }, "enabled": { "type": "boolean", "description": "分段是否已启用。" }, "regenerate_child_chunks": { "type": "boolean", "default": false, "description": "是否重新生成子分段。" }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "description": "附件文件 ID。" }, "summary": { "type": "string", "nullable": true, "description": "摘要索引的摘要内容。" } }, "description": "要更新的分段数据。" } } } } } }, "responses": { "200": { "description": "分段更新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "doc_form": { "type": "string", "description": "该文档使用的分块模式。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 0, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "updated_at": 1741267200, "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "child_chunks": [], "attachments": [], "summary": null }, "doc_form": "text_model" } } } } } }, "400": { "description": "- `provider_not_initialize` : 知识库使用高质量索引，但其嵌入模型缺失或配置有误。\n- `invalid_param` : 分段正在索引中或已被禁用，无法更新，或索引配置无效。", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } }, "invalid_param_state": { "summary": "invalid_param (state)", "value": { "status": 400, "code": "invalid_param", "message": "Segment is indexing, please try again later" } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chunks/update-chunk", "metadata": { "title": "更新文档中的分段", "sidebarTitle": "更新文档中的分段" } } }, "delete": { "tags": [ "分段" ], "summary": "删除文档中的分段", "description": "从文档中永久删除一个分段。", "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "分段 ID。来自 [从文档获取分段](/zh/api-reference/chunks/list-chunks)。" } ], "responses": { "204": { "description": "Success." }, "400": { "description": "- `invalid_param` : 知识库使用高质量索引，但其嵌入模型缺失或配置有误。\n- `invalid_param` : 该分段正在被另一并发请求删除。", "content": { "application/json": { "examples": { "invalid_param_model_setting": { "summary": "invalid_param (model setting)", "value": { "status": 400, "code": "invalid_param", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } }, "invalid_param_deleting": { "summary": "invalid_param (deleting)", "value": { "status": 400, "code": "invalid_param", "message": "Segment is deleting." } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chunks/delete-chunk", "metadata": { "title": "删除文档中的分段", "sidebarTitle": "删除文档中的分段" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { "post": { "tags": [ "分段" ], "summary": "创建子分段", "description": "在父分段下创建子分段。适用于使用父子（`hierarchical_model`）分块模式的文档。", "operationId": "createChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "父分段 ID。来自 [从文档获取分段](/zh/api-reference/chunks/list-chunks)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "子分段文本内容。" } } } } } }, "responses": { "200": { "description": "子分段创建成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChildChunk" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": { "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "content": "Dify is an open-source platform.", "position": 1, "word_count": 6, "type": "customized", "created_at": 1741267200, "updated_at": 1741267200 } } } } } } }, "400": { "description": "- `provider_not_initialize` : 知识库使用高质量索引，但其嵌入模型缺失或配置有误。\n- `invalid_param` : 在向量库中为子分段建立索引失败；错误信息中会携带底层向量库的报错。", "content": { "application/json": { "examples": { "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Vector store operation failed: [Errno 111] Connection refused" } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (upgrade plan)", "value": { "status": 403, "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chunks/create-child-chunk", "metadata": { "title": "创建子分段", "sidebarTitle": "创建子分段" } } }, "get": { "tags": [ "分段" ], "summary": "获取子分段", "description": "返回特定父分段下子分段的分页列表。", "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "父分段 ID。来自 [从文档获取分段](/zh/api-reference/chunks/list-chunks)。" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "页码。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1 }, "description": "每页的项目数量。服务器上限为 `100`。" }, { "name": "keyword", "in": "query", "schema": { "type": "string" }, "description": "搜索关键词。" } ], "responses": { "200": { "description": "子分段列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChildChunk" }, "description": "子分段列表。" }, "total": { "type": "integer", "description": "子分段总数。" }, "total_pages": { "type": "integer", "description": "总页数。" }, "page": { "type": "integer", "description": "当前页码。" }, "limit": { "type": "integer", "description": "每页条目数。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": [ { "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "content": "Dify is an open-source platform.", "position": 1, "word_count": 6, "type": "customized", "created_at": 1741267200, "updated_at": 1741267200 } ], "total": 1, "total_pages": 1, "page": 1, "limit": 20 } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chunks/list-child-chunks", "metadata": { "title": "获取子分段", "sidebarTitle": "获取子分段" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { "patch": { "tags": [ "分段" ], "summary": "更新子分段", "description": "更新现有子分段的内容。", "operationId": "updateChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "父分段 ID。来自 [从文档获取分段](/zh/api-reference/chunks/list-chunks)。" }, { "name": "child_chunk_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "子分段 ID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "子分段文本内容。" } } } } } }, "responses": { "200": { "description": "子分段更新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChildChunk" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": { "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "content": "Dify is an open-source platform.", "position": 1, "word_count": 6, "type": "customized", "created_at": 1741267200, "updated_at": 1741267200 } } } } } } }, "400": { "description": "`invalid_param` : 在向量库中重新索引子分段失败；错误信息中会携带底层向量库的报错。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Vector store operation failed: [Errno 111] Connection refused" } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (vector space)", "value": { "status": 403, "code": "forbidden", "message": "The capacity of the vector space has reached the limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_4": { "summary": "forbidden (upgrade plan)", "value": { "status": 403, "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。\n- `not_found` : 未找到子分段。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } }, "not_found_4": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Child chunk not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chunks/update-child-chunk", "metadata": { "title": "更新子分段", "sidebarTitle": "更新子分段" } } }, "delete": { "tags": [ "分段" ], "summary": "删除子分段", "description": "从父分段中永久删除一个子分段。", "operationId": "deleteChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "文档 ID。从 [获取知识库的文档列表](/zh/api-reference/documents/list-documents) 获取。" }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "父分段 ID。来自 [从文档获取分段](/zh/api-reference/chunks/list-chunks)。" }, { "name": "child_chunk_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "子分段 ID。" } ], "responses": { "204": { "description": "Success." }, "400": { "description": "`invalid_param` : 从向量库中移除子分段索引失败；错误信息中会携带底层向量库的报错。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Vector store operation failed: [Errno 111] Connection refused" } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } }, "forbidden_3": { "summary": "forbidden (upgrade plan)", "value": { "status": 403, "code": "forbidden", "message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan." } } } } } }, "404": { "description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。\n- `not_found` : 未找到子分段。", "content": { "application/json": { "examples": { "not_found_1": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } }, "not_found_2": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Document not found." } }, "not_found_3": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Segment not found." } }, "not_found_4": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Child chunk not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/chunks/delete-child-chunk", "metadata": { "title": "删除子分段", "sidebarTitle": "删除子分段" } } } }, "/datasets/{dataset_id}/retrieve": { "post": { "tags": [ "知识库" ], "summary": "从知识库检索分段 / 测试检索", "description": "搜索知识库，返回与查询最相关的分段，可用于生产环境检索和测试检索。", "operationId": "retrieveSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 250, "description": "搜索查询文本。" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", "description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。" }, "attachment_ids": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "要包含在检索上下文中的附件 ID 列表。" }, "external_retrieval_model": { "type": "object", "description": "外部知识库的检索设置。", "properties": { "top_k": { "type": "integer", "description": "返回结果的最大数量。" }, "score_threshold": { "type": "number", "description": "用于过滤结果的最小相似度分数阈值。" }, "score_threshold_enabled": { "type": "boolean", "description": "是否启用分数阈值过滤。" } } } } } } } }, "responses": { "200": { "description": "检索结果。", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "description": "原始查询对象。", "properties": { "content": { "type": "string", "description": "查询文本。" } } }, "records": { "type": "array", "items": { "type": "object", "properties": { "segment": { "type": "object", "description": "从知识库中匹配的分段。", "properties": { "id": { "type": "string", "description": "分段的唯一标识符。" }, "position": { "type": "integer", "description": "分段在文档中的位置。" }, "document_id": { "type": "string", "description": "该分段所属文档的 ID。" }, "content": { "type": "string", "description": "分段的文本内容。" }, "sign_content": { "type": "string", "description": "用于完整性验证的签名内容哈希。" }, "answer": { "type": "string", "description": "回答内容，用于问答模式文档。" }, "word_count": { "type": "integer", "description": "分段内容的字数。" }, "tokens": { "type": "integer", "description": "分段内容的令牌数。" }, "keywords": { "type": "array", "description": "与该分段关联的关键词，用于基于关键词的检索。", "items": { "type": "string" } }, "index_node_id": { "type": "string", "description": "向量存储中索引节点的 ID。" }, "index_node_hash": { "type": "string", "description": "索引内容的哈希值，用于检测变更。" }, "hit_count": { "type": "integer", "description": "该分段在检索查询中被匹配的次数。" }, "enabled": { "type": "boolean", "description": "该分段是否启用检索。" }, "disabled_at": { "type": "number", "nullable": true, "description": "分段被禁用的时间戳。启用时为 `null`。" }, "disabled_by": { "type": "string", "nullable": true, "description": "禁用该分段的用户 ID。启用时为 `null`。" }, "status": { "type": "string", "description": "分段的索引状态。" }, "created_by": { "type": "string", "description": "创建该分段的用户 ID。" }, "created_at": { "type": "number", "description": "创建时间戳（Unix 纪元，单位为秒）。" }, "indexing_at": { "type": "number", "nullable": true, "description": "索引开始的时间戳。尚未开始时为 `null`。" }, "completed_at": { "type": "number", "nullable": true, "description": "索引完成的时间戳。尚未完成时为 `null`。" }, "error": { "type": "string", "nullable": true, "description": "索引失败时的错误消息。无错误时为 `null`。" }, "stopped_at": { "type": "number", "nullable": true, "description": "索引停止的时间戳。未停止时为 `null`。" }, "document": { "type": "object", "description": "匹配分段的父文档信息。", "properties": { "id": { "type": "string", "description": "文档的唯一标识符。" }, "data_source_type": { "type": "string", "description": "文档的创建方式。" }, "name": { "type": "string", "description": "文档名称。" }, "doc_type": { "type": "string", "nullable": true, "description": "文档类型分类。未设置时为 `null`。" }, "doc_metadata": { "type": "object", "nullable": true, "description": "文档的元数据值。未配置元数据时为 `null`。" } } } } }, "child_chunks": { "type": "array", "description": "使用分层索引时，分段内匹配的子分段。", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "子分段的唯一标识符。" }, "content": { "type": "string", "description": "子分段的文本内容。" }, "position": { "type": "integer", "description": "子分段在父分段中的位置。" }, "score": { "type": "number", "description": "子分段的相关性得分。" } } } }, "score": { "type": "number", "description": "相关性得分。" }, "tsne_position": { "type": "object", "nullable": true, "description": "t-SNE 可视化位置。" }, "files": { "type": "array", "description": "附加到该分段的文件。", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "附件文件标识符。" }, "name": { "type": "string", "description": "原始文件名。" }, "size": { "type": "integer", "description": "文件大小（字节）。" }, "extension": { "type": "string", "description": "文件扩展名。" }, "mime_type": { "type": "string", "description": "文件的 MIME 类型。" }, "source_url": { "type": "string", "description": "访问附件的 URL。" } } } }, "summary": { "type": "string", "nullable": true, "description": "通过摘要索引检索到的摘要内容。" } } }, "description": "匹配的检索记录列表。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "query": { "content": "What is Dify?" }, "records": [ { "segment": { "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", "position": 1, "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "content": "Dify is an open-source LLM app development platform.", "sign_content": "", "answer": "", "word_count": 9, "tokens": 12, "keywords": [ "dify", "platform", "llm" ], "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", "index_node_hash": "abc123def456", "hit_count": 1, "enabled": true, "disabled_at": null, "disabled_by": null, "status": "completed", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": 1741267200, "indexing_at": 1741267200, "completed_at": 1741267200, "error": null, "stopped_at": null, "document": { "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", "data_source_type": "upload_file", "name": "guide.txt", "doc_type": null, "doc_metadata": null } }, "child_chunks": [], "score": 0.92, "tsne_position": null, "files": [], "summary": null } ] } } } } } }, "400": { "description": "- `dataset_not_initialized` : 知识库仍在初始化或索引中。\n- `provider_not_initialize` : 模型供应商未配置有效凭据。\n- `provider_quota_exceeded` : Dify 托管的模型供应商配额已用尽。\n- `model_currently_not_support` : 所选模型当前不受支持。\n- `completion_request_error` : 模型请求失败。\n- `invalid_param` : 请求参数无效。", "content": { "application/json": { "examples": { "dataset_not_initialized": { "summary": "dataset_not_initialized", "value": { "status": 400, "code": "dataset_not_initialized", "message": "The dataset is still being initialized or indexing. Please wait a moment." } }, "provider_not_initialize": { "summary": "provider_not_initialize", "value": { "status": 400, "code": "provider_not_initialize", "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." } }, "provider_quota_exceeded": { "summary": "provider_quota_exceeded", "value": { "status": 400, "code": "provider_quota_exceeded", "message": "Your quota for Dify Hosted Model Provider has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." } }, "model_currently_not_support": { "summary": "model_currently_not_support", "value": { "status": 400, "code": "model_currently_not_support", "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." } }, "completion_request_error": { "summary": "completion_request_error", "value": { "status": 400, "code": "completion_request_error", "message": "Completion request failed." } }, "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Invalid parameter value." } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到与 `dataset_id` 匹配的知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } }, "500": { "description": "`internal_server_error` : 检索过程中发生内部错误。", "content": { "application/json": { "examples": { "internal_server_error": { "summary": "internal_server_error", "value": { "status": 500, "code": "internal_server_error", "message": "An internal error occurred." } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval", "metadata": { "title": "从知识库检索分段 / 测试检索", "sidebarTitle": "从知识库检索分段 / 测试检索" } } } }, "/datasets/tags": { "post": { "tags": [ "标签" ], "summary": "创建知识库标签", "description": "创建用于组织知识库的标签。", "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "标签名称。在工作空间内必须唯一。" } } } } } }, "responses": { "200": { "description": "标签创建成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "标签标识符。" }, "name": { "type": "string", "description": "标签显示名称。" }, "type": { "type": "string", "description": "标签类型。知识库标签始终为 `knowledge`。" }, "binding_count": { "type": "string", "nullable": true, "description": "绑定到该标签的知识库数量。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs", "type": "knowledge", "binding_count": "0" } } } } } }, "400": { "description": "`invalid_param` : 已存在同名的知识库标签。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Tag name already exists" } } } } } } }, "x-mint": { "href": "/zh/api-reference/tags/create-knowledge-tag", "metadata": { "title": "创建知识库标签", "sidebarTitle": "创建知识库标签" } } }, "get": { "tags": [ "标签" ], "summary": "获取知识库标签列表", "description": "返回工作空间中所有的知识库标签。", "operationId": "getKnowledgeTags", "responses": { "200": { "description": "标签列表。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "标签标识符。" }, "name": { "type": "string", "description": "标签显示名称。" }, "type": { "type": "string", "description": "标签类型。知识库标签始终为 `knowledge`。" }, "binding_count": { "type": "string", "nullable": true, "description": "绑定到该标签的知识库数量。" } } } }, "examples": { "success": { "summary": "响应示例", "value": [ { "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs", "type": "knowledge", "binding_count": "0" } ] } } } } } }, "x-mint": { "href": "/zh/api-reference/tags/list-knowledge-tags", "metadata": { "title": "获取知识库标签列表", "sidebarTitle": "获取知识库标签列表" } } }, "patch": { "tags": [ "标签" ], "summary": "修改知识库标签", "description": "重命名知识库标签。", "operationId": "updateKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tag_id", "name" ], "properties": { "tag_id": { "type": "string", "description": "要重命名的标签 ID。参见 [获取知识库标签列表](/zh/api-reference/tags/list-knowledge-tags)。" }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "标签的新名称。在工作空间内必须唯一。" } } } } } }, "responses": { "200": { "description": "标签更新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "标签标识符。" }, "name": { "type": "string", "description": "标签显示名称。" }, "type": { "type": "string", "description": "标签类型。知识库标签始终为 `knowledge`。" }, "binding_count": { "type": "string", "nullable": true, "description": "绑定到该标签的知识库数量。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs", "type": "knowledge", "binding_count": "0" } } } } } }, "400": { "description": "`invalid_param` : 已存在同名的知识库标签。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Tag name already exists" } } } } } }, "404": { "description": "`not_found` : 指定的标签不存在。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Tag not found" } } } } } } }, "x-mint": { "href": "/zh/api-reference/tags/update-knowledge-tag", "metadata": { "title": "修改知识库标签", "sidebarTitle": "修改知识库标签" } } }, "delete": { "tags": [ "标签" ], "summary": "删除知识库标签", "description": "永久删除知识库标签。不会删除已被标记的知识库。", "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tag_id" ], "properties": { "tag_id": { "type": "string", "description": "要删除的标签 ID。参见 [获取知识库标签列表](/zh/api-reference/tags/list-knowledge-tags)。" } } } } } }, "responses": { "204": { "description": "Success." }, "404": { "description": "`not_found` : 指定的标签不存在。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Tag not found" } } } } } } }, "x-mint": { "href": "/zh/api-reference/tags/delete-knowledge-tag", "metadata": { "title": "删除知识库标签", "sidebarTitle": "删除知识库标签" } } } }, "/datasets/tags/binding": { "post": { "tags": [ "标签" ], "summary": "绑定标签到知识库", "description": "将一个或多个标签绑定到知识库。一个知识库可以有多个标签。", "operationId": "bindTagsToDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tag_ids", "target_id" ], "properties": { "tag_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "要绑定的标签 ID。参见 [获取知识库标签列表](/zh/api-reference/tags/list-knowledge-tags)。 未知的标签 ID 会被忽略，不会报错。" }, "target_id": { "type": "string", "description": "要绑定标签的知识库。参见 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases)。" } } } } } }, "responses": { "204": { "description": "Success." }, "404": { "description": "`not_found` : 目标知识库不存在。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found" } } } } } } }, "x-mint": { "href": "/zh/api-reference/tags/create-tag-binding", "metadata": { "title": "绑定标签到知识库", "sidebarTitle": "绑定标签到知识库" } } } }, "/datasets/tags/unbinding": { "post": { "tags": [ "标签" ], "summary": "解除标签与知识库的绑定", "description": "从知识库中移除一个或多个标签。", "operationId": "unbindTagFromDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_id" ], "properties": { "tag_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "要解绑的标签 ID 列表。未提供旧版 `tag_id` 时必填。参见 [获取知识库标签列表](/zh/api-reference/tags/list-knowledge-tags)。" }, "tag_id": { "type": "string", "deprecated": true, "description": "旧版单标签字段。服务端将其归一化为 `tag_ids`。新接入应使用 `tag_ids`。" }, "target_id": { "type": "string", "description": "要解绑标签的知识库。参见 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases)。" } } } } } }, "responses": { "204": { "description": "Success." }, "404": { "description": "`not_found` : 目标知识库不存在。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found" } } } } } } }, "x-mint": { "href": "/zh/api-reference/tags/delete-tag-binding", "metadata": { "title": "解除标签与知识库的绑定", "sidebarTitle": "解除标签与知识库的绑定" } } } }, "/datasets/{dataset_id}/tags": { "get": { "tags": [ "标签" ], "summary": "获取知识库绑定的标签", "description": "返回绑定到知识库的标签。", "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "responses": { "200": { "description": "绑定到知识库的标签。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "标签标识符。" }, "name": { "type": "string", "description": "标签显示名称。" } } }, "description": "绑定到此知识库的标签列表。" }, "total": { "type": "integer", "description": "绑定到该知识库的标签总数。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": [ { "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", "name": "Product Docs" } ], "total": 1 } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/tags/get-knowledge-base-tags", "metadata": { "title": "获取知识库绑定的标签", "sidebarTitle": "获取知识库绑定的标签" } } } }, "/datasets/{dataset_id}/metadata": { "post": { "tags": [ "元数据" ], "summary": "创建元数据字段", "description": "为知识库创建自定义元数据字段，用于给文档标注结构化信息。", "operationId": "createMetadataFieldZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "string", "number", "time" ], "description": "`string` 为文本值，`number` 为数值，`time` 为日期/时间值。" }, "name": { "type": "string", "description": "元数据字段的名称。在知识库的字段中必须唯一，且不超过 255 个字符。" } } } } } }, "responses": { "201": { "description": "元数据字段创建成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "元数据字段标识符。" }, "name": { "type": "string", "description": "元数据字段名称。" }, "type": { "type": "string", "description": "元数据字段类型。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", "name": "author", "type": "string" } } } } } }, "400": { "description": "`invalid_param` : 元数据名称已存在、超过 255 个字符，或与内置字段冲突。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Metadata name already exists." } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/metadata/create-metadata-field", "metadata": { "title": "创建元数据字段", "sidebarTitle": "创建元数据字段" } } }, "get": { "tags": [ "元数据" ], "summary": "获取元数据字段列表", "description": "返回知识库的所有元数据字段（包括自定义和内置字段），以及使用每个字段的文档数量。", "operationId": "listMetadataFieldsZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "responses": { "200": { "description": "知识库的元数据字段。", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc_metadata": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "元数据字段标识符。" }, "name": { "type": "string", "description": "元数据字段名称。" }, "type": { "type": "string", "description": "元数据字段类型。" }, "count": { "type": "integer", "description": "使用该元数据字段的文档数量。" } } }, "description": "元数据字段定义列表。" }, "built_in_field_enabled": { "type": "boolean", "description": "该知识库是否启用了内置元数据字段。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "doc_metadata": [ { "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", "name": "author", "type": "string", "count": 3 } ], "built_in_field_enabled": true } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/metadata/list-metadata-fields", "metadata": { "title": "获取元数据字段列表", "sidebarTitle": "获取元数据字段列表" } } } }, "/datasets/{dataset_id}/metadata/{metadata_id}": { "patch": { "tags": [ "元数据" ], "summary": "更新元数据字段", "description": "重命名自定义元数据字段。", "operationId": "updateMetadataFieldZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "metadata_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "要重命名的元数据字段 ID。参见 [获取元数据字段列表](/zh/api-reference/metadata/list-metadata-fields)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "字段的新名称。在知识库的字段中必须唯一，且不超过 255 个字符。" } } } } } }, "responses": { "200": { "description": "元数据字段更新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "元数据字段标识符。" }, "name": { "type": "string", "description": "元数据字段名称。" }, "type": { "type": "string", "description": "元数据字段类型。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", "name": "author", "type": "string" } } } } } }, "400": { "description": "`invalid_param` : 元数据名称已存在、超过 255 个字符，或与内置字段冲突。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Metadata name already exists." } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/metadata/update-metadata-field", "metadata": { "title": "更新元数据字段", "sidebarTitle": "更新元数据字段" } } }, "delete": { "tags": [ "元数据" ], "summary": "删除元数据字段", "description": "永久删除自定义元数据字段。使用过该字段的文档将丢失其对应的值。", "operationId": "deleteMetadataFieldZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "metadata_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "要删除的元数据字段 ID。参见 [获取元数据字段列表](/zh/api-reference/metadata/list-metadata-fields)。" } ], "responses": { "204": { "description": "Success." }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/metadata/delete-metadata-field", "metadata": { "title": "删除元数据字段", "sidebarTitle": "删除元数据字段" } } } }, "/datasets/{dataset_id}/metadata/built-in": { "get": { "tags": [ "元数据" ], "summary": "获取内置元数据字段", "description": "返回系统提供的内置元数据字段。", "operationId": "getBuiltInMetadataFieldsZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "responses": { "200": { "description": "内置元数据字段。", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "description": "系统提供的元数据字段列表。", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "内置字段标识符。`document_name` 表示文档标题，`uploader` 表示创建者，`upload_date` 表示创建时间，`last_update_date` 表示最后修改时间，`source` 表示文档来源。" }, "type": { "type": "string", "description": "字段数据类型。文本值为 `string`，日期/时间值为 `time`。" } } } } } }, "examples": { "success": { "summary": "响应示例", "value": { "fields": [ { "name": "document_name", "type": "string" }, { "name": "uploader", "type": "string" }, { "name": "upload_date", "type": "time" }, { "name": "last_update_date", "type": "time" }, { "name": "source", "type": "string" } ] } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/metadata/get-built-in-metadata-fields", "metadata": { "title": "获取内置元数据字段", "sidebarTitle": "获取内置元数据字段" } } } }, "/datasets/{dataset_id}/metadata/built-in/{action}": { "post": { "tags": [ "元数据" ], "summary": "更新内置元数据字段", "description": "启用或禁用知识库的内置元数据字段。", "operationId": "toggleBuiltInMetadataFieldZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "enable", "disable" ] }, "description": "`enable` 启用内置元数据字段，`disable` 停用内置元数据字段。" } ], "responses": { "200": { "description": "内置元数据字段切换成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "操作结果。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "result": "success" } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/metadata/update-built-in-metadata-field", "metadata": { "title": "更新内置元数据字段", "sidebarTitle": "更新内置元数据字段" } } } }, "/datasets/{dataset_id}/documents/metadata": { "post": { "tags": [ "元数据" ], "summary": "批量更新文档元数据", "description": "在一次请求中批量更新多个文档的元数据值。", "operationId": "batchUpdateDocumentMetadataZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operation_data" ], "properties": { "operation_data": { "type": "array", "items": { "type": "object", "required": [ "document_id", "metadata_list" ], "properties": { "document_id": { "type": "string", "description": "要更新的文档 ID。参见 [获取知识库的文档列表](/zh/api-reference/documents/list-documents)。" }, "metadata_list": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "元数据字段 ID。参见 [获取元数据字段列表](/zh/api-reference/metadata/list-metadata-fields)。" }, "name": { "type": "string", "description": "元数据字段名称。" }, "value": { "description": "元数据值。可以是字符串、数字或 `null`。" } } }, "description": "要设置到文档的元数据字段。" }, "partial_update": { "type": "boolean", "default": false, "description": "是否部分更新元数据，保留未指定字段的现有值。" } } }, "description": "文档元数据更新操作，每个文档一个条目。" } } } } } }, "responses": { "200": { "description": "文档元数据更新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "操作结果。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "result": "success" } } } } } }, "400": { "description": "`invalid_param` : 引用的文档不存在，或本次请求中的文档已有另一个元数据操作正在进行。", "content": { "application/json": { "examples": { "invalid_param_doc": { "summary": "invalid_param (document)", "value": { "status": 400, "code": "invalid_param", "message": "Document not found." } } } } } }, "403": { "description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。", "content": { "application/json": { "examples": { "forbidden_1": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } }, "forbidden_2": { "summary": "forbidden (rate limit)", "value": { "status": 403, "code": "forbidden", "message": "Sorry, you have reached the knowledge base request rate limit of your subscription." } } } } } }, "404": { "description": "`not_found` : 未找到知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/metadata/update-document-metadata-in-batch", "metadata": { "title": "批量更新文档元数据", "sidebarTitle": "批量更新文档元数据" } } } }, "/workspaces/current/models/model-types/{model_type}": { "get": { "tags": [ "模型" ], "summary": "获取可用模型", "description": "返回指定类型的可用模型。用它查找可配置到知识库的 `text-embedding` 和 `rerank` 模型。", "operationId": "getAvailableModelsZh", "parameters": [ { "name": "model_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "text-embedding", "rerank", "llm", "tts", "speech2text", "moderation" ] }, "description": "要获取的模型类型。对于知识库配置，使用 `text-embedding` 获取嵌入模型，使用 `rerank` 获取重排序模型。" } ], "responses": { "200": { "description": "指定类型的可用模型。", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "模型供应商及其可用模型的列表。", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如 `langgenius/openai/openai`）。旧版供应商可能返回简写形式（例如 `openai`）。" }, "label": { "type": "object", "description": "供应商的本地化显示名称。", "properties": { "en_US": { "type": "string", "description": "英文显示名称。" }, "zh_Hans": { "type": "string", "description": "中文显示名称。" } } }, "icon_small": { "type": "object", "description": "供应商小图标的 URL。", "properties": { "en_US": { "type": "string", "description": "小图标 URL。" }, "zh_Hans": { "type": "string", "description": "中文图标 URL。" } } }, "status": { "type": "string", "description": "供应商状态。凭证已配置且有效时为 `active`。" }, "models": { "type": "array", "description": "该供应商的可用模型列表。", "items": { "type": "object", "properties": { "model": { "type": "string", "description": "模型标识符。创建或更新知识库时，将此值作为 `embedding_model` 参数使用。" }, "label": { "type": "object", "description": "模型的本地化显示名称。", "properties": { "en_US": { "type": "string", "description": "英文模型名称。" }, "zh_Hans": { "type": "string", "description": "中文模型名称。" } } }, "model_type": { "type": "string", "description": "模型类型，与 `model_type` 路径参数匹配。" }, "features": { "type": "array", "nullable": true, "description": "模型支持的功能，无功能时为 `null`。", "items": { "type": "string" } }, "fetch_from": { "type": "string", "description": "模型定义的来源。`predefined-model` 表示内置模型，`customizable-model` 表示用户自配置的模型。" }, "model_properties": { "type": "object", "description": "模型特定的属性，例如 `context_size`。" }, "status": { "type": "string", "description": "模型可用状态。就绪时为 `active`。" }, "deprecated": { "type": "boolean", "description": "模型是否已弃用。" }, "load_balancing_enabled": { "type": "boolean", "description": "模型是否启用负载均衡。" }, "has_invalid_load_balancing_configs": { "type": "boolean", "description": "模型是否存在无效的负载均衡配置。" } } } }, "tenant_id": { "type": "string", "description": "该供应商配置所属的工作空间 ID。" }, "icon_small_dark": { "type": "object", "description": "深色模式图标 URL；供应商没有时为 `null`。", "properties": { "en_US": { "type": "string" }, "zh_Hans": { "type": "string" } } } } } } } }, "examples": { "success": { "summary": "响应示例", "value": { "data": [ { "provider": "langgenius/openai/openai", "label": { "en_US": "OpenAI", "zh_Hans": "OpenAI" }, "icon_small": { "en_US": "https://example.com/openai-small.svg", "zh_Hans": "https://example.com/openai-small.svg" }, "status": "active", "models": [ { "model": "text-embedding-3-small", "label": { "en_US": "text-embedding-3-small", "zh_Hans": "text-embedding-3-small" }, "model_type": "text-embedding", "features": null, "fetch_from": "predefined-model", "model_properties": { "context_size": 8191 }, "status": "active", "deprecated": false, "load_balancing_enabled": false, "has_invalid_load_balancing_configs": false } ], "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "icon_small_dark": null } ] } } } } } } }, "x-mint": { "href": "/zh/api-reference/models/get-available-models", "metadata": { "title": "获取可用模型", "sidebarTitle": "获取可用模型" } } } }, "/datasets/pipeline/file-upload": { "post": { "tags": [ "知识流水线" ], "summary": "上传流水线文件", "description": "上传文件以在知识流水线中使用。将返回的 `id` 用作 [运行流水线](/zh/api-reference/knowledge-pipeline/run-pipeline) 中 `local_file` 项的 `reference`。", "operationId": "uploadPipelineFileZh", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "要上传的文件，作为 `multipart/form-data` 的一个部分。" } } } } } }, "responses": { "201": { "description": "文件上传成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "已上传文件的唯一标识符。" }, "name": { "type": "string", "description": "原始文件名。" }, "size": { "type": "integer", "description": "文件大小（字节）。" }, "extension": { "type": "string", "description": "文件扩展名。" }, "mime_type": { "type": "string", "nullable": true, "description": "文件的 MIME 类型。若上传未包含 MIME 类型则可能为 `null`。" }, "created_by": { "type": "string", "description": "上传文件的用户 ID。" }, "created_at": { "type": "string", "nullable": true, "description": "上传时间戳（ISO 8601 格式）。在记录创建过程中可能为 `null`。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "report.pdf", "size": 524288, "extension": "pdf", "mime_type": "application/pdf", "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", "created_at": "2025-03-06T12:00:00" } } } } } }, "400": { "description": "- `no_file_uploaded` : 请求中未提供文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。\n- `too_many_files` : 每次请求仅允许一个文件。", "content": { "application/json": { "examples": { "no_file_uploaded": { "summary": "no_file_uploaded", "value": { "status": 400, "code": "no_file_uploaded", "message": "Please upload your file." } }, "filename_not_exists_error": { "summary": "filename_not_exists_error", "value": { "status": 400, "code": "filename_not_exists_error", "message": "The specified filename does not exist." } }, "too_many_files": { "summary": "too_many_files", "value": { "status": 400, "code": "too_many_files", "message": "Only one file is allowed." } } } } } }, "413": { "description": "`file_too_large` : 文件超出上传大小限制。", "content": { "application/json": { "examples": { "file_too_large": { "summary": "file_too_large", "value": { "status": 413, "code": "file_too_large", "message": "File size exceeded." } } } } } }, "415": { "description": "`unsupported_file_type` : 不支持的文件类型。", "content": { "application/json": { "examples": { "unsupported_file_type": { "summary": "unsupported_file_type", "value": { "status": 415, "code": "unsupported_file_type", "message": "File type not allowed." } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-pipeline/upload-pipeline-file", "metadata": { "title": "上传流水线文件", "sidebarTitle": "上传流水线文件" } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/pipeline/file-upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf'" } ] } }, "/datasets/{dataset_id}/pipeline/datasource-plugins": { "get": { "tags": [ "知识流水线" ], "summary": "获取数据源插件列表", "description": "返回知识流水线中已配置的数据源节点，每个节点包含其使用的插件，以及运行该节点所需的元数据。", "operationId": "listDatasourcePluginsZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "is_published", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "是否读取已发布流水线版本的节点，而非草稿版本。" } ], "responses": { "200": { "description": "流水线中已配置的数据源节点列表。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "node_id": { "type": "string", "description": "流水线工作流中数据源节点的 ID。调用 [执行数据源节点](/zh/api-reference/knowledge-pipeline/run-datasource-node) 时作为 `node_id` 传入，或调用 [运行流水线](/zh/api-reference/knowledge-pipeline/run-pipeline) 时作为 `start_node_id` 传入。" }, "plugin_id": { "type": "string", "description": "提供该节点的数据源插件的 ID。" }, "provider_name": { "type": "string", "description": "数据源插件注册的提供商名称。" }, "datasource_type": { "type": "string", "description": "数据源类型。取值为 `local_file`、`online_document`、`online_drive`、`website_crawl` 之一。" }, "title": { "type": "string", "description": "为该节点配置的显示标题。" }, "user_input_variables": { "type": "array", "description": "调用方需要为该数据源提供的流水线输入变量，来自节点数据源参数中 `{{#...#}}` 引用的变量。每一项遵循工作流使用的流水线变量结构。", "items": { "type": "object", "additionalProperties": true } }, "credentials": { "type": "array", "description": "可用于对该数据源进行认证的凭证列表。", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "凭证 ID。调用 [执行数据源节点](/zh/api-reference/knowledge-pipeline/run-datasource-node) 时作为 `credential_id` 传入，或作为 [运行流水线](/zh/api-reference/knowledge-pipeline/run-pipeline) 各数据源项中的 `credential_id` 字段。" }, "name": { "type": "string", "description": "凭证的显示名称。" }, "type": { "type": "string", "description": "数据源插件定义的凭证类型。" }, "is_default": { "type": "boolean", "description": "该凭证是否为提供商的默认凭证。" } } } } } } }, "examples": { "success": { "summary": "响应示例", "value": [ { "node_id": "1719288585006", "plugin_id": "langgenius/notion_datasource", "provider_name": "notion", "datasource_type": "online_document", "title": "Notion Documents", "user_input_variables": [], "credentials": [ { "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "name": "Production Notion", "type": "api-key", "is_default": true } ] } ] } } } } }, "400": { "description": "`invalid_param` : 该知识库未配置处理流水线。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Pipeline not found" } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 未找到与 `dataset_id` 匹配的知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-pipeline/list-datasource-plugins", "metadata": { "title": "获取数据源插件列表", "sidebarTitle": "获取数据源插件列表" } } } }, "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": { "post": { "tags": [ "知识流水线" ], "summary": "执行数据源节点", "description": "运行知识流水线中的单个数据源节点，并流式返回其执行事件。", "operationId": "runDatasourceNodeZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" }, { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "要运行的数据源节点 ID，来自 [获取数据源插件列表](/zh/api-reference/knowledge-pipeline/list-datasource-plugins)。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs", "datasource_type", "is_published" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "数据源节点的输入变量。" }, "datasource_type": { "type": "string", "enum": [ "online_document", "local_file", "website_crawl", "online_drive" ], "description": "数据源类型。" }, "credential_id": { "type": "string", "nullable": true, "description": "用于向数据源认证的凭证 ID，来自 [获取数据源插件列表](/zh/api-reference/knowledge-pipeline/list-datasource-plugins) 的 `credentials` 数组。" }, "is_published": { "type": "boolean", "description": "是否运行节点的已发布版本，而非草稿版本。" } } } } } }, "responses": { "200": { "description": "包含节点执行事件的流式响应。", "content": { "text/event-stream": { "schema": { "type": "string", "description": "包含节点执行进度和结果的 Server-Sent Events 流。解析方式参见 [SSE 流式传输](/zh/api-reference/guides/streaming)。" } } } }, "400": { "description": "`invalid_param` : 该知识库未配置处理流水线，或请求体校验失败。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Pipeline not found" } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 未找到与 `dataset_id` 匹配的知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-pipeline/run-datasource-node", "metadata": { "title": "执行数据源节点", "sidebarTitle": "执行数据源节点" } } } }, "/datasets/{dataset_id}/pipeline/run": { "post": { "tags": [ "知识流水线" ], "summary": "运行流水线", "description": "对一个或多个数据源运行完整的知识流水线。`response_mode` 选择流式或阻塞响应。", "operationId": "runPipelineZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "知识库 ID。从 [获取知识库列表](/zh/api-reference/knowledge-bases/list-knowledge-bases) 获取。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs", "datasource_type", "datasource_info_list", "start_node_id", "is_published", "response_mode" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "流水线输入变量的键值对，对应工作流中定义的流水线变量。如果流水线没有输入变量，传 `{}`。" }, "datasource_type": { "type": "string", "enum": [ "local_file", "online_document", "website_crawl", "online_drive" ], "description": "数据源类型。决定 `datasource_info_list` 中条目所需的字段。" }, "datasource_info_list": { "type": "array", "description": "待处理的数据源对象列表。条目结构取决于 `datasource_type`。", "items": { "oneOf": [ { "title": "Local File", "type": "object", "required": [ "reference" ], "properties": { "reference": { "type": "string", "description": "使用 [上传流水线文件](/zh/api-reference/knowledge-pipeline/upload-pipeline-file) 端点返回的 `id`。`related_id` 可作为别名使用。" }, "name": { "type": "string", "description": "文档标题。默认为 `\"untitled\"`。" } } }, { "title": "Online Document", "type": "object", "required": [ "workspace_id", "page" ], "properties": { "workspace_id": { "type": "string", "description": "外部平台中的工作空间或数据库 ID（例如 Notion 工作空间 ID）。" }, "page": { "type": "object", "description": "页面详情。", "required": [ "page_id", "type" ], "properties": { "page_id": { "type": "string", "description": "页面标识符。" }, "type": { "type": "string", "description": "由数据源插件定义的页面类型（例如 `\"page\"`、`\"database\"`）。" }, "page_name": { "type": "string", "description": "显示名称。默认为 `\"untitled\"`。" } } }, "credential_id": { "type": "string", "description": "用于与外部平台认证的凭证。通过 Dify 控制台管理。如省略，则使用该供应商的默认凭证。" } } }, { "title": "Website Crawl", "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "待爬取的 URL。" }, "title": { "type": "string", "description": "用作文档名称。默认为 `\"untitled\"`。" } } }, { "title": "Online Drive", "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "文件或文件夹 ID。" }, "type": { "type": "string", "enum": [ "file", "folder" ], "description": "该条目是单个文件还是待展开的文件夹。" }, "bucket": { "type": "string", "description": "存储桶名称。部分存储供应商需要此字段（例如 S3 兼容存储）；如果供应商不使用存储桶，可省略。" }, "name": { "type": "string", "description": "文件名称。默认为 `\"untitled\"`。" } } } ] } }, "start_node_id": { "type": "string", "description": "开始执行的节点 ID，来自 [获取数据源插件列表](/zh/api-reference/knowledge-pipeline/list-datasource-plugins)。" }, "is_published": { "type": "boolean", "description": "是否运行流水线的已发布版本，而非当前草稿。运行草稿可测试未发布的更改。" }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "流水线执行的响应模式。`streaming` 返回服务器发送事件流，`blocking` 等待并返回完整结果。" } } }, "examples": { "local_file": { "summary": "请求示例 - 本地文件", "value": { "inputs": {}, "datasource_type": "local_file", "datasource_info_list": [ { "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "quarterly-report.pdf" } ], "start_node_id": "1719288585006", "is_published": true, "response_mode": "blocking" } }, "online_document": { "summary": "请求示例 - 在线文档", "value": { "inputs": {}, "datasource_type": "online_document", "datasource_info_list": [ { "workspace_id": "ws-abc123", "page": { "page_id": "pg-def456", "type": "page", "page_name": "Product Roadmap" }, "credential_id": "cred-789xyz" } ], "start_node_id": "1719288585006", "is_published": true, "response_mode": "streaming" } }, "website_crawl": { "summary": "请求示例 - 网站爬取", "value": { "inputs": {}, "datasource_type": "website_crawl", "datasource_info_list": [ { "url": "https://example.com/docs/getting-started", "title": "Getting Started Guide" } ], "start_node_id": "1719288585006", "is_published": true, "response_mode": "blocking" } }, "online_drive": { "summary": "请求示例 - 在线存储", "value": { "inputs": {}, "datasource_type": "online_drive", "datasource_info_list": [ { "id": "file-abc123", "type": "file", "bucket": "my-bucket", "name": "meeting-notes.docx" } ], "start_node_id": "1719288585006", "is_published": true, "response_mode": "blocking" } } } } } }, "responses": { "200": { "description": "流水线执行结果。格式取决于 `response_mode`：流式返回 `text/event-stream`，阻塞返回完整的 JSON 结果。", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events 流。当 `response_mode` 为 `streaming` 时返回；线路格式参见 [SSE 流式传输](/zh/api-reference/guides/streaming)。\n\n主要事件：\n\n- `workflow_started`：执行开始\n- `node_started` / `node_finished`：逐节点进度，包含 `node_id`、`node_type`、`status`、`inputs`、`outputs`\n- `workflow_finished`：最终结果，包含 `status`、`outputs`、`total_tokens`、`elapsed_time`\n- `ping`：心跳保活" } }, "application/json": { "schema": { "type": "object", "description": "完整的流水线执行结果。当 `response_mode` 为 `blocking` 时返回。", "additionalProperties": true }, "examples": { "success": { "summary": "Blocking Response Example", "value": { "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", "data": { "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", "status": "succeeded", "outputs": {}, "created_at": 1741267200, "finished_at": 1741267210 } } } } } } }, "400": { "description": "`invalid_param` : 该知识库未配置处理流水线，或请求体校验失败。", "content": { "application/json": { "examples": { "invalid_param": { "summary": "invalid_param", "value": { "status": 400, "code": "invalid_param", "message": "Pipeline not found" } } } } } }, "403": { "description": "`forbidden` : 该知识库未启用 API 访问。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden (api access)", "value": { "status": 403, "code": "forbidden", "message": "Dataset api access is not enabled." } } } } } }, "404": { "description": "`not_found` : 未找到与 `dataset_id` 匹配的知识库。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Dataset not found." } } } } } }, "500": { "description": "`pipeline_run_error` : 流水线执行失败。", "content": { "application/json": { "examples": { "pipeline_run_error": { "summary": "pipeline_run_error", "value": { "status": 500, "code": "pipeline_run_error", "message": "Pipeline execution failed: connection timeout" } } } } } } }, "x-mint": { "href": "/zh/api-reference/knowledge-pipeline/run-pipeline", "metadata": { "title": "运行流水线", "sidebarTitle": "运行流水线" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "每个请求都通过 API Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API Key，知识库接口使用知识库 API Key（[快速开始](/zh/api-reference/guides/get-started)）。\n\nAPI Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。" } }, "responses": { "SuccessResult": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "操作结果，固定为 `success`。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "result": "success" } } } } } } }, "schemas": { "ChatRequest": { "type": "object", "required": [ "inputs", "query", "user" ], "properties": { "query": { "type": "string", "description": "用户发送的消息。" }, "inputs": { "type": "object", "description": "应用输入变量的值，以变量名为键。变量名称和类型可从 [获取应用参数](/zh/api-reference/applications/get-app-parameters) 响应中的 `user_input_form` 字段获取。", "additionalProperties": true }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "响应返回模式。省略时默认为阻塞模式。\n\n- `streaming`（推荐）：回复以 Server-Sent Events 形式返回。\n- `blocking`：生成完成后一次性返回。生成时间较长时有中断风险：在 Dify Cloud 上，如果边缘代理在超时时间内未收到响应，就可能中断连接。\n- Agent 和新 Agent 应用仅支持 `streaming`；使用 `blocking` 会返回 400。" }, "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。会话、消息和文件仅对携带相同 `user` 的请求可见。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" }, "conversation_id": { "type": "string", "description": "要继续的会话 ID。省略此字段或传入空字符串可开始新会话；响应会返回一个 `conversation_id`，在下一条消息中带上它即可。要恢复较早的会话，可从 [获取会话列表](/zh/api-reference/conversations/list-conversations) 获取其 ID。" }, "files": { "type": "array", "description": "要附加到消息的文件。本地文件需先通过 [上传文件](/zh/api-reference/files/upload-file) 上传，再将返回的 `id` 作为 `upload_file_id` 引用，并设置 `transfer_method: local_file`。新 Agent 应用接受文件引用，但不会处理其内容。", "items": { "type": "object", "required": [ "type", "transfer_method" ], "properties": { "type": { "type": "string", "enum": [ "image", "document", "audio", "video", "custom" ], "description": "文件类型。" }, "transfer_method": { "type": "string", "enum": [ "remote_url", "local_file" ], "description": "传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。" }, "url": { "type": "string", "format": "url", "description": "文件 URL（当 `transfer_method` 为 `remote_url` 时必填）。" }, "upload_file_id": { "type": "string", "description": "通过 [上传文件](/zh/api-reference/files/upload-file) API 获取的已上传文件 ID（当 `transfer_method` 为 `local_file` 时必填）。" } } } }, "auto_generate_name": { "type": "boolean", "description": "自动生成会话标题。如果为 `false`，请使用 [重命名会话](/zh/api-reference/conversations/rename-conversation) API 并设置 `auto_generate: true` 来异步生成标题。", "default": true }, "workflow_id": { "type": "string", "description": "仅适用于 Chatflow 应用。 指定要执行的已发布工作流版本 ID。如果未提供，将使用最新发布的版本。在 Dify Cloud 上，指定版本需要付费套餐。" } } }, "ChatCompletionResponse": { "type": "object", "properties": { "event": { "type": "string", "description": "事件类型，固定为 `message`。" }, "task_id": { "type": "string", "format": "uuid", "description": "用于请求追踪和停止响应 API 的任务 ID。" }, "id": { "type": "string", "format": "uuid", "description": "该响应事件的唯一 ID。" }, "message_id": { "type": "string", "format": "uuid", "description": "唯一的消息 ID。调用反馈或推荐问题接口时，将此值作为 `message_id` 参数使用。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, "mode": { "type": "string", "description": "应用模式。`chat` 表示聊天助手应用，`agent-chat` 表示 Agent 应用，`advanced-chat` 表示 Chatflow 应用。" }, "answer": { "type": "string", "description": "完整的响应内容。" }, "metadata": { "type": "object", "description": "包含用量和检索资源的元数据。", "properties": { "usage": { "$ref": "#/components/schemas/Usage" }, "retriever_resources": { "type": "array", "description": "使用的检索资源列表。", "items": { "$ref": "#/components/schemas/RetrieverResource" } } } }, "created_at": { "type": "integer", "format": "int64", "description": "消息创建时间戳（Unix 纪元秒）。" } } }, "ChunkChatEvent": { "type": "object", "description": "流式模式下 Server-Sent Event 块的基础 schema。", "properties": { "event": { "type": "string", "description": "事件类型。", "enum": [ "message", "agent_message", "agent_thought", "tts_message", "tts_message_end", "message_file", "message_end", "message_replace", "reasoning_chunk", "workflow_started", "workflow_finished", "node_started", "node_finished", "node_retry", "iteration_started", "iteration_next", "iteration_completed", "loop_started", "loop_next", "loop_completed", "workflow_paused", "human_input_required", "human_input_form_filled", "human_input_form_timeout", "agent_log", "text_chunk", "error", "ping" ] } }, "discriminator": { "propertyName": "event", "mapping": { "message": "#/components/schemas/StreamEventChatMessage", "agent_message": "#/components/schemas/StreamEventChatAgentMessage", "tts_message": "#/components/schemas/StreamEventChatTtsMessage", "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", "agent_thought": "#/components/schemas/StreamEventChatAgentThought", "message_file": "#/components/schemas/StreamEventChatMessageFile", "message_end": "#/components/schemas/StreamEventChatMessageEnd", "message_replace": "#/components/schemas/StreamEventChatMessageReplace", "error": "#/components/schemas/StreamEventChatError", "ping": "#/components/schemas/StreamEventChatPing", "reasoning_chunk": "#/components/schemas/StreamEventChatReasoningChunk", "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", "node_started": "#/components/schemas/StreamEventNodeStarted", "node_finished": "#/components/schemas/StreamEventNodeFinished", "node_retry": "#/components/schemas/StreamEventNodeRetry", "iteration_started": "#/components/schemas/StreamEventIterationStarted", "iteration_next": "#/components/schemas/StreamEventIterationNext", "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", "loop_started": "#/components/schemas/StreamEventLoopStarted", "loop_next": "#/components/schemas/StreamEventLoopNext", "loop_completed": "#/components/schemas/StreamEventLoopCompleted", "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout", "agent_log": "#/components/schemas/StreamEventAgentLog", "text_chunk": "#/components/schemas/StreamEventChatTextChunk" } } }, "StreamEventBase": { "type": "object", "description": "流式事件的基础属性。", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "message_id": { "type": "string", "format": "uuid", "description": "唯一消息 ID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" } } }, "StreamEventChatMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "answer": { "type": "string", "description": "LLM 返回的文本块。" } } } ] }, "StreamEventChatAgentMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "answer": { "type": "string", "description": "LLM 返回的文本块（Agent 模式）。" } } } ] }, "StreamEventChatTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "TTS 音频流事件（base64 编码的 Mp3）。自动播放启用时可用。", "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。" } } } ] }, "StreamEventChatTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "TTS 音频流结束事件。", "properties": { "audio": { "type": "string", "description": "空字符串。标识音频流结束。" } } } ] }, "StreamEventChatAgentThought": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "Agent 思考、LLM 推理、工具调用详情（Agent 模式）。", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent 思考 ID。" }, "position": { "type": "integer", "description": "该思考在消息序列中的位置。" }, "thought": { "type": "string", "description": "LLM 正在思考的内容。" }, "observation": { "type": "string", "description": "工具调用的响应。" }, "tool": { "type": "string", "description": "调用的工具列表，以 `;` 分隔。" }, "tool_input": { "type": "string", "description": "工具输入（JSON 格式）。" }, "message_files": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "与该思考相关的文件 ID 列表。" } } } ] }, "StreamEventChatMessageFile": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "消息文件事件，由工具创建的新文件。", "properties": { "id": { "type": "string", "format": "uuid", "description": "文件唯一 ID。" }, "type": { "type": "string", "description": "文件类型，例如 `image`。" }, "belongs_to": { "type": "string", "description": "该文件的所属者。工具生成的文件始终为 `assistant`。" }, "url": { "type": "string", "format": "url", "description": "文件的远程 URL。" } } } ] }, "StreamEventChatMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "消息结束事件，流式传输已结束。", "properties": { "id": { "type": "string", "format": "uuid", "description": "消息的唯一 ID。" }, "metadata": { "type": "object", "description": "包含用量和检索资源的元数据。", "properties": { "usage": { "$ref": "#/components/schemas/Usage" }, "retriever_resources": { "type": "array", "description": "使用的检索资源列表。", "items": { "$ref": "#/components/schemas/RetrieverResource" } } } } } } ] }, "StreamEventChatMessageReplace": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "消息内容替换事件（例如由于内容审核）。", "properties": { "answer": { "type": "string", "description": "替换内容。" }, "reason": { "type": "string", "description": "内容替换的原因。" } } } ] }, "StreamEventChatError": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "流式输出过程中的错误事件。", "properties": { "status": { "type": "integer", "description": "HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误信息。" } } } ] }, "StreamEventChatPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "type": "object", "description": "Ping 事件，用于保持连接活跃。以 `event: ping` 行的形式送达，无 `data:` 载荷。" } ] }, "Usage": { "type": "object", "description": "模型使用信息。", "properties": { "prompt_tokens": { "type": "integer", "description": "提示词中的令牌数。" }, "prompt_unit_price": { "type": "string", "format": "decimal", "description": "每个提示词令牌的单价。" }, "prompt_price_unit": { "type": "string", "format": "decimal", "description": "提示词令牌的价格单位。" }, "prompt_price": { "type": "string", "format": "decimal", "description": "提示词令牌的总价。" }, "completion_tokens": { "type": "integer", "description": "补全内容中的令牌数。" }, "completion_unit_price": { "type": "string", "format": "decimal", "description": "每个补全令牌的单价。" }, "completion_price_unit": { "type": "string", "format": "decimal", "description": "补全令牌的价格单位。" }, "completion_price": { "type": "string", "format": "decimal", "description": "补全令牌的总价。" }, "total_tokens": { "type": "integer", "description": "使用的令牌总数。" }, "total_price": { "type": "string", "format": "decimal", "description": "所有令牌的总价。" }, "currency": { "type": "string", "description": "计价货币。" }, "latency": { "type": "number", "format": "double", "description": "延迟时间（秒）。" } } }, "RetrieverResource": { "type": "object", "description": "检索资源的引用和归属信息。", "properties": { "id": { "type": "string", "format": "uuid", "description": "检索资源的唯一 ID。" }, "message_id": { "type": "string", "format": "uuid", "description": "该资源所属消息的 ID。" }, "position": { "type": "integer", "description": "资源在列表中的位置。" }, "dataset_id": { "type": "string", "format": "uuid", "description": "知识库 ID。" }, "dataset_name": { "type": "string", "description": "知识库名称。" }, "document_id": { "type": "string", "format": "uuid", "description": "文档 ID。" }, "document_name": { "type": "string", "description": "文档名称。" }, "data_source_type": { "type": "string", "description": "数据源类型。" }, "segment_id": { "type": "string", "format": "uuid", "description": "文档中特定块的 ID。" }, "score": { "type": "number", "format": "float", "description": "资源的相关性评分。" }, "hit_count": { "type": "integer", "description": "该块被命中的次数。" }, "word_count": { "type": "integer", "description": "块的字数。" }, "segment_position": { "type": "integer", "description": "块在文档中的位置。" }, "index_node_hash": { "type": "string", "description": "索引节点的哈希值。" }, "content": { "type": "string", "description": "资源的内容片段。" }, "summary": { "type": "string", "nullable": true, "description": "块内容的摘要。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳（Unix 纪元秒）。" } } }, "FileUploadResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "唯一文件 ID。" }, "reference": { "type": "string", "nullable": true, "description": "在 Agent 和工具场景中附加文件时内部使用的不透明文件引用。通过此端点上传的文件始终为 `null`。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件大小（字节）。" }, "extension": { "type": "string", "nullable": true, "description": "文件扩展名。" }, "mime_type": { "type": "string", "nullable": true, "description": "文件的 MIME 类型。" }, "created_by": { "type": "string", "format": "uuid", "nullable": true, "description": "上传者的终端用户 ID。可通过 [获取终端用户信息](/zh/api-reference/end-users/get-end-user-info) 查询详情。" }, "created_at": { "type": "integer", "format": "int64", "description": "上传时间戳（Unix 纪元秒）。" }, "preview_url": { "type": "string", "nullable": true, "description": "文件的预览 URL。" }, "source_url": { "type": "string", "description": "文件的签名下载 URL。" }, "original_url": { "type": "string", "nullable": true, "description": "文件的原始 URL。" }, "user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "未使用，始终为 `null`。" }, "tenant_id": { "type": "string", "format": "uuid", "nullable": true, "description": "关联的租户 ID。" }, "conversation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "关联的会话 ID。" }, "file_key": { "type": "string", "nullable": true, "description": "未使用，始终为 `null`。" } } }, "EndUserDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "终端用户 ID。" }, "tenant_id": { "type": "string", "format": "uuid", "description": "租户 ID。" }, "app_id": { "type": "string", "format": "uuid", "nullable": true, "description": "应用 ID。" }, "type": { "type": "string", "description": "终端用户类型。Service API 用户固定为 `service-api`。" }, "external_user_id": { "type": "string", "nullable": true, "description": "API 请求中提供的 `user` 标识符（例如 [发送对话消息](/zh/api-reference/chat-messages/send-chat-message) 中的 `user` 字段）。" }, "name": { "type": "string", "nullable": true, "description": "终端用户名称。" }, "is_anonymous": { "type": "boolean", "description": "用户是否为匿名用户。当原始 API 请求中未提供 `user` 标识符时，值为 `true`。" }, "session_id": { "type": "string", "description": "会话标识符。默认为 `external_user_id` 的值。" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间戳。" }, "updated_at": { "type": "string", "format": "date-time", "description": "最后更新时间戳。" } } }, "MessageFeedbackRequest": { "type": "object", "description": "提交消息反馈的请求体。", "required": [ "user" ], "properties": { "rating": { "type": "string", "enum": [ "like", "dislike", null ], "nullable": true, "description": "反馈评分。设为 `null` 可撤销之前提交的反馈。" }, "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。反馈按终端用户隔离，必须与收到该消息的 `user` 一致。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" }, "content": { "type": "string", "description": "提供额外详情的可选文字反馈。" } } }, "AppFeedbacksResponse": { "type": "object", "properties": { "data": { "type": "array", "description": "反馈项列表。", "items": { "$ref": "#/components/schemas/FeedbackItem" } } } }, "FeedbackItem": { "type": "object", "description": "单条反馈项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "反馈 ID。" }, "app_id": { "type": "string", "format": "uuid", "description": "应用 ID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, "message_id": { "type": "string", "format": "uuid", "description": "消息 ID。" }, "rating": { "type": "string", "description": "反馈评分。`like` 为正面，`dislike` 为负面。" }, "content": { "type": "string", "nullable": true, "description": "可选的文字反馈。" }, "from_source": { "type": "string", "description": "反馈来源。`user` 为终端用户通过 API 提交的反馈，`admin` 为从控制台提交的反馈。" }, "from_end_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "提交反馈的终端用户 ID。当 `from_source` 为 `user` 时存在。" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true, "description": "提交反馈的账户 ID。当 `from_source` 为 `admin` 时存在。" }, "created_at": { "type": "string", "format": "date-time", "description": "创建时间戳。" }, "updated_at": { "type": "string", "format": "date-time", "description": "最后更新时间戳。" } } }, "SuggestedQuestionsResponse": { "type": "object", "properties": { "result": { "type": "string", "description": "结果状态。" }, "data": { "type": "array", "items": { "type": "string" }, "description": "建议问题列表。" } } }, "ConversationHistoryResponse": { "type": "object", "properties": { "limit": { "type": "integer", "description": "每页条目数。" }, "has_more": { "type": "boolean", "description": "是否有更多消息。" }, "data": { "type": "array", "description": "消息列表。", "items": { "$ref": "#/components/schemas/ConversationMessageItem" } } } }, "ConversationMessageItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "消息 ID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, "parent_message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "线程会话的父消息 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "该消息的输入变量。" }, "query": { "type": "string", "description": "用户查询文本。" }, "answer": { "type": "string", "description": "助手回答文本。" }, "status": { "type": "string", "description": "消息状态。成功消息为 `normal`，生成失败时为 `error`。" }, "error": { "type": "string", "nullable": true, "description": "当 `status` 为 `error` 时的错误消息。" }, "message_files": { "type": "array", "description": "附加到该消息的文件。", "items": { "$ref": "#/components/schemas/MessageFileItem" } }, "feedback": { "type": "object", "nullable": true, "description": "该消息的用户反馈。", "properties": { "rating": { "type": "string", "description": "反馈评分。`like` 为正面，`dislike` 为负面。" } } }, "retriever_resources": { "type": "array", "description": "该消息使用的检索资源。", "items": { "$ref": "#/components/schemas/RetrieverResource" } }, "agent_thoughts": { "type": "array", "description": "该消息的 Agent 思考。", "items": { "$ref": "#/components/schemas/AgentThoughtItem" } }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳（Unix 纪元秒）。" }, "extra_contents": { "type": "array", "description": "与此消息关联的附加执行内容，例如 Chatflow 工作流中人工介入节点的表单数据。", "items": { "$ref": "#/components/schemas/HumanInputContent" } }, "message_tokens": { "type": "integer", "description": "输入消息的 token 数量。" }, "answer_tokens": { "type": "integer", "description": "生成回答的 token 数量。" }, "total_tokens": { "type": "integer", "description": "使用的 token 总数，即 `message_tokens` 与 `answer_tokens` 之和。" }, "provider_response_latency": { "type": "number", "format": "double", "description": "模型供应商的响应延迟，单位为秒。" }, "total_price": { "type": "string", "format": "decimal", "nullable": true, "description": "所用 token 的总价，无定价信息时为 `null`。" }, "currency": { "type": "string", "nullable": true, "description": "`total_price` 的货币单位（例如 `USD`），无定价信息时为 `null`。" } } }, "MessageFileItem": { "type": "object", "description": "附加到消息的文件。", "properties": { "id": { "type": "string", "format": "uuid", "description": "File ID." }, "filename": { "type": "string", "description": "原始文件名。" }, "type": { "type": "string", "description": "文件类型，例如 `image`。" }, "url": { "type": "string", "format": "url", "nullable": true, "description": "文件的预览 URL。" }, "mime_type": { "type": "string", "nullable": true, "description": "文件的 MIME 类型。" }, "size": { "type": "integer", "nullable": true, "description": "文件大小（字节）。" }, "transfer_method": { "type": "string", "description": "使用的传输方式。`remote_url` 表示基于 URL 的文件，`local_file` 表示已上传的文件，`tool_file` 表示工具生成的文件。" }, "belongs_to": { "type": "string", "nullable": true, "description": "该文件的所属者。用户上传的文件为 `user`，助手生成的文件为 `assistant`。" }, "upload_file_id": { "type": "string", "format": "uuid", "nullable": true, "description": "通过 `local_file` 传输时的上传文件 ID。" } } }, "AgentThoughtItem": { "type": "object", "description": "消息中的 Agent 思考步骤。", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent 思考 ID。" }, "chain_id": { "type": "string", "nullable": true, "description": "该思考的链 ID。" }, "message_id": { "type": "string", "format": "uuid", "description": "该思考所属的唯一消息 ID。" }, "position": { "type": "integer", "description": "该思考的位置。" }, "thought": { "type": "string", "description": "LLM 正在思考的内容。" }, "tool": { "type": "string", "description": "调用的工具，以 `;` 分隔。" }, "tool_labels": { "type": "object", "nullable": true, "additionalProperties": true, "description": "已使用工具的标签。" }, "tool_input": { "type": "string", "description": "工具输入（JSON 格式）。" }, "observation": { "type": "string", "description": "工具调用的响应。" }, "files": { "type": "array", "items": { "type": "string" }, "description": "与该思考相关的文件 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" } } }, "ConversationsListResponse": { "type": "object", "properties": { "limit": { "type": "integer", "description": "每页条目数。" }, "has_more": { "type": "boolean", "description": "是否有更多会话。" }, "data": { "type": "array", "description": "会话列表。", "items": { "$ref": "#/components/schemas/ConversationListItem" } } } }, "ConversationListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "会话 ID。" }, "name": { "type": "string", "description": "会话名称。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "会话的输入变量。" }, "status": { "type": "string", "description": "会话状态。活跃会话为 `normal`。" }, "introduction": { "type": "string", "description": "会话介绍。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最后更新时间戳。" } } }, "ConversationRenameRequest": { "type": "object", "description": "重命名会话的请求体。", "properties": { "name": { "type": "string", "description": "新的会话名称。除非 `auto_generate` 为 `true`，否则必填。" }, "auto_generate": { "type": "boolean", "default": false, "description": "自动生成会话名称。当为 `true` 时，`name` 字段将被忽略。" }, "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" } } }, "ConversationVariablesResponse": { "type": "object", "properties": { "limit": { "type": "integer", "description": "每页条目数。" }, "has_more": { "type": "boolean", "description": "是否有下一页。" }, "data": { "type": "array", "description": "会话变量列表。", "items": { "$ref": "#/components/schemas/ConversationVariableItem" } } } }, "ConversationVariableItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Variable ID." }, "name": { "type": "string", "description": "变量名称。" }, "value_type": { "type": "string", "description": "变量值类型。可选值：`string`、`number`、`object`、`secret`、`file`、`boolean`、`array[any]`、`array[string]`、`array[number]`、`array[object]`、`array[file]`、`array[boolean]`。" }, "value": { "type": "string", "description": "变量值（复杂类型可以是 JSON 字符串）。" }, "description": { "type": "string", "description": "变量描述。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最后更新时间戳。" } } }, "ConversationVariableUpdateRequest": { "type": "object", "description": "更新会话变量的请求体。", "required": [ "value" ], "properties": { "value": { "description": "变量的新值。必须与变量的预期类型匹配。" }, "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" } } }, "AudioToTextRequest": { "type": "object", "description": "语音转文字的请求体。", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "要转写的音频文件。接受的 MIME 类型：`audio/mp3`、`audio/m4a`、`audio/wav`、`audio/amr`、`audio/mpga`。其他类型（包括常见的 `audio/mpeg`）会返回 `unsupported_audio_type` 错误。最大 `30 MB`。" }, "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" } } }, "AudioToTextResponse": { "type": "object", "properties": { "text": { "type": "string", "description": "语音识别输出的文字。" } } }, "TextToAudioRequest": { "type": "object", "description": "文字转语音的请求体。提供 `message_id` 或 `text` 其中之一。", "properties": { "message_id": { "type": "string", "format": "uuid", "description": "要转为语音的消息答案的 ID。同时提供 `text` 时，优先使用 `message_id`。消息 ID 从 [获取会话历史消息](/zh/api-reference/conversations/list-conversation-messages) 获取。" }, "text": { "type": "string", "description": "要合成为语音的文本。" }, "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" }, "voice": { "type": "string", "description": "文字转语音使用的声音。可用声音取决于为此应用配置的 TTS 提供商。使用[获取应用参数](/zh/api-reference/applications/get-app-parameters) → `text_to_speech.voice` 中的 `voice` 值作为默认值。" }, "streaming": { "type": "boolean", "description": "为向后兼容而保留，但不产生任何效果。音频是否以流式返回由配置的 TTS 供应商的输出决定，而非此字段。" } } }, "AppInfoResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "应用名称。" }, "description": { "type": "string", "description": "应用描述。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "应用标签。" }, "mode": { "type": "string", "description": "应用模式。`completion` 为文本生成应用，`chat` 为基础对话应用，`agent-chat` 为 Agent 应用，`advanced-chat` 为 Chatflow 应用，`workflow` 为 Workflow 应用，`agent` 为新 Agent 应用。" }, "author_name": { "type": "string", "description": "应用作者名称。" } } }, "UserInputFormItem": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapper" }, { "$ref": "#/components/schemas/ParagraphControlWrapper" }, { "$ref": "#/components/schemas/SelectControlWrapper" } ] }, "TextInputControlWrapper": { "title": "Text Input", "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } } }, "ParagraphControlWrapper": { "title": "Paragraph", "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } } }, "SelectControlWrapper": { "title": "Select", "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } } }, "TextInputControl": { "type": "object", "properties": { "label": { "type": "string", "description": "表单字段的显示标签。" }, "variable": { "type": "string", "description": "用作 `inputs` 对象中键的变量名。" }, "required": { "type": "boolean", "description": "提交前是否必须填写此字段。" }, "default": { "type": "string", "description": "表单字段中预填的默认值。" } } }, "ParagraphControl": { "type": "object", "properties": { "label": { "type": "string", "description": "表单字段的显示标签。" }, "variable": { "type": "string", "description": "用作 `inputs` 对象中键的变量名。" }, "required": { "type": "boolean", "description": "提交前是否必须填写此字段。" }, "default": { "type": "string", "description": "表单字段中预填的默认值。" } } }, "SelectControl": { "type": "object", "properties": { "label": { "type": "string", "description": "表单字段的显示标签。" }, "variable": { "type": "string", "description": "用作 `inputs` 对象中键的变量名。" }, "required": { "type": "boolean", "description": "提交前是否必须做出选择。" }, "default": { "type": "string", "description": "默认选中的值。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "此表单控件的可选值列表。" } } }, "AppMetaResponse": { "type": "object", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "title": "Icon URL", "type": "string", "format": "url", "description": "图标的 URL。" }, { "$ref": "#/components/schemas/ToolIconDetail" } ] }, "description": "工具图标。键为工具名称。" } } }, "ToolIconDetail": { "title": "Emoji Icon", "type": "object", "description": "使用 emoji 的工具图标详情。", "properties": { "background": { "type": "string", "description": "十六进制格式的背景颜色。" }, "content": { "type": "string", "description": "Emoji 内容。" } } }, "WebAppSettingsResponse": { "type": "object", "properties": { "title": { "type": "string", "description": "WebApp 标题。" }, "chat_color_theme": { "type": "string", "description": "聊天主题颜色。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "聊天主题颜色是否反转。" }, "icon_type": { "type": "string", "description": "使用的图标类型。`emoji` 为表情图标，`image` 为上传的图片图标。" }, "icon": { "type": "string", "description": "图标内容（表情或图片 ID）。" }, "icon_background": { "type": "string", "description": "图标背景颜色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "图标图片的 URL。" }, "description": { "type": "string", "description": "WebApp 描述。" }, "copyright": { "type": "string", "description": "版权文本。" }, "privacy_policy": { "type": "string", "description": "隐私政策 URL。" }, "input_placeholder": { "type": "string", "nullable": true, "description": "WebApp 消息输入框中显示的占位文本。未配置时为 `null`。" }, "custom_disclaimer": { "type": "string", "description": "自定义免责声明文本。" }, "default_language": { "type": "string", "description": "默认语言代码。" }, "show_workflow_steps": { "type": "boolean", "description": "是否显示工作流步骤。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "是否使用应用图标作为回答图标。" } } }, "AnnotationListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItem" }, "description": "当前页面的标注项列表。" }, "has_more": { "type": "boolean", "description": "如果当前结果集之后还有更多页面，则为 `true`。" }, "limit": { "type": "integer", "description": "每页条目数。" }, "total": { "type": "integer", "description": "匹配查询条件的标注总数。" }, "page": { "type": "integer", "description": "当前页码。" } } }, "AnnotationItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "标注唯一标识符。" }, "question": { "type": "string", "nullable": true, "description": "触发该标注的问题文本。" }, "answer": { "type": "string", "nullable": true, "description": "标注被匹配时返回的预定义回答。" }, "hit_count": { "type": "integer", "nullable": true, "description": "该标注被匹配并作为回复返回的次数。" }, "created_at": { "type": "integer", "format": "int64", "nullable": true, "description": "创建时间戳（Unix 纪元秒）。" } } }, "CreateAnnotationRequest": { "type": "object", "description": "创建新标注的请求体。", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "description": "应用用来匹配用户输入的问题文本。" }, "answer": { "type": "string", "description": "命中该标注时返回的答案。" } } }, "UpdateAnnotationRequest": { "type": "object", "description": "更新标注的请求体。", "required": [ "question", "answer" ], "properties": { "question": { "type": "string", "description": "标注的新问题文本。" }, "answer": { "type": "string", "description": "标注的新答案文本。" } } }, "InitialAnnotationReplySettingsRequest": { "type": "object", "description": "配置标注回复设置的请求体。", "required": [ "score_threshold", "embedding_provider_name", "embedding_model_name" ], "properties": { "embedding_provider_name": { "type": "string", "description": "嵌入模型供应商（例如 `openai`）。可用供应商从 [获取可用模型](/zh/api-reference/models/get-available-models) 获取。" }, "embedding_model_name": { "type": "string", "description": "用于将标注向量化以进行匹配的嵌入模型（例如 `text-embedding-3-small`）。" }, "score_threshold": { "type": "number", "format": "float", "description": "标注被视为匹配的最低相似度分数。值越高，要求匹配越精确。" } } }, "InitialAnnotationReplySettingsResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "异步任务 ID。配合 [查询标注回复配置任务状态](/zh/api-reference/annotations/get-annotation-reply-job-status) 使用以跟踪进度。" }, "job_status": { "type": "string", "description": "当前任务状态，仅为 `waiting`（排队中）或 `processing`（处理中）；`completed` 和 `error` 仅由 [查询标注回复配置任务状态](/zh/api-reference/annotations/get-annotation-reply-job-status) 返回。" } } }, "InitialAnnotationReplySettingsStatusResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "来自 [配置标注回复](/zh/api-reference/annotations/configure-annotation-reply) 调用的任务 ID。" }, "job_status": { "type": "string", "description": "当前任务状态。`waiting` 表示排队中，`processing` 表示处理中，`completed` 表示已完成，`error` 表示失败。" }, "error_msg": { "type": "string", "description": "描述任务失败原因的错误消息。当 `job_status` 不是 `error` 时为空字符串。" } } }, "AppParametersResponse": { "type": "object", "properties": { "opening_statement": { "type": "string", "nullable": true, "description": "开场白文本。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "建议问题列表。" }, "suggested_questions_after_answer": { "type": "object", "description": "回答后建议问题的配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "speech_to_text": { "type": "object", "description": "语音转文字功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "text_to_speech": { "type": "object", "description": "文字转语音功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" }, "voice": { "type": "string", "description": "TTS 声音标识符。" }, "language": { "type": "string", "description": "TTS 语言。" }, "autoPlay": { "type": "string", "description": "自动播放设置。`enabled` 为自动播放音频，`disabled` 为需要手动播放。" } } }, "retriever_resource": { "type": "object", "description": "知识检索引用资源配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "annotation_reply": { "type": "object", "description": "标注回复功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "more_like_this": { "type": "object", "description": "更多类似推荐功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "sensitive_word_avoidance": { "type": "object", "description": "内容审核功能配置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用此功能。" } } }, "user_input_form": { "type": "array", "items": { "type": "object", "oneOf": [ { "title": "Text Input", "type": "object", "properties": { "text-input": { "type": "object", "properties": { "label": { "type": "string", "description": "输入字段的显示标签。" }, "variable": { "type": "string", "description": "工作流中使用的变量名称。" }, "required": { "type": "boolean", "description": "该字段是否必填。" }, "default": { "type": "string", "description": "输入字段的默认值。" } } } } }, { "title": "Paragraph", "type": "object", "properties": { "paragraph": { "type": "object", "properties": { "label": { "type": "string", "description": "段落字段的显示标签。" }, "variable": { "type": "string", "description": "工作流中使用的变量名称。" }, "required": { "type": "boolean", "description": "该字段是否必填。" }, "default": { "type": "string", "description": "段落字段的默认值。" } } } } }, { "title": "Select", "type": "object", "properties": { "select": { "type": "object", "properties": { "label": { "type": "string", "description": "下拉选择字段的显示标签。" }, "variable": { "type": "string", "description": "工作流中使用的变量名称。" }, "required": { "type": "boolean", "description": "该字段是否必填。" }, "default": { "type": "string", "description": "默认选中的值。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "此表单控件的可选值列表。" } } } } } ] }, "description": "用户输入表单配置。" }, "file_upload": { "type": "object", "description": "文件上传配置。", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是否启用图片上传。" }, "number_limits": { "type": "integer", "description": "可上传的最大图片数量。" }, "detail": { "type": "string", "description": "视觉模型的图像细节级别。" }, "transfer_methods": { "type": "array", "items": { "type": "string" }, "description": "图片上传允许的传输方式。`remote_url` 表示通过文件 URL 上传，`local_file` 表示上传本地文件。" } } } } }, "system_parameters": { "type": "object", "description": "系统级参数限制。", "properties": { "file_size_limit": { "type": "integer", "description": "常规文件最大大小（MB）。" }, "image_file_size_limit": { "type": "integer", "description": "最大图片文件大小（MB）。" }, "audio_file_size_limit": { "type": "integer", "description": "最大音频文件大小（MB）。" }, "video_file_size_limit": { "type": "integer", "description": "最大视频文件大小（MB）。" }, "workflow_file_upload_limit": { "type": "integer", "description": "每次工作流执行的最大文件数量。" } } } } }, "StreamEventWorkflowStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "工作流执行已开始。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "工作流运行 ID。" }, "workflow_id": { "type": "string", "description": "关联的工作流 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "本次工作流执行的输入变量。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间戳（Unix 纪元秒）。" }, "reason": { "type": "string", "description": "工作流启动原因。`initial` 表示首次启动，`resumption` 表示暂停后恢复（例如人工介入后）。" } } } } } ] }, "StreamEventWorkflowFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "工作流执行已完成。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "工作流运行 ID。" }, "workflow_id": { "type": "string", "description": "关联的工作流 ID。" }, "status": { "type": "string", "description": "执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`stopped` 表示手动停止，`partial-succeeded` 表示部分完成，`paused` 表示等待人工介入。" }, "outputs": { "type": "object", "nullable": true, "additionalProperties": true, "description": "工作流输出数据。" }, "error": { "type": "string", "nullable": true, "description": "执行失败时的错误消息。" }, "elapsed_time": { "type": "number", "description": "总执行耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "消耗的总令牌数。" }, "total_steps": { "type": "integer", "description": "已执行的总步数。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间戳（Unix 纪元秒）。" }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "结束时间戳（Unix 纪元秒）。" }, "exceptions_count": { "type": "integer", "nullable": true, "description": "执行期间的异常数量。" }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "工作流执行期间生成的文件。" } } } } } ] }, "StreamEventNodeStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "节点执行已开始。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" }, "node_type": { "type": "string", "description": "节点类型（例如 `llm`、`knowledge-retrieval`、`code`）。" }, "title": { "type": "string", "description": "Node title." }, "index": { "type": "integer", "description": "执行索引。" }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "前驱节点的 ID。" }, "inputs": { "type": "object", "nullable": true, "additionalProperties": true, "description": "节点输入数据。在简化 API 响应中可能为 `null`。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间戳（Unix 纪元秒）。" }, "extras": { "type": "object", "additionalProperties": true, "description": "附加元数据。" }, "iteration_id": { "type": "string", "nullable": true, "description": "如果该节点在迭代内运行，则为迭代 ID。" }, "loop_id": { "type": "string", "nullable": true, "description": "当该节点在循环内运行时的循环 ID。" } } } } } ] }, "StreamEventNodeFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "节点执行已完成。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "Node title." }, "index": { "type": "integer", "description": "执行索引。" }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "前驱节点的 ID。" }, "inputs": { "type": "object", "nullable": true, "additionalProperties": true, "description": "节点输入数据。在简化 API 响应中可能为 `null`。" }, "process_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "节点处理数据。在简化 API 响应中可能为 `null`。" }, "outputs": { "type": "object", "nullable": true, "additionalProperties": true, "description": "节点输出数据。在简化 API 响应中可能为 `null`。" }, "status": { "type": "string", "description": "节点执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。" }, "error": { "type": "string", "nullable": true, "description": "节点失败时的错误消息。" }, "elapsed_time": { "type": "number", "description": "节点执行耗时（秒）。" }, "execution_metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "执行元数据（例如令牌用量、模型信息）。在简化 API 响应中可能为 `null`。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间戳（Unix 纪元秒）。" }, "finished_at": { "type": "integer", "format": "int64", "description": "结束时间戳（Unix 纪元秒）。" }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "该节点生成的文件。" }, "iteration_id": { "type": "string", "nullable": true, "description": "如果该节点在迭代内运行，则为迭代 ID。" }, "loop_id": { "type": "string", "nullable": true, "description": "当该节点在循环内运行时的循环 ID。" } } } } } ] }, "StreamEventNodeRetry": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "节点重试次数。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "Node title." }, "index": { "type": "integer", "description": "执行索引。" }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "前驱节点的 ID。" }, "inputs": { "type": "object", "nullable": true, "additionalProperties": true, "description": "节点输入数据。" }, "process_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "节点处理数据。" }, "outputs": { "type": "object", "nullable": true, "additionalProperties": true, "description": "节点输出数据。" }, "status": { "type": "string", "description": "节点执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。" }, "error": { "type": "string", "nullable": true, "description": "本次重试的错误消息。" }, "elapsed_time": { "type": "number", "description": "本次尝试的执行时间（秒）。" }, "execution_metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "执行元数据。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间戳（Unix 纪元秒）。" }, "finished_at": { "type": "integer", "format": "int64", "description": "结束时间戳（Unix 纪元秒）。" }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "本次重试期间生成的文件。" }, "iteration_id": { "type": "string", "nullable": true, "description": "迭代 ID（如适用）。" }, "loop_id": { "type": "string", "nullable": true, "description": "循环 ID（如适用）。" }, "retry_index": { "type": "integer", "description": "重试次数索引，从 `0` 开始。" } } } } } ] }, "StreamEventIterationStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "迭代循环已开始。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "迭代执行 ID。" }, "node_id": { "type": "string", "description": "迭代节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "迭代节点标题。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间戳（Unix 纪元秒）。" }, "extras": { "type": "object", "additionalProperties": true, "description": "附加元数据。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "迭代元数据。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "迭代输入数据。" } } } } } ] }, "StreamEventIterationNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "迭代已进入下一项。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "迭代执行 ID。" }, "node_id": { "type": "string", "description": "迭代节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "迭代节点标题。" }, "index": { "type": "integer", "description": "当前迭代索引（从 0 开始）。" }, "created_at": { "type": "integer", "format": "int64", "description": "时间戳（Unix 纪元秒）。" }, "extras": { "type": "object", "additionalProperties": true, "description": "附加元数据。" } } } } } ] }, "StreamEventIterationCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "迭代循环已完成。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "迭代执行 ID。" }, "node_id": { "type": "string", "description": "迭代节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "迭代节点标题。" }, "outputs": { "type": "object", "nullable": true, "additionalProperties": true, "description": "迭代输出数据。" }, "status": { "type": "string", "description": "迭代执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。" }, "error": { "type": "string", "nullable": true, "description": "迭代失败时的错误消息。" }, "elapsed_time": { "type": "number", "description": "迭代总耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "所有迭代中消耗的令牌总数。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间戳（Unix 纪元秒）。" }, "finished_at": { "type": "integer", "format": "int64", "description": "结束时间戳（Unix 纪元秒）。" }, "steps": { "type": "integer", "description": "已执行的迭代步骤总数。" } } } } } ] }, "StreamEventLoopStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "循环已开始。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "循环执行 ID。" }, "node_id": { "type": "string", "description": "循环节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "循环节点标题。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间戳（Unix 纪元秒）。" }, "extras": { "type": "object", "additionalProperties": true, "description": "附加元数据。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "循环元数据。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "循环输入数据。" } } } } } ] }, "StreamEventLoopNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "循环已进入下一次迭代。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "循环执行 ID。" }, "node_id": { "type": "string", "description": "循环节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "循环节点标题。" }, "index": { "type": "integer", "description": "当前循环索引（从 0 开始）。" }, "created_at": { "type": "integer", "format": "int64", "description": "时间戳（Unix 纪元秒）。" }, "pre_loop_output": { "description": "上一次循环迭代的输出。" }, "extras": { "type": "object", "additionalProperties": true, "description": "附加元数据。" } } } } } ] }, "StreamEventLoopCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "循环已完成。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "循环执行 ID。" }, "node_id": { "type": "string", "description": "循环节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "循环节点标题。" }, "outputs": { "type": "object", "nullable": true, "additionalProperties": true, "description": "循环输出数据。" }, "status": { "type": "string", "description": "循环执行状态。`running` 表示进行中，`succeeded` 表示成功，`failed` 表示失败，`exception` 表示发生异常。" }, "error": { "type": "string", "nullable": true, "description": "循环失败时的错误消息。" }, "elapsed_time": { "type": "number", "description": "循环总执行耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "所有循环迭代中消耗的令牌总数。" }, "created_at": { "type": "integer", "format": "int64", "description": "开始时间戳（Unix 纪元秒）。" }, "finished_at": { "type": "integer", "format": "int64", "description": "结束时间戳（Unix 纪元秒）。" }, "steps": { "type": "integer", "description": "已执行的循环总步数。" } } } } } ] }, "StreamEventHumanInputRequired": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "form_id": { "type": "string", "description": "表单实例的标识符，会在错误消息和日志中出现。Service API 调用请使用 `form_token`。" }, "node_id": { "type": "string", "description": "产生该表单的 Human Input 节点 ID。" }, "node_title": { "type": "string", "description": "Human Input 节点的显示标题。" }, "form_content": { "type": "string", "description": "已替换工作流变量的预渲染表单正文。" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "表单输入控件类型。可用值：`paragraph`（多行文本输入）、`select`（从列表中单选）、`file`（单文件上传）和 `file-list`（多文件上传）。" }, "output_variable_name": { "type": "string", "description": "引用该输入提交值在工作流中使用的变量名。对应提交 `inputs` 对象中的键。" }, "default": { "type": "object", "nullable": true, "description": "从工作流上下文解析得到的默认值。未配置默认值时为 `null`。", "properties": { "type": { "type": "string", "description": "默认值来源。`constant` 表示将 `value` 作为字面字符串；`variable` 表示 `selector` 指向工作流变量。" }, "selector": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `variable` 时，变量引用路径（例如 `[\"node_id\", \"var_name\"]`）。至少包含两个元素。" }, "value": { "type": "string", "description": "当 `type` 为 `constant` 时的字面默认值。始终为字符串。" } } } } }, "description": "接收者需要填写的表单输入字段。" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "操作按钮的标识。当接收者选择该按钮时，作为 `action` 传入 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form)。" }, "title": { "type": "string", "maxLength": 100, "description": "显示给接收者的按钮文本。" }, "button_style": { "type": "string", "description": "按钮视觉样式。可用值：`primary`、`default`、`accent`、`ghost`。" } } }, "description": "接收者提交时可选择的用户操作（按钮）。" }, "display_in_ui": { "type": "boolean", "description": "表单是否也在 Dify 控制台中显示。" }, "form_token": { "type": "string", "nullable": true, "description": "[获取人工介入表单](/zh/api-reference/human-input/get-human-input-form) 和 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form) 的访问令牌。当人工介入节点使用邮件或控制台送达时为 `null`（Service API 仅能处理 WebApp 送达的表单）。" }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "按输入的 `output_variable_name` 分组的预填充默认值。所有值均为字符串。" }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix 时间戳（秒），超过后表单无法再被提交。" } } } } } ] }, "StreamEventWorkflowPaused": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/zh/api-reference/workflow-runs/get-workflow-run-detail) 使用以在执行后获取结果。" }, "paused_nodes": { "type": "array", "items": { "type": "string" }, "description": "已暂停的节点 ID 列表。" }, "outputs": { "type": "object", "additionalProperties": true, "description": "暂停时的部分输出。" }, "reasons": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "暂停原因。" }, "status": { "type": "string", "description": "工作流执行状态。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" }, "elapsed_time": { "type": "number", "format": "float", "description": "总耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "消耗的总令牌数。" }, "total_steps": { "type": "integer", "description": "已执行的总步数。" } } } } } ] }, "StreamEventHumanInputFormFilled": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "表单被填写的 Human Input 节点 ID。" }, "node_title": { "type": "string", "description": "Human Input 节点的显示标题。" }, "rendered_content": { "type": "string", "description": "包含接收者提交值的渲染后表单内容（`human_input_required` 上的 `form_content` 是未填写的模板）。" }, "action_id": { "type": "string", "description": "接收者所选操作的标识（与传入 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form) 的 `action` 一致）。" }, "action_text": { "type": "string", "description": "所选操作的显示文本。" }, "submitted_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "接收者提交的表单值，以各输入项的 `output_variable_name` 为键。" } } } } } ] }, "StreamEventHumanInputFormTimeout": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "表单过期的 Human Input 节点 ID。" }, "node_title": { "type": "string", "description": "Human Input 节点的显示标题。" }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix 时间戳（秒），表示表单过期时刻。" } } } } } ] }, "StreamEventAgentLog": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "description": "工作流中 Agent 节点的 Agent 日志。", "properties": { "data": { "type": "object", "properties": { "node_execution_id": { "type": "string", "description": "节点执行 ID。" }, "id": { "type": "string", "description": "日志条目 ID。" }, "label": { "type": "string", "description": "日志条目标签。" }, "parent_id": { "type": "string", "nullable": true, "description": "嵌套条目的父日志条目 ID。" }, "error": { "type": "string", "nullable": true, "description": "错误消息（如适用）。" }, "status": { "type": "string", "description": "日志条目状态。" }, "data": { "type": "object", "additionalProperties": true, "description": "日志条目数据。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "附加元数据。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" } } } } } ] }, "StreamEventChatReasoningChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "message_id": { "type": "string", "format": "uuid", "description": "此推理内容所属消息的 ID（与顶层 `message_id` 一致）。" }, "reasoning": { "type": "string", "description": "由 `reasoning_format` 为 `separated` 的 LLM 节点发送的推理内容增量。拼接连续的 `reasoning_chunk` 事件即可还原完整推理内容。本流与 `message` 并行；`message`（回答）流不含 `` 标签。" }, "node_id": { "type": "string", "nullable": true, "description": "产生该推理内容的 LLM 节点 ID。当多个 LLM 节点运行时，可据此归属推理内容。" }, "is_final": { "type": "boolean", "description": "`true` 标志 LLM 节点推理阶段结束（即「思考完成」信号）；该事件的 `reasoning` 可能为空。" } } } } } ] }, "StreamEventChatTextChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string", "description": "文本内容块。" }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "工作流中文本变量的源路径。" } } } } } ] }, "WorkflowRunDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "工作流运行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "工作流 ID." }, "status": { "type": "string", "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" }, "inputs": { "type": "string", "nullable": true, "description": "工作流运行的输入变量，以原始 JSON 字符串返回（例如 `{\"query\": \"...\"}`），客户端需自行解析；可能为 `null`。" }, "outputs": { "type": "object", "additionalProperties": true, "description": "工作流的输出数据。尚无输出时为空对象。" }, "error": { "type": "string", "nullable": true, "description": "工作流失败时的错误消息。" }, "total_steps": { "type": "integer", "description": "已执行的工作流总步数。" }, "total_tokens": { "type": "integer", "description": "消耗的总令牌数。" }, "created_at": { "type": "integer", "format": "int64", "description": "工作流运行创建时的 Unix 时间戳。" }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "工作流运行结束时的 Unix 时间戳。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "总耗时（秒）。" } } }, "WorkflowLogsResponse": { "type": "object", "properties": { "page": { "type": "integer", "description": "当前页码。" }, "limit": { "type": "integer", "description": "每页条目数。" }, "total": { "type": "integer", "description": "日志条目总数。" }, "has_more": { "type": "boolean", "description": "是否有更多可用页面。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowLogItem" }, "description": "工作流日志条目列表。" } } }, "WorkflowLogItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "日志条目 ID。" }, "workflow_run": { "$ref": "#/components/schemas/WorkflowRunSummary" }, "created_from": { "type": "string", "description": "工作流运行的来源（例如 `service-api`）。" }, "created_by_role": { "type": "string", "description": "创建者的角色（例如 `end_user`、`account`）。" }, "created_by_account": { "type": "object", "nullable": true, "description": "由管理员用户创建时的账户详情。", "properties": { "id": { "type": "string", "format": "uuid", "description": "账户 ID。" }, "name": { "type": "string", "description": "账户显示名称。" }, "email": { "type": "string", "description": "账户邮箱地址。" } } }, "created_by_end_user": { "$ref": "#/components/schemas/EndUserSummary" }, "created_at": { "type": "integer", "format": "int64", "description": "日志条目创建时的 Unix 时间戳。" }, "details": { "type": "object", "additionalProperties": true, "nullable": true, "description": "日志条目的附加详情。" } } }, "WorkflowRunSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "工作流运行 ID。" }, "version": { "type": "string", "description": "工作流版本标识符。" }, "status": { "type": "string", "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" }, "error": { "type": "string", "nullable": true, "description": "工作流失败时的错误消息。" }, "elapsed_time": { "type": "number", "format": "float", "description": "总耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "消耗的总令牌数。" }, "total_steps": { "type": "integer", "description": "已执行的工作流总步数。" }, "created_at": { "type": "integer", "format": "int64", "description": "工作流运行创建时的 Unix 时间戳。" }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "工作流运行结束时的 Unix 时间戳。" }, "exceptions_count": { "type": "integer", "description": "执行期间发生的异常数量。" }, "triggered_from": { "type": "string", "description": "触发工作流运行的来源。`app-run` 表示从应用或 API 发起的运行，`webhook` 表示由 Webhook 触发器发起的运行，`schedule` 表示由定时触发器发起的运行，`plugin` 表示由插件触发器发起的运行。" } } }, "EndUserSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "终端用户 ID。" }, "type": { "type": "string", "description": "终端用户类型。" }, "is_anonymous": { "type": "boolean", "description": "终端用户是否为匿名。" }, "session_id": { "type": "string", "description": "会话标识符。" } } }, "HumanInputContent": { "type": "object", "description": "人工介入节点的执行内容，包括表单定义和提交数据。", "properties": { "workflow_run_id": { "type": "string", "description": "该内容所属的工作流运行 ID。" }, "submitted": { "type": "boolean", "description": "人工介入表单是否已提交。" }, "type": { "type": "string", "description": "`human_input` 表示人工介入内容。" }, "form_definition": { "nullable": true, "description": "人工介入节点的表单定义。当内容表示提交响应时为 `null`。", "$ref": "#/components/schemas/HumanInputFormDefinition" }, "form_submission_data": { "nullable": true, "description": "已提交的表单数据。表单尚未提交时为 `null`。", "$ref": "#/components/schemas/HumanInputFormSubmissionData" } } }, "HumanInputFormDefinition": { "type": "object", "description": "由人工介入节点渲染的人工介入表单定义。", "properties": { "form_id": { "type": "string", "description": "表单唯一标识符。" }, "node_id": { "type": "string", "description": "生成该表单的人工介入节点 ID。" }, "node_title": { "type": "string", "description": "人工介入节点的标题。" }, "form_content": { "type": "string", "description": "与表单一起显示的 Markdown 或文本内容。" }, "inputs": { "type": "array", "description": "表单中的输入字段。", "items": { "$ref": "#/components/schemas/FormInput" } }, "actions": { "type": "array", "description": "表单上可用的操作按钮。", "items": { "$ref": "#/components/schemas/UserAction" } }, "display_in_ui": { "type": "boolean", "description": "表单是否应在 UI 中显示。" }, "form_token": { "type": "string", "nullable": true, "description": "表单提交认证的令牌。" }, "resolved_default_values": { "type": "object", "additionalProperties": true, "description": "表单输入的已解析默认值，按输出变量名称索引。" }, "expiration_time": { "type": "integer", "description": "表单过期的 Unix 时间戳。" } } }, "HumanInputFormSubmissionData": { "type": "object", "description": "来自已提交的人工介入表单的数据。", "properties": { "node_id": { "type": "string", "description": "人工介入节点的 ID。" }, "node_title": { "type": "string", "description": "人工介入节点的标题。" }, "rendered_content": { "type": "string", "description": "表单提交的渲染内容。" }, "action_id": { "type": "string", "description": "被点击的操作按钮的 ID。" }, "action_text": { "type": "string", "description": "被点击的操作按钮的显示文本。" } } }, "FormInput": { "type": "object", "description": "表单输入字段定义。", "properties": { "type": { "type": "string", "description": "表单输入控件类型。可用值：`paragraph`（多行文本输入）、`select`（从列表中单选）、`file`（单文件上传）和 `file-list`（多文件上传）。" }, "output_variable_name": { "type": "string", "description": "存储输入值的变量名称。" }, "default": { "nullable": true, "description": "该输入的默认值配置。", "$ref": "#/components/schemas/FormInputDefault" } } }, "FormInputDefault": { "type": "object", "description": "表单输入的默认值配置。", "properties": { "type": { "type": "string", "description": "`variable` for dynamic values from 工作流 variables, `constant` for static values." }, "selector": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `variable` 时的变量选择器路径。" }, "value": { "type": "string", "description": "当 `type` 为 `constant` 时的静态值。" } } }, "UserAction": { "type": "object", "description": "人工介入表单上的操作按钮。", "properties": { "id": { "type": "string", "description": "操作唯一标识符。" }, "title": { "type": "string", "description": "按钮显示文本。" }, "button_style": { "type": "string", "description": "`primary`, `default`, `accent`, or `ghost`." } } }, "WorkflowExecutionRequest": { "type": "object", "required": [ "inputs", "user" ], "properties": { "inputs": { "type": "object", "description": "工作流输入变量的键值对。变量名称和类型可从 [获取应用参数](/zh/api-reference/applications/get-app-parameters) 响应中的 `user_input_form` 字段获取。\n\n文件类型变量的值为文件对象数组，包含 `type`、`transfer_method` 以及 `url` 或 `upload_file_id`。", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" } } ] } }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "响应模式。使用 `blocking` 获取同步响应（Cloudflare 超时时间为 `100 s`），使用 `streaming` 获取服务器发送事件。未指定时默认为阻塞模式。" }, "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。用于限定数据访问范围：工作流运行及其文件仅对携带相同 `user` 的后续请求可见。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, "nullable": true, "description": "文件列表。适用于需要将文件与文本组合输入的场景，仅在模型支持 Vision 能力时可用。要附加本地文件，请先通过 [上传文件](/zh/api-reference/files/upload-file) 上传，然后将返回的 `id` 作为 `upload_file_id`，并设置 `transfer_method: local_file`。" } } }, "InputFileObject": { "type": "object", "required": [ "type", "transfer_method" ], "properties": { "type": { "type": "string", "enum": [ "image", "document", "audio", "video", "custom" ], "description": "文件类型。" }, "transfer_method": { "type": "string", "enum": [ "remote_url", "local_file" ], "description": "传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。" }, "url": { "type": "string", "format": "url", "description": "文件 URL（当 `transfer_method` 为 `remote_url` 时）。" }, "upload_file_id": { "type": "string", "description": "已上传文件 ID，通过 [上传文件](/zh/api-reference/files/upload-file) API 预先上传获取（当 `transfer_method` 为 `local_file` 时使用）。" } }, "anyOf": [ { "properties": { "transfer_method": { "enum": [ "remote_url" ] }, "url": { "type": "string", "format": "url" } }, "required": [ "url" ], "not": { "required": [ "upload_file_id" ] } }, { "properties": { "transfer_method": { "enum": [ "local_file" ] }, "upload_file_id": { "type": "string" } }, "required": [ "upload_file_id" ], "not": { "required": [ "url" ] } } ] }, "WorkflowBlockingResponse": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "进行中的执行任务 ID。配合 [停止工作流任务](/zh/api-reference/workflow-runs/stop-workflow-task) 使用以取消运行中的工作流。仅在执行期间有效。" }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/zh/api-reference/workflow-runs/get-workflow-run-detail) 使用以在执行后获取结果。" }, "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } }, "ChunkWorkflowEvent": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "enum": [ "workflow_started", "node_started", "node_finished", "node_retry", "iteration_started", "iteration_next", "iteration_completed", "loop_started", "loop_next", "loop_completed", "reasoning_chunk", "text_chunk", "workflow_finished", "tts_message", "tts_message_end", "workflow_paused", "agent_log", "human_input_required", "human_input_form_filled", "human_input_form_timeout", "error", "ping" ], "description": "流式事件的类型。" } }, "discriminator": { "propertyName": "event", "mapping": { "workflow_started": "#/components/schemas/WorkflowStreamEventWorkflowStarted", "node_started": "#/components/schemas/WorkflowStreamEventNodeStarted", "node_finished": "#/components/schemas/WorkflowStreamEventNodeFinished", "node_retry": "#/components/schemas/WorkflowStreamEventNodeRetry", "iteration_started": "#/components/schemas/WorkflowStreamEventIterationStarted", "iteration_next": "#/components/schemas/WorkflowStreamEventIterationNext", "iteration_completed": "#/components/schemas/WorkflowStreamEventIterationCompleted", "loop_started": "#/components/schemas/WorkflowStreamEventLoopStarted", "loop_next": "#/components/schemas/WorkflowStreamEventLoopNext", "loop_completed": "#/components/schemas/WorkflowStreamEventLoopCompleted", "reasoning_chunk": "#/components/schemas/StreamEventReasoningChunk", "text_chunk": "#/components/schemas/StreamEventTextChunk", "workflow_finished": "#/components/schemas/WorkflowStreamEventWorkflowFinished", "tts_message": "#/components/schemas/StreamEventTtsMessage", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", "error": "#/components/schemas/StreamEventError", "ping": "#/components/schemas/StreamEventPing", "workflow_paused": "#/components/schemas/WorkflowStreamEventWorkflowPaused", "agent_log": "#/components/schemas/WorkflowStreamEventAgentLog", "human_input_required": "#/components/schemas/WorkflowStreamEventHumanInputRequired", "human_input_form_filled": "#/components/schemas/WorkflowStreamEventHumanInputFormFilled", "human_input_form_timeout": "#/components/schemas/WorkflowStreamEventHumanInputFormTimeout" } } }, "StreamEventReasoningChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "reasoning": { "type": "string", "description": "由 `reasoning_format` 为 `separated` 的 LLM 节点发送的推理内容增量。拼接连续的 `reasoning_chunk` 事件即可还原完整推理内容。本流与 `text_chunk` 并行；`text` 流不含 `` 标签。" }, "node_id": { "type": "string", "nullable": true, "description": "产生该推理内容的 LLM 节点 ID。当多个 LLM 节点运行时，可据此归属推理内容。" }, "is_final": { "type": "boolean", "description": "`true` 标志 LLM 节点推理阶段结束（即「思考完成」信号）；该事件的 `reasoning` 可能为空。" } } } } } ] }, "StreamEventTextChunk": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string", "description": "文本内容块。" }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "工作流中文本变量的源路径。" } } } } } ] }, "StreamEventTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。" }, "created_at": { "type": "integer", "format": "int64", "description": "该音频块生成时的 Unix 时间戳。" } } } ] }, "StreamEventTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "audio": { "type": "string", "description": "空字符串。标识音频流结束。" }, "created_at": { "type": "integer", "format": "int64", "description": "音频流结束时的 Unix 时间戳。" } } } ] }, "StreamEventError": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "status": { "type": "integer", "description": "错误的 HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误信息。" } } } ] }, "StreamEventPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "type": "object", "description": "保活 ping 事件。无附加属性。" } ] }, "WorkflowFinishedData": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "工作流运行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "工作流 ID." }, "status": { "type": "string", "description": "工作流执行状态。`running` 表示执行中，`succeeded` 表示成功完成，`failed` 表示执行出错，`stopped` 表示手动停止，`partial-succeeded` 表示部分节点成功但其他失败，`paused` 表示等待人工介入。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "工作流的输出数据。" }, "error": { "type": "string", "nullable": true, "description": "工作流失败时的错误消息。" }, "elapsed_time": { "type": "number", "format": "float", "description": "总耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "所有节点消耗的总令牌数。" }, "total_steps": { "type": "integer", "description": "已执行的工作流总步数。" }, "created_at": { "type": "integer", "format": "int64", "description": "工作流运行创建时的 Unix 时间戳。" }, "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "工作流运行结束时的 Unix 时间戳。" }, "created_by": { "type": "object", "additionalProperties": true, "description": "创建者信息。仅存在于流式 `workflow_finished` 事件中。" }, "exceptions_count": { "type": "integer", "nullable": true, "description": "执行过程中遇到的异常数量。仅在流式 `workflow_finished` 事件中出现。" }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "nullable": true, "description": "工作流执行期间生成的文件。仅存在于流式 `workflow_finished` 事件中。" } } }, "WorkflowStreamEventBase": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "进行中的执行任务 ID。配合 [停止工作流任务](/zh/api-reference/workflow-runs/stop-workflow-task) 使用以取消运行中的工作流。仅在执行期间有效。" }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/zh/api-reference/workflow-runs/get-workflow-run-detail) 使用以在执行后获取结果。" } } }, "WorkflowStreamEventWorkflowStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "工作流运行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "工作流 ID." }, "inputs": { "type": "object", "additionalProperties": true, "description": "本次工作流运行的输入变量。" }, "created_at": { "type": "integer", "format": "int64", "description": "工作流运行开始时的 Unix 时间戳。" }, "reason": { "type": "string", "description": "工作流启动原因。`initial` 表示新执行，`resumption` 表示从暂停状态恢复。" } } } } } ] }, "WorkflowStreamEventWorkflowFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } } ] }, "WorkflowStreamEventNodeStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" }, "node_type": { "type": "string", "description": "节点类型（例如 `llm`、`code`、`template-transform`）。" }, "title": { "type": "string", "description": "节点的显示名称。" }, "index": { "type": "integer", "description": "执行序列索引。" }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "前驱节点的 ID（如有）。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "该节点的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "created_at": { "type": "integer", "format": "int64", "description": "节点执行开始时的 Unix 时间戳。" }, "extras": { "type": "object", "additionalProperties": true, "description": "节点执行的附加元数据。" }, "iteration_id": { "type": "string", "nullable": true, "description": "如果该节点在迭代内运行，则为父迭代 ID。" }, "loop_id": { "type": "string", "nullable": true, "description": "如果该节点在循环内运行，则为父循环 ID。" } } } } } ] }, "WorkflowStreamEventNodeFinished": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "节点的显示名称。" }, "index": { "type": "integer", "description": "执行序列索引。" }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "前驱节点的 ID（如有）。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "该节点的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点执行期间生成的处理数据。" }, "process_data_truncated": { "type": "boolean", "description": "`process_data` 是否被截断。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点的输出数据。" }, "outputs_truncated": { "type": "boolean", "description": "`outputs` 数据是否被截断。" }, "status": { "type": "string", "description": "节点执行状态。`running` 表示进行中，`succeeded` 表示已完成，`failed` 表示出错，`stopped` 表示手动停止，`exception` 表示意外失败。" }, "error": { "type": "string", "nullable": true, "description": "节点失败时的错误消息。" }, "elapsed_time": { "type": "number", "format": "float", "description": "耗时（秒）。" }, "execution_metadata": { "type": "object", "nullable": true, "description": "执行元数据，包含令牌用量。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "该节点消耗的总令牌数。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "该节点执行的总费用。" }, "currency": { "type": "string", "nullable": true, "description": "费用货币（例如 `USD`）。" } } }, "created_at": { "type": "integer", "format": "int64", "description": "节点执行开始时的 Unix 时间戳。" }, "finished_at": { "type": "integer", "format": "int64", "description": "节点执行结束时的 Unix 时间戳。" }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "该节点生成的文件。" }, "iteration_id": { "type": "string", "nullable": true, "description": "如果该节点在迭代内运行，则为父迭代 ID。" }, "loop_id": { "type": "string", "nullable": true, "description": "如果该节点在循环内运行，则为父循环 ID。" } } } } } ] }, "WorkflowStreamEventNodeRetry": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "工作流图中的节点 ID。" }, "node_type": { "type": "string", "description": "Node type." }, "title": { "type": "string", "description": "节点的显示名称。" }, "index": { "type": "integer", "description": "执行序列索引。" }, "predecessor_node_id": { "type": "string", "nullable": true, "description": "前驱节点的 ID（如有）。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点执行期间生成的处理数据。" }, "process_data_truncated": { "type": "boolean", "description": "`process_data` 是否被截断。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "`outputs` 数据是否被截断。" }, "status": { "type": "string", "description": "重试点的节点执行状态。" }, "error": { "type": "string", "nullable": true, "description": "触发重试的错误消息。" }, "elapsed_time": { "type": "number", "format": "float", "description": "耗时（秒）。" }, "created_at": { "type": "integer", "format": "int64" }, "finished_at": { "type": "integer", "format": "int64" }, "retry_index": { "type": "integer", "description": "从零开始的重试次数索引。" }, "iteration_id": { "type": "string", "nullable": true }, "loop_id": { "type": "string", "nullable": true }, "execution_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点执行的元数据。" }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "节点在执行期间生成的文件。" } } } } } ] }, "WorkflowStreamEventIterationStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "节点执行 ID。" }, "node_id": { "type": "string", "description": "迭代节点 ID。" }, "node_type": { "type": "string", "description": "节点类型（始终为 `iteration`）。" }, "title": { "type": "string", "description": "迭代节点的显示名称。" }, "created_at": { "type": "integer", "format": "int64" }, "inputs": { "type": "object", "additionalProperties": true, "description": "迭代的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "迭代元数据。" }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "WorkflowStreamEventIterationNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer", "description": "当前迭代索引（从零开始）。" }, "created_at": { "type": "integer", "format": "int64" }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "WorkflowStreamEventIterationCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "`outputs` 数据是否被截断。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "迭代的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "created_at": { "type": "integer", "format": "int64", "description": "迭代开始时的 Unix 时间戳。" }, "extras": { "type": "object", "additionalProperties": true, "nullable": true, "description": "迭代的附加元数据。" }, "status": { "type": "string", "description": "迭代完成状态。" }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float" }, "total_tokens": { "type": "integer" }, "execution_metadata": { "type": "object", "additionalProperties": true, "description": "执行元数据，包含令牌用量。" }, "finished_at": { "type": "integer", "format": "int64" }, "steps": { "type": "integer", "description": "已完成的迭代步数。" } } } } } ] }, "WorkflowStreamEventLoopStarted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "created_at": { "type": "integer", "format": "int64" }, "inputs": { "type": "object", "additionalProperties": true }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "metadata": { "type": "object", "additionalProperties": true }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "WorkflowStreamEventLoopNext": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer", "description": "当前循环迭代索引（从零开始）。" }, "created_at": { "type": "integer", "format": "int64" }, "pre_loop_output": { "description": "上一次循环迭代的输出。", "nullable": true }, "extras": { "type": "object", "additionalProperties": true } } } } } ] }, "WorkflowStreamEventLoopCompleted": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs_truncated": { "type": "boolean", "description": "`outputs` 数据是否被截断。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "循环的输入变量。" }, "inputs_truncated": { "type": "boolean", "description": "`inputs` 数据是否被截断。" }, "created_at": { "type": "integer", "format": "int64" }, "extras": { "type": "object", "additionalProperties": true, "nullable": true, "description": "循环的附加元数据。" }, "status": { "type": "string", "description": "循环完成状态。" }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float" }, "total_tokens": { "type": "integer" }, "execution_metadata": { "type": "object", "additionalProperties": true, "description": "执行元数据，包含令牌用量。" }, "finished_at": { "type": "integer", "format": "int64" }, "steps": { "type": "integer", "description": "已完成的循环迭代次数。" } } } } } ] }, "WorkflowStreamEventHumanInputRequired": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "form_id": { "type": "string", "description": "表单实例的标识符，会在错误消息和日志中出现。Service API 调用请使用 `form_token`。" }, "node_id": { "type": "string", "description": "产生该表单的 Human Input 节点 ID。" }, "node_title": { "type": "string", "description": "Human Input 节点的显示标题。" }, "form_content": { "type": "string", "description": "已替换工作流变量的预渲染表单正文。" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "表单输入控件类型。可用值：`paragraph`（多行文本输入）、`select`（从列表中单选）、`file`（单文件上传）和 `file-list`（多文件上传）。" }, "output_variable_name": { "type": "string", "description": "引用该输入提交值在工作流中使用的变量名。对应提交 `inputs` 对象中的键。" }, "default": { "type": "object", "nullable": true, "description": "从工作流上下文解析得到的默认值。未配置默认值时为 `null`。", "properties": { "type": { "type": "string", "description": "默认值来源。`constant` 表示将 `value` 作为字面字符串；`variable` 表示 `selector` 指向工作流变量。" }, "selector": { "type": "array", "items": { "type": "string" }, "description": "当 `type` 为 `variable` 时，变量引用路径（例如 `[\"node_id\", \"var_name\"]`）。至少包含两个元素。" }, "value": { "type": "string", "description": "当 `type` 为 `constant` 时的字面默认值。始终为字符串。" } } } } }, "description": "接收者需要填写的表单输入字段。" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "操作按钮的标识。当接收者选择该按钮时，作为 `action` 传入 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form)。" }, "title": { "type": "string", "maxLength": 100, "description": "显示给接收者的按钮文本。" }, "button_style": { "type": "string", "description": "按钮视觉样式。可用值：`primary`、`default`、`accent`、`ghost`。" } } }, "description": "接收者提交时可选择的用户操作（按钮）。" }, "display_in_ui": { "type": "boolean", "description": "表单是否也在 Dify 控制台中显示。" }, "form_token": { "type": "string", "nullable": true, "description": "[获取人工介入表单](/zh/api-reference/human-input/get-human-input-form) 和 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form) 的访问令牌。当人工介入节点使用邮件或控制台送达时为 `null`（Service API 仅能处理 WebApp 送达的表单）。" }, "resolved_default_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "按输入的 `output_variable_name` 分组的预填充默认值。所有值均为字符串。" }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix 时间戳（秒），超过后表单无法再被提交。" } } } } } ] }, "WorkflowStreamEventWorkflowPaused": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "workflow_run_id": { "type": "string", "format": "uuid", "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/zh/api-reference/workflow-runs/get-workflow-run-detail) 使用以在执行后获取结果。" }, "paused_nodes": { "type": "array", "items": { "type": "string" }, "description": "已暂停的节点 ID 列表。" }, "outputs": { "type": "object", "additionalProperties": true, "description": "暂停时的部分输出。" }, "reasons": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "暂停原因。" }, "status": { "type": "string", "description": "工作流执行状态。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" }, "elapsed_time": { "type": "number", "format": "float", "description": "总耗时（秒）。" }, "total_tokens": { "type": "integer", "description": "消耗的总令牌数。" }, "total_steps": { "type": "integer", "description": "已执行的总步数。" } } } } } ] }, "WorkflowStreamEventHumanInputFormFilled": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "表单被填写的 Human Input 节点 ID。" }, "node_title": { "type": "string", "description": "Human Input 节点的显示标题。" }, "rendered_content": { "type": "string", "description": "包含接收者提交值的渲染后表单内容（`human_input_required` 上的 `form_content` 是未填写的模板）。" }, "action_id": { "type": "string", "description": "接收者所选操作的标识（与传入 [提交人工介入表单](/zh/api-reference/human-input/submit-human-input-form) 的 `action` 一致）。" }, "action_text": { "type": "string", "description": "所选操作的显示文本。" }, "submitted_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "接收者提交的表单值，以各输入项的 `output_variable_name` 为键。" } } } } } ] }, "WorkflowStreamEventHumanInputFormTimeout": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_id": { "type": "string", "description": "表单过期的 Human Input 节点 ID。" }, "node_title": { "type": "string", "description": "Human Input 节点的显示标题。" }, "expiration_time": { "type": "integer", "format": "int64", "description": "Unix 时间戳（秒），表示表单过期时刻。" } } } } } ] }, "WorkflowStreamEventAgentLog": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/WorkflowStreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "node_execution_id": { "type": "string", "description": "节点执行 ID。" }, "id": { "type": "string", "description": "Agent 日志条目 ID。" }, "label": { "type": "string", "description": "Log label." }, "parent_id": { "type": "string", "nullable": true, "description": "父日志条目 ID。" }, "error": { "type": "string", "nullable": true, "description": "Agent 步骤失败时的错误消息。" }, "status": { "type": "string", "description": "Agent 步骤状态。" }, "data": { "type": "object", "additionalProperties": true, "description": "Agent 步骤数据。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Agent 步骤元数据。" }, "node_id": { "type": "string", "description": "Node ID." } } } } } ] }, "CompletionRequest": { "type": "object", "required": [ "inputs", "user" ], "properties": { "inputs": { "type": "object", "description": "应用输入变量的值，以变量名为键。变量名称和类型可从 [获取应用参数](/zh/api-reference/applications/get-app-parameters) 响应中的 `user_input_form` 字段获取。", "additionalProperties": true }, "query": { "type": "string", "default": "", "description": "要处理的文本。旧版字段；较新的应用改为在 `inputs` 中传递。" }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "响应返回模式。`streaming`（推荐）使用 SSE。`blocking` 等待完成后返回（长时间处理可能会被中断）。Cloudflare 超时为 `100 s`。省略时默认为阻塞模式。" }, "user": { "type": "string", "description": "终端用户标识，由你的应用定义，需在应用内唯一。消息和文件仅对携带相同 `user` 的请求可见。参见 [终端用户身份](/zh/api-reference/guides/end-user-identity)。" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, "description": "要附加到请求的文件。本地文件需先通过 [上传文件](/zh/api-reference/files/upload-file) 上传，再将返回的 `id` 作为 `upload_file_id` 引用，并设置 `transfer_method: local_file`。" } } }, "CompletionResponse": { "type": "object", "properties": { "event": { "type": "string", "description": "事件类型，固定为 `message`。" }, "task_id": { "type": "string", "format": "uuid", "description": "用于请求追踪和 [停止响应](/zh/api-reference/completion-messages/stop-completion-message-generation) API 的任务 ID。" }, "id": { "type": "string", "format": "uuid", "description": "该响应事件的唯一 ID。" }, "message_id": { "type": "string", "format": "uuid", "description": "唯一的消息 ID。调用反馈或推荐问题接口时，将此值作为 `message_id` 参数使用。" }, "mode": { "type": "string", "description": "应用模式，固定为 `completion`。" }, "answer": { "type": "string", "description": "完整的响应内容。" }, "metadata": { "type": "object", "description": "包含用量和检索资源的元数据。", "properties": { "usage": { "$ref": "#/components/schemas/Usage" }, "retriever_resources": { "type": "array", "description": "使用的检索资源列表。", "items": { "$ref": "#/components/schemas/RetrieverResource" } } } }, "created_at": { "type": "integer", "format": "int64", "description": "消息创建时间戳（Unix 纪元秒）。" } } }, "ChunkCompletionEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "message", "message_end", "message_file", "tts_message", "tts_message_end", "message_replace", "error", "ping" ], "description": "流式事件的类型。" } }, "discriminator": { "propertyName": "event", "mapping": { "message": "#/components/schemas/StreamEventMessage", "message_end": "#/components/schemas/StreamEventMessageEnd", "message_file": "#/components/schemas/StreamEventMessageFile", "tts_message": "#/components/schemas/CompletionStreamEventTtsMessage", "tts_message_end": "#/components/schemas/CompletionStreamEventTtsMessageEnd", "message_replace": "#/components/schemas/StreamEventMessageReplace", "error": "#/components/schemas/CompletionStreamEventError", "ping": "#/components/schemas/CompletionStreamEventPing" } } }, "StreamEventMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "LLM 返回文本块事件。", "properties": { "answer": { "type": "string", "description": "LLM 返回的文本块内容。" } } } ] }, "StreamEventMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "消息结束事件，收到此事件表示流式输出已结束。", "properties": { "id": { "type": "string", "format": "uuid", "description": "消息的唯一 ID。" }, "metadata": { "type": "object", "description": "包含用量和检索资源的元数据。", "properties": { "usage": { "$ref": "#/components/schemas/Usage" }, "retriever_resources": { "type": "array", "description": "使用的检索资源列表。", "items": { "$ref": "#/components/schemas/RetrieverResource" } } } }, "files": { "type": "array", "nullable": true, "description": "本次消息生成的文件，例如模型生成的图片。未生成任何文件时为 `null`。", "items": { "type": "object", "properties": { "related_id": { "type": "string", "description": "消息文件记录的 ID。" }, "type": { "type": "string", "description": "文件类型，例如 `image`。" }, "filename": { "type": "string", "description": "文件名。" }, "extension": { "type": "string", "description": "文件扩展名，包含前导点，例如 `.png`。" }, "mime_type": { "type": "string", "description": "文件的 MIME 类型。" }, "size": { "type": "integer", "description": "文件大小，单位为字节。" }, "transfer_method": { "type": "string", "description": "文件的引用方式：`remote_url`、`local_file` 或 `tool_file`。" }, "url": { "type": "string", "description": "文件的可访问 URL。" }, "upload_file_id": { "type": "string", "description": "关联的上传文件 ID。" }, "remote_url": { "type": "string", "nullable": true, "description": "当文件以远程 URL 形式提供时的原始远程 URL，否则为空字符串。" } } } } } } ] }, "StreamEventMessageFile": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "type": "object", "description": "消息文件事件，生成过程中产生的文件（通常为模型生成的图片）。", "properties": { "id": { "type": "string", "format": "uuid", "description": "文件唯一 ID。" }, "type": { "type": "string", "description": "文件类型，例如 `image`。" }, "belongs_to": { "type": "string", "enum": [ "assistant" ], "description": "该文件的归属方，此处始终为 `assistant`。" }, "url": { "type": "string", "format": "url", "description": "文件的远程 URL。" } } } ] }, "StreamEventMessageReplace": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "消息内容替换事件（例如由于内容审核）。", "properties": { "answer": { "type": "string", "description": "替换内容。" }, "reason": { "type": "string", "description": "内容替换的原因。" } } } ] }, "CompletionStreamEventBase": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "message_id": { "type": "string", "format": "uuid", "description": "唯一消息 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时间戳。" } } }, "CompletionStreamEventTtsMessage": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "TTS 音频流事件（base64 编码的 MP3）。在启用自动播放时可用。", "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。" } } } ] }, "CompletionStreamEventTtsMessageEnd": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "TTS 音频流结束事件。", "properties": { "audio": { "type": "string", "description": "空字符串。标识音频流结束。" } } } ] }, "CompletionStreamEventError": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "$ref": "#/components/schemas/CompletionStreamEventBase" }, { "type": "object", "description": "流式输出过程中的错误事件。", "properties": { "status": { "type": "integer", "description": "HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误信息。" } } } ] }, "CompletionStreamEventPing": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEvent" }, { "type": "object", "description": "Ping 事件，用于保持连接活跃。" } ] }, "Dataset": { "type": "object", "properties": { "id": { "type": "string", "description": "知识库的唯一标识符。" }, "name": { "type": "string", "description": "知识库的显示名称。在工作区内唯一。" }, "description": { "type": "string", "description": "描述知识库用途或内容的可选文本。" }, "provider": { "type": "string", "description": "供应商类型。内部管理为 `vendor`，外部知识库连接为 `external`。" }, "permission": { "type": "string", "description": "控制谁可以访问此知识库。可选值：`only_me`、`all_team_members`、`partial_members`。" }, "data_source_type": { "type": "string", "description": "文档的数据源类型，尚未配置时为 `null`。" }, "indexing_technique": { "type": "string", "description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。" }, "app_count": { "type": "integer", "description": "当前使用该知识库的应用数量。" }, "document_count": { "type": "integer", "description": "知识库中的文档总数。" }, "word_count": { "type": "integer", "description": "所有文档的总字数。" }, "created_by": { "type": "string", "description": "创建该知识库的用户 ID。" }, "author_name": { "type": "string", "description": "创建者的显示名称。" }, "created_at": { "type": "number", "description": "创建时间戳（Unix 纪元，单位为秒）。" }, "updated_by": { "type": "string", "description": "最后更新该知识库的用户 ID。" }, "updated_at": { "type": "number", "description": "最后更新时间戳（Unix 纪元，单位为秒）。" }, "embedding_model": { "type": "string", "description": "用于索引的嵌入模型名称。" }, "embedding_model_provider": { "type": "string", "description": "嵌入模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如 `langgenius/openai/openai`）。旧版知识库可能返回简写形式（例如 `openai`）。" }, "embedding_available": { "type": "boolean", "description": "配置的嵌入模型当前是否可用。" }, "retrieval_model_dict": { "type": "object", "description": "知识库的检索配置。", "properties": { "search_method": { "type": "string", "description": "用于检索的搜索方式。`keyword_search` 表示关键词匹配，`semantic_search` 表示基于嵌入的语义相似度，`full_text_search` 表示全文索引，`hybrid_search` 表示语义和关键词混合搜索。" }, "reranking_enable": { "type": "boolean", "description": "是否启用重排序。" }, "reranking_mode": { "type": "string", "nullable": true, "description": "重排序模式。`reranking_model` 表示基于模型的重排序，`weighted_score` 表示基于分数的加权。重排序禁用时为 `null`。" }, "reranking_model": { "type": "object", "description": "重排序模型配置。", "properties": { "reranking_provider_name": { "type": "string", "description": "重排序模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如 `langgenius/cohere/cohere`）。旧版知识库可能返回简写形式（例如 `cohere`）。" }, "reranking_model_name": { "type": "string", "description": "重排序模型名称。" } } }, "weights": { "type": "object", "nullable": true, "description": "混合搜索的权重配置。", "properties": { "weight_type": { "type": "string", "description": "平衡语义搜索和关键词搜索权重的策略。" }, "vector_setting": { "type": "object", "description": "语义搜索权重设置。", "properties": { "vector_weight": { "type": "number", "description": "分配给语义（向量）搜索结果的权重。" }, "embedding_provider_name": { "type": "string", "description": "用于向量搜索的嵌入模型供应商。" }, "embedding_model_name": { "type": "string", "description": "用于向量搜索的嵌入模型名称。" } } }, "keyword_setting": { "type": "object", "description": "关键词搜索权重设置。", "properties": { "keyword_weight": { "type": "number", "description": "分配给关键词搜索结果的权重。" } } } } }, "top_k": { "type": "integer", "description": "返回的最大结果数。" }, "score_threshold_enabled": { "type": "boolean", "description": "是否启用分数阈值过滤。" }, "score_threshold": { "type": "number", "description": "结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。" } } }, "summary_index_setting": { "type": "object", "nullable": true, "description": "摘要索引配置。", "properties": { "enable": { "type": "boolean", "description": "是否已启用摘要索引。" }, "model_name": { "type": "string", "description": "用于生成摘要的模型名称。" }, "model_provider_name": { "type": "string", "description": "摘要生成模型的供应商。" }, "summary_prompt": { "type": "string", "description": "用于摘要生成的提示词模板。" } } }, "tags": { "type": "array", "description": "与该知识库关联的标签。", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "标签标识符。" }, "name": { "type": "string", "description": "Tag name." }, "type": { "type": "string", "description": "标签类型。知识库标签始终为 `knowledge`。" } } } }, "doc_form": { "type": "string", "description": "文档分块模式。`text_model` 表示标准文本分块，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对提取。" }, "external_knowledge_info": { "type": "object", "nullable": true, "description": "外部知识库的连接详情。当 `provider` 为 `external` 时存在。", "properties": { "external_knowledge_id": { "type": "string", "description": "外部知识库的 ID。" }, "external_knowledge_api_id": { "type": "string", "description": "外部知识库 API 连接的 ID。" }, "external_knowledge_api_name": { "type": "string", "description": "外部知识库 API 的显示名称。" }, "external_knowledge_api_endpoint": { "type": "string", "description": "外部知识库 API 的端点 URL。" } } }, "external_retrieval_model": { "type": "object", "nullable": true, "description": "外部知识库的检索设置。内部知识库时为 `null`。", "properties": { "top_k": { "type": "integer", "description": "从外部知识库返回的最大结果数量。" }, "score_threshold": { "type": "number", "description": "最低相关性得分阈值。" }, "score_threshold_enabled": { "type": "boolean", "description": "是否启用分数阈值过滤。" } } }, "doc_metadata": { "type": "array", "description": "知识库的元数据字段定义。", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "元数据字段标识符。" }, "name": { "type": "string", "description": "元数据字段名称。" }, "type": { "type": "string", "description": "元数据字段值类型。" } } } }, "built_in_field_enabled": { "type": "boolean", "description": "是否启用内置元数据字段（例如 `document_name`、`uploader`）。" }, "pipeline_id": { "type": "string", "nullable": true, "description": "自定义处理流水线的 ID（如果已配置）。" }, "runtime_mode": { "type": "string", "nullable": true, "description": "运行时处理模式。" }, "chunk_structure": { "type": "string", "nullable": true, "description": "分段结构配置。" }, "icon_info": { "type": "object", "nullable": true, "description": "知识库的图标显示配置。", "properties": { "icon_type": { "type": "string", "description": "图标类型。" }, "icon": { "type": "string", "description": "图标标识符或表情符号。" }, "icon_background": { "type": "string", "description": "图标的背景颜色。" }, "icon_url": { "type": "string", "description": "自定义图标图片的 URL。" } } }, "is_published": { "type": "boolean", "description": "知识库是否已发布。" }, "total_documents": { "type": "integer", "description": "文档总数。" }, "total_available_documents": { "type": "integer", "description": "已启用且可用的文档数量。" }, "enable_api": { "type": "boolean", "description": "该知识库是否启用 API 访问。" }, "is_multimodal": { "type": "boolean", "description": "是否启用多模态内容处理。" }, "maintainer": { "type": "string", "nullable": true, "description": "知识库维护者的显示名称。未设置时为 `null`。" }, "partial_member_list": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "当 `permission` 为 `partial_members` 时被授予访问权限的成员账户 ID。更新响应中始终返回；详情响应中仅当 `permission` 为 `partial_members` 时返回。" } } }, "Document": { "type": "object", "properties": { "id": { "type": "string", "description": "文档的唯一标识符。" }, "position": { "type": "integer", "description": "文档在列表中的显示位置。" }, "data_source_type": { "type": "string", "description": "文档的创建方式。文件上传为 `upload_file`，Notion 导入为 `notion_import`。" }, "data_source_info": { "type": "object", "description": "原始数据源信息，随 `data_source_type` 而异。" }, "data_source_detail_dict": { "type": "object", "description": "详细的数据源信息，包括文件详情。" }, "dataset_process_rule_id": { "type": "string", "description": "应用于该文档的处理规则 ID。" }, "name": { "type": "string", "description": "文档名称。" }, "created_from": { "type": "string", "description": "文档来源。通过 API 创建时为 `api`，通过 UI 创建时为 `web`。" }, "created_by": { "type": "string", "description": "创建该文档的用户 ID。" }, "created_at": { "type": "number", "description": "创建时间戳（Unix 纪元，单位为秒）。" }, "tokens": { "type": "integer", "description": "文档中的令牌总数。" }, "indexing_status": { "type": "string", "description": "当前索引状态。`waiting` 表示排队中，`parsing` 表示正在提取内容，`cleaning` 表示正在去噪，`splitting` 表示正在分块，`indexing` 表示正在构建向量，`completed` 表示就绪，`error` 表示失败，`paused` 表示手动暂停。" }, "error": { "type": "string", "nullable": true, "description": "索引失败时的错误消息。无错误时为 `null`。" }, "enabled": { "type": "boolean", "description": "该文档是否启用检索。" }, "disabled_at": { "type": "number", "nullable": true, "description": "文档被禁用的时间戳。启用时为 `null`。" }, "disabled_by": { "type": "string", "nullable": true, "description": "禁用该文档的用户 ID。启用时为 `null`。" }, "archived": { "type": "boolean", "description": "文档是否已归档。" }, "display_status": { "type": "string", "description": "基于 `indexing_status` 和 `enabled` 状态派生的面向用户的显示状态。" }, "word_count": { "type": "integer", "description": "文档的总字数。" }, "hit_count": { "type": "integer", "description": "该文档在检索查询中被匹配的次数。" }, "doc_form": { "type": "string", "description": "文档分块模式。`text_model` 表示标准文本分块，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对提取。" }, "doc_metadata": { "type": "array", "description": "分配给该文档的元数据值。", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "元数据字段标识符。" }, "name": { "type": "string", "description": "元数据字段名称。" }, "type": { "type": "string", "description": "元数据字段值类型。" }, "value": { "type": "string", "description": "此文档的元数据值。" } } } }, "summary_index_status": { "type": "string", "nullable": true, "description": "该文档的摘要索引状态。未配置摘要索引时为 `null`。" }, "need_summary": { "type": "boolean", "description": "是否需要为该文档生成摘要。" } } }, "Segment": { "type": "object", "properties": { "id": { "type": "string", "description": "分段的唯一标识符。" }, "position": { "type": "integer", "description": "分段在文档中的位置。" }, "document_id": { "type": "string", "description": "该分段所属文档的 ID。" }, "content": { "type": "string", "description": "分段的文本内容。" }, "sign_content": { "type": "string", "description": "用于完整性验证的签名内容哈希。" }, "answer": { "type": "string", "description": "回答内容，用于问答模式文档。" }, "word_count": { "type": "integer", "description": "分段内容的字数。" }, "tokens": { "type": "integer", "description": "分段内容的令牌数。" }, "keywords": { "type": "array", "description": "与该分段关联的关键词，用于基于关键词的检索。", "items": { "type": "string" } }, "index_node_id": { "type": "string", "description": "向量存储中索引节点的 ID。" }, "index_node_hash": { "type": "string", "description": "索引内容的哈希值，用于检测变更。" }, "hit_count": { "type": "integer", "description": "该分段在检索查询中被匹配的次数。" }, "enabled": { "type": "boolean", "description": "该分段是否启用检索。" }, "disabled_at": { "type": "number", "nullable": true, "description": "分段被禁用的时间戳。启用时为 `null`。" }, "disabled_by": { "type": "string", "nullable": true, "description": "禁用该分段的用户 ID。启用时为 `null`。" }, "status": { "type": "string", "description": "分段的当前索引状态，例如 `completed`、`indexing`、`error`。" }, "created_by": { "type": "string", "description": "创建该分段的用户 ID。" }, "created_at": { "type": "number", "description": "创建时间戳（Unix 纪元，单位为秒）。" }, "updated_at": { "type": "number", "description": "最后更新时间戳（Unix 纪元，单位为秒）。" }, "updated_by": { "type": "string", "description": "最后更新该分段的用户 ID。" }, "indexing_at": { "type": "number", "nullable": true, "description": "索引开始的时间戳。尚未开始时为 `null`。" }, "completed_at": { "type": "number", "nullable": true, "description": "索引完成的时间戳。尚未完成时为 `null`。" }, "error": { "type": "string", "nullable": true, "description": "索引失败时的错误消息。无错误时为 `null`。" }, "stopped_at": { "type": "number", "nullable": true, "description": "索引停止的时间戳。未停止时为 `null`。" }, "child_chunks": { "type": "array", "description": "属于该分段的子分段。仅在分层模式文档中存在。", "items": { "$ref": "#/components/schemas/ChildChunk" } }, "attachments": { "type": "array", "description": "附加到该分段的文件。", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "附件文件标识符。" }, "name": { "type": "string", "description": "原始文件名。" }, "size": { "type": "integer", "description": "文件大小（字节）。" }, "extension": { "type": "string", "description": "文件扩展名。" }, "mime_type": { "type": "string", "description": "文件的 MIME 类型。" }, "source_url": { "type": "string", "description": "访问附件的 URL。" } } } }, "summary": { "type": "string", "nullable": true, "description": "AI 生成的分段内容摘要。未启用摘要索引时为 `null`。" } } }, "ChildChunk": { "type": "object", "properties": { "id": { "type": "string", "description": "子分段的唯一标识符。" }, "segment_id": { "type": "string", "description": "该子分段所属的父分段 ID。" }, "content": { "type": "string", "description": "子分段的文本内容。" }, "position": { "type": "integer", "description": "子分段在父分段中的位置。" }, "word_count": { "type": "integer", "description": "子分段内容的字数。" }, "type": { "type": "string", "description": "子分段的创建方式。通过 API 创建或更新的子分段始终为 `customized`。系统生成的子分段为 `automatic`。" }, "created_at": { "type": "number", "description": "创建时间戳（Unix 纪元，单位为秒）。" }, "updated_at": { "type": "number", "description": "最后更新时间戳（Unix 纪元，单位为秒）。" } } }, "RetrievalModel": { "type": "object", "required": [ "search_method", "reranking_enable", "top_k", "score_threshold_enabled" ], "properties": { "search_method": { "type": "string", "description": "用于检索的搜索方法。", "enum": [ "keyword_search", "semantic_search", "full_text_search", "hybrid_search" ] }, "reranking_enable": { "type": "boolean", "description": "是否启用重排序。" }, "reranking_model": { "type": "object", "description": "重排序模型配置。", "properties": { "reranking_provider_name": { "type": "string", "description": "重排序模型供应商标识符，格式为 `organization/plugin_name/provider_name`（例如 `langgenius/cohere/cohere`）。`cohere` 这类简写会展开为 `langgenius//`，仅对 langgenius 发布的插件有效。\n\n有效取值从 [获取可用模型](/zh/api-reference/models/get-available-models) 中 `model_type=rerank` 返回的 `provider` 字段获取。" }, "reranking_model_name": { "type": "string", "description": "重排序模型名称。" } } }, "reranking_mode": { "type": "string", "enum": [ "reranking_model", "weighted_score" ], "nullable": true, "description": "重排序模式。当 `reranking_enable` 为 `true` 时必填。" }, "top_k": { "type": "integer", "description": "返回的最大结果数。" }, "score_threshold_enabled": { "type": "boolean", "description": "是否启用分数阈值过滤。" }, "score_threshold": { "type": "number", "nullable": true, "description": "结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。" }, "weights": { "type": "object", "nullable": true, "description": "混合搜索的权重配置。", "properties": { "weight_type": { "type": "string", "description": "平衡语义搜索和关键词搜索权重的策略。", "enum": [ "semantic_first", "keyword_first", "customized" ] }, "vector_setting": { "type": "object", "description": "语义搜索权重设置。", "properties": { "vector_weight": { "type": "number", "description": "分配给语义（向量）搜索结果的权重。" }, "embedding_provider_name": { "type": "string", "description": "用于向量搜索的嵌入模型供应商。" }, "embedding_model_name": { "type": "string", "description": "用于向量搜索的嵌入模型名称。" } } }, "keyword_setting": { "type": "object", "description": "关键词搜索权重设置。", "properties": { "keyword_weight": { "type": "number", "description": "分配给关键词搜索结果的权重。" } } } } }, "metadata_filtering_conditions": { "type": "object", "nullable": true, "description": "仅检索文档元数据匹配指定条件的分段。条件由服务端基于文档元数据字段评估。", "properties": { "logical_operator": { "type": "string", "enum": [ "and", "or" ], "default": "and", "nullable": true, "description": "多个条件之间的组合方式。" }, "conditions": { "type": "array", "nullable": true, "description": "要评估的元数据条件列表。", "items": { "type": "object", "required": [ "name", "comparison_operator" ], "properties": { "name": { "type": "string", "description": "用于比较的元数据字段名称。" }, "comparison_operator": { "type": "string", "description": "按元数据类型选择要应用的比较方式：\n\n- 字符串或数组类型元数据：`contains`、`not contains`、`start with`、`end with`、`is`、`is not`、`empty`、`not empty`、`in`、`not in`\n- 数值类型元数据：`=`、`≠`、`>`、`<`、`≥`、`≤`\n- 时间类型元数据：`before`、`after`", "enum": [ "contains", "not contains", "start with", "end with", "is", "is not", "empty", "not empty", "in", "not in", "=", "≠", ">", "<", "≥", "≤", "before", "after" ] }, "value": { "nullable": true, "description": "用于比较的值。类型取决于 `comparison_operator`：大多数字符串运算符使用字符串；`in` 和 `not in` 使用字符串数组；数值运算符使用数字；`empty` 和 `not empty` 时省略。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" } ] } } } } } } } } } } }