{ "openapi": "3.0.1", "info": { "title": "工作流编排对话型应用 API (对话流 API)", "description": "对话流应用支持会话持久化，允许将之前的聊天记录作为响应的上下文。对话流应用使用 `advanced-chat` 模式，提供工作流级别的流式事件，用于详细的执行追踪，包括节点开始、完成、迭代和工作流生命周期。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", "description": "工作流编排对话型应用 API 的基础 URL。请将 {api_base_url} 替换为你的应用实际提供的 API 基础 URL。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", "description": "API 的实际基础 URL" } } } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/chat-messages": { "post": { "summary": "发送对话消息", "description": "向对话型应用发送请求。", "operationId": "sendChatMessageCn", "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` 和 `ChunkChatEvent` 对象流。", "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": "advanced-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": "服务器发送事件 (SSE) 流。每个事件是一个以 `data: ` 为前缀的 JSON 对象，以两个换行符终止。\n\n**SSE 解析指南：**每个事件是一行以 `data: ` 为前缀的 JSON 对象，以 `\\n\\n` 终止。解析 JSON 前先去除 `data: ` 前缀。JSON 内的 `event` 字段决定事件类型。当收到终止事件（如 `message_end`、`workflow_finished` 或 `error`）时流结束。忽略 `ping` 事件（每 10 秒发送一次以保持连接活跃）。注意即使流中出现错误事件，HTTP 状态码仍为 `200`。" }, "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\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" }, "streamingResponseWorkflow": { "summary": "Response Example - Streaming (工作流)", "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"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\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} 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\", \"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\", \"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\", \"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}}" } } } } }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\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.", "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." } }, "conversation_completed": { "summary": "conversation_completed", "value": { "status": 400, "code": "conversation_completed", "message": "The conversation has ended. Please start a new conversation." } }, "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'. " } } } } } }, "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` : 上游模型提供商的速率限制已超出。", "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." } } } } } } } } }, "/chat-messages/{task_id}/stop": { "post": { "summary": "停止响应", "description": "停止聊天消息生成任务。仅在 `streaming` 模式下支持。", "operationId": "stopChatMessageGenerationCn", "tags": [ "对话消息" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "任务 ID，可以从 [发送对话消息](/api-reference/对话消息/发送对话消息) API 的流式分块返回中获取。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "string", "description": "用户标识符，必须和发送消息接口传入的 user 保持一致。" } } }, "examples": { "example": { "summary": "请求示例", "value": { "user": "abc-123" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SuccessResult" }, "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." } } } } } } } } }, "/messages/{message_id}/suggested": { "get": { "summary": "获取下一轮建议问题列表", "description": "获取当前消息的下一步建议问题。", "operationId": "getSuggestedQuestionsCn", "tags": [ "对话消息" ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "消息 ID。", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": true, "description": "用户标识符。", "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": "Internal server error." } } } } } } } } }, "/files/upload": { "post": { "operationId": "uploadFileCn", "tags": [ "文件操作" ], "summary": "上传文件", "description": "上传文件用于发送消息时使用，支持图片、文档、音频和视频的多模态理解。上传的文件仅供当前终端用户使用。", "requestBody": { "description": "文件上传请求。需要 multipart/form-data 格式。", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "要上传的文件。支持的类型包括图片、文档、音频和视频。" }, "user": { "type": "string", "description": "用户标识符，由开发者定义的规则生成，必须在应用内唯一。" } } } } } }, "responses": { "201": { "description": "文件上传成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" }, "examples": { "uploadSuccess": { "summary": "响应示例", "value": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "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": null, "original_url": null, "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", "conversation_id": null, "file_key": "uploads/product-photo.png" } } } } } }, "400": { "description": "- `no_file_uploaded` : 请求中未提供文件。\n- `too_many_files` : 每次请求仅允许上传一个文件。\n- `filename_not_exists_error` : 上传的文件没有文件名。", "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." } } } } } }, "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." } } } } } } } } }, "/files/{file_id}/preview": { "get": { "operationId": "previewChatFlowFileCn", "tags": [ "文件操作" ], "summary": "下载文件", "description": "预览或下载之前通过[上传文件](/api-reference/文件操作/上传文件) API 上传的文件。仅可访问属于请求应用内消息的文件。", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "要预览的文件唯一标识符，从 [上传文件](/api-reference/文件操作/上传文件) API 响应中获取。", "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": "用户标识符，用于终端用户上下文。", "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` : 未找到请求的文件。", "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." } } } } } } } } }, "/end-users/{end_user_id}": { "get": { "operationId": "getEndUserChatflowCn", "tags": [ "终端用户" ], "summary": "获取终端用户信息", "description": "根据 ID 获取终端用户信息。当其他 API 返回终端用户 ID（例如[上传文件](/api-reference/文件操作/上传文件)返回的 `created_by`）时很有用。", "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." } } } } } } } } }, "/messages/{message_id}/feedbacks": { "post": { "operationId": "postMessageFeedbackCn", "tags": [ "消息反馈" ], "summary": "提交消息反馈", "description": "提交消息反馈。终端用户可以对消息评价 `like` 或 `dislike`，并可选择提供文字反馈。将 `rating` 设为 `null` 可撤销之前提交的反馈。", "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "消息 ID。", "schema": { "type": "string" } } ], "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" }, "404": { "description": "`not_found` : 消息不存在。", "content": { "application/json": { "examples": { "message_not_exists": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Message Not Exists." } } } } } } } } }, "/app/feedbacks": { "get": { "operationId": "getAppFeedbacksCn", "tags": [ "消息反馈" ], "summary": "获取应用的消息反馈", "description": "获取此应用中所有消息反馈的分页列表，包括终端用户和管理员反馈。", "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" } ] } } } } } } } } }, "/conversations": { "get": { "summary": "获取会话列表", "description": "获取当前用户的会话列表，按最近活跃时间排序。", "operationId": "getConversationsListCn", "tags": [ "会话管理" ], "parameters": [ { "name": "user", "in": "query", "required": false, "description": "用户标识符。", "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." } } } } } } } } }, "/messages": { "get": { "summary": "获取会话历史消息", "description": "以滚动加载的格式返回历史聊天记录，首页返回最新的 `limit` 条消息，即按时间倒序排列。", "operationId": "getConversationHistoryCn", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "query", "required": true, "description": "会话 ID。", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "用户标识符。", "schema": { "type": "string" } }, { "name": "first_id", "in": "query", "required": false, "description": "当前页第一条聊天记录的 ID。默认为 `null`（获取最新消息）。获取后续页面时，使用当前列表中第一条消息的 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 } ] } } } } } }, "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` : 第一条消息不存在。", "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." } } } } } } } } }, "/conversations/{conversation_id}/variables": { "get": { "summary": "获取对话变量", "description": "从特定会话中获取变量。", "operationId": "getConversationVariablesCn", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "会话 ID。", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "用户标识符。", "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 路由不匹配。", "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." } } } } } } } } }, "/conversations/{conversation_id}/name": { "post": { "summary": "重命名会话", "description": "重命名会话或自动生成名称。会话名称用于在支持多会话的客户端上显示。", "operationId": "renameConversationCn", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "会话 ID。", "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 路由不匹配。", "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." } } } } } } } } }, "/conversations/{conversation_id}/variables/{variable_id}": { "put": { "summary": "更新对话变量", "description": "更新特定会话变量的值。值必须与预期类型匹配。", "operationId": "updateChatflowConversationVariableZh", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "会话 ID。", "schema": { "type": "string", "format": "uuid" } }, { "name": "variable_id", "in": "path", "required": true, "description": "Variable ID.", "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": "Value type mismatch: expected string, got integer." } } } } } }, "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." } } } } } } } } }, "/conversations/{conversation_id}": { "delete": { "summary": "删除会话", "description": "删除会话。", "operationId": "deleteConversationCn", "tags": [ "会话管理" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "会话 ID。", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "用户标识符。" } } }, "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." } } } } } } } } }, "/audio-to-text": { "post": { "operationId": "audioToTextCn", "tags": [ "语音与文字转换" ], "summary": "语音转文字", "description": "将音频文件转换为文字。支持的格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件大小限制为 `30 MB`。", "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- `no_audio_uploaded` : 未上传音频文件。\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." } }, "no_audio_uploaded": { "summary": "no_audio_uploaded", "value": { "status": 400, "code": "no_audio_uploaded", "message": "Please upload your audio." } }, "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` : 音频文件大小超出限制。", "content": { "application/json": { "examples": { "audio_too_large": { "summary": "audio_too_large", "value": { "status": 413, "code": "audio_too_large", "message": "Audio size exceeded." } } } } } }, "415": { "description": "`unsupported_audio_type` : 不允许的音频类型。", "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": "Internal server error." } } } } } } } } }, "/text-to-audio": { "post": { "operationId": "textToAudioCn", "tags": [ "语音与文字转换" ], "summary": "文字转语音", "description": "将文字转换为语音。", "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`）。如果 `streaming` 为 `true`，音频将以分块传输编码方式流式返回。", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "- `app_unavailable` : 应用不可用或配置错误。\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." } }, "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": "Internal server error." } } } } } } } } }, "/info": { "get": { "operationId": "getAppInfoCn", "tags": [ "应用配置" ], "summary": "获取应用基本信息", "description": "获取应用的基本信息，包括名称、描述、标签和模式。", "responses": { "200": { "description": "应用的基本信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponse" }, "examples": { "appInfo": { "summary": "响应示例", "value": { "name": "My Chatflow App", "description": "一个有用的客服聊天机器人。", "tags": [ "customer-service", "chatbot" ], "mode": "advanced-chat", "author_name": "Dify Team" } } } } } } } } }, "/parameters": { "get": { "operationId": "getAppParametersCn", "tags": [ "应用配置" ], "summary": "获取应用参数", "description": "获取应用的输入表单配置，包括功能开关、输入参数名称、类型和默认值。", "responses": { "200": { "description": "应用参数信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAppParametersResponse" }, "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` : 应用不可用或配置错误。", "content": { "application/json": { "examples": { "app_unavailable": { "summary": "app_unavailable", "value": { "status": 400, "code": "app_unavailable", "message": "App unavailable, please check your app configurations." } } } } } } } } }, "/meta": { "get": { "operationId": "getAppMetaCn", "tags": [ "应用配置" ], "summary": "获取应用元数据", "description": "获取应用的元数据，包括工具图标和其他配置详情。", "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": "🧮" } } } } } } } } } } }, "/site": { "get": { "operationId": "getWebAppSettingsCn", "tags": [ "应用配置" ], "summary": "获取应用 WebApp 设置", "description": "获取应用的 WebApp 设置，包括站点配置、主题和自定义选项。", "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", "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": "Forbidden." } } } } } } } } }, "/apps/annotations": { "post": { "summary": "创建标注", "description": "创建新的标注。标注提供预定义的问答对，应用可以直接匹配并返回，而无需生成回复。", "operationId": "createAnnotationCn", "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 } } } } } } } }, "get": { "summary": "获取标注列表", "description": "获取应用的标注分页列表。支持关键词搜索筛选。", "operationId": "getAnnotationListCn", "tags": [ "标注管理" ], "parameters": [ { "name": "page", "in": "query", "description": "分页页码。", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "每页条目数。", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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 } } } } } } } } }, "/apps/annotations/{annotation_id}": { "put": { "summary": "更新标注", "description": "更新现有标注的问题和回答。", "operationId": "updateAnnotationCn", "tags": [ "标注管理" ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "description": "要更新的标注的唯一标识符。", "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 } } } } } }, "403": { "description": "`forbidden` : 编辑标注的权限不足。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden", "value": { "status": 403, "code": "forbidden", "message": "Forbidden." } } } } } }, "404": { "description": "`not_found` : 标注不存在。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Annotation not found." } } } } } } } }, "delete": { "summary": "删除标注", "description": "删除标注及其关联的命中历史。", "operationId": "deleteAnnotationCn", "tags": [ "标注管理" ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, "description": "要删除的标注的唯一标识符。", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "标注删除成功。" }, "403": { "description": "`forbidden` : 编辑标注的权限不足。", "content": { "application/json": { "examples": { "forbidden": { "summary": "forbidden", "value": { "status": 403, "code": "forbidden", "message": "Forbidden." } } } } } }, "404": { "description": "`not_found` : 标注不存在。", "content": { "application/json": { "examples": { "not_found": { "summary": "not_found", "value": { "status": 404, "code": "not_found", "message": "Annotation not found." } } } } } } } } }, "/apps/annotation-reply/{action}": { "post": { "summary": "配置标注回复", "description": "启用或禁用标注回复功能。启用时需要配置嵌入模型。异步执行——使用 [查询标注回复配置任务状态](/api-reference/标注管理/查询标注回复配置任务状态) 跟踪进度。", "operationId": "initialAnnotationReplySettingsCn", "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" } } } } } } } } }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { "summary": "查询标注回复配置任务状态", "description": "获取由 [配置标注回复](/api-reference/标注管理/配置标注回复) 发起的异步标注回复配置任务的状态。", "operationId": "getInitialAnnotationReplySettingsStatusCn", "tags": [ "标注管理" ], "parameters": [ { "name": "action", "in": "path", "required": true, "description": "操作类型，必须与 [配置标注回复](/api-reference/标注管理/配置标注回复) 调用中的一致。", "schema": { "type": "string", "enum": [ "enable", "disable" ] } }, { "name": "job_id", "in": "path", "required": true, "description": "由 [配置标注回复](/api-reference/标注管理/配置标注回复) 接口返回的任务 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." } } } } } } } } }, "/workflows/run/{workflow_run_id}": { "get": { "summary": "获取工作流执行情况", "description": "根据工作流执行 ID 获取工作流任务的当前执行结果。", "operationId": "getChatflowWorkflowRunDetailZh", "tags": [ "工作流执行" ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "description": "工作流运行 ID，可从流式事件或消息元数据中获取。", "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." } } } } } } } } }, "/workflows/logs": { "get": { "summary": "获取工作流日志", "description": "获取分页的工作流执行日志，支持筛选选项。", "operationId": "listChatflowWorkflowLogsZh", "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": "按账户 ID 筛选。", "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 }, "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_chatflow_123" }, "created_at": 1705407629 } ] } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**" } }, "responses": { "SuccessResult": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "结果状态。" } } }, "examples": { "success": { "summary": "响应示例", "value": { "result": "success" } } } } } } }, "schemas": { "ChatRequest": { "type": "object", "required": [ "inputs", "query", "user" ], "properties": { "query": { "type": "string", "description": "用户输入/问题内容。" }, "inputs": { "type": "object", "description": "允许输入应用定义的各种变量值。包含键值对。请参阅 [获取应用参数](/api-reference/应用配置/获取应用参数) 响应中的 `user_input_form` 字段，以了解应用所需的变量名称和类型。", "additionalProperties": true }, "response_mode": { "type": "string", "enum": [ "streaming", "blocking" ], "description": "响应返回模式。`streaming`（推荐）使用 SSE。`blocking` 等待完成后返回（长时间处理可能会被中断）。Cloudflare 超时为 `100 s`。省略时默认为阻塞模式。" }, "user": { "type": "string", "description": "用户标识符，在应用内唯一。此标识符用于限定数据访问范围——会话、消息和文件仅在使用相同的 `user` 值查询时可见。" }, "conversation_id": { "type": "string", "description": "用于继续会话的会话 ID。传入上一条消息的 `conversation_id`。要开始新会话，请省略此字段或传入空字符串。响应会返回一个 `conversation_id`——在后续消息中传入该值即可继续该会话。" }, "files": { "type": "array", "description": "用于多模态理解的文件列表，包括图片、文档、音频和视频。要附加本地文件，请先通过 [上传文件](/api-reference/文件操作/上传文件) 上传，然后将返回的 `id` 作为 `upload_file_id`，并设置 `transfer_method: local_file`。", "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": "通过 [上传文件](/api-reference/文件操作/上传文件) API 获取的已上传文件 ID（当 `transfer_method` 为 `local_file` 时必填）。" } } } }, "auto_generate_name": { "type": "boolean", "description": "自动生成会话标题。如果为 `false`，请使用 [重命名会话](/api-reference/会话管理/重命名会话) API 并设置 `auto_generate: true` 来异步生成标题。", "default": true }, "workflow_id": { "type": "string", "description": "指定要执行的已发布工作流版本 ID。如果未提供，将使用最新发布的版本。" } } }, "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": "应用模式，固定为 `advanced-chat`。" }, "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", "tts_message", "tts_message_end", "message_file", "message_end", "message_replace", "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", "text_replace", "error", "ping" ] } }, "discriminator": { "propertyName": "event", "mapping": { "message": "#/components/schemas/StreamEventChatMessage", "tts_message": "#/components/schemas/StreamEventChatTtsMessage", "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", "message_file": "#/components/schemas/StreamEventChatMessageFile", "message_end": "#/components/schemas/StreamEventChatMessageEnd", "message_replace": "#/components/schemas/StreamEventChatMessageReplace", "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", "text_replace": "#/components/schemas/StreamEventChatTextReplace", "error": "#/components/schemas/StreamEventChatError", "ping": "#/components/schemas/StreamEventChatPing" } } }, "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 返回的文本块。" } } } ] }, "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": "空字符串。标识音频流结束。" } } } ] }, "StreamEventChatMessageFile": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "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。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "会话 ID。" } } } ] }, "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 事件，用于保持连接活跃。" } ] }, "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。" }, "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。" }, "created_at": { "type": "integer", "format": "int64", "description": "上传时间戳（Unix 纪元秒）。" }, "preview_url": { "type": "string", "nullable": true, "description": "文件的预览 URL。" }, "source_url": { "type": "string", "nullable": true, "description": "文件的源 URL。" }, "original_url": { "type": "string", "nullable": true, "description": "文件的原始 URL。" }, "user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "关联的用户 ID。" }, "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": "文件的存储键。" } } }, "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` 标识符（例如 [发送对话消息](/api-reference/对话消息/发送对话消息) 中的 `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": "用户标识符，由开发者定义，必须确保在应用内唯一。" }, "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", "description": "会话中的单条消息。", "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": "与此消息关联的附加执行内容，例如对话流工作流中人工介入节点的表单数据。", "items": { "$ref": "#/components/schemas/HumanInputContent" } } } }, "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": "重命名会话的请求体。", "required": [ "user" ], "properties": { "name": { "type": "string", "description": "会话名称。当 `auto_generate` 为 `false` 时必填。" }, "auto_generate": { "type": "boolean", "default": false, "description": "自动生成会话名称。当为 `true` 时，`name` 字段将被忽略。" }, "user": { "type": "string", "description": "用户标识符。" } } }, "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": "用户标识符。" } } }, "AudioToTextRequest": { "type": "object", "description": "语音转文字的请求体。", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "音频文件。支持格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。大小限制：`30 MB`。" }, "user": { "type": "string", "description": "用户标识符。" } } }, "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` 时，优先使用消息 ID。" }, "text": { "type": "string", "description": "要转换的语音内容。" }, "user": { "type": "string", "description": "用户标识符。" }, "voice": { "type": "string", "description": "文字转语音使用的声音。可用声音取决于为此应用配置的 TTS 提供商。使用[获取应用参数](/api-reference/应用配置/获取应用参数) → `text_to_speech.voice` 中的 `voice` 值作为默认值。" }, "streaming": { "type": "boolean", "description": "是否启用流式响应。" } } }, "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` 为对话流应用，`workflow` 为工作流应用。" }, "author_name": { "type": "string", "description": "应用作者名称。" } } }, "ChatAppParametersResponse": { "type": "object", "properties": { "opening_statement": { "type": "string", "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", "description": "用户输入表单元素列表。", "items": { "$ref": "#/components/schemas/UserInputFormItem" } }, "file_upload": { "type": "object", "description": "文件上传配置。", "properties": { "image": { "type": "object", "description": "图片上传设置。", "properties": { "enabled": { "type": "boolean", "description": "是否启用图片上传。" }, "number_limits": { "type": "integer", "description": "最大图片数量。" }, "detail": { "type": "string", "description": "图片精细程度。" }, "transfer_methods": { "type": "array", "items": { "type": "string" }, "description": "允许的传输方式。" } } } } }, "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": "工作流文件上传的最大文件数。" } } } } }, "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", "description": "文本输入表单控件。", "properties": { "label": { "type": "string", "description": "显示标签。" }, "variable": { "type": "string", "description": "变量名称。" }, "required": { "type": "boolean", "description": "输入是否必填。" }, "default": { "type": "string", "description": "默认值。" } } }, "ParagraphControl": { "type": "object", "description": "段落（多行文本）表单控件。", "properties": { "label": { "type": "string", "description": "显示标签。" }, "variable": { "type": "string", "description": "变量名称。" }, "required": { "type": "boolean", "description": "输入是否必填。" }, "default": { "type": "string", "description": "默认值。" } } }, "SelectControl": { "type": "object", "description": "下拉选择表单控件。", "properties": { "label": { "type": "string", "description": "显示标签。" }, "variable": { "type": "string", "description": "变量名称。" }, "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。" }, "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`、`cohere`）。" }, "embedding_model_name": { "type": "string", "description": "用于标注匹配的嵌入模型名称（例如 `text-embedding-3-small`）。" }, "score_threshold": { "type": "number", "format": "float", "description": "标注被视为匹配的最低相似度分数。值越高，要求匹配越精确。", "minimum": 0, "maximum": 1 } } }, "InitialAnnotationReplySettingsResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "异步任务 ID。配合 [查询标注回复配置任务状态](/api-reference/标注管理/查询标注回复配置任务状态) 使用以跟踪进度。" }, "job_status": { "type": "string", "description": "当前任务状态。`waiting` 表示排队中，`processing` 表示处理中，`completed` 表示已完成，`error` 表示失败。" } } }, "InitialAnnotationReplySettingsStatusResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "来自 [配置标注回复](/api-reference/标注管理/配置标注回复) 调用的任务 ID。" }, "job_status": { "type": "string", "description": "当前任务状态。`waiting` 表示排队中，`processing` 表示处理中，`completed` 表示已完成，`error` 表示失败。" }, "error_msg": { "type": "string", "description": "描述任务失败原因的错误消息。当 `job_status` 不是 `error` 时为空字符串。" } } }, "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", "description": "人工介入节点正在等待用户输入。", "properties": { "workflow_run_id": { "type": "string", "description": "工作流执行运行 ID。" }, "data": { "type": "object", "properties": { "form_id": { "type": "string", "description": "用于提交响应的表单 ID。" }, "node_id": { "type": "string", "description": "人工介入节点的节点 ID。" }, "node_title": { "type": "string", "description": "人工介入节点的标题。" }, "form_content": { "type": "string", "description": "给用户的表单内容/说明。" }, "inputs": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "表单输入字段定义。" }, "actions": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "可用的用户操作。" }, "form_token": { "type": "string", "nullable": true, "description": "表单提交认证的令牌。" }, "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", "format": "uuid", "description": "此工作流运行记录的持久化标识符。配合 [获取工作流运行详情](/api-reference/工作流/获取-工作流-执行情况) 使用以在执行后获取结果。" }, "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": "Node ID." }, "node_title": { "type": "string", "description": "Node title." }, "rendered_content": { "type": "string", "description": "表单提交后的渲染内容。" }, "action_id": { "type": "string", "description": "已执行操作的 ID。" }, "action_text": { "type": "string", "description": "已执行操作的文本。" } } } } } ] }, "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": "Node ID." }, "node_title": { "type": "string", "description": "Node title." }, "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。" } } } } } ] }, "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": "工作流中文本变量的源路径。" } } } } } ] }, "StreamEventChatTextReplace": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string", "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": "object", "additionalProperties": true, "description": "工作流运行的输入变量。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": 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": "触发工作流运行的来源。`debugging` 表示从编辑器发起的测试运行，`app` 表示 API 或应用发起的运行。" } } }, "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": "`text_input` 为单行文本，`paragraph` 为多行文本。" }, "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`." } } } } }, "tags": [ { "name": "对话消息", "description": "与聊天消息和交互相关的操作。" }, { "name": "文件操作", "description": "文件上传和预览操作。" }, { "name": "终端用户", "description": "终端用户信息相关操作。" }, { "name": "消息反馈", "description": "用户反馈操作。" }, { "name": "会话管理", "description": "与管理会话相关的操作。" }, { "name": "语音与文字转换", "description": "文字转语音和语音转文字操作。" }, { "name": "应用配置", "description": "获取应用设置和信息的操作。" }, { "name": "标注管理", "description": "与管理标注直接回复相关的操作。" }, { "name": "工作流执行", "description": "与工作流执行详情和日志相关的操作。" } ] }