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_chat.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

4427 lines
147 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",
"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