langgenius/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-07-22 12:25:45 -04:00
Code Issues 10 Packages Projects Releases Wiki Activity
Files
af1be52cfff2ff0fca367d5bd7f4ccd5d2ebbd47
dify-docs/zh/api-reference/openapi_chat.json
T
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

4427 lines
147 KiB
JSON
Raw Blame History

{
"openapi": "3.0.1",
"info": {
"title": "对话型应用 API",
"description": "对话型应用支持会话持久化，允许将之前的聊天记录作为上下文进行回复。适用于聊天机器人、客服 AI 等场景。",
"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": "sendBasicChatMessageCn",
"tags": [
"对话消息"
],
"requestBody": {
"description": "发送对话消息的请求体。",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatRequest"
},
"examples": {
"streaming_example": {
"summary": "请求示例 - 流式模式",
"value": {
"inputs": {
"city": "San Francisco"
},
"query": "What are the specs of the iPhone 13 Pro Max?",
"response_mode": "streaming",
"conversation_id": "",
"user": "abc-123",
"files": [
{
"type": "image",
"transfer_method": "remote_url",
"url": "https://cloud.dify.ai/logo/logo-site.png"
}
]
}
},
"blocking_example": {
"summary": "请求示例 - 阻塞模式",
"value": {
"inputs": {},
"query": "What are the specs of the iPhone 13 Pro Max?",
"response_mode": "blocking",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"user": "abc-123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。\n\n- 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `ChatCompletionResponse` 对象。\n- 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和 `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": "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}}}"
},
"streamingResponseAgent": {
"summary": "Response Example - Streaming (Agent)",
"value": "data: {\"event\": \"agent_thought\", \"id\": \"agent_thought_id_1\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"position\": 1, \"thought\": \"Thinking about calling a tool...\", \"tool\": \"dalle3\", \"tool_input\": \"{\\\"dalle3\\\": {\\\"prompt\\\": \\\"a cute cat\\\"}}\", \"created_at\": 1705395332} data: {\"event\": \"message_file\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"conversation_id\": \"conv123\"} data: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333} data: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}"
}
}
}
}
},
"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` : 文本生成失败。",
"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."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 会话不存在。",
"content": {
"application/json": {
"examples": {
"conversation_not_exists": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Conversation Not Exists."
}
}
}
}
}
},
"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": "stopBasicChatMessageGenerationCn",
"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": "getBasicChatSuggestedQuestionsCn",
"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": {
"summary": "上传文件",
"description": "上传文件用于发送消息时使用，支持图片、文档、音频和视频的多模态理解。上传的文件仅供当前终端用户使用。",
"operationId": "uploadBasicChatFileCn",
"tags": [
"文件操作"
],
"requestBody": {
"description": "文件上传请求。需要 multipart/form-data 格式。",
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "要上传的文件。支持的类型包括图片、文档、音频和视频。"
},
"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": {
"summary": "下载文件",
"description": "预览或下载之前通过[上传文件](/api-reference/文件操作/上传文件) API 上传的文件。仅可访问属于请求应用内消息的文件。",
"operationId": "previewBasicChatFileCn",
"tags": [
"文件操作"
],
"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": {
"summary": "获取终端用户信息",
"description": "根据 ID 获取终端用户信息。当其他 API 返回终端用户 ID（例如[上传文件](/api-reference/文件操作/上传文件)返回的 `created_by`）时很有用。",
"operationId": "getEndUserChatCn",
"tags": [
"终端用户"
],
"parameters": [
{
"name": "end_user_id",
"in": "path",
"required": true,
"description": "终端用户 ID。",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "成功获取终端用户。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EndUserDetail"
},
"examples": {
"endUserDetail": {
"summary": "响应示例",
"value": {
"id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"type": "service_api",
"external_user_id": "abc-123",
"name": null,
"is_anonymous": false,
"session_id": "abc-123",
"created_at": "2024-01-16T12:00:29Z",
"updated_at": "2024-01-16T12:00:29Z"
}
}
}
}
}
},
"404": {
"description": "`end_user_not_found` : 未找到终端用户。",
"content": {
"application/json": {
"examples": {
"end_user_not_found": {
"summary": "end_user_not_found",
"value": {
"status": 404,
"code": "end_user_not_found",
"message": "End user not found."
}
}
}
}
}
}
}
}
},
"/messages/{message_id}/feedbacks": {
"post": {
"summary": "提交消息反馈",
"description": "提交消息反馈。终端用户可以对消息评价 `like` 或 `dislike`，并可选择提供文字反馈。将 `rating` 设为 `null` 可撤销之前提交的反馈。",
"operationId": "postBasicChatMessageFeedbackCn",
"tags": [
"消息反馈"
],
"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": {
"summary": "获取应用的消息反馈",
"description": "获取此应用中所有消息反馈的分页列表，包括终端用户和管理员反馈。",
"operationId": "getBasicChatAppFeedbacksCn",
"tags": [
"消息反馈"
],
"parameters": [
{
"name": "page",
"in": "query",
"description": "分页页码。",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"name": "limit",
"in": "query",
"description": "每页记录数。",
"required": false,
"schema": {
"type": "integer",
"default": 20,
"minimum": 1,
"maximum": 101
}
}
],
"responses": {
"200": {
"description": "应用反馈列表。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppFeedbacksResponse"
},
"examples": {
"feedbacksList": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456",
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"rating": "like",
"content": "The response accurately answered my question about product specifications.",
"from_source": "user",
"from_end_user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
"from_account_id": null,
"created_at": "2025-01-16T14:30:29Z",
"updated_at": "2025-01-16T14:30:29Z"
},
{
"id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678",
"app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"conversation_id": "56812a93-9229-5cd6-9f0c-75673b666603",
"message_id": "ae24b5c0-f814-584d-a493-5439e5d6b7b1",
"rating": "dislike",
"content": "The answer was too vague and did not address the specific pricing question.",
"from_source": "user",
"from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210",
"from_account_id": null,
"created_at": "2025-01-15T09:12:45Z",
"updated_at": "2025-01-15T09:12:45Z"
}
]
}
}
}
}
}
}
}
}
},
"/conversations": {
"get": {
"summary": "获取会话列表",
"description": "获取当前用户的会话列表，按最近活跃时间排序。",
"operationId": "getBasicChatConversationsListCn",
"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": "getBasicChatConversationHistoryCn",
"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,
"extra_contents": []
}
]
}
}
}
}
}
},
"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": "getBasicChatConversationVariablesCn",
"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": "renameBasicChatConversationCn",
"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": "updateChatConversationVariableZh",
"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": "deleteBasicChatConversationCn",
"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": {
"summary": "语音转文字",
"description": "将音频文件转换为文字。支持的格式：`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件大小限制为 `30 MB`。",
"operationId": "basicChatAudioToTextCn",
"tags": [
"语音与文字转换"
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/AudioToTextRequest"
}
}
}
},
"responses": {
"200": {
"description": "语音转文字成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AudioToTextResponse"
},
"examples": {
"audioToTextSuccess": {
"summary": "响应示例",
"value": {
"text": "Hello, I would like to know more about the iPhone 13 Pro Max."
}
}
}
}
}
},
"400": {
"description": "- `app_unavailable` : 应用不可用或配置错误。\n- `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": {
"summary": "文字转语音",
"description": "将文字转换为语音。",
"operationId": "basicChatTextToAudioCn",
"tags": [
"语音与文字转换"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TextToAudioRequest"
},
"examples": {
"textToAudioExample": {
"summary": "请求示例",
"value": {
"text": "Hello, welcome to our service.",
"user": "abc-123",
"voice": "alloy",
"streaming": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "返回生成的音频文件。`Content-Type` 头设置为音频 MIME 类型（例如 `audio/wav`、`audio/mp3`）。如果 `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": {
"summary": "获取应用基本信息",
"description": "获取应用的基本信息，包括名称、描述、标签和模式。",
"operationId": "getBasicChatAppInfoCn",
"tags": [
"应用配置"
],
"responses": {
"200": {
"description": "应用的基本信息。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppInfoResponse"
},
"examples": {
"appInfo": {
"summary": "响应示例",
"value": {
"name": "My Chat App",
"description": "一个有用的客服聊天机器人。",
"tags": [
"customer-service",
"chatbot"
],
"mode": "chat",
"author_name": "Dify Team"
}
}
}
}
}
}
}
}
},
"/parameters": {
"get": {
"summary": "获取应用参数",
"description": "获取应用的输入表单配置，包括功能开关、输入参数名称、类型和默认值。",
"operationId": "getBasicChatAppParametersCn",
"tags": [
"应用配置"
],
"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": {
"summary": "获取应用元数据",
"description": "获取应用的元数据，包括工具图标和其他配置详情。",
"operationId": "getBasicChatAppMetaCn",
"tags": [
"应用配置"
],
"responses": {
"200": {
"description": "成功获取应用元数据。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppMetaResponse"
},
"examples": {
"appMeta": {
"summary": "响应示例",
"value": {
"tool_icons": {
"dalle3": "https://example.com/icons/dalle3.png",
"calculator": {
"background": "#4A90D9",
"content": "🧮"
}
}
}
}
}
}
}
}
}
}
},
"/site": {
"get": {
"summary": "获取应用 WebApp 设置",
"description": "获取应用的 WebApp 设置，包括站点配置、主题和自定义选项。",
"operationId": "getBasicChatWebAppSettingsCn",
"tags": [
"应用配置"
],
"responses": {
"200": {
"description": "应用的 WebApp 设置。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebAppSettingsResponse"
},
"examples": {
"webAppSettings": {
"summary": "响应示例",
"value": {
"title": "My Chat App",
"chat_color_theme": "#4A90D9",
"chat_color_theme_inverted": false,
"icon_type": "emoji",
"icon": "🤖",
"icon_background": "#FFFFFF",
"icon_url": null,
"description": "一个有用的客服聊天机器人。",
"copyright": "2025 Dify",
"privacy_policy": "https://example.com/privacy",
"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": "createChatAnnotationZh",
"tags": [
"标注管理"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAnnotationRequest"
},
"examples": {
"createAnnotation": {
"summary": "请求示例",
"value": {
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform."
}
}
}
}
}
},
"responses": {
"201": {
"description": "标注创建成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnnotationItem"
},
"examples": {
"createdAnnotation": {
"summary": "响应示例",
"value": {
"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"question": "What is Dify?",
"answer": "Dify is an open-source LLM application development platform.",
"hit_count": 0,
"created_at": 1705407629
}
}
}
}
}
}
}
},
"get": {
"summary": "获取标注列表",
"description": "获取应用的标注分页列表。支持关键词搜索筛选。",
"operationId": "listChatAnnotationsZh",
"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": "updateChatAnnotationZh",
"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": "deleteChatAnnotationZh",
"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": "setChatAnnotationReplyZh",
"tags": [
"标注管理"
],
"parameters": [
{
"name": "action",
"in": "path",
"required": true,
"description": "要执行的操作。",
"schema": {
"type": "string",
"enum": [
"enable",
"disable"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest"
},
"examples": {
"enableAnnotationReply": {
"summary": "请求示例",
"value": {
"score_threshold": 0.9,
"embedding_provider_name": "openai",
"embedding_model_name": "text-embedding-3-small"
}
}
}
}
}
},
"responses": {
"200": {
"description": "标注回复设置任务已启动。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse"
},
"examples": {
"annotationReplyResponse": {
"summary": "响应示例",
"value": {
"job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"job_status": "waiting"
}
}
}
}
}
}
}
}
},
"/apps/annotation-reply/{action}/status/{job_id}": {
"get": {
"summary": "查询标注回复配置任务状态",
"description": "获取由 [配置标注回复](/api-reference/标注管理/配置标注回复) 发起的异步标注回复配置任务的状态。",
"operationId": "getChatAnnotationReplyStatusZh",
"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."
}
}
}
}
}
}
}
}
}
},
"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` 在完成后返回（长时间处理可能中断；Agent 助手模式不支持此选项）。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
}
}
},
"ChatCompletionResponse": {
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "事件类型，固定为 `message`。"
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "用于请求追踪和停止响应 API 的任务 ID。"
},
"id": {
"type": "string",
"format": "uuid",
"description": "该响应事件的唯一 ID。"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "唯一的消息 ID。调用反馈或推荐问题接口时，将此值作为 `message_id` 参数使用。"
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "会话 ID。"
},
"mode": {
"type": "string",
"description": "应用模式，固定为 `chat`。"
},
"answer": {
"type": "string",
"description": "完整的响应内容。"
},
"metadata": {
"type": "object",
"description": "包含用量和检索资源的元数据。",
"properties": {
"usage": {
"$ref": "#/components/schemas/Usage"
},
"retriever_resources": {
"type": "array",
"description": "使用的检索资源列表。",
"items": {
"$ref": "#/components/schemas/RetrieverResource"
}
}
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "消息创建时间戳（Unix 纪元秒）。"
}
}
},
"ChunkChatEvent": {
"type": "object",
"description": "流式模式下 Server-Sent Event 块的基础 schema。",
"properties": {
"event": {
"type": "string",
"description": "事件类型。",
"enum": [
"message",
"agent_message",
"tts_message",
"tts_message_end",
"agent_thought",
"message_file",
"message_end",
"message_replace",
"error",
"ping"
]
}
},
"discriminator": {
"propertyName": "event",
"mapping": {
"message": "#/components/schemas/StreamEventChatMessage",
"agent_message": "#/components/schemas/StreamEventChatAgentMessage",
"tts_message": "#/components/schemas/StreamEventChatTtsMessage",
"tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd",
"agent_thought": "#/components/schemas/StreamEventChatAgentThought",
"message_file": "#/components/schemas/StreamEventChatMessageFile",
"message_end": "#/components/schemas/StreamEventChatMessageEnd",
"message_replace": "#/components/schemas/StreamEventChatMessageReplace",
"error": "#/components/schemas/StreamEventChatError",
"ping": "#/components/schemas/StreamEventChatPing"
}
}
},
"StreamEventBase": {
"type": "object",
"description": "流式事件的基础属性。",
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "任务 ID。"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "唯一消息 ID。"
},
"conversation_id": {
"type": "string",
"format": "uuid",
"description": "会话 ID。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳。"
}
}
},
"StreamEventChatMessage": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"answer": {
"type": "string",
"description": "LLM 返回的文本块。"
}
}
}
]
},
"StreamEventChatAgentMessage": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"properties": {
"answer": {
"type": "string",
"description": "LLM 返回的文本块（Agent 模式）。"
}
}
}
]
},
"StreamEventChatTtsMessage": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "TTS 音频流事件（base64 编码的 Mp3）。自动播放启用时可用。",
"properties": {
"audio": {
"type": "string",
"format": "byte",
"description": "Base64 编码的 MP3 音频块。按顺序解码并拼接所有块即可生成完整的音频文件。"
}
}
}
]
},
"StreamEventChatTtsMessageEnd": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "TTS 音频流结束事件。",
"properties": {
"audio": {
"type": "string",
"description": "空字符串。标识音频流结束。"
}
}
}
]
},
"StreamEventChatAgentThought": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"$ref": "#/components/schemas/StreamEventBase"
},
{
"type": "object",
"description": "Agent 思考、LLM 推理、工具调用详情（Agent 模式）。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Agent 思考 ID。"
},
"position": {
"type": "integer",
"description": "该思考在消息序列中的位置。"
},
"thought": {
"type": "string",
"description": "LLM 正在思考的内容。"
},
"observation": {
"type": "string",
"description": "工具调用的响应。"
},
"tool": {
"type": "string",
"description": "调用的工具列表，以 `;` 分隔。"
},
"tool_input": {
"type": "string",
"description": "工具输入（JSON 格式）。"
},
"message_files": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "与该思考相关的文件 ID 列表。"
}
}
}
]
},
"StreamEventChatMessageFile": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkChatEvent"
},
{
"type": "object",
"description": "消息文件事件，由工具创建的新文件。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "文件唯一 ID。"
},
"type": {
"type": "string",
"description": "文件类型，例如 `image`。"
},
"belongs_to": {
"type": "string",
"description": "该文件的所属者。工具生成的文件始终为 `assistant`。"
},
"url": {
"type": "string",
"format": "url",
"description": "文件的远程 URL。"
},
"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": {
"type": "object",
"additionalProperties": true
}
}
}
},
"MessageFileItem": {
"type": "object",
"description": "附加到消息的文件。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "File ID."
},
"filename": {
"type": "string",
"description": "原始文件名。"
},
"type": {
"type": "string",
"description": "文件类型，例如 `image`。"
},
"url": {
"type": "string",
"format": "url",
"nullable": true,
"description": "文件的预览 URL。"
},
"mime_type": {
"type": "string",
"nullable": true,
"description": "文件的 MIME 类型。"
},
"size": {
"type": "integer",
"nullable": true,
"description": "文件大小（字节）。"
},
"transfer_method": {
"type": "string",
"description": "使用的传输方式。`remote_url` 表示基于 URL 的文件，`local_file` 表示已上传的文件，`tool_file` 表示工具生成的文件。"
},
"belongs_to": {
"type": "string",
"nullable": true,
"description": "该文件的所属者。用户上传的文件为 `user`，助手生成的文件为 `assistant`。"
},
"upload_file_id": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "通过 `local_file` 传输时的上传文件 ID。"
}
}
},
"AgentThoughtItem": {
"type": "object",
"description": "消息中的 Agent 思考步骤。",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Agent 思考 ID。"
},
"chain_id": {
"type": "string",
"nullable": true,
"description": "该思考的链 ID。"
},
"message_id": {
"type": "string",
"format": "uuid",
"description": "该思考所属的唯一消息 ID。"
},
"position": {
"type": "integer",
"description": "该思考的位置。"
},
"thought": {
"type": "string",
"description": "LLM 正在思考的内容。"
},
"tool": {
"type": "string",
"description": "调用的工具，以 `;` 分隔。"
},
"tool_labels": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "已使用工具的标签。"
},
"tool_input": {
"type": "string",
"description": "工具输入（JSON 格式）。"
},
"observation": {
"type": "string",
"description": "工具调用的响应。"
},
"files": {
"type": "array",
"items": {
"type": "string"
},
"description": "与该思考相关的文件 ID。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳。"
}
}
},
"ConversationsListResponse": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "每页条目数。"
},
"has_more": {
"type": "boolean",
"description": "是否有更多会话。"
},
"data": {
"type": "array",
"description": "会话列表。",
"items": {
"$ref": "#/components/schemas/ConversationListItem"
}
}
}
},
"ConversationListItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "会话 ID。"
},
"name": {
"type": "string",
"description": "会话名称。"
},
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "会话的输入变量。"
},
"status": {
"type": "string",
"description": "会话状态。活跃会话为 `normal`。"
},
"introduction": {
"type": "string",
"description": "会话介绍。"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "创建时间戳。"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "最后更新时间戳。"
}
}
},
"ConversationRenameRequest": {
"type": "object",
"description": "重命名会话的请求体。",
"properties": {
"name": {
"type": "string",
"description": "会话名称。当 `auto_generate` 为 `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": "应用模式。`chat` 表示基础聊天应用，`agent-chat` 表示 Agent 应用，`advanced-chat` 表示对话流应用。"
},
"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` 时为空字符串。"
}
}
}
}
},
"tags": [
{
"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