centersl/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-03-27 13:28:32 +07:00
Code Issues Packages Projects Releases Wiki Activity
Files
21122c4282c5730d54cefde9066367cd37eaaf62
dify-docs/zh/api-reference/openapi_chatflow.json
Riskey 21122c4282 Batch update apis (#715) 
* Batch update service apis

* final check and add zh/ja docs

* add temporary redirects for changed api links embedded in the product

* Restore original operationIds to preserve SDK compatibility

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* complete the missing descriptions

* correct the human input terminology

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23 16:38:10 +08:00

6208 lines
209 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"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": "与工作流执行详情和日志相关的操作。"
}
]
}
Reference in New Issue View Git Blame Copy Permalink