From 69253c75253159f445950dfd48d8c44a83ee3107 Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Tue, 10 Mar 2026 18:09:26 +0800 Subject: [PATCH 1/6] Batch update service apis --- en/api-reference/openapi_chat.json | 4218 +++++++++--- en/api-reference/openapi_chatflow.json | 5917 ++++++++++++++--- en/api-reference/openapi_completion.json | 2388 +++++-- en/api-reference/openapi_knowledge.json | 7573 ++++++++++++++++------ en/api-reference/openapi_workflow.json | 3899 ++++++++++- 5 files changed, 19478 insertions(+), 4517 deletions(-) diff --git a/en/api-reference/openapi_chat.json b/en/api-reference/openapi_chat.json index 85c9cee25..182599e78 100644 --- a/en/api-reference/openapi_chat.json +++ b/en/api-reference/openapi_chat.json @@ -8,7 +8,7 @@ "servers": [ { "url": "{api_base_url}", - "description": "The base URL for the Chat App API. Replace {api_base_url} with the actual API base URL provided for your application (e.g., from props.appDetail.api_base_url).", + "description": "The base URL for the Chat App API. Replace {api_base_url} with the actual API base URL provided for your application.", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", @@ -27,8 +27,10 @@ "post": { "summary": "Send Chat Message", "description": "Send a request to the chat application.", - "operationId": "sendChatMessage", - "tags": ["Chat"], + "operationId": "createChatMessage", + "tags": [ + "Chats" + ], "requestBody": { "description": "Request body to send a chat message.", "required": true, @@ -39,9 +41,11 @@ }, "examples": { "streaming_example": { - "summary": "Streaming mode example with file", + "summary": "Request Example - Streaming mode", "value": { - "inputs": {}, + "inputs": { + "city": "San Francisco" + }, "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", "conversation_id": "", @@ -54,6 +58,16 @@ } ] } + }, + "blocking_example": { + "summary": "Request Example - Blocking mode", + "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" + } } } } @@ -61,7 +75,7 @@ }, "responses": { "200": { - "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n- If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkChatEvent` objects.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkChatEvent` objects.", "content": { "application/json": { "schema": { @@ -69,11 +83,11 @@ }, "examples": { "blockingResponse": { - "summary": "Example of a blocking mode response", + "summary": "Response Example - Blocking mode", "value": { "event": "message", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", - "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "mode": "chat", @@ -102,7 +116,7 @@ "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\"\n\"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\"" + "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\"" } ] }, @@ -114,71 +128,188 @@ "text/event-stream": { "schema": { "type": "string", - "description": "A stream of Server-Sent Events. Each event is a JSON object prefixed with 'data: ' and suffixed with '\\n\\n'. See `ChunkChatEvent` for possible event structures." + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkChatEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `message_end` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." }, "examples": { "streamingResponseBasic": { - "summary": "Example of a streaming mode response (Basic Assistant)", - "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}\n\ndata: {\"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}}}\n\n" + "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": "Example of a streaming mode response (Agent Assistant with agent_thought and message_file)", - "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}\n\ndata: {\"event\": \"message_file\", \"id\": \"file_id_1\", \"type\": \"image\", \"belongs_to\": \"assistant\", \"url\": \"https://example.com/cat.png\", \"conversation_id\": \"conv123\"}\n\ndata: {\"event\": \"agent_message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \"Here is the image: \", \"created_at\": 1705395333}\n\ndata: {\"event\": \"message_end\", \"task_id\":\"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}\n\n" + "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": "Bad Request. Possible error codes:\n- `invalid_param`: Abnormal parameter input.\n- `app_unavailable`: App configuration unavailable.\n- `provider_not_initialize`: No available model credential configuration.\n- `provider_quota_exceeded`: Model invocation quota insufficient.\n- `model_currently_not_support`: Current model unavailable.\n- `completion_request_error`: Text generation failed.", + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "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": "Conversation does not exist.", + "description": "`not_found` : Conversation does not exist.", + "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` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "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.", + "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } } } }, - "/files/upload": { + "/chat-messages/{task_id}/stop": { "post": { - "summary": "File Upload", - "description": "Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text. Supports png, jpg, jpeg, webp, gif formats. Uploaded files are for use by the current end-user only.", - "operationId": "uploadChatFile", - "tags": ["Files"], + "summary": "Stop Chat Message Generation", + "description": "Stops a chat message generation task. Only supported in `streaming` mode.", + "operationId": "stopChatMessage", + "tags": [ + "Chats" + ], + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "description": "Task ID, can be obtained from the streaming chunk return of the [Send Chat Message](/api-reference/chats/send-chat-message) API.", + "schema": { + "type": "string" + } + } + ], "requestBody": { - "description": "File upload request. Requires multipart/form-data.", "required": true, "content": { - "multipart/form-data": { + "application/json": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "user" + ], "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "The file to be uploaded. Supported image types: png, jpg, jpeg, webp, gif." - }, "user": { "type": "string", - "description": "User identifier, defined by the developer's rules, must be unique within the application. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "description": "User identifier, must be consistent with the user passed in the send message interface." + } + } + }, + "examples": { + "example": { + "summary": "Request Example", + "value": { + "user": "abc-123" } } } @@ -187,220 +318,169 @@ }, "responses": { "200": { - "description": "File uploaded successfully.", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponse" + "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." + } + } } } } - }, - "400": { "$ref": "#/components/responses/BadRequestFile" }, - "413": { "$ref": "#/components/responses/FileTooLarge" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFile" }, - "503": { "$ref": "#/components/responses/S3ErrorFile" }, - "500": { "$ref": "#/components/responses/InternalServerError" } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "Get End User", - "description": "Retrieve an end user by ID.\n\nThis is useful when other APIs return an end-user ID (e.g. `created_by` from File Upload).", - "operationId": "getEndUserChat", - "tags": ["End Users"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "End user ID.", - "schema": { "type": "string", "format": "uuid" } } - ], - "responses": { - "200": { - "description": "End user retrieved successfully.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetail" } - } - } - }, - "404": { "$ref": "#/components/responses/EndUserNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } } } }, - "/files/{file_id}/preview": { + "/messages/{message_id}/suggested": { "get": { - "summary": "File Preview", - "description": "Preview or download uploaded files. This endpoint allows you to access files that have been previously uploaded via the File Upload API. Files can only be accessed if they belong to messages within the requesting application.", - "operationId": "previewChatFile", - "tags": ["Files"], + "summary": "Get Next Suggested Questions", + "description": "Get next questions suggestions for the current message.", + "operationId": "getChatSuggestedQuestions", + "tags": [ + "Chats" + ], "parameters": [ { - "name": "file_id", + "name": "message_id", "in": "path", "required": true, - "description": "The unique identifier of the file to preview, obtained from the File Upload API response.", + "description": "Message ID.", "schema": { - "type": "string", - "format": "uuid" + "type": "string" } }, { - "name": "as_attachment", + "name": "user", "in": "query", - "required": false, - "description": "Whether to force download the file as an attachment. Default is `false` (preview in browser).", + "required": true, + "description": "User identifier.", "schema": { - "type": "boolean", - "default": false + "type": "string" } } ], "responses": { "200": { - "description": "File content returned successfully. Headers set based on file type and request parameters.", + "description": "Successfully retrieved suggested questions.", "content": { - "image/png": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - }, - "headers": { - "Content-Type": { - "description": "MIME type of the file", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "File size in bytes (if available)", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "Set to 'attachment' if as_attachment=true", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "Caching headers for performance", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "Set to 'bytes' for audio/video files", + "application/json": { "schema": { - "type": "string", - "example": "bytes" + "$ref": "#/components/schemas/SuggestedQuestionsResponse" + }, + "examples": { + "suggestedQuestions": { + "summary": "Response Example", + "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": "Bad Request. Possible error codes:\n- `invalid_param`: Abnormal parameter input.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "403": { - "description": "Forbidden. Possible error codes:\n- `file_access_denied`: File access denied or file does not belong to current application.", + "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Suggested questions feature is disabled.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "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. Possible error codes:\n- `file_not_found`: File not found or has been deleted.", + "description": "`not_found` : Message does not exist.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } } } }, "500": { - "description": "Internal server error.", + "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } } } }, - "/chat-messages/{task_id}/stop": { + "/files/upload": { "post": { - "summary": "Stop Chat Message Generation", - "description": "Stops a chat message generation task. Only supported in streaming mode.", - "operationId": "stopChatMessageGeneration", - "tags": ["Chat"], - "parameters": [ - { - "name": "task_id", - "in": "path", - "required": true, - "description": "Task ID, can be obtained from the streaming chunk return of a `/chat-messages` request.", - "schema": { - "type": "string" - } - } + "summary": "Upload File", + "description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", + "operationId": "uploadChatFile", + "tags": [ + "Files" ], "requestBody": { + "description": "File upload request. Requires multipart/form-data.", "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "file" + ], "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "The file to be uploaded. Supported types include images, documents, audio, and video." + }, "user": { "type": "string", - "description": "User identifier, must be consistent with the user passed in the send message interface. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." - } - } - }, - "examples": { - "example":{ - "value": { - "user": "abc-123" + "description": "User identifier, defined by the developer's rules, must be unique within the application." } } } @@ -408,77 +488,188 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "Message Feedback", - "description": "End-users can provide feedback messages, facilitating application developers to optimize expected outputs.", - "operationId": "postChatMessageFeedback", - "tags": ["Feedback"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "Message ID for which feedback is being provided.", - "schema": { - "type": "string" + "201": { + "description": "File uploaded successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "Response Example", + "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" + } + } + } + } } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "400": { + "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.", + "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` : File size exceeded.", + "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` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } } } } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } } } }, - "/app/feedbacks": { + "/files/{file_id}/preview": { "get": { - "summary": "Get feedbacks of application", - "description": "Get application's feedbacks.", - "operationId": "getChatAppFeedbacks", - "tags": ["Feedback"], + "summary": "Download File", + "description": "Preview or download uploaded files previously uploaded via the [File Upload](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", + "operationId": "previewChatFile", + "tags": [ + "Files" + ], "parameters": [ { - "name": "page", + "name": "file_id", + "in": "path", + "required": true, + "description": "The unique identifier of the file to preview, obtained from the [File Upload](/api-reference/files/upload-file) API response.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", "in": "query", - "description": "(optional) Pagination page number. Default: 1", "required": false, + "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", "schema": { - "type": "integer", - "default": 1 + "type": "boolean", + "default": false } }, { - "name": "limit", + "name": "user", "in": "query", - "description": "(optional) Records per page. Default: 20", "required": false, + "description": "User identifier, used for end-user context.", "schema": { - "type": "integer", - "default": 20 + "type": "string" } } ], "responses": { "200": { - "description": "A list of application feedbacks.", + "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "$ref": "#/components/schemas/AppFeedbacksResponse" + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : Access to the requested file is 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` : The requested file was 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." + } + } } } } @@ -486,39 +677,130 @@ } } }, - "/messages/{message_id}/suggested": { + "/end-users/{end_user_id}": { "get": { - "summary": "Next Suggested Questions", - "description": "Get next questions suggestions for the current message.", - "operationId": "getSuggestedQuestions", - "tags": ["Chat"], + "summary": "Get End User", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", + "operationId": "getChatEndUser", + "tags": [ + "End Users" + ], "parameters": [ { - "name": "message_id", + "name": "end_user_id", "in": "path", "required": true, - "description": "Message ID.", + "description": "End user ID.", "schema": { - "type": "string" + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "End user retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "Response Example", + "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` : 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": "Submit Message Feedback", + "description": "Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.", + "operationId": "createChatMessageFeedback", + "tags": [ + "Feedback" + ], + "parameters": [ { - "name": "user", - "in": "query", + "name": "message_id", + "in": "path", "required": true, - "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface.", + "description": "Message ID.", "schema": { "type": "string" } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "Request Example", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } + } + } + } + }, "responses": { "200": { - "description": "Successfully retrieved suggested questions.", + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : Message does not exist.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/SuggestedQuestionsResponse" + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } } } } @@ -526,49 +808,81 @@ } } }, - "/messages": { + "/app/feedbacks": { "get": { - "summary": "Get Conversation History Messages", - "description": "Returns historical chat records in a scrolling load format, with the first page returning the latest `{limit}` messages, i.e., in reverse order.", - "operationId": "getConversationHistory", - "tags": ["Conversations"], + "summary": "List App Feedbacks", + "description": "Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.", + "operationId": "listChatFeedbacks", + "tags": [ + "Feedback" + ], "parameters": [ { - "name": "conversation_id", - "in": "query", - "required": true, - "description": "Conversation ID.", - "schema": { "type": "string" } - }, - { - "name": "user", - "in": "query", - "required": true, - "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface.", - "schema": { "type": "string" } - }, - { - "name": "first_id", + "name": "page", "in": "query", + "description": "Page number for pagination.", "required": false, - "description": "The ID of the first chat record on the current page, default is null (for fetching the latest). For subsequent pages, use the ID of the first message from the current list to get older messages.", - "schema": { "type": "string" } + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } }, { "name": "limit", "in": "query", + "description": "Number of records per page.", "required": false, - "description": "How many chat history messages to return in one request, default is 20.", - "schema": { "type": "integer", "default": 20 } + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } } ], "responses": { "200": { - "description": "Successfully retrieved conversation history.", + "description": "A list of application feedbacks.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConversationHistoryResponse" + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "Response Example", + "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-75673b6666g3", + "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" + } + ] + } + } } } } @@ -578,40 +892,56 @@ }, "/conversations": { "get": { - "summary": "Get Conversations", - "description": "Retrieve the conversation list for the current user, defaulting to the most recent 20 entries.", - "operationId": "getConversationsList", - "tags": ["Conversations"], + "summary": "List Conversations", + "description": "Retrieve the conversation list for the current user, ordered by most recently active.", + "operationId": "listChatConversations", + "tags": [ + "Conversations" + ], "parameters": [ { "name": "user", "in": "query", - "required": true, - "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface.", - "schema": { "type": "string" } + "required": false, + "description": "User identifier.", + "schema": { + "type": "string" + } }, { "name": "last_id", "in": "query", "required": false, - "description": "(Optional) The ID of the last record on the current page (for pagination).", - "schema": { "type": "string" } + "description": "The ID of the last record on the current page (for pagination).", + "schema": { + "type": "string" + } }, { "name": "limit", "in": "query", "required": false, - "description": "(Optional) How many records to return. Default 20, Min 1, Max 100.", - "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } + "description": "Number of records to return.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } }, { "name": "sort_by", "in": "query", "required": false, - "description": "Sorting Field. Default: -updated_at. '-' prefix for descending.", + "description": "Sorting field. Use '-' prefix for descending order.", "schema": { "type": "string", - "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], + "enum": [ + "created_at", + "-created_at", + "updated_at", + "-updated_at" + ], "default": "-updated_at" } } @@ -623,6 +953,62 @@ "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsListResponse" + }, + "examples": { + "conversationsList": { + "summary": "Response Example", + "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` : App mode does not match the API route.", + "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 conversation does not exist (invalid `last_id`).", + "content": { + "application/json": { + "examples": { + "last_conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Last Conversation Not Exists." + } + } } } } @@ -630,75 +1016,135 @@ } } }, - "/conversations/{conversation_id}": { - "delete": { - "summary": "Delete Conversation", - "description": "Delete a conversation.", - "operationId": "deleteConversation", - "tags": ["Conversations"], + "/messages": { + "get": { + "summary": "List Conversation Messages", + "description": "Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order.", + "operationId": "listChatMessages", + "tags": [ + "Conversations" + ], "parameters": [ { "name": "conversation_id", - "in": "path", + "in": "query", "required": true, "description": "Conversation ID.", - "schema": { "type": "string" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["user"], - "properties": { - "user": { - "type": "string", - "description": "The user identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." - } - } - } + "schema": { + "type": "string" } - } - }, - "responses": { - "204": { "description": "Conversation deleted successfully. No Content." } - } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "Conversation Rename", - "description": "Rename the session. The session name is used for display on clients that support multiple sessions.", - "operationId": "renameConversation", - "tags": ["Conversations"], - "parameters": [ + }, { - "name": "conversation_id", - "in": "path", - "required": true, - "description": "Conversation ID.", - "schema": { "type": "string" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConversationRenameRequest" - } + "name": "user", + "in": "query", + "required": false, + "description": "User identifier.", + "schema": { + "type": "string" + } + }, + { + "name": "first_id", + "in": "query", + "required": false, + "description": "The ID of the first chat record on the current page. Default is `null` (fetches the latest messages). For subsequent pages, use the ID of the first message from the current list to get older messages.", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of chat history messages to return per request.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 } } - }, + ], "responses": { "200": { - "description": "Conversation renamed successfully.", + "description": "Successfully retrieved conversation history.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConversationRenameResponse" + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "Response Example", + "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` : App mode does not match the API route.", + "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` : Conversation does not exist.\n- `not_found` : First message does not exist.", + "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." + } + } } } } @@ -708,45 +1154,62 @@ }, "/conversations/{conversation_id}/variables": { "get": { - "summary": "Get Conversation Variables", + "summary": "List Conversation Variables", "description": "Retrieve variables from a specific conversation.", - "operationId": "getConversationVariables", - "tags": ["Conversations"], + "operationId": "listChatConversationVariables", + "tags": [ + "Conversations" + ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, - "description": "The ID of the conversation to retrieve variables from.", - "schema": { "type": "string" } + "description": "Conversation ID.", + "schema": { + "type": "string" + } }, { "name": "user", "in": "query", - "required": true, + "required": false, "description": "The user identifier.", - "schema": { "type": "string" } + "schema": { + "type": "string" + } }, { "name": "last_id", "in": "query", "required": false, - "description": "(Optional) The ID of the last record on the current page (for pagination).", - "schema": { "type": "string" } + "description": "The ID of the last record on the current page (for pagination).", + "schema": { + "type": "string" + } }, { "name": "limit", "in": "query", "required": false, - "description": "(Optional) How many records to return. Default 20, Min 1, Max 100.", - "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } + "description": "Number of records to return.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } }, { "name": "variable_name", "in": "query", "required": false, - "description": "(Optional) Filter variables by a specific name.", - "schema": { "type": "string" } + "description": "Filter variables by a specific name.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } } ], "responses": { @@ -754,37 +1217,62 @@ "description": "Successfully retrieved conversation variables.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationVariablesResponse" } + "schema": { + "$ref": "#/components/schemas/ConversationVariablesResponse" + }, + "examples": { + "conversationVariables": { + "summary": "Response Example", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "dark_mode", + "description": "User preference setting", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } } } }, - "404": { "$ref": "#/components/responses/ConversationNotFound" } - } - } - }, - "/audio-to-text": { - "post": { - "summary": "Speech to Text", - "description": "Convert audio file to text. Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm. File size limit: 15MB.", - "operationId": "audioToText", - "tags": ["TTS"], - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "$ref": "#/components/schemas/AudioToTextRequest" + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "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." + } + } + } } } - } - }, - "responses": { - "200": { - "description": "Successfully converted audio to text.", + }, + "404": { + "description": "`not_found` : Conversation does not exist.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/AudioToTextResponse" + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } } } } @@ -792,60 +1280,101 @@ } } }, - "/text-to-audio": { + "/conversations/{conversation_id}/name": { "post": { - "summary": "Text to Audio", - "description": "Convert text to speech.", - "operationId": "textToAudioChat", - "tags": ["TTS"], + "summary": "Rename Conversation", + "description": "Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations.", + "operationId": "renameChatConversation", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + } + ], "requestBody": { "required": true, "content": { - "multipart/form-data": { + "application/json": { "schema": { - "$ref": "#/components/schemas/TextToAudioFormRequest" + "$ref": "#/components/schemas/ConversationRenameRequest" + }, + "examples": { + "renameExample": { + "summary": "Request Example", + "value": { + "name": "iPhone Specs Chat", + "user": "abc-123" + } + } } } } }, "responses": { "200": { - "description": "Audio file generated successfully.", + "description": "Conversation renamed successfully.", "content": { - "audio/wav": { + "application/json": { "schema": { - "type": "string", - "format": "binary", - "description": "The generated audio file." + "$ref": "#/components/schemas/ConversationListItem" + }, + "examples": { + "renamedConversation": { + "summary": "Response Example", + "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 + } + } } } - }, - "headers": { - "Content-Type": { - "description": "The content type of the response, typically `audio/wav` or `audio/mp3`.", - "schema": { - "type": "string", - "example": "audio/wav" + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "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." + } + } } } } - } - } - } - }, - "/info": { - "get": { - "summary": "Get Application Basic Information", - "description": "Used to get basic information about this application.", - "operationId": "getChatAppInfo", - "tags": ["Application"], - "responses": { - "200": { - "description": "Basic information of the application.", + }, + "404": { + "description": "`not_found` : Conversation does not exist.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/AppInfoResponse" + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } } } } @@ -853,28 +1382,650 @@ } } }, - "/parameters": { - "get": { - "summary": "Get Application Parameters Information", - "description": "Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values.", - "operationId": "getChatAppParameters", - "tags": ["Application"], + "/conversations/{conversation_id}/variables/{variable_id}": { + "put": { + "summary": "Update Conversation Variable", + "description": "Update the value of a specific conversation variable. The value must match the expected type.", + "operationId": "updateChatConversationVariable", + "tags": [ + "Conversations" + ], "parameters": [ - { - "name": "user", - "in": "query", + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "variable_id", + "in": "path", "required": true, - "description": "User identifier, defined by the developer's rules, must be unique within the application.", - "schema": { "type": "string" } + "description": "Variable ID.", + "schema": { + "type": "string", + "format": "uuid" + } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableUpdateRequest" + }, + "examples": { + "updateStringVariable": { + "summary": "Request Example", + "value": { + "value": "new value", + "user": "abc-123" + } + } + } + } + } + }, "responses": { "200": { - "description": "Application parameters information.", + "description": "Variable updated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatAppParametersResponse" + "$ref": "#/components/schemas/ConversationVariableItem" + }, + "examples": { + "updatedVariable": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "new value", + "description": "User preference setting", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Variable value type mismatch.", + "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` : Conversation does not exist.\n- `not_found` : Conversation variable does not exist.", + "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": "Delete Conversation", + "description": "Delete a conversation.", + "operationId": "deleteChatConversation", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user": { + "type": "string", + "description": "The user identifier." + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "Request Example" + } + } + } + } + }, + "responses": { + "204": { + "description": "Conversation deleted successfully." + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "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` : Conversation does not exist.", + "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": "Convert Audio to Text", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `15 MB`.", + "operationId": "chatAudioToText", + "tags": [ + "TTS" + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully converted audio to text.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "Response Example", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", + "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` : Audio file size exceeded the limit.", + "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` : Audio type is not allowed.", + "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` : 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": "Convert Text to Audio", + "description": "Convert text to speech.", + "operationId": "chatTextToAudio", + "tags": [ + "TTS" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "Request Example", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", + "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." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : Audio file size exceeded.", + "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` : Audio type not allowed.", + "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` : 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": "Get App Info", + "description": "Retrieve basic information about this application, including name, description, tags, and mode.", + "operationId": "getChatAppInfo", + "tags": [ + "Applications" + ], + "responses": { + "200": { + "description": "Basic information of the application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "Response Example", + "value": { + "name": "My Chat App", + "description": "A helpful customer service chatbot.", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "chat", + "author_name": "Dify Team" + } + } + } + } + } + } + } + } + }, + "/parameters": { + "get": { + "summary": "Get App Parameters", + "description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.", + "operationId": "getChatAppParameters", + "tags": [ + "Applications" + ], + "responses": { + "200": { + "description": "Application parameters information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "Response Example", + "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` : App unavailable or misconfigured.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } } } } @@ -884,10 +2035,12 @@ }, "/meta": { "get": { - "summary": "Get Application Meta Information", - "description": "Used to get icons of tools in this application.", + "summary": "Get App Meta", + "description": "Retrieve metadata about this application, including tool icons and other configuration details.", "operationId": "getChatAppMeta", - "tags": ["Application"], + "tags": [ + "Applications" + ], "responses": { "200": { "description": "Successfully retrieved application meta information.", @@ -895,6 +2048,20 @@ "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "Response Example", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } } } } @@ -904,10 +2071,12 @@ }, "/site": { "get": { - "summary": "Get Application WebApp Settings", - "description": "Used to get the WebApp settings of the application.", + "summary": "Get App WebApp Settings", + "description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.", "operationId": "getChatWebAppSettings", - "tags": ["Application"], + "tags": [ + "Applications" + ], "responses": { "200": { "description": "WebApp settings of the application.", @@ -915,6 +2084,44 @@ "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "Response Example", + "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": "A helpful customer service chatbot.", + "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` : Site not found for this application or the workspace has been archived.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } } } } @@ -923,57 +2130,123 @@ } }, "/apps/annotations": { + "post": { + "summary": "Create Annotation", + "description": "Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response.", + "operationId": "createChatAnnotation", + "tags": [ + "Annotations" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAnnotationRequest" + }, + "examples": { + "createAnnotation": { + "summary": "Request Example", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Annotation created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "createdAnnotation": { + "summary": "Response Example", + "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": "Get Annotation List", - "description": "Retrieves a list of annotations for the application.", - "operationId": "getAnnotationList", - "tags": ["Annotations"], + "summary": "List Annotations", + "description": "Retrieves a paginated list of annotations for the application. Supports keyword search filtering.", + "operationId": "listChatAnnotations", + "tags": [ + "Annotations" + ], "parameters": [ { "name": "page", "in": "query", - "description": "Page number.", + "description": "Page number for pagination.", "required": false, - "schema": { "type": "integer", "default": 1 } + "schema": { + "type": "integer", + "default": 1 + } }, { "name": "limit", "in": "query", - "description": "Number of items returned, default 20, range 1-100.", + "description": "Number of items per page.", "required": false, - "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } - } - ], - "responses": { - "200": { - "description": "Successfully retrieved annotation list.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/AnnotationListResponse" } - } + "schema": { + "type": "integer", + "default": 20 } - } - } - }, - "post": { - "summary": "Create Annotation", - "description": "Creates a new annotation.", - "operationId": "createAnnotation", - "tags": ["Annotations"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" } + }, + { + "name": "keyword", + "in": "query", + "description": "Keyword to filter annotations by question or answer content.", + "required": false, + "schema": { + "type": "string" } } - }, + ], "responses": { "200": { - "description": "Annotation created successfully.", + "description": "Successfully retrieved annotation list.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AnnotationItem" } + "schema": { + "$ref": "#/components/schemas/AnnotationListResponse" + }, + "examples": { + "annotationList": { + "summary": "Response Example", + "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 + } + } + } } } } @@ -983,23 +2256,39 @@ "/apps/annotations/{annotation_id}": { "put": { "summary": "Update Annotation", - "description": "Updates an existing annotation.", - "operationId": "updateAnnotation", - "tags": ["Annotations"], + "description": "Updates the question and answer of an existing annotation.", + "operationId": "updateChatAnnotation", + "tags": [ + "Annotations" + ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, - "description": "Annotation ID.", - "schema": { "type": "string" } + "description": "The unique identifier of the annotation to update.", + "schema": { + "type": "string", + "format": "uuid" + } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" } + "schema": { + "$ref": "#/components/schemas/UpdateAnnotationRequest" + }, + "examples": { + "updateAnnotation": { + "summary": "Request Example", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." + } + } + } } } }, @@ -1008,7 +2297,55 @@ "description": "Annotation updated successfully.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AnnotationItem" } + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "updatedAnnotation": { + "summary": "Response Example", + "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` : Insufficient permissions to edit annotations.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Annotation does not exist.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } } } } @@ -1016,43 +2353,104 @@ }, "delete": { "summary": "Delete Annotation", - "description": "Deletes an annotation.", - "operationId": "deleteAnnotation", - "tags": ["Annotations"], + "description": "Deletes an annotation and its associated hit history.", + "operationId": "deleteChatAnnotation", + "tags": [ + "Annotations" + ], "parameters": [ { "name": "annotation_id", "in": "path", "required": true, - "description": "Annotation ID.", - "schema": { "type": "string" } + "description": "The unique identifier of the annotation to delete.", + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { - "204": { "description": "Annotation deleted successfully. No Content." } + "204": { + "description": "Annotation deleted successfully." + }, + "403": { + "description": "`forbidden` : Insufficient permissions to edit annotations.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Annotation does not exist.", + "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": "Initial Annotation Reply Settings", - "description": "Enable or disable annotation reply settings and configure embedding models. This interface is executed asynchronously.", - "operationId": "initialAnnotationReplySettings", - "tags": ["Annotations"], + "summary": "Configure Annotation Reply", + "description": "Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Retrieve Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.", + "operationId": "setChatAnnotationReply", + "tags": [ + "Annotations" + ], "parameters": [ { "name": "action", "in": "path", "required": true, - "description": "Action, can only be 'enable' or 'disable'.", - "schema": { "type": "string", "enum": ["enable", "disable"] } + "description": "Action to perform.", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" } + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" + }, + "examples": { + "enableAnnotationReply": { + "summary": "Request Example", + "value": { + "score_threshold": 0.9, + "embedding_provider_name": "openai", + "embedding_model_name": "text-embedding-3-small" + } + } + } } } }, @@ -1061,7 +2459,18 @@ "description": "Annotation reply settings task initiated.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" } + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" + }, + "examples": { + "annotationReplyResponse": { + "summary": "Response Example", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "waiting" + } + } + } } } } @@ -1070,24 +2479,35 @@ }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { - "summary": "Query Initial Annotation Reply Settings Task Status", - "description": "Queries the status of an asynchronously executed annotation reply settings task.", - "operationId": "getInitialAnnotationReplySettingsStatus", - "tags": ["Annotations"], + "summary": "Get Annotation Reply Job Status", + "description": "Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", + "operationId": "getChatAnnotationReplyStatus", + "tags": [ + "Annotations" + ], "parameters": [ { "name": "action", "in": "path", "required": true, - "description": "Action, must be the same as in the initial settings call ('enable' or 'disable').", - "schema": { "type": "string", "enum": ["enable", "disable"] } + "description": "Action type, must match the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call.", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } }, { "name": "job_id", "in": "path", "required": true, - "description": "Job ID obtained from the initial settings call.", - "schema": { "type": "string" } + "description": "Job ID returned by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", + "schema": { + "type": "string", + "format": "uuid" + } } ], "responses": { @@ -1095,7 +2515,36 @@ "description": "Successfully retrieved task status.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" } + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "Response Example", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : The specified job does not exist.", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "The job does not exist." + } + } + } } } } @@ -1109,137 +2558,124 @@ "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", - "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with 'Bearer '. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" } }, "responses": { - "BadRequestFile": { - "description": "Bad Request for file operations. Possible error codes:\n- `no_file_uploaded`: A file must be provided.\n- `too_many_files`: Currently only one file is accepted.\n- `unsupported_preview`: The file does not support preview.\n- `unsupported_estimate`: The file does not support estimation.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "FileTooLarge": { - "description": "`file_too_large`: The file is too large.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "UnsupportedFileTypeFile": { - "description": "`unsupported_file_type`: Unsupported extension. (Note: The description for `/files/upload` lists image types, while this generic error mentions document files. This might indicate a context-specific message from the backend).", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "S3ErrorFile": { - "description": "Service Unavailable for S3 operations. Possible error codes:\n- `s3_connection_failed`: Unable to connect to S3 service.\n- `s3_permission_denied`: No permission to upload files to S3.\n- `s3_file_too_large`: File exceeds S3 size limit.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "InternalServerError": { - "description": "Internal server error.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "SuccessResult": { - "description": "Operation successful.", - "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } - }, - "ConversationNotFound": { - "description": "Conversation not found. Error code: `conversation_not_exists`", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } - }, - "EndUserNotFound": { - "description": "End user not found. Error code: `end_user_not_found`", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } + "SuccessResult": { + "description": "Operation successful.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Result status." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } } + } }, "schemas": { "ChatRequest": { "type": "object", - "required": ["query", "user"], + "required": [ + "inputs", + "query", + "user" + ], "properties": { "query": { "type": "string", - "description": "User Input/Question content." + "description": "User input/question content." }, "inputs": { "type": "object", - "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs. Default {}.", - "additionalProperties": true, - "default": {} + "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", + "additionalProperties": true }, "response_mode": { "type": "string", - "enum": ["streaming", "blocking"], - "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes; not supported in Agent Assistant mode). Cloudflare timeout is 100s.", - "default": "streaming" + "enum": [ + "streaming", + "blocking" + ], + "default": "blocking", + "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes; not supported in Agent Assistant mode). Cloudflare timeout is `100 s`." }, "user": { "type": "string", - "description": "User identifier, unique within the application. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "description": "User identifier, unique within the application. This identifier scopes data access — conversations, messages, and files are only visible when queried with the same `user` value." }, "conversation_id": { "type": "string", - "description": "Conversation ID to continue a conversation. Pass the previous message's conversation_id." + "description": "Conversation ID to continue a conversation. Pass the previous message's `conversation_id`. To start a new conversation, omit this field or pass an empty string. The response will return a `conversation_id` — pass it in subsequent messages to continue that conversation." }, "files": { "type": "array", + "description": "File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`.", "items": { - "$ref": "#/components/schemas/InputFileObject" - }, - "description": "File list (images) for Vision-capable models." + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "File type." + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file." + }, + "url": { + "type": "string", + "format": "url", + "description": "File URL (required when `transfer_method` is `remote_url`)." + }, + "upload_file_id": { + "type": "string", + "description": "Uploaded file ID obtained from the [File Upload](/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`)." + } + } + } }, "auto_generate_name": { "type": "boolean", - "description": "Auto-generate conversation title. Default `true`. If `false`, use conversation rename API with `auto_generate: true` for async title generation.", + "description": "Auto-generate conversation title. If `false`, use the [Rename Conversation](/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation.", "default": true } } }, - "InputFileObject": { - "type": "object", - "required": ["type", "transfer_method"], - "properties": { - "type": { - "type": "string", - "enum": ["image"], - "description": "Supported type: `image`." - }, - "transfer_method": { - "type": "string", - "enum": ["remote_url", "local_file"], - "description": "Transfer method, `remote_url` for image URL / `local_file` for file upload" - }, - "url": { - "type": "string", - "format": "url", - "description": "Image URL (when the transfer method is `remote_url`)" - }, - "upload_file_id": { - "type": "string", - "description": "Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`)" - } - }, - "anyOf": [ - { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } - }, - { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } - } - ] - }, "ChatCompletionResponse": { "type": "object", - "description": "Response object for blocking mode chat completion.", "properties": { "event": { "type": "string", - "description": "Event type, fixed as `message`.", - "example": "message" + "description": "Event type, fixed as `message`." }, "task_id": { "type": "string", @@ -1249,12 +2685,12 @@ "id": { "type": "string", "format": "uuid", - "description": "Unique ID of this response/message event." + "description": "Unique ID of this response event." }, "message_id": { "type": "string", "format": "uuid", - "description": "Unique message ID." + "description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints." }, "conversation_id": { "type": "string", @@ -1263,8 +2699,7 @@ }, "mode": { "type": "string", - "description": "App mode, fixed as `chat`.", - "example": "chat" + "description": "App mode, fixed as `chat`." }, "answer": { "type": "string", @@ -1272,11 +2707,17 @@ }, "metadata": { "type": "object", + "description": "Metadata including usage and retriever resources.", "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, + "usage": { + "$ref": "#/components/schemas/Usage" + }, "retriever_resources": { "type": "array", - "items": { "$ref": "#/components/schemas/RetrieverResource" } + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } } } }, @@ -1290,12 +2731,22 @@ "ChunkChatEvent": { "type": "object", "description": "Base schema for Server-Sent Event chunks in streaming mode.", - "required": ["event"], "properties": { "event": { "type": "string", "description": "The type of event.", - "enum": ["message", "agent_message", "tts_message", "tts_message_end", "agent_thought", "message_file", "message_end", "message_replace", "error", "ping"] + "enum": [ + "message", + "agent_message", + "tts_message", + "tts_message_end", + "agent_thought", + "message_file", + "message_end", + "message_replace", + "error", + "ping" + ] } }, "discriminator": { @@ -1316,86 +2767,153 @@ }, "StreamEventBase": { "type": "object", + "description": "Base properties for stream events.", "properties": { - "task_id": { "type": "string", "format": "uuid", "description": "Task ID." }, - "message_id": { "type": "string", "format": "uuid", "description": "Unique message ID." }, - "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, - "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." } + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + } } }, "StreamEventChatMessage": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "required": ["answer"], "properties": { - "answer": { "type": "string", "description": "LLM returned text chunk." } + "answer": { + "type": "string", + "description": "LLM returned text chunk." + } } } ] }, "StreamEventChatAgentMessage": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "required": ["answer"], "properties": { - "answer": { "type": "string", "description": "LLM returned text chunk (Agent mode)." } + "answer": { + "type": "string", + "description": "LLM returned text chunk (Agent mode)." + } } } ] }, "StreamEventChatTtsMessage": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "TTS audio stream event (base64 encoded Mp3). Available if auto-play enabled.", - "required": ["audio"], "properties": { - "audio": { "type": "string", "format": "byte", "description": "Base64 encoded audio chunk." } + "audio": { + "type": "string", + "format": "byte", + "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." + } } } ] }, "StreamEventChatTtsMessageEnd": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "TTS audio stream end event.", - "required": ["audio"], "properties": { - "audio": { "type": "string", "description": "Empty string for end event." } + "audio": { + "type": "string", + "description": "Empty string. Signals the end of the audio stream." + } } } ] }, "StreamEventChatAgentThought": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Agent thought, LLM thinking, tool call details (Agent mode).", - "required": ["id", "position"], "properties": { - "id": { "type": "string", "format": "uuid", "description": "Agent thought ID." }, - "position": { "type": "integer", "description": "Position of this thought in the sequence for the message." }, - "thought": { "type": "string", "description": "What LLM is thinking." }, - "observation": { "type": "string", "description": "Response from tool calls." }, - "tool": { "type": "string", "description": "List of tools called, split by ';'." }, - "tool_input": { "type": "string", "description": "Input of tools in JSON format. Example: {\"dalle3\": {\"prompt\": \"a cute cat\"}}." }, + "id": { + "type": "string", + "format": "uuid", + "description": "Agent thought ID." + }, + "position": { + "type": "integer", + "description": "Position of this thought in the sequence for the message." + }, + "thought": { + "type": "string", + "description": "What LLM is thinking." + }, + "observation": { + "type": "string", + "description": "Response from tool calls." + }, + "tool": { + "type": "string", + "description": "List of tools called, split by `;`." + }, + "tool_input": { + "type": "string", + "description": "Input of tools in JSON format." + }, "message_files": { "type": "array", - "items": { "type": "string", "format": "uuid" }, - "description": "File IDs of files related to this thought (e.g., generated by a tool)." + "items": { + "type": "string", + "format": "uuid" + }, + "description": "File IDs of files related to this thought." } } } @@ -1403,37 +2921,65 @@ }, "StreamEventChatMessageFile": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, { "type": "object", "description": "Message file event, a new file created by a tool.", - "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { - "id": { "type": "string", "format": "uuid", "description": "File unique ID." }, - "type": { "type": "string", "enum": ["image"], "description": "File type, currently only 'image'." }, - "belongs_to": { "type": "string", "enum": ["assistant"], "description": "Who this file belongs to, always 'assistant' here." }, - "url": { "type": "string", "format": "url", "description": "Remote URL of the file." }, - "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID." } + "id": { + "type": "string", + "format": "uuid", + "description": "File unique ID." + }, + "type": { + "type": "string", + "description": "File type, e.g. `image`." + }, + "belongs_to": { + "type": "string", + "description": "Who this file belongs to. Always `assistant` for tool-generated files." + }, + "url": { + "type": "string", + "format": "url", + "description": "Remote URL of the file." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + } } } ] }, "StreamEventChatMessageEnd": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Message end event, streaming has ended.", - "required": ["metadata"], "properties": { "metadata": { "type": "object", + "description": "Metadata including usage and retriever resources.", "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, + "usage": { + "$ref": "#/components/schemas/Usage" + }, "retriever_resources": { "type": "array", - "items": { "$ref": "#/components/schemas/RetrieverResource" } + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } } } } @@ -1443,37 +2989,61 @@ }, "StreamEventChatMessageReplace": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Message content replacement event (e.g., due to content moderation).", - "required": ["answer"], "properties": { - "answer": { "type": "string", "description": "Replacement content." } + "answer": { + "type": "string", + "description": "Replacement content." + }, + "reason": { + "type": "string", + "description": "Reason for the content replacement." + } } } ] }, "StreamEventChatError": { "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, - { "$ref": "#/components/schemas/StreamEventBase" }, + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Error event during streaming.", - "required": ["status", "code", "message"], "properties": { - "status": { "type": "integer", "description": "HTTP status code." }, - "code": { "type": "string", "description": "Error code." }, - "message": { "type": "string", "description": "Error message." } + "status": { + "type": "integer", + "description": "HTTP status code." + }, + "code": { + "type": "string", + "description": "Error code." + }, + "message": { + "type": "string", + "description": "Error message." + } } } ] }, "StreamEventChatPing": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkChatEvent" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, { "type": "object", "description": "Ping event to keep connection alive." @@ -1484,72 +3054,301 @@ "type": "object", "description": "Model usage information.", "properties": { - "prompt_tokens": { "type": "integer" }, - "prompt_unit_price": { "type": "string", "format": "decimal" }, - "prompt_price_unit": { "type": "string", "format": "decimal" }, - "prompt_price": { "type": "string", "format": "decimal" }, - "completion_tokens": { "type": "integer" }, - "completion_unit_price": { "type": "string", "format": "decimal" }, - "completion_price_unit": { "type": "string", "format": "decimal" }, - "completion_price": { "type": "string", "format": "decimal" }, - "total_tokens": { "type": "integer" }, - "total_price": { "type": "string", "format": "decimal" }, - "currency": { "type": "string", "example": "USD" }, - "latency": { "type": "number", "format": "double" } + "prompt_tokens": { + "type": "integer", + "description": "Number of tokens in the prompt." + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per prompt token." + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for prompt tokens." + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "Total price for prompt tokens." + }, + "completion_tokens": { + "type": "integer", + "description": "Number of tokens in the completion." + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per completion token." + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for completion tokens." + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "Total price for completion tokens." + }, + "total_tokens": { + "type": "integer", + "description": "Total number of tokens used." + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "Total price for all tokens." + }, + "currency": { + "type": "string", + "description": "Currency for pricing." + }, + "latency": { + "type": "number", + "format": "double", + "description": "Latency in seconds." + } } }, "RetrieverResource": { "type": "object", - "description": "Citation and Attribution information for a resource.", + "description": "Citation and attribution information for a retriever resource.", "properties": { - "position": { "type": "integer", "description": "Position of the resource in the list." }, - "dataset_id": { "type": "string", "format": "uuid", "description": "ID of the dataset." }, - "dataset_name": { "type": "string", "description": "Name of the dataset." }, - "document_id": { "type": "string", "format": "uuid", "description": "ID of the document." }, - "document_name": { "type": "string", "description": "Name of the document." }, - "segment_id": { "type": "string", "format": "uuid", "description": "ID of the specific segment within the document." }, - "score": { "type": "number", "format": "float", "description": "Relevance score of the resource." }, - "content": { "type": "string", "description": "Content snippet from the resource." } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of the retriever resource." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "ID of the message this resource belongs to." + }, + "position": { + "type": "integer", + "description": "Position of the resource in the list." + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "ID of the knowledge base." + }, + "dataset_name": { + "type": "string", + "description": "Name of the knowledge base." + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "ID of the document." + }, + "document_name": { + "type": "string", + "description": "Name of the document." + }, + "data_source_type": { + "type": "string", + "description": "Type of the data source." + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "ID of the specific chunk within the document." + }, + "score": { + "type": "number", + "format": "float", + "description": "Relevance score of the resource." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this chunk was hit." + }, + "word_count": { + "type": "integer", + "description": "Word count of the chunk." + }, + "segment_position": { + "type": "integer", + "description": "Position of the chunk within the document." + }, + "index_node_hash": { + "type": "string", + "description": "Hash of the index node." + }, + "content": { + "type": "string", + "description": "Content snippet from the resource." + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary of the chunk content." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." + } } }, "FileUploadResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" }, - "size": { "type": "integer" }, - "extension": { "type": "string" }, - "mime_type": { "type": "string" }, - "created_by": { "type": "string", "format": "uuid" }, - "created_at": { "type": "integer", "format": "int64" } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique file ID." + }, + "name": { + "type": "string", + "description": "File name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "nullable": true, + "description": "File extension." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Upload timestamp (Unix epoch seconds)." + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "Preview URL for the file." + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "Source URL of the file." + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "Original URL of the file." + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated user." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated tenant." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated conversation." + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "Storage key for the file." + } } }, "EndUserDetail": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "Tenant ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Application ID." + }, + "type": { + "type": "string", + "description": "End user type. Always `service_api` for Service API users." + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/api-reference/chats/send-chat-message))." + }, + "name": { + "type": "string", + "nullable": true, + "description": "End user name." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request." + }, + "session_id": { + "type": "string", + "description": "Session identifier. Defaults to the `external_user_id` value." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } } }, "MessageFeedbackRequest": { "type": "object", - "required": ["user"], + "description": "Request body for submitting message feedback.", + "required": [ + "user" + ], "properties": { "rating": { "type": "string", - "enum": ["like", "dislike", null], - "nullable": true + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "Feedback rating. Set to `null` to revoke previously submitted feedback." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer, must ensure uniqueness within the application." }, - "user": { "type": "string" }, - "content": { "type": "string" } + "content": { + "type": "string", + "description": "Optional text feedback providing additional detail." + } } }, "AppFeedbacksResponse": { @@ -1557,171 +3356,467 @@ "properties": { "data": { "type": "array", - "items": { "$ref": "#/components/schemas/FeedbackItem" } + "description": "List of feedback items.", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } } } }, "FeedbackItem": { "type": "object", + "description": "A single feedback item.", "properties": { - "id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "message_id": { "type": "string", "format": "uuid" }, - "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, - "content": { "type": "string" }, - "from_source": { "type": "string" }, - "from_end_user_id": { "type": "string", "format": "uuid" }, - "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "Feedback ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "Application ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + }, + "content": { + "type": "string", + "nullable": true, + "description": "Optional text feedback." + }, + "from_source": { + "type": "string", + "description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console." + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "End user ID who submitted the feedback. Present when `from_source` is `user`." + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Account ID who submitted the feedback. Present when `from_source` is `admin`." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } } }, "SuggestedQuestionsResponse": { "type": "object", "properties": { - "result": { "type": "string", "example": "success" }, + "result": { + "type": "string", + "description": "Result status." + }, "data": { "type": "array", - "items": { "type": "string" }, - "example": ["a", "b", "c"] + "items": { + "type": "string" + }, + "description": "List of suggested questions." } } }, "ConversationHistoryResponse": { "type": "object", "properties": { - "limit": { "type": "integer" }, - "has_more": { "type": "boolean" }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more messages." + }, "data": { "type": "array", - "items": { "$ref": "#/components/schemas/ConversationMessageItem" } + "description": "List of messages.", + "items": { + "$ref": "#/components/schemas/ConversationMessageItem" + } } } }, "ConversationMessageItem": { "type": "object", + "description": "A single message in a conversation.", "properties": { - "id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "inputs": { "type": "object", "additionalProperties": true }, - "query": { "type": "string" }, - "answer": { "type": "string" }, + "id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "parent_message_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Parent message ID for threaded conversations." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for this message." + }, + "query": { + "type": "string", + "description": "User query text." + }, + "answer": { + "type": "string", + "description": "Assistant answer text." + }, + "status": { + "type": "string", + "description": "Message status. `normal` for successful messages, `error` when generation failed." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if `status` is `error`." + }, "message_files": { "type": "array", - "items": { "$ref": "#/components/schemas/MessageFileItem" } + "description": "Files attached to this message.", + "items": { + "$ref": "#/components/schemas/MessageFileItem" + } }, "feedback": { "type": "object", "nullable": true, + "description": "User feedback for this message.", "properties": { - "rating": { "type": "string", "enum": ["like", "dislike"] } + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + } } }, "retriever_resources": { "type": "array", - "items": { "$ref": "#/components/schemas/RetrieverResource" } + "description": "Retriever resources used for this message.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } }, "agent_thoughts": { "type": "array", - "items": { "$ref": "#/components/schemas/AgentThoughtItem" } + "description": "Agent thoughts for this message.", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." }, - "created_at": { "type": "integer", "format": "int64" } + "extra_contents": { + "type": "array", + "description": "Additional execution content associated with this message, such as human input form data.", + "items": { + "type": "object", + "additionalProperties": true + } + } } }, "MessageFileItem": { "type": "object", + "description": "A file attached to a message.", "properties": { - "id": { "type": "string", "format": "uuid" }, - "type": { "type": "string", "description": "File type, e.g., 'image'." }, - "url": { "type": "string", "format": "url", "description": "Preview image URL." }, - "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "Who this file belongs to." } + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "Original filename." + }, + "type": { + "type": "string", + "description": "File type, e.g., `image`." + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "Preview URL for the file." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "size": { + "type": "integer", + "nullable": true, + "description": "File size in bytes." + }, + "transfer_method": { + "type": "string", + "description": "Transfer method used. `remote_url` for URL-based files, `local_file` for uploaded files, `tool_file` for tool-generated files." + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "Who this file belongs to. `user` for user-uploaded files, `assistant` for assistant-generated files." + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Upload file ID if transferred via `local_file`." + } } }, "AgentThoughtItem": { "type": "object", + "description": "An agent thought step in the message.", "properties": { - "id": { "type": "string", "format": "uuid", "description": "Agent thought ID." }, - "message_id": { "type": "string", "format": "uuid", "description": "Unique message ID this thought belongs to." }, - "position": { "type": "integer", "description": "Position of this thought." }, - "thought": { "type": "string", "description": "What LLM is thinking." }, - "tool": { "type": "string", "description": "Tools called, split by ';'." }, - "tool_input": { "type": "string", "description": "Input of tools in JSON format." }, - "observation": { "type": "string", "description": "Response from tool calls." }, + "id": { + "type": "string", + "format": "uuid", + "description": "Agent thought ID." + }, + "chain_id": { + "type": "string", + "nullable": true, + "description": "Chain ID for this thought." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID this thought belongs to." + }, + "position": { + "type": "integer", + "description": "Position of this thought." + }, + "thought": { + "type": "string", + "description": "What LLM is thinking." + }, + "tool": { + "type": "string", + "description": "Tools called, split by `;`." + }, + "tool_labels": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Labels for tools used." + }, + "tool_input": { + "type": "string", + "description": "Input of tools in JSON format." + }, + "observation": { + "type": "string", + "description": "Response from tool calls." + }, "files": { - "type": "array", - "items": { "type": "string", "format": "uuid" }, - "description": "File IDs related to this thought (from example, Markdown text says 'message_files')." + "type": "array", + "items": { + "type": "string" + }, + "description": "File IDs related to this thought." }, - "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." } + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + } } }, "ConversationsListResponse": { "type": "object", "properties": { - "limit": { "type": "integer" }, - "has_more": { "type": "boolean" }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more conversations." + }, "data": { "type": "array", - "items": { "$ref": "#/components/schemas/ConversationListItem" } + "description": "List of conversations.", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } } } }, "ConversationListItem": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" }, - "inputs": { "type": "object", "additionalProperties": true }, - "status": { "type": "string" }, - "introduction": { "type": "string" }, - "created_at": { "type": "integer", "format": "int64" }, - "updated_at": { "type": "integer", "format": "int64" } + "id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "name": { + "type": "string", + "description": "Conversation name." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the conversation." + }, + "status": { + "type": "string", + "description": "Conversation status. `normal` for active conversations." + }, + "introduction": { + "type": "string", + "description": "Conversation introduction." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update timestamp." + } } }, "ConversationRenameRequest": { "type": "object", - "required": ["user"], + "description": "Request body for renaming a conversation.", "properties": { - "name": { "type": "string", "description": "(Optional) The name of the conversation. Omit if auto_generate is true." }, - "auto_generate": { "type": "boolean", "default": false, "description": "(Optional) Automatically generate the title. Default false." }, - "user": { "type": "string", "description": "The user identifier." } + "name": { + "type": "string", + "description": "The name of the conversation. Required when `auto_generate` is `false`." + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "Automatically generate the conversation name. When `true`, the `name` field is ignored." + }, + "user": { + "type": "string", + "description": "The user identifier." + } } }, - "ConversationRenameResponse": { - "$ref": "#/components/schemas/ConversationListItem" - }, "ConversationVariablesResponse": { - "type": "object", - "properties": { - "limit": { "type": "integer", "description": "Number of items per page." }, - "has_more": { "type": "boolean", "description": "Whether there is a next page." }, - "data": { - "type": "array", - "items": { "$ref": "#/components/schemas/ConversationVariableItem" } - } + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there is a next page." + }, + "data": { + "type": "array", + "description": "List of conversation variables.", + "items": { + "$ref": "#/components/schemas/ConversationVariableItem" + } + } + } + }, + "ConversationVariableItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Variable ID." + }, + "name": { + "type": "string", + "description": "Variable name." + }, + "value_type": { + "type": "string", + "description": "Variable value type. Possible values: `string`, `number`, `object`, `secret`, `file`, `boolean`, `array[any]`, `array[string]`, `array[number]`, `array[object]`, `array[file]`, `array[boolean]`." + }, + "value": { + "type": "string", + "description": "Variable value (can be a JSON string for complex types)." + }, + "description": { + "type": "string", + "description": "Variable description." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update timestamp." } + } }, - "ConversationVariableItem": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "Variable ID." }, - "name": { "type": "string", "description": "Variable name." }, - "value_type": { "type": "string", "description": "Variable type (string, number, object, json, etc.)." }, - "value": { "type": "string", "description": "Variable value (can be a JSON string for complex types)." }, - "description": { "type": "string", "description": "Variable description." }, - "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp." }, - "updated_at": { "type": "integer", "format": "int64", "description": "Last update timestamp." } + "ConversationVariableUpdateRequest": { + "type": "object", + "description": "Request body for updating a conversation variable.", + "required": [ + "value" + ], + "properties": { + "value": { + "description": "The new value for the variable. Must match the variable's expected type." + }, + "user": { + "type": "string", + "description": "User identifier." } + } }, "AudioToTextRequest": { "type": "object", - "required": ["file", "user"], + "description": "Request body for audio-to-text conversion.", + "required": [ + "file" + ], "properties": { "file": { "type": "string", "format": "binary", - "description": "Audio file. Supported: mp3, mp4, mpeg, mpga, m4a, wav, webm. Limit: 15MB." + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `15 MB`." }, "user": { "type": "string", @@ -1732,92 +3827,225 @@ "AudioToTextResponse": { "type": "object", "properties": { - "text": { "type": "string", "description": "Output text from speech recognition." } + "text": { + "type": "string", + "description": "Output text from speech recognition." + } } }, - "TextToAudioFormRequest": { + "TextToAudioRequest": { "type": "object", - "required": ["user"], + "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", "properties": { "message_id": { "type": "string", "format": "uuid", - "description": "Message ID (priority if both text and message_id provided)." + "description": "Message ID. Takes priority over `text` when both are provided." }, "text": { "type": "string", - "description": "Speech content." + "description": "Speech content to convert." }, "user": { "type": "string", "description": "User identifier." + }, + "voice": { + "type": "string", + "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." + }, + "streaming": { + "type": "boolean", + "description": "Whether to enable streaming response." } - }, - "description": "Requires `user`. Provide either `message_id` or `text`." + } }, "AppInfoResponse": { "type": "object", "properties": { - "name": { "type": "string" }, - "description": { "type": "string" }, - "tags": { "type": "array", "items": { "type": "string" } } + "name": { + "type": "string", + "description": "Application name." + }, + "description": { + "type": "string", + "description": "Application description." + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Application tags." + }, + "mode": { + "type": "string", + "description": "Application mode. `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for chatflow apps." + }, + "author_name": { + "type": "string", + "description": "Name of the application author." + } } }, "ChatAppParametersResponse": { "type": "object", "properties": { - "opening_statement": { "type": "string" }, - "suggested_questions": { "type": "array", "items": { "type": "string" } }, + "opening_statement": { + "type": "string", + "description": "Opening statement displayed at conversation start." + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of suggested starter questions." + }, "suggested_questions_after_answer": { "type": "object", - "properties": { "enabled": { "type": "boolean" } } + "description": "Configuration for suggested questions after answer.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } }, "speech_to_text": { "type": "object", - "properties": { "enabled": { "type": "boolean" } } + "description": "Speech-to-text configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } }, "text_to_speech": { "type": "object", + "description": "Text-to-speech configuration.", "properties": { - "enabled": { "type": "boolean" }, - "voice": { "type": "string" }, - "language": { "type": "string" }, - "autoPlay": { "type": "string", "enum": ["enabled", "disabled"] } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + }, + "voice": { + "type": "string", + "description": "Voice identifier for TTS." + }, + "language": { + "type": "string", + "description": "Language for TTS." + }, + "autoPlay": { + "type": "string", + "description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play." + } } }, "retriever_resource": { "type": "object", - "properties": { "enabled": { "type": "boolean" } } + "description": "Retriever resource configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } }, "annotation_reply": { "type": "object", - "properties": { "enabled": { "type": "boolean" } } + "description": "Annotation reply configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "more_like_this": { + "type": "object", + "description": "More-like-this configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "Sensitive word avoidance configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } }, "user_input_form": { "type": "array", - "items": { "$ref": "#/components/schemas/UserInputFormItem" } + "description": "List of user input form elements.", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } }, "file_upload": { "type": "object", + "description": "File upload configuration.", "properties": { "image": { "type": "object", + "description": "Image upload settings.", "properties": { - "enabled": { "type": "boolean" }, - "number_limits": { "type": "integer" }, - "detail": {"type": "string"}, - "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } + "enabled": { + "type": "boolean", + "description": "Whether image upload is enabled." + }, + "number_limits": { + "type": "integer", + "description": "Maximum number of images." + }, + "detail": { + "type": "string", + "description": "Image detail level." + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Allowed transfer methods." + } } } } }, "system_parameters": { "type": "object", + "description": "System-level parameters and limits.", "properties": { - "file_size_limit": { "type": "integer" }, - "image_file_size_limit": { "type": "integer" }, - "audio_file_size_limit": { "type": "integer" }, - "video_file_size_limit": { "type": "integer" } + "file_size_limit": { + "type": "integer", + "description": "Maximum file size in MB." + }, + "image_file_size_limit": { + "type": "integer", + "description": "Maximum image file size in MB." + }, + "audio_file_size_limit": { + "type": "integer", + "description": "Maximum audio file size in MB." + }, + "video_file_size_limit": { + "type": "integer", + "description": "Maximum video file size in MB." + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "Maximum number of files for workflow file upload." + } } } } @@ -1825,31 +4053,116 @@ "UserInputFormItem": { "type": "object", "oneOf": [ - { "$ref": "#/components/schemas/TextInputControlWrapper" }, - { "$ref": "#/components/schemas/ParagraphControlWrapper" }, - { "$ref": "#/components/schemas/SelectControlWrapper" } + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } ] }, "TextInputControlWrapper": { - "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } },"required":["text-input"] + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } }, "ParagraphControlWrapper": { - "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } },"required":["paragraph"] + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } }, "SelectControlWrapper": { - "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } },"required":["select"] + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } }, "TextInputControl": { - "type": "object", "required": ["label", "variable", "required"], - "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } + "type": "object", + "description": "Text input form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether input is required." + }, + "default": { + "type": "string", + "description": "Default value." + } + } }, "ParagraphControl": { - "type": "object", "required": ["label", "variable", "required"], - "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } + "type": "object", + "description": "Paragraph (multi-line text) form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether input is required." + }, + "default": { + "type": "string", + "description": "Default value." + } + } }, "SelectControl": { - "type": "object", "required": ["label", "variable", "required", "options"], - "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } } + "type": "object", + "description": "Select (dropdown) form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether selection is required." + }, + "default": { + "type": "string", + "description": "Default selected value." + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of selectable values for this form control." + } + } }, "AppMetaResponse": { "type": "object", @@ -1858,8 +4171,15 @@ "type": "object", "additionalProperties": { "oneOf": [ - { "type": "string", "format": "url", "description": "URL of the icon." }, - { "$ref": "#/components/schemas/ToolIconDetail" } + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "URL of the icon." + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } ] }, "description": "Tool icons. Keys are tool names." @@ -1867,100 +4187,270 @@ } }, "ToolIconDetail": { + "title": "Emoji Icon", "type": "object", + "description": "Detail of a tool icon using emoji.", "properties": { - "background": { "type": "string", "description": "Background color in hex format." }, - "content": { "type": "string", "description": "Emoji content." } + "background": { + "type": "string", + "description": "Background color in hex format." + }, + "content": { + "type": "string", + "description": "Emoji content." + } } }, "WebAppSettingsResponse": { "type": "object", "properties": { - "title": { "type": "string" }, "chat_color_theme": { "type": "string" }, "chat_color_theme_inverted": { "type": "boolean" }, - "icon_type": { "type": "string", "enum": ["emoji", "image"] }, "icon": { "type": "string" }, "icon_background": { "type": "string" }, - "icon_url": { "type": "string", "format": "url", "nullable": true }, "description": { "type": "string" }, "copyright": { "type": "string" }, - "privacy_policy": { "type": "string" }, "custom_disclaimer": { "type": "string" }, "default_language": { "type": "string" }, - "show_workflow_steps": { "type": "boolean" }, "use_icon_as_answer_icon": { "type": "boolean" } + "title": { + "type": "string", + "description": "WebApp title." + }, + "chat_color_theme": { + "type": "string", + "description": "Chat color theme." + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "Whether the chat color theme is inverted." + }, + "icon_type": { + "type": "string", + "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." + }, + "icon": { + "type": "string", + "description": "Icon content (emoji or image ID)." + }, + "icon_background": { + "type": "string", + "description": "Icon background color." + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "URL of the icon image." + }, + "description": { + "type": "string", + "description": "WebApp description." + }, + "copyright": { + "type": "string", + "description": "Copyright text." + }, + "privacy_policy": { + "type": "string", + "description": "Privacy policy URL." + }, + "custom_disclaimer": { + "type": "string", + "description": "Custom disclaimer text." + }, + "default_language": { + "type": "string", + "description": "Default language code." + }, + "show_workflow_steps": { + "type": "boolean", + "description": "Whether to show workflow steps." + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "Whether to use the app icon as the answer icon." + } } }, "AnnotationListResponse": { "type": "object", "properties": { - "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItem" } }, - "has_more": { "type": "boolean" }, - "limit": { "type": "integer" }, - "total": { "type": "integer" }, - "page": { "type": "integer" } + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "description": "List of annotation items for the current page." + }, + "has_more": { + "type": "boolean", + "description": "`true` if more pages are available beyond the current result set." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of annotations matching the query." + }, + "page": { + "type": "integer", + "description": "Current page number." + } } }, "AnnotationItem": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "question": { "type": "string" }, - "answer": { "type": "string" }, - "hit_count": { "type": "integer" }, - "created_at": { "type": "integer", "format": "int64" } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique annotation identifier." + }, + "question": { + "type": "string", + "nullable": true, + "description": "Question text that triggers this annotation." + }, + "answer": { + "type": "string", + "nullable": true, + "description": "Predefined answer returned when the annotation is matched." + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "Number of times this annotation has been matched and returned as a reply." + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Creation timestamp (Unix epoch seconds)." + } } }, "CreateAnnotationRequest": { "type": "object", - "required": ["question", "answer"], + "description": "Request body for creating a new annotation.", + "required": [ + "question", + "answer" + ], "properties": { - "question": { "type": "string" }, - "answer": { "type": "string" } + "question": { + "type": "string", + "description": "Annotation question." + }, + "answer": { + "type": "string", + "description": "Annotation answer." + } } }, "UpdateAnnotationRequest": { "type": "object", - "required": ["question", "answer"], + "description": "Request body for updating an annotation.", + "required": [ + "question", + "answer" + ], "properties": { - "question": { "type": "string" }, - "answer": { "type": "string" } + "question": { + "type": "string", + "description": "Updated annotation question." + }, + "answer": { + "type": "string", + "description": "Updated annotation answer." + } } }, "InitialAnnotationReplySettingsRequest": { "type": "object", - "required": ["score_threshold"], + "description": "Request body for configuring annotation reply settings.", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], "properties": { - "embedding_provider_name": { "type": "string", "description": "Specified embedding model provider name (Optional)." }, - "embedding_model_name": { "type": "string", "description": "Specified embedding model name (Optional)." }, - "score_threshold": { "type": "number", "format": "float", "description": "Similarity threshold for matching annotated replies." } + "embedding_provider_name": { + "type": "string", + "description": "Name of the embedding model provider (e.g., `openai`, `cohere`)." + }, + "embedding_model_name": { + "type": "string", + "description": "Name of the embedding model to use for annotation matching (e.g., `text-embedding-3-small`)." + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "Minimum similarity score for an annotation to be considered a match. Higher values require closer matches.", + "minimum": 0, + "maximum": 1 + } } }, "InitialAnnotationReplySettingsResponse": { "type": "object", "properties": { - "job_id": { "type": "string", "format": "uuid" }, - "job_status": { "type": "string" } + "job_id": { + "type": "string", + "format": "uuid", + "description": "Asynchronous job ID. Use with [Retrieve Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress." + }, + "job_status": { + "type": "string", + "description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed." + } } }, "InitialAnnotationReplySettingsStatusResponse": { "type": "object", "properties": { - "job_id": { "type": "string", "format": "uuid" }, - "job_status": { "type": "string" }, - "error_msg": { "type": "string", "nullable": true } - } - }, - "ErrorResponse": { - "type": "object", - "properties": { - "status": { "type": "integer" }, - "code": { "type": "string" }, - "message": { "type": "string" } + "job_id": { + "type": "string", + "format": "uuid", + "description": "Job ID from the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call." + }, + "job_status": { + "type": "string", + "description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed." + }, + "error_msg": { + "type": "string", + "description": "Error message describing why the job failed. Empty string when `job_status` is not `error`." + } } } } }, "tags": [ - { "name": "Chat", "description": "Operations related to chat messages and interactions." }, - { "name": "Files", "description": "File upload and preview operations." }, - { "name": "End Users", "description": "Operations related to end user information." }, - { "name": "Feedback", "description": "User feedback operations." }, - { "name": "Conversations", "description": "Operations related to managing conversations." }, - { "name": "TTS", "description": "Text-to-Speech and Speech-to-Text operations." }, - { "name": "Application", "description": "Operations to retrieve application settings and information." }, - { "name": "Annotations", "description": "Operations related to managing annotations for direct replies." } + { + "name": "Chats", + "description": "Operations related to chat messages and interactions." + }, + { + "name": "Files", + "description": "File upload and preview operations." + }, + { + "name": "End Users", + "description": "Operations related to end user information." + }, + { + "name": "Feedback", + "description": "User feedback operations." + }, + { + "name": "Conversations", + "description": "Operations related to managing conversations." + }, + { + "name": "TTS", + "description": "Text-to-Speech and Speech-to-Text operations." + }, + { + "name": "Applications", + "description": "Operations to retrieve application settings and information." + }, + { + "name": "Annotations", + "description": "Operations related to managing annotations for direct replies." + } ] } diff --git a/en/api-reference/openapi_chatflow.json b/en/api-reference/openapi_chatflow.json index 04499f1c4..b8eac2fde 100644 --- a/en/api-reference/openapi_chatflow.json +++ b/en/api-reference/openapi_chatflow.json @@ -1,14 +1,14 @@ { "openapi": "3.0.1", "info": { - "title": "Advanced Chat App API", - "description": "Chat applications support session persistence, allowing previous chat history to be used as context for responses. This can be applicable for chatbot, customer service AI, etc. This version includes advanced features like workflow events and more detailed file type support.", + "title": "Chatflow App API", + "description": "Chatflow applications support session persistence, allowing previous chat history to be used as context for responses. Chatflow apps use the `advanced-chat` mode, providing workflow-level streaming events for detailed execution tracking including node starts, finishes, iterations, and workflow lifecycle.", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "The base URL for the Advanced Chat App API. Replace {api_base_url} with the actual API base URL provided for your application (e.g., from props.appDetail.api_base_url).", + "description": "The base URL for the Chatflow App API. Replace {api_base_url} with the actual API base URL provided for your application.", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", @@ -26,34 +26,47 @@ "/chat-messages": { "post": { "summary": "Send Chat Message", - "description": "Send a request to the advanced chat application, supporting various file types and workflow events.", - "operationId": "sendAdvancedChatMessage", - "tags": ["Chatflow"], + "description": "Send a request to the chat application.", + "operationId": "createChatflowMessage", + "tags": [ + "Chats" + ], "requestBody": { - "description": "Request body to send an advanced chat message.", + "description": "Request body to send a chat message.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdvancedChatRequest" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file_and_workflow": { - "summary": "Streaming mode example with image file", + "streaming_example": { + "summary": "Request Example - Streaming mode", "value": { - "inputs": {"user_name": "Alice"}, - "query": "Analyze this document and tell me its sentiment.", + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "conv_12345", - "user": "user_alice", + "conversation_id": "", + "user": "abc-123", "files": [ { - "type": "document", + "type": "image", "transfer_method": "remote_url", - "url": "https://example.com/mydoc.pdf" + "url": "https://cloud.dify.ai/logo/logo-site.png" } - ], - "auto_generate_name": true + ] + } + }, + "blocking_example": { + "summary": "Request Example - Blocking mode", + "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" } } } @@ -62,269 +75,436 @@ }, "responses": { "200": { - "description": "Successful response. The content type and structure depend on the `response_mode`.\n- `blocking`: `application/json` with `ChatCompletionResponse`.\n- `streaming`: `text/event-stream` with `ChunkAdvancedChatEvent` stream.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkChatEvent` objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "Response Example - Blocking mode", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "advanced-chat", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "A stream of Server-Sent Events. See `ChunkAdvancedChatEvent` for structures." + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkChatEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `message_end` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." }, "examples": { - "workflow_events_example": { - "summary": "Example stream including workflow events", - "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task_abc\", \"workflow_run_id\": \"wf_run_1\", \"data\": {\"id\": \"wf_run_1\", \"workflow_id\": \"wf_def_xyz\", \"sequence_number\": 1, \"created_at\": 1705395332}}\n\ndata: {\"event\": \"node_started\", \"task_id\": \"task_abc\", \"workflow_run_id\": \"wf_run_1\", \"data\": {\"id\": \"node_run_1\", \"node_id\": \"node_start\", \"node_type\": \"start\", \"title\": \"Start Node\", \"index\": 0, \"inputs\": {}, \"created_at\": 1705395333}}\n\ndata: {\"event\": \"message\", \"task_id\": \"task_abc\", \"message_id\": \"msg_123\", \"conversation_id\": \"conv_123\", \"answer\": \"Processing... \", \"created_at\": 1705395334}\n\ndata: {\"event\": \"node_finished\", \"task_id\": \"task_abc\", \"workflow_run_id\": \"wf_run_1\", \"data\": {\"id\": \"node_run_1\", \"node_id\": \"node_start\", \"node_type\": \"start\", \"title\": \"Start Node\", \"index\": 0, \"status\": \"succeeded\", \"elapsed_time\": 0.5, \"created_at\": 1705395333}}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"task_abc\", \"message_id\": \"msg_123\", \"conversation_id\": \"conv_123\", \"metadata\": {\"usage\": {\"total_tokens\": 10}}}\n\ndata: {\"event\": \"workflow_finished\", \"task_id\": \"task_abc\", \"workflow_run_id\": \"wf_run_1\", \"data\": {\"id\": \"wf_run_1\", \"workflow_id\": \"wf_def_xyz\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705395332, \"finished_at\": 1705395335}}\n\n" + "streamingResponseBasic": { + "summary": "Response Example - Streaming (Basic)", + "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" + }, + "streamingResponseWorkflow": { + "summary": "Response Example - Streaming (Workflow)", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}} 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` : App unavailable or misconfigured.\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.\n- `bad_request` : Cannot use draft workflow version.\n- `bad_request` : Invalid `workflow_id` format.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "conversation_completed": { + "summary": "conversation_completed", + "value": { + "status": 400, + "code": "conversation_completed", + "message": "The conversation has ended. Please start a new conversation." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "is_draft_workflow": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. " + } + }, + "workflow_id_format_error": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Invalid workflow_id format: 'not-a-valid-id'. " } + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestGeneric" }, - "404": { "$ref": "#/components/responses/ConversationNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } - } - } - }, - "/files/upload": { - "post": { - "summary": "File Upload", - "description": "Upload a file for use when sending messages, enabling multimodal understanding. Supports any formats supported by your application. Uploaded files are for use by the current end-user only.", - "operationId": "uploadAdvancedChatFile", - "tags": ["Files"], - "requestBody": { - "description": "File upload request. Requires multipart/form-data.", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "The file to be uploaded." + "404": { + "description": "- `not_found` : Conversation does not exist.\n- `not_found` : Workflow not found with the specified `workflow_id`.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } }, - "user": { - "type": "string", - "description": "User identifier, unique within the application. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "workflow_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab" + } } } } } - } - }, - "responses": { - "200": { - "description": "File uploaded successfully.", + }, + "429": { + "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponse" + "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" + } + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestFile" }, - "413": { "$ref": "#/components/responses/FileTooLarge" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFile" }, - "503": { "$ref": "#/components/responses/S3ErrorFile" }, - "500": { "$ref": "#/components/responses/InternalServerError" } + "500": { + "description": "`internal_server_error` : 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." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { - "get": { - "summary": "Get End User", - "description": "Retrieve an end user by ID.\n\nThis is useful when other APIs return an end-user ID (e.g. `created_by` from File Upload).", - "operationId": "getEndUserChatflow", - "tags": ["End Users"], + "/chat-messages/{task_id}/stop": { + "post": { + "summary": "Stop Chat Message Generation", + "description": "Stops a chat message generation task. Only supported in `streaming` mode.", + "operationId": "stopChatflowMessage", + "tags": [ + "Chats" + ], "parameters": [ { - "name": "end_user_id", + "name": "task_id", "in": "path", "required": true, - "description": "End user ID.", - "schema": { "type": "string", "format": "uuid" } + "description": "Task ID, can be obtained from the streaming chunk return of the [Send Chat Message](/api-reference/chats/send-chat-message) API.", + "schema": { + "type": "string" + } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "user" + ], + "properties": { + "user": { + "type": "string", + "description": "User identifier, must be consistent with the user passed in the send message interface." + } + } + }, + "examples": { + "example": { + "summary": "Request Example", + "value": { + "user": "abc-123" + } + } + } + } + } + }, "responses": { "200": { - "description": "End user retrieved successfully.", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetail" } + "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": { "$ref": "#/components/responses/EndUserNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } + } } } }, - "/files/{file_id}/preview": { + "/messages/{message_id}/suggested": { "get": { - "summary": "File Preview", - "description": "Preview or download uploaded files. This endpoint allows you to access files that have been previously uploaded via the File Upload API. Files can only be accessed if they belong to messages within the requesting application.", - "operationId": "previewChatFlowFile", - "tags": ["Files"], + "summary": "Get Next Suggested Questions", + "description": "Get next questions suggestions for the current message.", + "operationId": "getChatflowSuggestedQuestions", + "tags": [ + "Chats" + ], "parameters": [ { - "name": "file_id", + "name": "message_id", "in": "path", "required": true, - "description": "The unique identifier of the file to preview, obtained from the File Upload API response.", + "description": "Message ID.", "schema": { - "type": "string", - "format": "uuid" + "type": "string" } }, { - "name": "as_attachment", + "name": "user", "in": "query", - "required": false, - "description": "Whether to force download the file as an attachment. Default is `false` (preview in browser).", + "required": true, + "description": "User identifier.", "schema": { - "type": "boolean", - "default": false + "type": "string" } } ], "responses": { "200": { - "description": "File content returned successfully. Headers set based on file type and request parameters.", + "description": "Successfully retrieved suggested questions.", "content": { - "image/png": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - }, - "headers": { - "Content-Type": { - "description": "MIME type of the file", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "File size in bytes (if available)", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "Set to 'attachment' if as_attachment=true", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "Caching headers for performance", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "Set to 'bytes' for audio/video files", + "application/json": { "schema": { - "type": "string", - "example": "bytes" + "$ref": "#/components/schemas/SuggestedQuestionsResponse" + }, + "examples": { + "suggestedQuestions": { + "summary": "Response Example", + "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": "Bad Request. Possible error codes:\n- `invalid_param`: Abnormal parameter input.", + "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Suggested questions feature is disabled.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "403": { - "description": "Forbidden. Possible error codes:\n- `file_access_denied`: File access denied or file does not belong to current application.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "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. Possible error codes:\n- `file_not_found`: File not found or has been deleted.", + "description": "`not_found` : Message does not exist.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } } } }, "500": { - "description": "Internal server error.", + "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } } } }, - "/chat-messages/{task_id}/stop": { + "/files/upload": { "post": { - "summary": "Stop Advanced Chat Message Generation", - "description": "Stops an advanced chat message generation task. Only supported in streaming mode.", - "operationId": "stopAdvancedChatMessageGeneration", - "tags": ["Chatflow"], - "parameters": [ - { - "name": "task_id", - "in": "path", - "required": true, - "description": "Task ID from the streaming chunk.", - "schema": { "type": "string" } - } + "operationId": "uploadChatflowFile", + "tags": [ + "Files" ], + "summary": "Upload File", + "description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", "requestBody": { + "description": "File upload request. Requires multipart/form-data.", "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "file" + ], "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "The file to be uploaded. Supported types include images, documents, audio, and video." + }, "user": { "type": "string", - "description": "User identifier, consistent with the send message call. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." + "description": "User identifier, defined by the developer's rules, must be unique within the application." } } } @@ -332,853 +512,4916 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "Message Feedback", - "description": "Provide feedback for a message.", - "operationId": "postAdvancedChatMessageFeedback", - "tags": ["Feedback"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "Message ID.", - "schema": { "type": "string" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequest" } - } - } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } - } - } - }, - "/app/feedbacks": { - "get": { - "summary": "Get feedbacks of application", - "description": "Get application's feedbacks.", - "operationId": "getAdvancedChatAppFeedbacks", - "tags": ["Feedback"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParam" } - ], - "responses": { - "200": { - "description": "A list of application feedbacks.", + "201": { + "description": "File uploaded successfully.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponse" } - } - } - } - } - } - }, - "/messages/{message_id}/suggested": { - "get": { - "summary": "Next Suggested Questions", - "description": "Get next questions suggestions for the current message.", - "operationId": "getAdvancedSuggestedQuestions", - "tags": ["Chatflow"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "Message ID.", - "schema": { "type": "string" } + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "Response Example", + "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" + } + } + } + } + } }, - { "$ref": "#/components/parameters/UserQueryParam" } - ], - "responses": { - "200": { - "description": "Successfully retrieved suggested questions.", + "400": { + "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.", + "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` : File size exceeded.", + "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` : File type not allowed.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponse" } + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } } } } } } }, - "/messages": { + "/files/{file_id}/preview": { "get": { - "summary": "Get Conversation History Messages", - "description": "Returns historical chat records in a scrolling load format.", - "operationId": "getAdvancedConversationHistory", - "tags": ["Conversations"], + "operationId": "previewChatflowFile", + "tags": [ + "Files" + ], + "summary": "Download File", + "description": "Preview or download uploaded files previously uploaded via the [File Upload](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", "parameters": [ - { "$ref": "#/components/parameters/ConversationIdQueryParam" }, - { "$ref": "#/components/parameters/UserQueryParam" }, { - "name": "first_id", + "name": "file_id", + "in": "path", + "required": true, + "description": "The unique identifier of the file to preview, obtained from the [File Upload](/api-reference/files/upload-file) API response.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", "in": "query", - "description": "ID of the first chat record on the current page (for pagination).", - "schema": { "type": "string" } + "required": false, + "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", + "schema": { + "type": "boolean", + "default": false + } }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20" } + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier, used for end-user context.", + "schema": { + "type": "string" + } + } ], "responses": { "200": { - "description": "Successfully retrieved conversation history.", + "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : Access to the requested file is 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` : The requested file was not found.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationHistoryResponse" } + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } } } } } } }, - "/conversations": { + "/end-users/{end_user_id}": { "get": { - "summary": "Get Conversations", - "description": "Retrieve the conversation list for the current user.", - "operationId": "getAdvancedConversationsList", - "tags": ["Conversations"], + "operationId": "getChatflowEndUser", + "tags": [ + "End Users" + ], + "summary": "Get End User", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", "parameters": [ - { "$ref": "#/components/parameters/UserQueryParam" }, - { "$ref": "#/components/parameters/LastIdQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100" }, - { "$ref": "#/components/parameters/SortByQueryParam" } + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "End user ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } ], "responses": { "200": { - "description": "Successfully retrieved conversations list.", + "description": "End user retrieved successfully.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationsListResponse" } + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "Response Example", + "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" + } + } + } } } - } - } - } - }, - "/conversations/{conversation_id}": { - "delete": { - "summary": "Delete Conversation", - "description": "Delete a conversation.", - "operationId": "deleteAdvancedConversation", - "tags": ["Conversations"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParam" } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["user"], - "properties": { - "user": { "type": "string", "description": "The user identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." } + }, + "404": { + "description": "`end_user_not_found` : 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." + } + } } } } } - }, - "responses": { - "204": { "description": "Conversation deleted successfully. No Content." } } } }, - "/conversations/{conversation_id}/name": { + "/messages/{message_id}/feedbacks": { "post": { - "summary": "Conversation Rename", - "description": "Rename the session.", - "operationId": "renameAdvancedConversation", - "tags": ["Conversations"], + "operationId": "createChatflowMessageFeedback", + "tags": [ + "Feedback" + ], + "summary": "Submit Message Feedback", + "description": "Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.", "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParam" } + { + "name": "message_id", + "in": "path", + "required": true, + "description": "Message ID.", + "schema": { + "type": "string" + } + } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationRenameRequest" } + "schema": { + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "Request Example", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } + } } } }, "responses": { "200": { - "description": "Conversation renamed successfully.", + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : Message does not exist.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationRenameResponse" } + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } } } } } } }, - "/conversations/{conversation_id}/variables": { + "/app/feedbacks": { "get": { - "summary": "Get Conversation Variables", - "description": "Retrieve variables from a specific conversation.", - "operationId": "getAdvancedConversationVariables", - "tags": ["Conversations"], - "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParam" }, - { "$ref": "#/components/parameters/UserQueryParam" }, - { "$ref": "#/components/parameters/LastIdQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100" } + "operationId": "listChatflowFeedbacks", + "tags": [ + "Feedback" ], - "responses": { - "200": { - "description": "Successfully retrieved conversation variables.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ConversationVariablesResponse" } - } + "summary": "List App Feedbacks", + "description": "Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.", + "parameters": [ + { + "name": "page", + "in": "query", + "description": "Page number for pagination.", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 } }, - "404": { "$ref": "#/components/responses/ConversationNotFound" } - } - } - }, - "/audio-to-text": { - "post": { - "summary": "Speech to Text", - "description": "Convert audio file to text. Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm. File size limit: 15MB.", - "operationId": "advancedAudioToText", - "tags": ["TTS"], - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { - "schema": { "$ref": "#/components/schemas/AudioToTextRequest" } + { + "name": "limit", + "in": "query", + "description": "Number of records per page.", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 } } - }, + ], "responses": { "200": { - "description": "Successfully converted audio to text.", + "description": "A list of application feedbacks.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AudioToTextResponse" } + "schema": { + "$ref": "#/components/schemas/AppFeedbacksResponse" + }, + "examples": { + "feedbacksList": { + "summary": "Response Example", + "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-75673b6666g3", + "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" + } + ] + } + } + } } } } } } }, - "/text-to-audio": { - "post": { - "summary": "Text to Audio", - "description": "Convert text to speech.", - "operationId": "advancedTextToAudio", - "tags": ["TTS"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/TextToAudioJsonRequest" } + "/conversations": { + "get": { + "summary": "List Conversations", + "description": "Retrieve the conversation list for the current user, ordered by most recently active.", + "operationId": "listChatflowConversations", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier.", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "The ID of the last record on the current page (for pagination).", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of records to return.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "sort_by", + "in": "query", + "required": false, + "description": "Sorting field. Use '-' prefix for descending order.", + "schema": { + "type": "string", + "enum": [ + "created_at", + "-created_at", + "updated_at", + "-updated_at" + ], + "default": "-updated_at" } } - }, + ], "responses": { "200": { - "description": "Audio file generated successfully.", + "description": "Successfully retrieved conversations list.", "content": { - "audio/wav": { "schema": { "type": "string", "format": "binary" } }, - "audio/mp3": { "schema": { "type": "string", "format": "binary" } } - }, - "headers": { - "Content-Type": { - "schema": { "type": "string", "example": "audio/wav" } + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationsListResponse" + }, + "examples": { + "conversationsList": { + "summary": "Response Example", + "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 + } + ] + } + } + } } } - } - } - } - }, - "/info": { - "get": { - "summary": "Get Application Basic Information", - "operationId": "getAdvancedChatAppInfo", - "tags": ["Application"], - "responses": { - "200": { - "description": "Basic application information.", + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppInfoResponse" } + "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." + } + } + } } } - } - } - } - }, - "/parameters": { - "get": { - "summary": "Get Application Parameters Information", - "operationId": "getAdvancedChatAppParameters", - "tags": ["Application"], - "responses": { - "200": { - "description": "Application parameters.", + }, + "404": { + "description": "`not_found` : Last conversation does not exist (invalid `last_id`).", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ChatAppParametersResponse" } + "examples": { + "last_conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Last Conversation Not Exists." + } + } + } } } } } } }, - "/meta": { + "/messages": { "get": { - "summary": "Get Application Meta Information", - "operationId": "getAdvancedChatAppMeta", - "tags": ["Application"], + "summary": "List Conversation Messages", + "description": "Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order.", + "operationId": "listChatflowMessages", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier.", + "schema": { + "type": "string" + } + }, + { + "name": "first_id", + "in": "query", + "required": false, + "description": "The ID of the first chat record on the current page. Default is `null` (fetches the latest messages). For subsequent pages, use the ID of the first message from the current list to get older messages.", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of chat history messages to return per request.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], "responses": { "200": { - "description": "Application meta information (tool icons).", + "description": "Successfully retrieved conversation history.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "Response Example", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "parent_message_id": null, + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "status": "normal", + "error": null, + "message_files": [], + "feedback": { + "rating": "like" + }, + "retriever_resources": [], + "agent_thoughts": [], + "created_at": 1705407629 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppMetaResponse" } + "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." + } + } + } } } - } - } - } - }, - "/site": { - "get": { - "summary": "Get Application WebApp Settings", - "operationId": "getAdvancedChatWebAppSettings", - "tags": ["Application"], - "responses": { - "200": { - "description": "WebApp settings.", + }, + "404": { + "description": "- `not_found` : Conversation does not exist.\n- `not_found` : First message does not exist.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" } + "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." + } + } + } } } } } } }, - "/apps/annotations": { + "/conversations/{conversation_id}/variables": { "get": { - "summary": "Get Annotation List", - "operationId": "getAdvancedAnnotationList", - "tags": ["Annotations"], + "summary": "List Conversation Variables", + "description": "Retrieve variables from a specific conversation.", + "operationId": "listChatflowConversationVariables", + "tags": [ + "Conversations" + ], "parameters": [ - { "$ref": "#/components/parameters/PageQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100" } + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "The user identifier.", + "schema": { + "type": "string" + } + }, + { + "name": "last_id", + "in": "query", + "required": false, + "description": "The ID of the last record on the current page (for pagination).", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "Number of records to return.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "variable_name", + "in": "query", + "required": false, + "description": "Filter variables by a specific name.", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 255 + } + } ], "responses": { "200": { - "description": "Annotation list.", + "description": "Successfully retrieved conversation variables.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariablesResponse" + }, + "examples": { + "conversationVariables": { + "summary": "Response Example", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "dark_mode", + "description": "User preference setting", + "created_at": 1705407629, + "updated_at": 1705411229 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "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` : Conversation does not exist.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AnnotationListResponse" } + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } } } } } - }, + } + }, + "/conversations/{conversation_id}/name": { "post": { - "summary": "Create Annotation", - "operationId": "createAdvancedAnnotation", - "tags": ["Annotations"], + "summary": "Rename Conversation", + "description": "Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations.", + "operationId": "renameChatflowConversation", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + } + ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" } + "schema": { + "$ref": "#/components/schemas/ConversationRenameRequest" + }, + "examples": { + "renameExample": { + "summary": "Request Example", + "value": { + "name": "iPhone Specs Chat", + "user": "abc-123" + } + } + } } } }, "responses": { - "200": { "description": "Annotation created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } }, - "201": { "description": "Annotation created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } } + "200": { + "description": "Conversation renamed successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationListItem" + }, + "examples": { + "renamedConversation": { + "summary": "Response Example", + "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` : App mode does not match the API route.", + "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` : Conversation does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } } } }, - "/apps/annotations/{annotation_id}": { + "/conversations/{conversation_id}/variables/{variable_id}": { "put": { - "summary": "Update Annotation", - "operationId": "updateAdvancedAnnotation", - "tags": ["Annotations"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParam" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" } } } - }, - "responses": { - "200": { "description": "Annotation updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } } - } - }, - "delete": { - "summary": "Delete Annotation", - "operationId": "deleteAdvancedAnnotation", - "tags": ["Annotations"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParam" } ], - "responses": { - "204": { "description": "Annotation deleted." } - } - } - }, - "/apps/annotation-reply/{action}": { - "post": { - "summary": "Initial Annotation Reply Settings", - "operationId": "initialAdvancedAnnotationReplySettings", - "tags": ["Annotations"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationActionPathParam" } ], + "summary": "Update Conversation Variable", + "description": "Update the value of a specific conversation variable. The value must match the expected type.", + "operationId": "updateChatflowConversationVariable", + "tags": [ + "Conversations" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation 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/InitialAnnotationReplySettingsRequest" } } } + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableUpdateRequest" + }, + "examples": { + "updateStringVariable": { + "summary": "Request Example", + "value": { + "value": "new value", + "user": "abc-123" + } + } + } + } + } }, "responses": { - "200": { "description": "Task initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" } } } }, - "202": { "description": "Task accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" } } } } - } - } - }, - "/apps/annotation-reply/{action}/status/{job_id}": { - "get": { - "summary": "Query Initial Annotation Reply Settings Task Status", - "operationId": "getAdvancedInitialAnnotationReplySettingsStatus", - "tags": ["Annotations"], + "200": { + "description": "Variable updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableItem" + }, + "examples": { + "updatedVariable": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "new value", + "description": "User preference setting", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : App mode does not match the API route.\n- `bad_request` : Variable value type mismatch.", + "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` : Conversation does not exist.\n- `not_found` : Conversation variable does not exist.", + "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": "Delete Conversation", + "description": "Delete a conversation.", + "operationId": "deleteChatflowConversation", + "tags": [ + "Conversations" + ], "parameters": [ - { "$ref": "#/components/parameters/AnnotationActionPathParam" }, - { "$ref": "#/components/parameters/JobIdPathParam" } + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "Conversation ID.", + "schema": { + "type": "string" + } + } ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user": { + "type": "string", + "description": "The user identifier." + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "Request Example" + } + } + } + } + }, "responses": { - "200": { "description": "Task status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" } } } } + "204": { + "description": "Conversation deleted successfully. No content returned." + }, + "400": { + "description": "`not_chat_app` : App mode does not match the API route.", + "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` : Conversation does not exist.", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } } } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "API_KEY", - "description": "API Key authentication." - } }, - "parameters": { - "PageQueryParam": { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParam": { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer" } }, - "LimitQueryParamDefault20": { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100": { "name": "limit", "in": "query", "description": "Number of items per page (Default 20, Max 100).", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParam": { "name": "user", "in": "query", "required": true, "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface.", "schema": { "type": "string" } }, - "ConversationIdQueryParam": { "name": "conversation_id", "in": "query", "required": true, "description": "Conversation ID.", "schema": { "type": "string" } }, - "LastIdQueryParam": { "name": "last_id", "in": "query", "description": "ID of the last record for pagination.", "schema": { "type": "string" } }, - "SortByQueryParam": { "name": "sort_by", "in": "query", "description": "Sorting field (e.g., -updated_at).", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParam": { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID.", "schema": { "type": "string" } }, - "AnnotationIdPathParam": { "name": "annotation_id", "in": "path", "required": true, "description": "Annotation ID.", "schema": { "type": "string", "format": "uuid" } }, - "AnnotationActionPathParam": { "name": "action", "in": "path", "required": true, "description": "Action: 'enable' or 'disable'.", "schema": { "type": "string", "enum": ["enable", "disable"] } }, - "JobIdPathParam": { "name": "job_id", "in": "path", "required": true, "description": "Job ID.", "schema": { "type": "string", "format": "uuid" } } + "/audio-to-text": { + "post": { + "operationId": "chatflowAudioToText", + "tags": [ + "TTS" + ], + "summary": "Convert Audio to Text", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `15 MB`.", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully converted audio to text.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "Response Example", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", + "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` : Audio file size exceeded the limit.", + "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` : Audio type is not allowed.", + "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` : 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." + } + } + } + } + } + } + } + } }, - "responses": { - "BadRequestGeneric": { "description": "Bad Request. Check parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "BadRequestFile": { "description": "Bad Request for file operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "FileTooLarge": { "description": "File is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "UnsupportedFileTypeFile": { "description": "Unsupported file type for upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "S3ErrorFile": { "description": "S3 storage error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "InternalServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "SuccessResult": { "description": "Operation successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFound": { "description": "Conversation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "EndUserNotFound": { "description": "End user not found. Error code: `end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } + "/text-to-audio": { + "post": { + "operationId": "chatflowTextToAudio", + "tags": [ + "TTS" + ], + "summary": "Convert Text to Audio", + "description": "Convert text to speech.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "Request Example", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", + "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." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : Audio file size exceeded.", + "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` : Audio type not allowed.", + "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` : 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." + } + } + } + } + } + } + } + } }, - "schemas": { - "AdvancedChatRequest": { + "/info": { + "get": { + "operationId": "getChatflowAppInfo", + "tags": [ + "Applications" + ], + "summary": "Get App Info", + "description": "Retrieve basic information about this application, including name, description, tags, and mode.", + "responses": { + "200": { + "description": "Basic information of the application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "Response Example", + "value": { + "name": "My Chatflow App", + "description": "A helpful customer service chatbot.", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "advanced-chat", + "author_name": "Dify Team" + } + } + } + } + } + } + } + } + }, + "/parameters": { + "get": { + "operationId": "getChatflowAppParameters", + "tags": [ + "Applications" + ], + "summary": "Get App Parameters", + "description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.", + "responses": { + "200": { + "description": "Application parameters information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "Response Example", + "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` : App unavailable or misconfigured.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getChatflowAppMeta", + "tags": [ + "Applications" + ], + "summary": "Get App Meta", + "description": "Retrieve metadata about this application, including tool icons and other configuration details.", + "responses": { + "200": { + "description": "Successfully retrieved application meta information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "Response Example", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } + } + }, + "/site": { + "get": { + "operationId": "getChatflowWebAppSettings", + "tags": [ + "Applications" + ], + "summary": "Get App WebApp Settings", + "description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.", + "responses": { + "200": { + "description": "WebApp settings of the application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "Response Example", + "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": "A helpful customer service chatbot.", + "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` : Site not found for this application or the workspace has been archived.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } + } + }, + "/apps/annotations": { + "post": { + "summary": "Create Annotation", + "description": "Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response.", + "operationId": "createChatflowAnnotation", + "tags": [ + "Annotations" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAnnotationRequest" + }, + "examples": { + "createAnnotation": { + "summary": "Request Example", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Annotation created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "createdAnnotation": { + "summary": "Response Example", + "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": "List Annotations", + "description": "Retrieves a paginated list of annotations for the application. Supports keyword search filtering.", + "operationId": "listChatflowAnnotations", + "tags": [ + "Annotations" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "Page number for pagination.", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of items per page.", + "required": false, + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "keyword", + "in": "query", + "description": "Keyword to filter annotations by question or answer content.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved annotation list.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationListResponse" + }, + "examples": { + "annotationList": { + "summary": "Response Example", + "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": "Update Annotation", + "description": "Updates the question and answer of an existing annotation.", + "operationId": "updateChatflowAnnotation", + "tags": [ + "Annotations" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "The unique identifier of the annotation to update.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateAnnotationRequest" + }, + "examples": { + "updateAnnotation": { + "summary": "Request Example", + "value": { + "question": "What is Dify?", + "answer": "Dify is an open-source LLM application development platform for building AI-powered apps." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Annotation updated successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "examples": { + "updatedAnnotation": { + "summary": "Response Example", + "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` : Insufficient permissions to edit annotations.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Annotation does not exist.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Annotation not found." + } + } + } + } + } + } + } + }, + "delete": { + "summary": "Delete Annotation", + "description": "Deletes an annotation and its associated hit history.", + "operationId": "deleteChatflowAnnotation", + "tags": [ + "Annotations" + ], + "parameters": [ + { + "name": "annotation_id", + "in": "path", + "required": true, + "description": "The unique identifier of the annotation to delete.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Annotation deleted successfully." + }, + "403": { + "description": "`forbidden` : Insufficient permissions to edit annotations.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Annotation does not exist.", + "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": "Configure Annotation Reply", + "description": "Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.", + "operationId": "setChatflowAnnotationReply", + "tags": [ + "Annotations" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "Action to perform.", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" + }, + "examples": { + "enableAnnotationReply": { + "summary": "Request Example", + "value": { + "score_threshold": 0.9, + "embedding_provider_name": "openai", + "embedding_model_name": "text-embedding-3-small" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Annotation reply settings task initiated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponse" + }, + "examples": { + "annotationReplyResponse": { + "summary": "Response Example", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "waiting" + } + } + } + } + } + } + } + } + }, + "/apps/annotation-reply/{action}/status/{job_id}": { + "get": { + "summary": "Get Annotation Reply Job Status", + "description": "Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", + "operationId": "getChatflowAnnotationReplyStatus", + "tags": [ + "Annotations" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "Action type, must match the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call.", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "Job ID returned by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved task status.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "Response Example", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : The specified job does not exist.", + "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 authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" + } + }, + "responses": { + "SuccessResult": { + "description": "Operation successful.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Result status." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + } + }, + "schemas": { + "ChatRequest": { + "type": "object", + "required": [ + "inputs", + "query", + "user" + ], + "properties": { + "query": { + "type": "string", + "description": "User input/question content." + }, + "inputs": { + "type": "object", + "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", + "additionalProperties": true + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "default": "blocking", + "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`." + }, + "user": { + "type": "string", + "description": "User identifier, unique within the application. This identifier scopes data access — conversations, messages, and files are only visible when queried with the same `user` value." + }, + "conversation_id": { + "type": "string", + "description": "Conversation ID to continue a conversation. Pass the previous message's `conversation_id`. To start a new conversation, omit this field or pass an empty string. The response will return a `conversation_id` — pass it in subsequent messages to continue that conversation." + }, + "files": { + "type": "array", + "description": "File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`.", + "items": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "File type." + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file." + }, + "url": { + "type": "string", + "format": "url", + "description": "File URL (required when `transfer_method` is `remote_url`)." + }, + "upload_file_id": { + "type": "string", + "description": "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`)." + } + } + } + }, + "auto_generate_name": { + "type": "boolean", + "description": "Auto-generate conversation title. If `false`, use the [Rename Conversation](/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation.", + "default": true + }, + "workflow_id": { + "type": "string", + "description": "Specify a published workflow version ID to execute. If not provided, the latest published version is used." + } + } + }, + "ChatCompletionResponse": { + "type": "object", + "properties": { + "event": { + "type": "string", + "description": "Event type, fixed as `message`." + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID for request tracking and stop response API." + }, + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of this response event." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "mode": { + "type": "string", + "description": "App mode, fixed as `advanced-chat`." + }, + "answer": { + "type": "string", + "description": "Complete response content." + }, + "metadata": { + "type": "object", + "description": "Metadata including usage and retriever resources.", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Message creation timestamp (Unix epoch seconds)." + } + } + }, + "ChunkChatEvent": { + "type": "object", + "description": "Base schema for Server-Sent Event chunks in streaming mode.", + "properties": { + "event": { + "type": "string", + "description": "The type of event.", + "enum": [ + "message", + "tts_message", + "tts_message_end", + "message_file", + "message_end", + "message_replace", + "workflow_started", + "workflow_finished", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "human_input_required", + "agent_log", + "error", + "ping" + ] + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventChatMessage", + "tts_message": "#/components/schemas/StreamEventChatTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", + "message_file": "#/components/schemas/StreamEventChatMessageFile", + "message_end": "#/components/schemas/StreamEventChatMessageEnd", + "message_replace": "#/components/schemas/StreamEventChatMessageReplace", + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "error": "#/components/schemas/StreamEventChatError", + "ping": "#/components/schemas/StreamEventChatPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "description": "Base properties for stream events.", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + } + } + }, + "StreamEventChatMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "answer": { + "type": "string", + "description": "LLM returned text chunk." + } + } + } + ] + }, + "StreamEventChatTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS audio stream event (base64 encoded Mp3). Available if auto-play enabled.", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." + } + } + } + ] + }, + "StreamEventChatTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS audio stream end event.", + "properties": { + "audio": { + "type": "string", + "description": "Empty string. Signals the end of the audio stream." + } + } + } + ] + }, + "StreamEventChatMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "Message file event, a new file created by a tool.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File unique ID." + }, + "type": { + "type": "string", + "description": "File type, e.g. `image`." + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "Who this file belongs to, always `assistant` here." + }, + "url": { + "type": "string", + "format": "url", + "description": "Remote URL of the file." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + } + } + } + ] + }, + "StreamEventChatMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Message end event, streaming has ended.", + "properties": { + "metadata": { + "type": "object", + "description": "Metadata including usage and retriever resources.", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } + ] + }, + "StreamEventChatMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Message content replacement event (e.g., due to content moderation).", + "properties": { + "answer": { + "type": "string", + "description": "Replacement content." + }, + "reason": { + "type": "string", + "description": "Reason for the content replacement." + } + } + } + ] + }, + "StreamEventChatError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Error event during streaming.", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code." + }, + "code": { + "type": "string", + "description": "Error code." + }, + "message": { + "type": "string", + "description": "Error message." + } + } + } + ] + }, + "StreamEventChatPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "Ping event to keep connection alive." + } + ] + }, + "Usage": { + "type": "object", + "description": "Model usage information.", + "properties": { + "prompt_tokens": { + "type": "integer", + "description": "Number of tokens in the prompt." + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per prompt token." + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for prompt tokens." + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "Total price for prompt tokens." + }, + "completion_tokens": { + "type": "integer", + "description": "Number of tokens in the completion." + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per completion token." + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for completion tokens." + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "Total price for completion tokens." + }, + "total_tokens": { + "type": "integer", + "description": "Total number of tokens used." + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "Total price for all tokens." + }, + "currency": { + "type": "string", + "description": "Currency for pricing." + }, + "latency": { + "type": "number", + "format": "double", + "description": "Latency in seconds." + } + } + }, + "RetrieverResource": { + "type": "object", + "description": "Citation and attribution information for a retriever resource.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of the retriever resource." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "ID of the message this resource belongs to." + }, + "position": { + "type": "integer", + "description": "Position of the resource in the list." + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "ID of the knowledge base." + }, + "dataset_name": { + "type": "string", + "description": "Name of the knowledge base." + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "ID of the document." + }, + "document_name": { + "type": "string", + "description": "Name of the document." + }, + "data_source_type": { + "type": "string", + "description": "Type of the data source." + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "ID of the specific chunk within the document." + }, + "score": { + "type": "number", + "format": "float", + "description": "Relevance score of the resource." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this chunk was hit." + }, + "word_count": { + "type": "integer", + "description": "Word count of the chunk." + }, + "segment_position": { + "type": "integer", + "description": "Position of the chunk within the document." + }, + "index_node_hash": { + "type": "string", + "description": "Hash of the index node." + }, + "content": { + "type": "string", + "description": "Content snippet from the resource." + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary of the chunk content." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." + } + } + }, + "FileUploadResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique file ID." + }, + "name": { + "type": "string", + "description": "File name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "nullable": true, + "description": "File extension." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Upload timestamp (Unix epoch seconds)." + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "Preview URL for the file." + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "Source URL of the file." + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "Original URL of the file." + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated user." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated tenant." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated conversation." + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "Storage key for the file." + } + } + }, + "EndUserDetail": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "Tenant ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Application ID." + }, + "type": { + "type": "string", + "description": "End user type. Always `service_api` for Service API users." + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/api-reference/chats/send-chat-message))." + }, + "name": { + "type": "string", + "nullable": true, + "description": "End user name." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request." + }, + "session_id": { + "type": "string", + "description": "Session identifier. Defaults to the `external_user_id` value." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } + } + }, + "MessageFeedbackRequest": { + "type": "object", + "description": "Request body for submitting message feedback.", + "required": [ + "user" + ], + "properties": { + "rating": { + "type": "string", + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "Feedback rating. Set to `null` to revoke previously submitted feedback." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer, must ensure uniqueness within the application." + }, + "content": { + "type": "string", + "description": "Optional text feedback providing additional detail." + } + } + }, + "AppFeedbacksResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "List of feedback items.", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } + } + } + }, + "FeedbackItem": { + "type": "object", + "description": "A single feedback item.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Feedback ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "Application ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + }, + "content": { + "type": "string", + "nullable": true, + "description": "Optional text feedback." + }, + "from_source": { + "type": "string", + "description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console." + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "End user ID who submitted the feedback. Present when `from_source` is `user`." + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Account ID who submitted the feedback. Present when `from_source` is `admin`." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } + } + }, + "SuggestedQuestionsResponse": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Result status." + }, + "data": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of suggested questions." + } + } + }, + "ConversationHistoryResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more messages." + }, + "data": { + "type": "array", + "description": "List of messages.", + "items": { + "$ref": "#/components/schemas/ConversationMessageItem" + } + } + } + }, + "ConversationMessageItem": { + "type": "object", + "description": "A single message in a conversation.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "parent_message_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Parent message ID for threaded conversations." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for this message." + }, + "query": { + "type": "string", + "description": "User query text." + }, + "answer": { + "type": "string", + "description": "Assistant answer text." + }, + "status": { + "type": "string", + "description": "Message status. `normal` for successful messages, `error` when generation failed." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if `status` is `error`." + }, + "message_files": { + "type": "array", + "description": "Files attached to this message.", + "items": { + "$ref": "#/components/schemas/MessageFileItem" + } + }, + "feedback": { + "type": "object", + "nullable": true, + "description": "User feedback for this message.", + "properties": { + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + } + } + }, + "retriever_resources": { + "type": "array", + "description": "Retriever resources used for this message.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + }, + "agent_thoughts": { + "type": "array", + "description": "Agent thoughts for this message.", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." + } + } + }, + "MessageFileItem": { + "type": "object", + "description": "A file attached to a message.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "Original filename." + }, + "type": { + "type": "string", + "description": "File type, e.g., `image`." + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "Preview URL for the file." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "size": { + "type": "integer", + "nullable": true, + "description": "File size in bytes." + }, + "transfer_method": { + "type": "string", + "description": "Transfer method used. `remote_url` for URL-based files, `local_file` for uploaded files, `tool_file` for tool-generated files." + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "Who this file belongs to. `user` for user-uploaded files, `assistant` for assistant-generated files." + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Upload file ID if transferred via `local_file`." + } + } + }, + "AgentThoughtItem": { + "type": "object", + "description": "An agent thought step in the message.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Agent thought ID." + }, + "chain_id": { + "type": "string", + "nullable": true, + "description": "Chain ID for this thought." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID this thought belongs to." + }, + "position": { + "type": "integer", + "description": "Position of this thought." + }, + "thought": { + "type": "string", + "description": "What LLM is thinking." + }, + "tool": { + "type": "string", + "description": "Tools called, split by `;`." + }, + "tool_labels": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Labels for tools used." + }, + "tool_input": { + "type": "string", + "description": "Input of tools in JSON format." + }, + "observation": { + "type": "string", + "description": "Response from tool calls." + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "File IDs related to this thought." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + } + } + }, + "ConversationsListResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there are more conversations." + }, + "data": { + "type": "array", + "description": "List of conversations.", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } + } + } + }, + "ConversationListItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "name": { + "type": "string", + "description": "Conversation name." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the conversation." + }, + "status": { + "type": "string", + "description": "Conversation status. `normal` for active conversations." + }, + "introduction": { + "type": "string", + "description": "Conversation introduction." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update timestamp." + } + } + }, + "ConversationRenameRequest": { + "type": "object", + "description": "Request body for renaming a conversation.", + "required": [ + "user" + ], + "properties": { + "name": { + "type": "string", + "description": "The name of the conversation. Required when `auto_generate` is `false`." + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "Automatically generate the conversation name. When `true`, the `name` field is ignored." + }, + "user": { + "type": "string", + "description": "The user identifier." + } + } + }, + "ConversationVariablesResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "has_more": { + "type": "boolean", + "description": "Whether there is a next page." + }, + "data": { + "type": "array", + "description": "List of conversation variables.", + "items": { + "$ref": "#/components/schemas/ConversationVariableItem" + } + } + } + }, + "ConversationVariableItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Variable ID." + }, + "name": { + "type": "string", + "description": "Variable name." + }, + "value_type": { + "type": "string", + "description": "Variable value type. Possible values: `string`, `number`, `object`, `secret`, `file`, `boolean`, `array[any]`, `array[string]`, `array[number]`, `array[object]`, `array[file]`, `array[boolean]`." + }, + "value": { + "type": "string", + "description": "Variable value (can be a JSON string for complex types)." + }, + "description": { + "type": "string", + "description": "Variable description." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "Last update timestamp." + } + } + }, + "ConversationVariableUpdateRequest": { + "type": "object", + "description": "Request body for updating a conversation variable.", + "required": [ + "value" + ], + "properties": { + "value": { + "description": "The new value for the variable. Must match the variable's expected type." + }, + "user": { + "type": "string", + "description": "User identifier." + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "Request body for audio-to-text conversion.", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `15 MB`." + }, + "user": { + "type": "string", + "description": "User identifier." + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "Output text from speech recognition." + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID. Takes priority over `text` when both are provided." + }, + "text": { + "type": "string", + "description": "Speech content to convert." + }, + "user": { + "type": "string", + "description": "User identifier." + }, + "voice": { + "type": "string", + "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." + }, + "streaming": { + "type": "boolean", + "description": "Whether to enable streaming response." + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Application name." + }, + "description": { + "type": "string", + "description": "Application description." + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Application tags." + }, + "mode": { + "type": "string", + "description": "Application mode. `completion` for text generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for chatflow apps, `workflow` for workflow apps." + }, + "author_name": { + "type": "string", + "description": "Name of the application author." + } + } + }, + "ChatAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "Opening statement displayed at conversation start." + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of suggested starter questions." + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "Configuration for suggested questions after answer.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "speech_to_text": { + "type": "object", + "description": "Speech-to-text configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "text_to_speech": { + "type": "object", + "description": "Text-to-speech configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + }, + "voice": { + "type": "string", + "description": "Voice identifier for TTS." + }, + "language": { + "type": "string", + "description": "Language for TTS." + }, + "autoPlay": { + "type": "string", + "description": "Auto-play setting. `enabled` to auto-play audio, `disabled` to require manual play." + } + } + }, + "retriever_resource": { + "type": "object", + "description": "Retriever resource configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "annotation_reply": { + "type": "object", + "description": "Annotation reply configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "more_like_this": { + "type": "object", + "description": "More-like-this configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "Sensitive word avoidance configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "user_input_form": { + "type": "array", + "description": "List of user input form elements.", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "File upload configuration.", + "properties": { + "image": { + "type": "object", + "description": "Image upload settings.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether image upload is enabled." + }, + "number_limits": { + "type": "integer", + "description": "Maximum number of images." + }, + "detail": { + "type": "string", + "description": "Image detail level." + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Allowed transfer methods." + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "System-level parameters and limits.", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "Maximum file size in MB." + }, + "image_file_size_limit": { + "type": "integer", + "description": "Maximum image file size in MB." + }, + "audio_file_size_limit": { + "type": "integer", + "description": "Maximum audio file size in MB." + }, + "video_file_size_limit": { + "type": "integer", + "description": "Maximum video file size in MB." + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "Maximum number of files for workflow file upload." + } + } + } + } + }, + "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": "Text input form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether input is required." + }, + "default": { + "type": "string", + "description": "Default value." + } + } + }, + "ParagraphControl": { + "type": "object", + "description": "Paragraph (multi-line text) form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether input is required." + }, + "default": { + "type": "string", + "description": "Default value." + } + } + }, + "SelectControl": { + "type": "object", + "description": "Select (dropdown) form control.", + "properties": { + "label": { + "type": "string", + "description": "Display label." + }, + "variable": { + "type": "string", + "description": "Variable name." + }, + "required": { + "type": "boolean", + "description": "Whether selection is required." + }, + "default": { + "type": "string", + "description": "Default selected value." + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of selectable values for this form control." + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "URL of the icon." + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "Tool icons. Keys are tool names." + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "Detail of a tool icon using emoji.", + "properties": { + "background": { + "type": "string", + "description": "Background color in hex format." + }, + "content": { + "type": "string", + "description": "Emoji content." + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp title." + }, + "chat_color_theme": { + "type": "string", + "description": "Chat color theme." + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "Whether the chat color theme is inverted." + }, + "icon_type": { + "type": "string", + "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." + }, + "icon": { + "type": "string", + "description": "Icon content (emoji or image ID)." + }, + "icon_background": { + "type": "string", + "description": "Icon background color." + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "URL of the icon image." + }, + "description": { + "type": "string", + "description": "WebApp description." + }, + "copyright": { + "type": "string", + "description": "Copyright text." + }, + "privacy_policy": { + "type": "string", + "description": "Privacy policy URL." + }, + "custom_disclaimer": { + "type": "string", + "description": "Custom disclaimer text." + }, + "default_language": { + "type": "string", + "description": "Default language code." + }, + "show_workflow_steps": { + "type": "boolean", + "description": "Whether to show workflow steps." + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "Whether to use the app icon as the answer icon." + } + } + }, + "AnnotationListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "description": "List of annotation items for the current page." + }, + "has_more": { + "type": "boolean", + "description": "`true` if more pages are available beyond the current result set." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of annotations matching the query." + }, + "page": { + "type": "integer", + "description": "Current page number." + } + } + }, + "AnnotationItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique annotation identifier." + }, + "question": { + "type": "string", + "nullable": true, + "description": "Question text that triggers this annotation." + }, + "answer": { + "type": "string", + "nullable": true, + "description": "Predefined answer returned when the annotation is matched." + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "Number of times this annotation has been matched and returned as a reply." + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Creation timestamp (Unix epoch seconds)." + } + } + }, + "CreateAnnotationRequest": { + "type": "object", + "description": "Request body for creating a new annotation.", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "Annotation question." + }, + "answer": { + "type": "string", + "description": "Annotation answer." + } + } + }, + "UpdateAnnotationRequest": { + "type": "object", + "description": "Request body for updating an annotation.", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "Updated annotation question." + }, + "answer": { + "type": "string", + "description": "Updated annotation answer." + } + } + }, + "InitialAnnotationReplySettingsRequest": { "type": "object", - "required": ["query", "user"], + "description": "Request body for configuring annotation reply settings.", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], "properties": { - "query": { "type": "string", "description": "User input/question content." }, - "inputs": { - "type": "object", - "description": "Key/value pairs for app variables. For file type variables, value should be an InputFileObject.", - "additionalProperties": { - "oneOf": [ - { "type": "string" }, - { "type": "number" }, - { "type": "boolean" }, - { "$ref": "#/components/schemas/InputFileObjectAdvanced" } - ] - }, - "default": {} + "embedding_provider_name": { + "type": "string", + "description": "Name of the embedding model provider (e.g., `openai`, `cohere`)." }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "Response mode. Cloudflare timeout is 100s for blocking." }, - "user": { "type": "string", "description": "User identifier. **Note**: The Service API does not share conversations created by the WebApp. Conversations created through the API are isolated from those created in the WebApp interface." }, - "conversation_id": { "type": "string", "description": "Conversation ID to continue." }, - "files": { - "type": "array", - "items": { "$ref": "#/components/schemas/InputFileObjectAdvanced" }, - "description": "List of files for Vision-capable models or general file input." + "embedding_model_name": { + "type": "string", + "description": "Name of the embedding model to use for annotation matching (e.g., `text-embedding-3-small`)." }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "Auto-generate conversation title." } + "score_threshold": { + "type": "number", + "format": "float", + "description": "Minimum similarity score for an annotation to be considered a match. Higher values require closer matches.", + "minimum": 0, + "maximum": 1 + } } }, - "InputFileObjectAdvanced": { + "InitialAnnotationReplySettingsResponse": { "type": "object", - "required": ["type", "transfer_method"], "properties": { - "type": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "Asynchronous job ID. Use with [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress." + }, + "job_status": { + "type": "string", + "description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed." + } + } + }, + "InitialAnnotationReplySettingsStatusResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "Job ID from the [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply) call." + }, + "job_status": { + "type": "string", + "description": "Current job status. `waiting` for queued, `processing` for in progress, `completed` when finished, `error` if failed." + }, + "error_msg": { "type": "string", - "enum": ["document", "image", "audio", "video", "custom"], - "description": "Type of the file. 'document' covers TXT, MD, PDF, HTML, XLSX, DOCX, CSV, EML, MSG, PPTX, XML, EPUB. 'image' covers JPG, PNG, GIF, WEBP, SVG. 'audio' covers MP3, M4A, WAV, WEBM, AMR. 'video' covers MP4, MOV, MPEG, MPGA." + "description": "Error message describing why the job failed. Empty string when `job_status` is not `error`." + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Workflow execution started.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "description": "Associated workflow ID." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for this workflow execution." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Workflow execution finished.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "description": "Associated workflow ID." + }, + "status": { + "type": "string", + "enum": [ + "running", + "succeeded", + "failed", + "stopped", + "partial-succeeded" + ], + "description": "Execution status." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Workflow output data." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if execution failed." + }, + "elapsed_time": { + "type": "number", + "description": "Total execution time in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total steps executed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Finish timestamp (Unix epoch seconds)." + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "default": 0, + "description": "Number of exceptions during execution." + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files generated during workflow execution." + } + } + } + } + } + ] + }, + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Node execution started.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type (e.g., `llm`, `knowledge-retrieval`, `code`)." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "Execution index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node." + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node input data. May be `null` in simplified API responses." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Iteration ID if this node runs inside an iteration." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Loop ID if this node runs inside a loop." + } + } + } + } + } + ] + }, + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Node execution finished.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "Execution index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node." + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node input data. May be `null` in simplified API responses." + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node processing data. May be `null` in simplified API responses." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node output data. May be `null` in simplified API responses." + }, + "status": { + "type": "string", + "enum": [ + "running", + "succeeded", + "failed", + "exception" + ], + "description": "Node execution status." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if node failed." + }, + "elapsed_time": { + "type": "number", + "description": "Node execution time in seconds." + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Execution metadata (e.g., token usage, model info). May be `null` in simplified API responses." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Finish timestamp (Unix epoch seconds)." + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files generated by this node." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Iteration ID if this node runs inside an iteration." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Loop ID if this node runs inside a loop." + } + } + } + } + } + ] + }, + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Node retry attempt.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "Execution index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node." + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node input data." + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node processing data." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Node output data." + }, + "status": { + "type": "string", + "enum": [ + "running", + "succeeded", + "failed", + "exception" + ], + "description": "Node execution status." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message for this retry attempt." + }, + "elapsed_time": { + "type": "number", + "description": "Execution time for this attempt in seconds." + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Execution metadata." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Finish timestamp (Unix epoch seconds)." + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files generated during this retry." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Iteration ID if applicable." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Loop ID if applicable." + }, + "retry_index": { + "type": "integer", + "default": 0, + "description": "Retry attempt index (0-based)." + } + } + } + } + } + ] + }, + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Iteration loop started.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Iteration execution ID." + }, + "node_id": { + "type": "string", + "description": "Iteration node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Iteration node title." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Iteration metadata." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Iteration input data." + } + } + } + } + } + ] + }, + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Iteration progressed to next item.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Iteration execution ID." + }, + "node_id": { + "type": "string", + "description": "Iteration node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Iteration node title." + }, + "index": { + "type": "integer", + "description": "Current iteration index (0-based)." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Timestamp (Unix epoch seconds)." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "Transfer method, `remote_url` for file URL / `local_file` for file upload" }, - "url": { "type": "string", "format": "url", "description": "File URL (when the transfer method is `remote_url`)" }, - "upload_file_id": { "type": "string", "description": "Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`)" } - }, - "anyOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "$ref": "#/components/schemas/StreamEventBase" }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } - } - ], - "example": { "type": "image", "transfer_method": "remote_url", "url": "https://example.com/image.png" } - }, - "ChatCompletionResponse": { - "type": "object", - "description": "Response for blocking mode chat.", - "properties": { - "event": { "type": "string", "example": "message" }, - "task_id": { "type": "string", "format": "uuid" }, - "id": { "type": "string", "format": "uuid", "description": "Unique ID of this response event." }, - "message_id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "mode": { "type": "string", "example": "chat" }, - "answer": { "type": "string" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadata" }, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "ResponseMetadata": { - "type": "object", - "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, - "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResource" } } - } - }, - "ChunkAdvancedChatEvent": { - "type": "object", - "required": ["event"], - "properties": { - "event": { "type": "string", "enum": ["message", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "workflow_started", "node_started", "node_finished", "workflow_finished", "error", "ping"] } - }, - "discriminator": { - "propertyName": "event", - "mapping": { - "message": "#/components/schemas/StreamEventAdvChatMessage", - "message_file": "#/components/schemas/StreamEventAdvMessageFile", - "message_end": "#/components/schemas/StreamEventAdvMessageEnd", - "tts_message": "#/components/schemas/StreamEventAdvTtsMessage", - "tts_message_end": "#/components/schemas/StreamEventAdvTtsMessageEnd", - "message_replace": "#/components/schemas/StreamEventAdvMessageReplace", - "workflow_started": "#/components/schemas/StreamEventAdvWorkflowStarted", - "node_started": "#/components/schemas/StreamEventAdvNodeStarted", - "node_finished": "#/components/schemas/StreamEventAdvNodeFinished", - "workflow_finished": "#/components/schemas/StreamEventAdvWorkflowFinished", - "error": "#/components/schemas/StreamEventAdvError", - "ping": "#/components/schemas/StreamEventAdvPing" - } - } - }, - "StreamEventBaseAdv": { - "type": "object", - "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "message_id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "StreamEventAdvChatMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string" } } } ] - }, - "StreamEventAdvMessageFile": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], + "type": "object", + "description": "Iteration loop completed.", "properties": { - "id": { "type": "string", "format": "uuid" }, - "type": { "type": "string", "description": "File type, e.g., 'image'." }, - "belongs_to": { "type": "string", "enum": ["assistant"] }, - "url": { "type": "string", "format": "url" }, - "conversation_id": { "type": "string", "format": "uuid" } + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Iteration execution ID." + }, + "node_id": { + "type": "string", + "description": "Iteration node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Iteration node title." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Iteration output data." + }, + "status": { + "type": "string", + "enum": [ + "running", + "succeeded", + "failed", + "exception" + ], + "description": "Iteration execution status." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if iteration failed." + }, + "elapsed_time": { + "type": "number", + "description": "Total iteration time in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed across all iterations." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Finish timestamp (Unix epoch seconds)." + }, + "steps": { + "type": "integer", + "description": "Total number of iteration steps executed." + } + } + } } } ] }, - "StreamEventAdvMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } } } ] - }, - "StreamEventAdvTtsMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 encoded audio." } } } - ] - }, - "StreamEventAdvTtsMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "Empty string." } } } - ] - }, - "StreamEventAdvMessageReplace": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "$ref": "#/components/schemas/StreamEventBaseAdv" }, - { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "Replacement content." } } } - ] - }, - "StreamEventAdvWorkflowStarted": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "workflow_run_id", "data"], + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Loop started.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/WorkflowStartedData" } + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Loop execution ID." + }, + "node_id": { + "type": "string", + "description": "Loop node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Loop node title." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Loop metadata." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Loop input data." + } + } + } } } ] }, - "WorkflowStartedData": { - "type": "object", "required": ["id", "workflow_id", "sequence_number", "created_at"], - "properties": { - "id": { "type": "string", "format": "uuid" }, - "workflow_id": { "type": "string", "format": "uuid" }, - "sequence_number": { "type": "integer" }, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "StreamEventAdvNodeStarted": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "workflow_run_id", "data"], + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Loop progressed to next iteration.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/NodeStartedData" } + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Loop execution ID." + }, + "node_id": { + "type": "string", + "description": "Loop node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Loop node title." + }, + "index": { + "type": "integer", + "description": "Current loop index (0-based)." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Timestamp (Unix epoch seconds)." + }, + "pre_loop_output": { + "description": "Output from the previous loop iteration." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + } + } + } } } ] }, - "NodeStartedData": { - "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], - "properties": { - "id": { "type": "string", "format": "uuid", "description": "Unique ID of this node execution instance." }, - "node_id": { "type": "string", "format": "uuid", "description": "ID of the node definition." }, - "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer" }, - "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true }, - "inputs": { "type": "object", "additionalProperties": true, "description": "Variables used by the node." }, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "StreamEventAdvNodeFinished": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "workflow_run_id", "data"], + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Loop completed.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/NodeFinishedData" } + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Loop execution ID." + }, + "node_id": { + "type": "string", + "description": "Loop node ID." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Loop node title." + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "Loop output data." + }, + "status": { + "type": "string", + "enum": [ + "running", + "succeeded", + "failed", + "exception" + ], + "description": "Loop execution status." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if loop failed." + }, + "elapsed_time": { + "type": "number", + "description": "Total loop execution time in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed across all loop iterations." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Start timestamp (Unix epoch seconds)." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Finish timestamp (Unix epoch seconds)." + }, + "steps": { + "type": "integer", + "description": "Total number of loop steps executed." + } + } + } } } ] }, - "NodeFinishedData": { - "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "status", "created_at"], - "properties": { - "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "format": "uuid" }, - "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer" }, - "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true }, - "inputs": { "type": "object", "additionalProperties": true, "nullable": true }, - "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Node process data (JSON)." }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output content (JSON)." }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, - "error": { "type": "string", "nullable": true }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true }, - "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadata" , "nullable": true}, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "NodeExecutionMetadata": { - "type": "object", - "properties": { - "total_tokens": { "type": "integer", "nullable": true }, - "total_price": { "type": "number", "format": "float", "nullable": true, "description": "Using float for price compatibility, MD says decimal." }, - "currency": { "type": "string", "nullable": true, "example": "USD" } - } - }, - "StreamEventAdvWorkflowFinished": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "workflow_run_id", "data"], + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Human input node is waiting for user input.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "Form ID for submitting the response." + }, + "node_id": { + "type": "string", + "description": "Node ID of the human input node." + }, + "node_title": { + "type": "string", + "description": "Title of the human input node." + }, + "form_content": { + "type": "string", + "description": "Form content/instructions for the user." + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Form input field definitions." + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Available user actions." + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "Token for form submission authentication." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp when the form expires." + } + } + } } } ] }, - "WorkflowFinishedData": { - "type": "object", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], - "properties": { - "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Output content (JSON)." }, - "error": { "type": "string", "nullable": true }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true }, - "total_tokens": { "type": "integer", "nullable": true }, - "total_steps": { "type": "integer", "default": 0 }, - "created_at": { "type": "integer", "format": "int64" }, - "finished_at": { "type": "integer", "format": "int64" } - } - }, - "StreamEventAdvError": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, - { "type": "object", "required": ["task_id", "status", "code", "message"], + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Agent log from an agent node within the workflow.", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "May not always be present in a generic error." }, - "status": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" } + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "Node execution ID." + }, + "id": { + "type": "string", + "description": "Log entry ID." + }, + "label": { + "type": "string", + "description": "Log entry label." + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "Parent log entry ID for nested entries." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if applicable." + }, + "status": { + "type": "string", + "description": "Log entry status." + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "Log entry data." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + } + } + } } } ] - }, - "StreamEventAdvPing": { - "allOf": [ { "$ref": "#/components/schemas/ChunkAdvancedChatEvent" }, { "type": "object" } ] - }, - "Usage": { - "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } - }, - "RetrieverResource": { - "type": "object", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } - }, - "FileUploadResponse": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "size": { "type": "integer" }, "extension": { "type": "string" }, "mime_type": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" } } - }, - "EndUserDetail": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } - } - }, - "MessageFeedbackRequest": { - "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "user": { "type": "string" }, "content": { "type": "string", "nullable": true } } - }, - "AppFeedbacksResponse": { - "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItem" } } } - }, - "FeedbackItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } - }, - "SuggestedQuestionsResponse": { - "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" } } } - }, - "ConversationHistoryResponse": { - "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessageItem" } } } - }, - "ConversationMessageItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "inputs": { "type": "object", "additionalProperties": true }, "query": { "type": "string" }, "answer": { "type": "string" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItem" } }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"] } } }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResource" } }, "created_at": { "type": "integer", "format": "int64" } } - }, - "MessageFileItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "url": { "type": "string", "format": "url" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"] } } - }, - "ConversationsListResponse": { - "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItem" } } } - }, - "ConversationListItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": true }, "status": { "type": "string" }, "introduction": { "type": "string", "nullable": true }, "created_at": { "type": "integer", "format": "int64" }, "updated_at": { "type": "integer", "format": "int64" } } - }, - "ConversationRenameRequest": { - "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true }, "auto_generate": { "type": "boolean", "default": false }, "user": { "type": "string" } } - }, - "ConversationRenameResponse": { "$ref": "#/components/schemas/ConversationListItem" }, - "ConversationVariablesResponse": { - "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItem" } } } - }, - "ConversationVariableItem": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "value_type": { "type": "string" }, "value": { "type": "string" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "integer", "format": "int64" }, "updated_at": { "type": "integer", "format": "int64" } } - }, - "AudioToTextRequest": { - "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file. Formats: mp3, mp4, mpeg, mpga, m4a, wav, webm. Limit: 15MB." }, "user": { "type": "string" } } - }, - "AudioToTextResponse": { "type": "object", "properties": { "text": { "type": "string" } } }, - "TextToAudioJsonRequest": { - "type": "object", "required": ["user"], - "properties": { - "message_id": { "type": "string", "format": "uuid", "description": "Message ID (priority)." }, - "text": { "type": "string", "description": "Speech content." }, - "user": { "type": "string" }, - "streaming": {"type": "boolean", "default": false, "description": "If true, response will be a stream of audio chunks."} - }, - "description": "Requires `user`. Provide `message_id` or `text`." - }, - "AppInfoResponse": { - "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } - }, - "ChatAppParametersResponse": { - "type": "object", "properties": { "opening_statement": { "type": "string" }, "suggested_questions": { "type": "array", "items": { "type": "string" } }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "voice": { "type": "string" }, "language": { "type": "string" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"] } } }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItem" } }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } } } } }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer" }, "image_file_size_limit": { "type": "integer" }, "audio_file_size_limit": { "type": "integer" }, "video_file_size_limit": { "type": "integer" } } } } - }, - "UserInputFormItem": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapper" }, { "$ref": "#/components/schemas/ParagraphControlWrapper" }, { "$ref": "#/components/schemas/SelectControlWrapper" } ] }, - "TextInputControlWrapper": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } }, "required":["text-input"] }, - "ParagraphControlWrapper": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } }, "required":["paragraph"] }, - "SelectControlWrapper": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } }, "required":["select"] }, - "TextInputControl": { "type": "object", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } }, - "ParagraphControl": { "type": "object", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } }, - "SelectControl": { "type": "object", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } } }, - "AppMetaResponse": { "type": "object", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url" }, { "$ref": "#/components/schemas/ToolIconDetail" } ] } } } }, - "ToolIconDetail": { "type": "object", "properties": { "background": { "type": "string" }, "content": { "type": "string" } } }, - "WebAppSettingsResponse": { "type": "object", "properties": { "title": { "type": "string" }, "chat_color_theme": { "type": "string" }, "chat_color_theme_inverted": { "type": "boolean" }, "icon_type": { "type": "string", "enum": ["emoji", "image"] }, "icon": { "type": "string" }, "icon_background": { "type": "string" }, "icon_url": { "type": "string", "format": "url", "nullable": true }, "description": { "type": "string" }, "copyright": { "type": "string" }, "privacy_policy": { "type": "string" }, "custom_disclaimer": { "type": "string" }, "default_language": { "type": "string" }, "show_workflow_steps": { "type": "boolean" }, "use_icon_as_answer_icon": { "type": "boolean" } } }, - "AnnotationListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItem" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } }, - "AnnotationItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "question": { "type": "string" }, "answer": { "type": "string" }, "hit_count": { "type": "integer" }, "created_at": { "type": "integer", "format": "int64" } } }, - "CreateAnnotationRequest": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } }, - "UpdateAnnotationRequest": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } }, - "InitialAnnotationReplySettingsRequest": { "type": "object", "required": ["score_threshold"], "properties": { "embedding_provider_name": { "type": "string", "nullable": true }, "embedding_model_name": { "type": "string", "nullable": true }, "score_threshold": { "type": "number", "format": "float" } } }, - "InitialAnnotationReplySettingsResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "job_status": { "type": "string" } } }, - "InitialAnnotationReplySettingsStatusResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "job_status": { "type": "string" }, "error_msg": { "type": "string", "nullable": true } } }, - "ErrorResponse": { "type": "object", "properties": { "status": { "type": "integer", "nullable": true }, "code": { "type": "string", "nullable": true }, "message": { "type": "string" } } } + } } }, "tags": [ - { "name": "Chatflow", "description": "Advanced chat operations with workflow events." }, - { "name": "Files", "description": "File upload and preview operations for advanced chat." }, - { "name": "End Users", "description": "Operations related to end user information." }, - { "name": "Feedback", "description": "User feedback operations for advanced chat." }, - { "name": "Conversations", "description": "Conversation management for advanced chat." }, - { "name": "TTS", "description": "Speech and Text conversion for advanced chat." }, - { "name": "Application", "description": "Application settings and info for advanced chat." }, - { "name": "Annotations", "description": "Annotation management for advanced chat." } + { + "name": "Chats", + "description": "Operations related to chat messages and interactions." + }, + { + "name": "Files", + "description": "File upload and preview operations." + }, + { + "name": "End Users", + "description": "Operations related to end user information." + }, + { + "name": "Feedback", + "description": "User feedback operations." + }, + { + "name": "Conversations", + "description": "Operations related to managing conversations." + }, + { + "name": "TTS", + "description": "Text-to-Speech and Speech-to-Text operations." + }, + { + "name": "Applications", + "description": "Operations to retrieve application settings and information." + }, + { + "name": "Annotations", + "description": "Operations related to managing annotations for direct replies." + } ] } diff --git a/en/api-reference/openapi_completion.json b/en/api-reference/openapi_completion.json index 3fcda7240..5af6289dc 100644 --- a/en/api-reference/openapi_completion.json +++ b/en/api-reference/openapi_completion.json @@ -8,7 +8,7 @@ "servers": [ { "url": "{api_base_url}", - "description": "The base URL for the Completion App API. Replace {api_base_url} with the actual API base URL provided for your application (e.g., from props.appDetail.api_base_url).", + "description": "The base URL for the Completion App API. Replace {api_base_url} with the actual API base URL provided for your application.", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", @@ -25,10 +25,12 @@ "paths": { "/completion-messages": { "post": { - "summary": "Create Completion Message", + "summary": "Send Completion Message", "description": "Send a request to the text generation application.", "operationId": "createCompletionMessage", - "tags": ["Completion"], + "tags": [ + "Completions" + ], "requestBody": { "description": "Request body to create a completion message.", "required": true, @@ -39,17 +41,30 @@ }, "examples": { "streaming_example": { - "summary": "Streaming mode example", + "summary": "Request Example - Streaming mode", "value": { - "inputs": {"query": "Hello, world!"}, + "inputs": { + "city": "San Francisco" + }, + "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", - "user": "abc-123" + "user": "abc-123", + "files": [ + { + "type": "image", + "transfer_method": "remote_url", + "url": "https://cloud.dify.ai/logo/logo-site.png" + } + ] } }, "blocking_example": { - "summary": "Blocking mode example", + "summary": "Request Example - Blocking mode", "value": { - "inputs": {"query": "Translate this to French: Hello"}, + "inputs": { + "city": "New York" + }, + "query": "Summarize the following text: ...", "response_mode": "blocking", "user": "def-456" } @@ -60,7 +75,7 @@ }, "responses": { "200": { - "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n- If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a `ChunkCompletionResponse` stream.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkCompletionEvent` objects.", "content": { "application/json": { "schema": { @@ -68,9 +83,11 @@ }, "examples": { "blockingResponse": { - "summary": "Example of a blocking mode response", + "summary": "Response Example - Blocking mode", "value": { "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "mode": "completion", "answer": "Hello World!...", @@ -98,177 +115,105 @@ "text/event-stream": { "schema": { "type": "string", - "description": "A stream of Server-Sent Events. Each event is a JSON object prefixed with 'data: ' and suffixed with '\\n\\n'. See `ChunkCompletionEvent` for possible event structures." + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkCompletionEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `message_end` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." }, "examples": { "streamingResponse": { - "summary": "Example of a streaming mode response", - "value": "data: {\"event\": \"message\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\ndata: {\"event\": \"tts_message\", \"task_id\": \"3bf8a0bb-e73b-4690-9e66-4e429bad8ee7\", \"message_id\": \"a8bdc41c-13b2-4c18-bfd9-054b9803038c\", \"created_at\": 1721205487, \"audio\": \"base64encodedaudio...\"}\n\ndata: {\"event\": \"tts_message_end\", \"task_id\": \"3bf8a0bb-e73b-4690-9e66-4e429bad8ee7\", \"message_id\": \"a8bdc41c-13b2-4c18-bfd9-054b9803038c\", \"created_at\": 1721205487, \"audio\": \"\"}\n\n" + "summary": "Response Example - Streaming mode", + "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n" } } } } }, "400": { - "description": "Bad Request. Possible error codes:\n- `invalid_param`: Abnormal parameter input.\n- `app_unavailable`: App configuration unavailable.\n- `provider_not_initialize`: No available model credential configuration.\n- `provider_quota_exceeded`: Model invocation quota insufficient.\n- `model_currently_not_support`: Current model unavailable.\n- `completion_request_error`: Text generation failed.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "404": { - "description": "Conversation does not exist.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "500": { - "description": "Internal server error.", + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Text generation failed.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - } - } - } - }, - "/files/upload": { - "post": { - "summary": "File Upload", - "description": "Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text. Supports png, jpg, jpeg, webp, gif formats. Uploaded files are for use by the current end-user only.", - "operationId": "uploadFile", - "tags": ["Files"], - "requestBody": { - "description": "File upload request. Requires multipart/form-data.", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "The file to be uploaded. Supported image types: png, jpg, jpeg, webp, gif." + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } }, - "user": { - "type": "string", - "description": "User identifier, defined by the developer's rules, must be unique within the application." + "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." + } } } } } - } - }, - "responses": { - "200": { - "description": "File uploaded successfully.", + }, + "429": { + "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponse" - }, "examples": { - "success": { + "too_many_requests": { + "summary": "too_many_requests", "value": { - "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67", - "name": "example.png", - "size": 1024, - "extension": "png", - "mime_type": "image/png", - "created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13", - "created_at": 1577836800 + "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" } } } } } }, - "400": { - "description": "Bad Request. Possible error codes:\n- `no_file_uploaded`: A file must be provided.\n- `too_many_files`: Currently only one file is accepted.\n- `unsupported_preview`: The file does not support preview.\n- `unsupported_estimate`: The file does not support estimation.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "413": { - "description": "`file_too_large`: The file is too large.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "415": { - "description": "`unsupported_file_type`: Unsupported extension. Currently only document files are accepted (Note: description says image types png, jpg, etc. are supported for this endpoint, but this error message refers to document files. Clarification might be needed from source documentation).", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "503": { - "description": "Service Unavailable. Possible error codes:\n- `s3_connection_failed`: Unable to connect to S3 service.\n- `s3_permission_denied`: No permission to upload files to S3.\n- `s3_file_too_large`: File exceeds S3 size limit.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, - "500": { - "description": "Internal server error.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "Get End User", - "description": "Retrieve an end user by ID.\n\nThis is useful when other APIs return an end-user ID (e.g. `created_by` from File Upload).", - "operationId": "getEndUserCompletion", - "tags": ["End Users"], - "parameters": [ - { - "name": "end_user_id", - "in": "path", - "required": true, - "description": "End user ID.", - "schema": { "type": "string", "format": "uuid" } - } - ], - "responses": { - "200": { - "description": "End user retrieved successfully.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetail" } - } - } - }, - "404": { - "description": "End user not found. Error code: `end_user_not_found`", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, "500": { - "description": "Internal server error.", + "description": "`internal_server_error` : Internal server error.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -277,16 +222,18 @@ }, "/completion-messages/{task_id}/stop": { "post": { - "summary": "Stop Generate", - "description": "Stops a generation task. Only supported in streaming mode.", - "operationId": "stopGenerate", - "tags": ["Completion"], + "summary": "Stop Completion Message Generation", + "description": "Stops a completion message generation task. Only supported in `streaming` mode.", + "operationId": "stopCompletionMessage", + "tags": [ + "Completions" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "Task ID, can be obtained from the streaming chunk return of a `/completion-messages` request.", + "description": "Task ID, can be obtained from the streaming chunk return of the [Send Completion Message](/api-reference/completions/send-completion-message) API.", "schema": { "type": "string" } @@ -298,16 +245,19 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { "user": { "type": "string", - "description": "User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface." + "description": "User identifier, must be consistent with the user passed in the send message interface." } } }, "examples": { - "example":{ + "example": { + "summary": "Request Example", "value": { "user": "abc-123" } @@ -318,22 +268,19 @@ }, "responses": { "200": { - "description": "Stop request successful.", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`app_unavailable` : App unavailable or misconfigured.", "content": { "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" - } - } - }, "examples": { - "success": { + "app_unavailable": { + "summary": "app_unavailable", "value": { - "result": "success" + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." } } } @@ -345,16 +292,18 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "summary": "Message Feedback", - "description": "End-users can provide feedback messages, facilitating application developers to optimize expected outputs.", - "operationId": "postMessageFeedback", - "tags": ["Feedback"], + "operationId": "createCompletionMessageFeedback", + "tags": [ + "Feedback" + ], + "summary": "Submit Message Feedback", + "description": "Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.", "parameters": [ { "name": "message_id", "in": "path", "required": true, - "description": "Message ID for which feedback is being provided.", + "description": "Message ID.", "schema": { "type": "string" } @@ -368,11 +317,12 @@ "$ref": "#/components/schemas/MessageFeedbackRequest" }, "examples": { - "like_example": { + "likeFeedback": { + "summary": "Request Example", "value": { "rating": "like", "user": "abc-123", - "content": "message feedback information" + "content": "This answer was very helpful!" } } } @@ -381,22 +331,19 @@ }, "responses": { "200": { - "description": "Feedback submitted successfully.", + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : Message does not exist.", "content": { "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" - } - } - }, "examples": { - "success": { + "message_not_exists": { + "summary": "not_found", "value": { - "result": "success" + "status": 404, + "code": "not_found", + "message": "Message Not Exists." } } } @@ -408,29 +355,34 @@ }, "/app/feedbacks": { "get": { - "summary": "Get feedbacks of application", - "description": "Get application's feedbacks.", - "operationId": "getAppFeedbacks", - "tags": ["Feedback"], + "operationId": "listCompletionFeedbacks", + "tags": [ + "Feedback" + ], + "summary": "List App Feedbacks", + "description": "Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.", "parameters": [ { "name": "page", "in": "query", - "description": "(optional) Pagination page number. Default: 1", + "description": "Page number for pagination.", "required": false, "schema": { - "type": "integer", - "default": 1 + "type": "integer", + "default": 1, + "minimum": 1 } }, { "name": "limit", "in": "query", - "description": "(optional) Records per page. Default: 20", + "description": "Number of records per page.", "required": false, "schema": { "type": "integer", - "default": 20 + "default": 20, + "minimum": 1, + "maximum": 101 } } ], @@ -443,21 +395,35 @@ "$ref": "#/components/schemas/AppFeedbacksResponse" }, "examples": { - "success": { + "feedbacksList": { + "summary": "Response Example", "value": { "data": [ { - "id": "8c0fbed8-e2f9-49ff-9f0e-15a35bdd0e25", - "app_id": "f252d396-fe48-450e-94ec-e184218e7346", - "conversation_id": "2397604b-9deb-430e-b285-4726e51fd62d", - "message_id": "709c0b0f-0a96-4a4e-91a4-ec0889937b11", + "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": "message feedback information-3", + "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-75673b6666g3", + "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": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_end_user_id": "d2c1b0a9-8765-4321-fedc-ba9876543210", "from_account_id": null, - "created_at": "2025-04-24T09:24:38", - "updated_at": "2025-04-24T09:24:38" + "created_at": "2025-01-15T09:12:45Z", + "updated_at": "2025-01-15T09:12:45Z" } ] } @@ -469,25 +435,33 @@ } } }, - "/text-to-audio": { + "/files/upload": { "post": { - "summary": "Text to Audio", - "description": "Convert text to speech.", - "operationId": "textToAudio", - "tags": ["TTS"], + "operationId": "uploadCompletionFile", + "tags": [ + "Files" + ], + "summary": "Upload File", + "description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", "requestBody": { + "description": "File upload request. Requires multipart/form-data.", "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/TextToAudioRequest" - }, - "examples": { - "example": { - "value": { - "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", - "text": "Hello Dify", - "user": "abc-123" + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "The file to be uploaded. Supported types include images, documents, audio, and video." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer's rules, must be unique within the application." } } } @@ -495,53 +469,98 @@ } }, "responses": { - "200": { - "description": "Audio file generated successfully.", + "201": { + "description": "File uploaded successfully.", "content": { - "audio/wav": { + "application/json": { "schema": { - "type": "string", - "format": "binary", - "description": "The generated audio file in WAV format." + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "Response Example", + "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" + } + } } } - }, - "headers": { - "Content-Type": { - "description": "The content type of the response, typically `audio/wav` or `audio/mp3` depending on server configuration.", - "schema": { - "type": "string", - "example": "audio/wav" + } + }, + "400": { + "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.", + "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." + } + } } } } - } - } - } - }, - "/info": { - "get": { - "summary": "Get Application Basic Information", - "description": "Used to get basic information about this application.", - "operationId": "getAppInfo", - "tags": ["Application"], - "responses": { - "200": { - "description": "Basic information of the application.", + }, + "413": { + "description": "`file_too_large` : File size exceeded.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/AppInfoResponse" - }, "examples": { - "success": { + "file_too_large": { + "summary": "file_too_large", "value": { - "name": "My App", - "description": "This is my app.", - "tags": [ - "tag1", - "tag2" - ] + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_file_type` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." } } } @@ -551,41 +570,553 @@ } } }, - "/parameters": { + "/files/{file_id}/preview": { "get": { - "summary": "Get Application Parameters Information", - "description": "Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values.", - "operationId": "getAppParameters", - "tags": ["Application"], + "operationId": "previewCompletionFile", + "tags": [ + "Files" + ], + "summary": "Download File", + "description": "Preview or download uploaded files previously uploaded via the [File Upload](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "The unique identifier of the file to preview, obtained from the [File Upload](/api-reference/files/upload-file) API response.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier, used for end-user context.", + "schema": { + "type": "string" + } + } + ], "responses": { "200": { - "description": "Application parameters information.", + "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "$ref": "#/components/schemas/AppParametersResponse" - }, - "examples": { - "success": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "description": "`file_access_denied` : Access to the requested file is 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` : The requested file was not found.", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "operationId": "getCompletionEndUser", + "tags": [ + "End Users" + ], + "summary": "Get End User", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "End user ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "End user retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "Response Example", + "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` : 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." + } + } + } + } + } + } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "completionAudioToText", + "tags": [ + "TTS" + ], + "summary": "Convert Audio to Text", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `15 MB`.", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully converted audio to text.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "Response Example", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", + "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` : Audio file size exceeded the limit.", + "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` : Audio type is not allowed.", + "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` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/text-to-audio": { + "post": { + "operationId": "completionTextToAudio", + "tags": [ + "TTS" + ], + "summary": "Convert Text to Audio", + "description": "Convert text to speech.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "Request Example", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", + "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." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : Audio file size exceeded.", + "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` : Audio type not allowed.", + "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` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/info": { + "get": { + "operationId": "getCompletionAppInfo", + "tags": [ + "Applications" + ], + "summary": "Get App Info", + "description": "Retrieve basic information about this application, including name, description, tags, and mode.", + "responses": { + "200": { + "description": "Basic information of the application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "Response Example", "value": { - "opening_statement": "Hello!", + "name": "My Completion App", + "description": "A helpful customer service chatbot.", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "completion", + "author_name": "Dify Team" + } + } + } + } + } + } + } + } + }, + "/parameters": { + "get": { + "operationId": "getCompletionAppParameters", + "tags": [ + "Applications" + ], + "summary": "Get App Parameters", + "description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.", + "responses": { + "200": { + "description": "Application parameters information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompletionAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "Response Example", + "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": true + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" }, "retriever_resource": { "enabled": true }, "annotation_reply": { - "enabled": true + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false }, "user_input_form": [ { - "paragraph": { - "label": "Query", - "variable": "query", + "text-input": { + "label": "City", + "variable": "city", "required": true, "default": "" } @@ -593,7 +1124,7 @@ ], "file_upload": { "image": { - "enabled": false, + "enabled": true, "number_limits": 3, "detail": "high", "transfer_methods": [ @@ -601,12 +1132,66 @@ "local_file" ] } - }, - "system_parameters": { - "file_size_limit": 15, - "image_file_size_limit": 10, - "audio_file_size_limit": 50, - "video_file_size_limit": 100 + }, + "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` : App unavailable or misconfigured.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getCompletionAppMeta", + "tags": [ + "Applications" + ], + "summary": "Get App Meta", + "description": "Retrieve metadata about this application, including tool icons and other configuration details.", + "responses": { + "200": { + "description": "Successfully retrieved application meta information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "Response Example", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } } } } @@ -619,10 +1204,12 @@ }, "/site": { "get": { - "summary": "Get Application WebApp Settings", - "description": "Used to get the WebApp settings of the application.", - "operationId": "getWebAppSettings", - "tags": ["Application"], + "operationId": "getCompletionWebAppSettings", + "tags": [ + "Applications" + ], + "summary": "Get App WebApp Settings", + "description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.", "responses": { "200": { "description": "WebApp settings of the application.", @@ -632,22 +1219,40 @@ "$ref": "#/components/schemas/WebAppSettingsResponse" }, "examples": { - "success": { + "webAppSettings": { + "summary": "Response Example", "value": { - "title": "My App", - "chat_color_theme": "#ff4a4a", + "title": "My Chat App", + "chat_color_theme": "#4A90D9", "chat_color_theme_inverted": false, "icon_type": "emoji", - "icon": "😄", - "icon_background": "#FFEAD5", + "icon": "🀖", + "icon_background": "#FFFFFF", "icon_url": null, - "description": "This is my app.", - "copyright": "all rights reserved", - "privacy_policy": "", - "custom_disclaimer": "All generated by AI", + "description": "A helpful customer service chatbot.", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", "default_language": "en-US", "show_workflow_steps": false, - "use_icon_as_answer_icon": false + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : Site not found for this application or the workspace has been archived.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." } } } @@ -664,117 +1269,180 @@ "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", - "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with 'Bearer '. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" + "description": "API Key authentication. For all API requests, include your API Key in the Authorization HTTP Header, prefixed with 'Bearer '. Example: Authorization: Bearer {API_KEY}. Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences." + } + }, + "responses": { + "SuccessResult": { + "description": "Operation successful.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Result status." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } } }, "schemas": { "CompletionRequest": { "type": "object", + "required": [ + "inputs", + "user" + ], "properties": { "inputs": { "type": "object", - "description": "Allows the entry of various variable values defined by the App. The `inputs` parameter contains multiple key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. The text generation application requires at least one key/value pair to be inputted.", - "required": ["query"], - "properties": { - "query": { - "type": "string", - "description": "The input text, the content to be processed." - } - }, - "additionalProperties": { - "type": "string" - }, - "example": {"query": "Translate 'hello' to Spanish."} + "description": "Allows the entry of various variable values defined by the App. Contains key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", + "additionalProperties": true + }, + "query": { + "type": "string", + "default": "", + "description": "The input text to be processed. This is a legacy parameter; in newer apps, the query should be passed inside the `inputs` object." }, "response_mode": { "type": "string", - "enum": ["streaming", "blocking"], - "description": "The mode of response return.\n- `streaming`: Streaming mode (recommended), implements a typewriter-like output through SSE ([Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)).\n- `blocking`: Blocking mode, returns result after execution is complete. (Requests may be interrupted if the process is long). *Due to Cloudflare restrictions, the request will be interrupted without a return after 100 seconds in blocking mode for long processes.*", - "example": "streaming" + "enum": [ + "streaming", + "blocking" + ], + "default": "blocking", + "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`." }, "user": { "type": "string", - "description": "User identifier, used to define the identity of the end-user for retrieval and statistics. Should be uniquely defined by the developer within the application.", - "example": "user-12345" + "description": "User identifier, unique within the application. This identifier scopes data access — messages and files are only visible when queried with the same `user` value." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObject" }, - "description": "File list, suitable for inputting files (images) combined with text understanding and answering questions, available only when the model supports Vision capability." + "description": "File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`." } - }, - "required": [ - "inputs" - ] + } }, "InputFileObject": { "type": "object", - "required": ["type", "transfer_method"], + "required": [ + "type", + "transfer_method" + ], "properties": { "type": { "type": "string", - "enum": ["image"], - "description": "Supported type: `image` (currently only supports image type)." + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "File type." }, "transfer_method": { "type": "string", - "enum": ["remote_url", "local_file"], - "description": "Transfer method, `remote_url` for image URL / `local_file` for file upload" + "enum": [ + "remote_url", + "local_file" + ], + "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file." }, "url": { "type": "string", "format": "url", - "description": "Image URL (when the transfer method is `remote_url`)" + "description": "File URL (when `transfer_method` is `remote_url`)." }, "upload_file_id": { "type": "string", - "description": "Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`)" + "description": "Uploaded file ID, obtained by uploading through the [File Upload](/api-reference/files/upload-file) API in advance (when `transfer_method` is `local_file`)." } }, "anyOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } + "properties": { + "transfer_method": { + "enum": [ + "remote_url" + ] + }, + "url": { + "type": "string", + "format": "url" + } }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "required": [ + "url" + ], + "not": { + "required": [ + "upload_file_id" + ] + } }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } + "properties": { + "transfer_method": { + "enum": [ + "local_file" + ] + }, + "upload_file_id": { + "type": "string" + } }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "required": [ + "upload_file_id" + ], + "not": { + "required": [ + "url" + ] + } } - ], - "example": { - "type": "image", - "transfer_method": "remote_url", - "url": "https://example.com/image.png" - } + ] }, "CompletionResponse": { "type": "object", - "description": "Response object for blocking mode completion.", "properties": { "event": { "type": "string", - "description": "Event type, for blocking mode this is typically 'message'.", - "example": "message" + "description": "Event type, fixed as `message`." + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID for request tracking and the [Stop Completion Message Generation](/api-reference/completions/stop-completion-message-generation) API." + }, + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of this response event." }, "message_id": { "type": "string", "format": "uuid", - "description": "Unique message ID." + "description": "Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints." }, "mode": { "type": "string", - "description": "App mode, fixed as `completion` for this response type (Note: MD also mentions 'chat', using 'completion' from example).", - "example": "completion" + "description": "App mode, fixed as `completion`." }, "answer": { "type": "string", @@ -782,70 +1450,87 @@ }, "metadata": { "type": "object", + "description": "Metadata including usage and retriever resources.", "properties": { "usage": { "$ref": "#/components/schemas/Usage" }, "retriever_resources": { "type": "array", + "description": "List of retriever resources used.", "items": { "$ref": "#/components/schemas/RetrieverResource" - }, - "description": "Citation and Attribution List." + } } } }, "created_at": { "type": "integer", "format": "int64", - "description": "Message creation timestamp (Unix epoch).", - "example": 1705395332 + "description": "Message creation timestamp (Unix epoch seconds)." } } }, "ChunkCompletionEvent": { "type": "object", - "description": "Structure of a Server-Sent Event chunk in streaming mode. The `event` field determines the structure of the rest of the object.", + "properties": { + "event": { + "type": "string", + "enum": [ + "message", + "message_end", + "message_file", + "tts_message", + "tts_message_end", + "message_replace", + "error", + "ping" + ], + "description": "The type of streaming event." + } + }, "discriminator": { "propertyName": "event", "mapping": { "message": "#/components/schemas/StreamEventMessage", "message_end": "#/components/schemas/StreamEventMessageEnd", + "message_file": "#/components/schemas/StreamEventMessageFile", "tts_message": "#/components/schemas/StreamEventTtsMessage", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", "message_replace": "#/components/schemas/StreamEventMessageReplace", "error": "#/components/schemas/StreamEventError", "ping": "#/components/schemas/StreamEventPing" } - }, + } + }, + "StreamEventBase": { + "type": "object", "properties": { - "event": { - "type": "string", - "enum": ["message", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], - "description": "The type of event." - }, "task_id": { "type": "string", "format": "uuid", - "description": "Task ID, used for request tracking and the Stop Generate API. Not present in 'ping' event." + "description": "Task ID." }, "message_id": { "type": "string", "format": "uuid", - "description": "Unique message ID. Not present in 'ping' event." + "description": "Unique message ID." }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation timestamp (Unix epoch). Not present in 'ping' event.", - "example": 1705395332 + "description": "Creation timestamp." } - }, - "required": ["event"] + } }, "StreamEventMessage": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "LLM returns text chunk event.", @@ -854,91 +1539,154 @@ "type": "string", "description": "LLM returned text chunk content." } - }, - "required": ["task_id", "message_id", "answer", "created_at"] + } } ] }, "StreamEventMessageEnd": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "Message end event, receiving this event means streaming has ended.", "properties": { "metadata": { "type": "object", + "description": "Metadata including usage and retriever resources.", "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, + "usage": { + "$ref": "#/components/schemas/Usage" + }, "retriever_resources": { "type": "array", - "items": { "$ref": "#/components/schemas/RetrieverResource" }, - "description": "Citation and Attribution List." + "description": "List of retriever resources used.", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } } } } - }, - "required": ["task_id", "message_id", "metadata"] + } } ] }, "StreamEventTtsMessage": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "description": "TTS audio stream event. The content is an audio block in Mp3 format, encoded as a base64 string. (This message is available only when auto-play is enabled)", + "description": "TTS audio stream event (base64 encoded MP3). Available if auto-play is enabled.", "properties": { "audio": { "type": "string", "format": "byte", - "description": "The audio after speech synthesis, encoded in base64 text content. When playing, simply decode the base64 and feed it into the player." + "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." } - }, - "required": ["task_id", "message_id", "audio", "created_at"] + } } ] }, - "StreamEventTtsMessageEnd": { + "StreamEventTtsMessageEnd": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", "description": "TTS audio stream end event.", "properties": { "audio": { "type": "string", - "description": "The end event has no audio, so this is an empty string." + "description": "Empty string. Signals the end of the audio stream." } - }, - "required": ["task_id", "message_id", "audio", "created_at"] + } + } + ] + }, + "StreamEventMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "Message file event, a new file created by a tool.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File unique ID." + }, + "type": { + "type": "string", + "description": "File type, e.g. `image`." + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "Who this file belongs to, always `assistant` here." + }, + "url": { + "type": "string", + "format": "url", + "description": "Remote URL of the file." + } + } } ] }, "StreamEventMessageReplace": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "description": "Message content replacement event. When output content moderation is enabled, if the content is flagged, then the message content will be replaced with a preset reply through this event.", + "description": "Message content replacement event (e.g., due to content moderation).", "properties": { "answer": { "type": "string", - "description": "Replacement content (directly replaces all LLM reply text)." + "description": "Replacement content." + }, + "reason": { + "type": "string", + "description": "Reason for the content replacement." } - }, - "required": ["task_id", "message_id", "answer", "created_at"] + } } ] }, "StreamEventError": { - "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, { "type": "object", - "description": "Exceptions that occur during the streaming process will be output in the form of stream events, and reception of an error event will end the stream.", + "description": "Error event during streaming.", "properties": { - "status": { + "status": { "type": "integer", "description": "HTTP status code." }, @@ -950,192 +1698,581 @@ "type": "string", "description": "Error message." } - }, - "required": ["task_id", "message_id", "status", "code", "message"] + } } ] }, "StreamEventPing": { "allOf": [ - { "$ref": "#/components/schemas/ChunkCompletionEvent" }, + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, { "type": "object", - "description": "Ping event every 10 seconds to keep the connection alive. This event type does not contain other fields like task_id or message_id." + "description": "Ping event to keep connection alive." } ] }, "Usage": { "type": "object", - "description": "Model usage information.", "properties": { - "prompt_tokens": { "type": "integer" }, - "prompt_unit_price": { "type": "string", "format": "decimal" }, - "prompt_price_unit": { "type": "string", "format": "decimal" }, - "prompt_price": { "type": "string", "format": "decimal" }, - "completion_tokens": { "type": "integer" }, - "completion_unit_price": { "type": "string", "format": "decimal" }, - "completion_price_unit": { "type": "string", "format": "decimal" }, - "completion_price": { "type": "string", "format": "decimal" }, - "total_tokens": { "type": "integer" }, - "total_price": { "type": "string", "format": "decimal" }, - "currency": { "type": "string", "example": "USD" }, - "latency": { "type": "number", "format": "double" } + "prompt_tokens": { + "type": "integer", + "description": "Number of tokens in the prompt." + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per prompt token." + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for prompt tokens." + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "Total price for prompt tokens." + }, + "completion_tokens": { + "type": "integer", + "description": "Number of tokens in the completion." + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "Unit price per completion token." + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "Price unit for completion tokens." + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "Total price for completion tokens." + }, + "total_tokens": { + "type": "integer", + "description": "Total number of tokens used." + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "Total price for all tokens." + }, + "currency": { + "type": "string", + "description": "Currency for pricing." + }, + "latency": { + "type": "number", + "format": "double", + "description": "Latency in seconds." + } } }, "RetrieverResource": { "type": "object", - "description": "Citation and Attribution information for a resource.", "properties": { - "document_id": { "type": "string", "description": "ID of the retrieved document." }, - "segment_id": { "type": "string", "description": "ID of the specific segment within the document." }, - "score": { "type": "number", "format": "float", "description": "Relevance score of the resource." }, - "content": { "type": "string", "description": "Content snippet from the resource." } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique ID of the retriever resource." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "ID of the message this resource belongs to." + }, + "position": { + "type": "integer", + "description": "Position of the resource in the list." + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "ID of the knowledge base." + }, + "dataset_name": { + "type": "string", + "description": "Name of the knowledge base." + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "ID of the document." + }, + "document_name": { + "type": "string", + "description": "Name of the document." + }, + "data_source_type": { + "type": "string", + "description": "Type of the data source." + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "ID of the specific chunk within the document." + }, + "score": { + "type": "number", + "format": "float", + "description": "Relevance score of the resource." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this chunk was hit." + }, + "word_count": { + "type": "integer", + "description": "Word count of the chunk." + }, + "segment_position": { + "type": "integer", + "description": "Position of the chunk within the document." + }, + "index_node_hash": { + "type": "string", + "description": "Hash of the index node." + }, + "content": { + "type": "string", + "description": "Content snippet from the resource." + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary of the chunk content." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp (Unix epoch seconds)." + } } }, "FileUploadResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "ID of the uploaded file." }, - "name": { "type": "string", "description": "File name." }, - "size": { "type": "integer", "description": "File size (bytes)." }, - "extension": { "type": "string", "description": "File extension." }, - "mime_type": { "type": "string", "description": "File mime-type." }, - "created_by": { "type": "string", "format": "uuid", "description": "End-user ID who uploaded the file." }, - "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp (Unix epoch).", "example": 1577836800 } + "id": { + "type": "string", + "format": "uuid", + "description": "Unique file ID." + }, + "name": { + "type": "string", + "description": "File name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "nullable": true, + "description": "File extension." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Upload timestamp (Unix epoch seconds)." + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "Preview URL for the file." + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "Source URL of the file." + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "Original URL of the file." + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated user." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated tenant." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated conversation." + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "Storage key for the file." + } } }, "EndUserDetail": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "Tenant ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Application ID." + }, + "type": { + "type": "string", + "description": "End user type. Always `service_api` for Service API users." + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/api-reference/chats/send-chat-message))." + }, + "name": { + "type": "string", + "nullable": true, + "description": "End user name." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request." + }, + "session_id": { + "type": "string", + "description": "Session identifier. Defaults to the `external_user_id` value." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } } }, "MessageFeedbackRequest": { "type": "object", + "description": "Request body for submitting message feedback.", + "required": [ + "user" + ], "properties": { "rating": { "type": "string", - "enum": ["like", "dislike", null], + "enum": [ + "like", + "dislike", + null + ], "nullable": true, - "description": "Upvote as `like`, downvote as `dislike`, revoke upvote/downvote as `null`." + "description": "Feedback rating. Set to `null` to revoke previously submitted feedback." }, "user": { "type": "string", - "description": "User identifier, defined by the developer's rules, must be unique within the application." + "description": "User identifier, defined by the developer, must ensure uniqueness within the application." }, "content": { "type": "string", - "description": "The specific content of message feedback." + "description": "Optional text feedback providing additional detail." } - }, - "required": ["user"] + } }, "AppFeedbacksResponse": { "type": "object", "properties": { "data": { "type": "array", + "description": "List of feedback items.", "items": { "$ref": "#/components/schemas/FeedbackItem" - }, - "description": "List of application feedback items." + } } } }, "FeedbackItem": { + "type": "object", + "description": "A single feedback item.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Feedback ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "Application ID." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "Conversation ID." + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID." + }, + "rating": { + "type": "string", + "description": "Feedback rating. `like` for positive, `dislike` for negative." + }, + "content": { + "type": "string", + "nullable": true, + "description": "Optional text feedback." + }, + "from_source": { + "type": "string", + "description": "Feedback source. `user` for end-user feedback submitted via API, `admin` for feedback submitted from the console." + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "End user ID who submitted the feedback. Present when `from_source` is `user`." + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Account ID who submitted the feedback. Present when `from_source` is `admin`." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "Request body for audio-to-text conversion.", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `15 MB`." + }, + "user": { + "type": "string", + "description": "User identifier." + } + } + }, + "AudioToTextResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid" }, - "conversation_id": { "type": "string", "format": "uuid" }, - "message_id": { "type": "string", "format": "uuid" }, - "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, - "content": { "type": "string" }, - "from_source": { "type": "string" }, - "from_end_user_id": { "type": "string", "format": "uuid" }, - "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "text": { + "type": "string", + "description": "Output text from speech recognition." + } } }, "TextToAudioRequest": { "type": "object", + "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", "properties": { "message_id": { "type": "string", "format": "uuid", - "description": "For text messages generated by Dify, simply pass the generated message-id directly. The backend will use the message-id to look up the corresponding content and synthesize the voice information directly. If both message_id and text are provided simultaneously, the message_id is given priority." + "description": "Message ID. Takes priority over `text` when both are provided." }, "text": { "type": "string", - "description": "Speech generated content. Used if message_id is not provided or not found." + "description": "Speech content to convert." }, "user": { "type": "string", - "description": "The user identifier, defined by the developer, must ensure uniqueness within the app." + "description": "User identifier." + }, + "voice": { + "type": "string", + "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." + }, + "streaming": { + "type": "boolean", + "description": "Whether to enable streaming response." } - }, - "required": ["user"], - "description": "At least one of `message_id` or `text` must be provided, along with `user`." + } }, "AppInfoResponse": { "type": "object", "properties": { - "name": { "type": "string", "description": "Application name." }, - "description": { "type": "string", "description": "Application description." }, + "name": { + "type": "string", + "description": "Application name." + }, + "description": { + "type": "string", + "description": "Application description." + }, "tags": { "type": "array", - "items": { "type": "string" }, + "items": { + "type": "string" + }, "description": "Application tags." + }, + "mode": { + "type": "string", + "description": "Application mode. `completion` for text generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for chatflow apps, `workflow` for workflow apps." + }, + "author_name": { + "type": "string", + "description": "Name of the application author." } } }, - "AppParametersResponse": { + "CompletionAppParametersResponse": { "type": "object", "properties": { - "opening_statement": { "type": "string", "description": "Opening statement." }, + "opening_statement": { + "type": "string", + "description": "Opening statement displayed at start." + }, "suggested_questions": { "type": "array", - "items": { "type": "string" }, - "description": "List of suggested questions for the opening." + "items": { + "type": "string" + }, + "description": "List of suggested starter questions." }, "suggested_questions_after_answer": { "type": "object", + "description": "Configuration for suggested questions after answer.", "properties": { - "enabled": { "type": "boolean", "description": "Whether suggesting questions after an answer is enabled." } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } } }, "speech_to_text": { "type": "object", + "description": "Speech-to-text configuration.", "properties": { - "enabled": { "type": "boolean", "description": "Whether speech to text is enabled." } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "text_to_speech": { + "type": "object", + "description": "Text-to-speech configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + }, + "voice": { + "type": "string", + "description": "Voice identifier for TTS." + }, + "language": { + "type": "string", + "description": "Language for TTS." + }, + "autoPlay": { + "type": "string", + "enum": [ + "enabled", + "disabled" + ], + "description": "Auto-play setting." + } } }, "retriever_resource": { "type": "object", + "description": "Retriever resource configuration.", "properties": { - "enabled": { "type": "boolean", "description": "Whether citation and attribution (retriever resource) is enabled." } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } } }, "annotation_reply": { "type": "object", + "description": "Annotation reply configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "more_like_this": { + "type": "object", + "description": "More-like-this configuration.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "Sensitive word avoidance configuration.", "properties": { - "enabled": { "type": "boolean", "description": "Whether annotation reply is enabled." } + "enabled": { + "type": "boolean", + "description": "Whether this feature is enabled." + } } }, "user_input_form": { "type": "array", - "items": { "$ref": "#/components/schemas/UserInputFormItem" }, - "description": "User input form configuration." + "description": "List of user input form elements.", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } }, "file_upload": { "type": "object", @@ -1143,15 +2280,30 @@ "properties": { "image": { "type": "object", - "description": "Image settings. Currently only supports image types: png, jpg, jpeg, webp, gif.", + "description": "Image upload settings.", "properties": { - "enabled": { "type": "boolean", "description": "Whether image upload is enabled." }, - "number_limits": { "type": "integer", "description": "Image number limit, default is 3." }, - "detail": {"type": "string", "description": "Detail level for image processing (e.g., 'high'). From example, not in main description."}, + "enabled": { + "type": "boolean", + "description": "Whether image upload is enabled." + }, + "number_limits": { + "type": "integer", + "description": "Maximum number of images." + }, + "detail": { + "type": "string", + "description": "Image detail level." + }, "transfer_methods": { "type": "array", - "items": { "type": "string", "enum": ["remote_url", "local_file"] }, - "description": "List of transfer methods, must choose at least one if enabled." + "items": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ] + }, + "description": "Allowed transfer methods." } } } @@ -1159,119 +2311,269 @@ }, "system_parameters": { "type": "object", - "description": "System parameters.", + "description": "System-level parameters and limits.", "properties": { - "file_size_limit": { "type": "integer", "description": "Document upload size limit (MB)." }, - "image_file_size_limit": { "type": "integer", "description": "Image file upload size limit (MB)." }, - "audio_file_size_limit": { "type": "integer", "description": "Audio file upload size limit (MB)." }, - "video_file_size_limit": { "type": "integer", "description": "Video file upload size limit (MB)." } + "file_size_limit": { + "type": "integer", + "description": "Maximum file size in MB." + }, + "image_file_size_limit": { + "type": "integer", + "description": "Maximum image file size in MB." + }, + "audio_file_size_limit": { + "type": "integer", + "description": "Maximum audio file size in MB." + }, + "video_file_size_limit": { + "type": "integer", + "description": "Maximum video file size in MB." + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "Maximum number of files for workflow file upload." + } } } } }, "UserInputFormItem": { "type": "object", - "description": "Represents a single item in the user input form. It will have one of the specific control type keys.", "oneOf": [ - { "$ref": "#/components/schemas/TextInputControlWrapper" }, - { "$ref": "#/components/schemas/ParagraphControlWrapper" }, - { "$ref": "#/components/schemas/SelectControlWrapper" } + { + "$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" } - }, - "required": ["text-input"] + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } }, "ParagraphControlWrapper": { + "title": "Paragraph", "type": "object", "properties": { - "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } - }, - "required": ["paragraph"] + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } }, "SelectControlWrapper": { + "title": "Select", "type": "object", "properties": { - "select": { "$ref": "#/components/schemas/SelectControl" } - }, - "required": ["select"] + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } }, "TextInputControl": { "type": "object", - "description": "Text input control.", "properties": { - "label": { "type": "string", "description": "Variable display label name." }, - "variable": { "type": "string", "description": "Variable ID." }, - "required": { "type": "boolean", "description": "Whether it is required." }, - "default": { "type": "string", "description": "Default value." } - }, - "required": ["label", "variable", "required"] + "label": { + "type": "string", + "description": "Display label for the form field." + }, + "variable": { + "type": "string", + "description": "Variable name used as the key in the `inputs` object." + }, + "required": { + "type": "boolean", + "description": "Whether this field must be filled before submission." + }, + "default": { + "type": "string", + "description": "Default value pre-filled in the form field." + } + } }, "ParagraphControl": { "type": "object", - "description": "Paragraph text input control.", "properties": { - "label": { "type": "string", "description": "Variable display label name." }, - "variable": { "type": "string", "description": "Variable ID." }, - "required": { "type": "boolean", "description": "Whether it is required." }, - "default": { "type": "string", "description": "Default value." } - }, - "required": ["label", "variable", "required"] + "label": { + "type": "string", + "description": "Display label for the form field." + }, + "variable": { + "type": "string", + "description": "Variable name used as the key in the `inputs` object." + }, + "required": { + "type": "boolean", + "description": "Whether this field must be filled before submission." + }, + "default": { + "type": "string", + "description": "Default value pre-filled in the form field." + } + } }, "SelectControl": { "type": "object", - "description": "Dropdown control.", "properties": { - "label": { "type": "string", "description": "Variable display label name." }, - "variable": { "type": "string", "description": "Variable ID." }, - "required": { "type": "boolean", "description": "Whether it is required." }, - "default": { "type": "string", "description": "Default value." }, + "label": { + "type": "string", + "description": "Display label for the form field." + }, + "variable": { + "type": "string", + "description": "Variable name used as the key in the `inputs` object." + }, + "required": { + "type": "boolean", + "description": "Whether a selection must be made before submission." + }, + "default": { + "type": "string", + "description": "Default selected value." + }, "options": { "type": "array", - "items": { "type": "string" }, - "description": "Option values." + "items": { + "type": "string" + }, + "description": "List of selectable values for this form control." } - }, - "required": ["label", "variable", "required", "options"] + } }, - "WebAppSettingsResponse": { + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "URL of the icon." + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "Tool icons. Keys are tool names." + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", "type": "object", + "description": "Detail of a tool icon using emoji.", "properties": { - "title": { "type": "string", "description": "WebApp name." }, - "chat_color_theme": { "type": "string", "description": "Chat color theme, in hex format (e.g., #RRGGBB)." }, - "chat_color_theme_inverted": { "type": "boolean", "description": "Whether the chat color theme is inverted." }, - "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "Icon type." }, - "icon": { "type": "string", "description": "Icon. If it's `emoji` type, it's an emoji symbol; if it's `image` type, it's an image URL." }, - "icon_background": { "type": "string", "description": "Background color in hex format (e.g., #RRGGBB)." }, - "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "Icon URL (likely refers to image type if `icon` field is just a name/id)." }, - "description": { "type": "string", "description": "Description." }, - "copyright": { "type": "string", "description": "Copyright information." }, - "privacy_policy": { "type": "string", "description": "Privacy policy link." }, - "custom_disclaimer": { "type": "string", "description": "Custom disclaimer." }, - "default_language": { "type": "string", "description": "Default language (e.g., en-US)." }, - "show_workflow_steps": { "type": "boolean", "description": "Whether to show workflow details." }, - "use_icon_as_answer_icon": { "type": "boolean", "description": "Whether to replace 🀖 in chat with the WebApp icon." } + "background": { + "type": "string", + "description": "Background color in hex format." + }, + "content": { + "type": "string", + "description": "Emoji content." + } } }, - "ErrorResponse": { + "WebAppSettingsResponse": { "type": "object", "properties": { - "status": { "type": "integer", "description": "HTTP status code." }, - "code": { "type": "string", "description": "Error code specific to the application." }, - "message": { "type": "string", "description": "A human-readable error message." } + "title": { + "type": "string", + "description": "WebApp title." + }, + "chat_color_theme": { + "type": "string", + "description": "Chat color theme." + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "Whether the chat color theme is inverted." + }, + "icon_type": { + "type": "string", + "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." + }, + "icon": { + "type": "string", + "description": "Icon content (emoji or image ID)." + }, + "icon_background": { + "type": "string", + "description": "Icon background color." + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "URL of the icon image." + }, + "description": { + "type": "string", + "description": "WebApp description." + }, + "copyright": { + "type": "string", + "description": "Copyright text." + }, + "privacy_policy": { + "type": "string", + "description": "Privacy policy URL." + }, + "custom_disclaimer": { + "type": "string", + "description": "Custom disclaimer text." + }, + "default_language": { + "type": "string", + "description": "Default language code." + }, + "show_workflow_steps": { + "type": "boolean", + "description": "Whether to show workflow steps." + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "Whether to use the app icon as the answer icon." + } } } } }, "tags": [ - { "name": "Completion", "description": "Operations related to text generation and completion." }, - { "name": "Files", "description": "Operations related to file management." }, - { "name": "End Users", "description": "Operations related to end user information." }, - { "name": "Feedback", "description": "Operations related to user feedback." }, - { "name": "TTS", "description": "Operations related to Text-to-Speech." }, - { "name": "Application", "description": "Operations to retrieve application settings and information." } + { + "name": "Completions", + "description": "Operations related to text generation and completion." + }, + { + "name": "Files", + "description": "Operations related to file management." + }, + { + "name": "End Users", + "description": "Operations related to end user information." + }, + { + "name": "Feedback", + "description": "Operations related to user feedback." + }, + { + "name": "TTS", + "description": "Operations related to Text-to-Speech and Speech-to-Text." + }, + { + "name": "Applications", + "description": "Operations to retrieve application settings and information." + } ] } diff --git a/en/api-reference/openapi_knowledge.json b/en/api-reference/openapi_knowledge.json index f17376516..c767d23ce 100644 --- a/en/api-reference/openapi_knowledge.json +++ b/en/api-reference/openapi_knowledge.json @@ -2,7 +2,7 @@ "openapi": "3.0.1", "info": { "title": "Knowledge API", - "description": "API for managing knowledge bases (datasets), documents, and segments, including creation, retrieval, and configuration.", + "description": "API for managing knowledge bases, documents, chunks, metadata, and tags, including creation, retrieval, and configuration. **Note:** A single Knowledge Base API key has permission to operate on all visible knowledge bases under the same account. Please pay attention to data security.", "version": "1.0.0" }, "servers": [ @@ -24,127 +24,376 @@ ], "tags": [ { - "name": "Datasets", - "description": "Operations related to managing knowledge bases (datasets)." + "name": "Knowledge Bases", + "description": "Operations for managing knowledge bases, including creation, configuration, and retrieval." }, { "name": "Documents", - "description": "Operations for creating, updating, and managing documents within a dataset." + "description": "Operations for creating, updating, and managing documents within a knowledge base." }, { "name": "Chunks", - "description": "Operations for managing document chunks (segments)." + "description": "Operations for managing document chunks and child chunks." }, { - "name": "Metadata & Tags", - "description": "Operations for managing dataset tags and metadata." + "name": "Metadata", + "description": "Operations for managing knowledge base metadata fields and document metadata values." + }, + { + "name": "Tags", + "description": "Operations for managing knowledge base tags and tag bindings." }, { "name": "Models", "description": "Operations for retrieving available models." + }, + { + "name": "Knowledge Pipeline", + "description": "Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution." } ], "paths": { "/datasets": { "post": { "tags": [ - "Datasets" + "Knowledge Bases" ], "summary": "Create an Empty Knowledge Base", - "description": "Creates a new, empty knowledge base (dataset) with specified configurations.", - "operationId": "createDataset", + "description": "Create a new empty knowledge base. After creation, use [Create Document by Text](/api-reference/documents/create-document-by-text) or [Create Document by File](/api-reference/documents/create-document-by-file) to add documents.", + "operationId": "createKnowledgeBase", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateDatasetRequest" + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "Name of the knowledge base." + }, + "description": { + "type": "string", + "maxLength": 400, + "default": "", + "description": "Description of the knowledge base." + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "default": "only_me", + "description": "Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members." + }, + "provider": { + "type": "string", + "enum": [ + "vendor", + "external" + ], + "default": "vendor", + "description": "`vendor` for internal knowledge base, `external` for external knowledge base." + }, + "embedding_model": { + "type": "string", + "description": "Embedding model name. Use the `model` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "embedding_model_provider": { + "type": "string", + "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + }, + "external_knowledge_api_id": { + "type": "string", + "description": "ID of the external knowledge API connection." + }, + "external_knowledge_id": { + "type": "string", + "description": "ID of the external knowledge base." + }, + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "Summary index configuration.", + "properties": { + "enable": { + "type": "boolean", + "description": "Whether to enable summary indexing." + }, + "model_name": { + "type": "string", + "description": "Name of the model used for generating summaries." + }, + "model_provider_name": { + "type": "string", + "description": "Provider of the summary generation model." + }, + "summary_prompt": { + "type": "string", + "description": "Custom prompt template for summary generation." + } + } + } + } } } } }, "responses": { "200": { - "description": "Successfully created dataset.", + "description": "Knowledge base created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "Technical documentation for the product API", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "description": "- `dataset_name_duplicate` : The dataset name already exists. Please modify your dataset name.", + "content": { + "application/json": { + "examples": { + "dataset_name_duplicate": { + "summary": "dataset_name_duplicate", + "value": { + "status": 409, + "code": "dataset_name_duplicate", + "message": "The dataset name already exists. Please modify your dataset name." + } + } + } + } + } } } }, "get": { "tags": [ - "Datasets" + "Knowledge Bases" ], - "summary": "Get Knowledge Base List", - "description": "Retrieves a list of knowledge bases, with options for pagination and filtering.", - "operationId": "listDatasets", + "summary": "List Knowledge Bases", + "description": "Returns a paginated list of knowledge bases. Supports filtering by keyword and tags.", + "operationId": "listKnowledgeBases", "parameters": [ { - "name": "keyword", - "in": "query", - "description": "Search keyword to filter datasets by name.", - "schema": { - "type": "string" - } - }, - { - "name": "tag_ids", + "name": "page", "in": "query", - "description": "List of tag IDs to filter by. Datasets must have all specified tags.", "schema": { - "type": "array", - "items": { - "type": "string" - } + "type": "integer", + "default": 1 }, - "style": "form", - "explode": false + "description": "Page number." }, { - "name": "page", + "name": "limit", "in": "query", - "description": "Page number for pagination.", "schema": { "type": "integer", - "default": 1 - } + "default": 20 + }, + "description": "Number of items per page." }, { - "name": "limit", + "name": "keyword", "in": "query", - "description": "Number of items to return per page.", "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } + "type": "string" + }, + "description": "Search keyword to filter by name." }, { "name": "include_all", "in": "query", - "description": "Whether to include all datasets. This is effective only for workspace owners.", "schema": { "type": "boolean", "default": false - } + }, + "description": "Whether to include all knowledge bases regardless of permissions." + }, + { + "name": "tag_ids", + "in": "query", + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "Tag IDs to filter by." } ], "responses": { "200": { - "description": "A paginated list of datasets.", + "description": "List of knowledge bases.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "Array of knowledge base objects.", + "items": { + "$ref": "#/components/schemas/Dataset" + } + }, + "has_more": { + "type": "boolean", + "description": "Whether more items exist on the next page." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of matching items." + }, + "page": { + "type": "integer", + "description": "Current page number." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "Technical documentation for the product API", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } } } } @@ -155,30 +404,118 @@ "/datasets/{dataset_id}": { "get": { "tags": [ - "Datasets" + "Knowledge Bases" ], - "summary": "Get Knowledge Base Details", - "description": "Fetches the detailed information of a specific knowledge base by its ID.", - "operationId": "getDatasetDetail", + "summary": "Get Knowledge Base", + "description": "Retrieve detailed information about a specific knowledge base, including its embedding model, retrieval configuration, and document statistics.", + "operationId": "getKnowledgeBase", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The unique identifier of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "responses": { "200": { - "description": "Detailed information about the dataset.", + "description": "Knowledge base details.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "Technical documentation for the product API", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } + } + } + } + }, + "403": { + "description": "- `forbidden` : Insufficient permissions to access this knowledge base.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } } } } @@ -187,21 +524,21 @@ }, "patch": { "tags": [ - "Datasets" + "Knowledge Bases" ], "summary": "Update Knowledge Base", - "description": "Updates the settings of a specific knowledge base.", - "operationId": "updateDataset", + "description": "Update the name, description, permissions, or retrieval settings of an existing knowledge base. Only the fields provided in the request body are updated.", + "operationId": "updateKnowledgeBase", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The unique identifier of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "requestBody": { @@ -209,90 +546,247 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateDatasetRequest" + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "Name of the knowledge base." + }, + "description": { + "type": "string", + "maxLength": 400, + "description": "Description of the knowledge base." + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "description": "Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members." + }, + "embedding_model": { + "type": "string", + "description": "Embedding model name. Use the `model` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "embedding_model_provider": { + "type": "string", + "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + }, + "partial_member_list": { + "type": "array", + "description": "List of team members with access when `permission` is `partial_members`.", + "items": { + "type": "object", + "properties": { + "user_id": { + "type": "string", + "description": "ID of the team member to grant access." + } + } + } + }, + "external_retrieval_model": { + "type": "object", + "description": "Retrieval settings for external knowledge bases.", + "properties": { + "top_k": { + "type": "integer", + "description": "Maximum number of results to return." + }, + "score_threshold": { + "type": "number", + "description": "Minimum relevance score threshold for filtering results." + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + } + } + }, + "external_knowledge_id": { + "type": "string", + "description": "ID of the external knowledge base." + }, + "external_knowledge_api_id": { + "type": "string", + "description": "ID of the external knowledge API connection." + } + } } } } }, "responses": { "200": { - "description": "Successfully updated dataset details.", + "description": "Knowledge base updated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "Technical documentation for the product API", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, - "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "403": { + "description": "- `forbidden` : Insufficient permissions to access this knowledge base.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } }, "delete": { "tags": [ - "Datasets" + "Knowledge Bases" ], - "summary": "Delete a Knowledge Base", - "description": "Deletes a knowledge base and all its associated documents and data.", - "operationId": "deleteDataset", + "summary": "Delete Knowledge Base", + "description": "Permanently delete a knowledge base and all its documents. The knowledge base must not be in use by any application.", + "operationId": "deleteKnowledgeBase", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The unique identifier of the knowledge base to delete.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "responses": { "204": { - "description": "Successfully deleted the dataset." - } - } - } - }, - "/datasets/{dataset_id}/document/create-by-text": { - "post": { - "tags": [ - "Documents" - ], - "summary": "Create a Document from Text", - "description": "Creates a new document within an existing knowledge base directly from text content.", - "operationId": "createDocumentFromText", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "The ID of the knowledge base to add the document to.", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateDocumentByTextRequest" + "description": "Success." + }, + "404": { + "description": "- `not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } } } - } - }, - "responses": { - "200": { - "description": "Document created successfully and is being indexed.", + }, + "409": { + "description": "- `dataset_in_use` : The knowledge base is being used by some apps. Please remove it from the apps before deleting.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "examples": { + "dataset_in_use": { + "summary": "dataset_in_use", + "value": { + "status": 409, + "code": "dataset_in_use", + "message": "The dataset is being used by some apps. Please remove the dataset from the apps before deleting it." + } + } } } } @@ -300,118 +794,243 @@ } } }, - "/datasets/{dataset_id}/document/create-by-file": { + "/datasets/{dataset_id}/document/create-by-text": { "post": { "tags": [ "Documents" ], - "summary": "Create a Document from a File", - "description": "Creates a new document within an existing knowledge base by uploading a file.", - "operationId": "createDocumentFromFile", + "summary": "Create Document by Text", + "description": "Create a document from raw text content. The document is processed asynchronously — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", + "operationId": "createDocumentByText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base to add the document to.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "requestBody": { "required": true, "content": { - "multipart/form-data": { + "application/json": { "schema": { "type": "object", + "required": [ + "name", + "text" + ], "properties": { - "data": { + "name": { "type": "string", - "description": "A JSON string containing document metadata and processing rules. See `CreateDocumentByFileRequestData` schema for details.", - "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\": {\"separator\":\"###\", \"max_tokens\":500}}},\"summary_index_setting\":{\"enable\":true,\"model_name\":\"qwen-vl-plus\",\"model_provider_name\":\"langgenius/tongyi/tongyi\",\"summary_prompt\":\"summarize the text\"}}" + "description": "Document name." }, - "file": { + "text": { "type": "string", - "format": "binary", - "description": "The file to upload." - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Document created successfully and is being indexed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "description": "Document text content." + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "description": "Required when adding the first document to a knowledge base. Subsequent documents inherit the knowledge base's indexing technique if omitted. `high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction." + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "Language of the document for processing optimization." + }, + "process_rule": { + "type": "object", + "description": "Processing rules for chunking.", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "Processing mode. `automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`)." + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": ["remove_stopwords", "remove_extra_spaces", "remove_urls_emails"], + "description": "Rule identifier." + }, + "enabled": { + "type": "boolean", + "description": "Whether this preprocessing rule is enabled." + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "Custom separator for splitting text." + }, + "max_tokens": { + "type": "integer", + "description": "Maximum token count per chunk." + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "Token overlap between chunks." + } + } + } + } + } + } + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + }, + "embedding_model": { + "type": "string", + "description": "Embedding model name. Use the `model` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "embedding_model_provider": { + "type": "string", + "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." + }, + "original_document_id": { + "type": "string", + "description": "Original document ID for versioning." + } } } } - }, - "400": { - "$ref": "#/components/responses/FileError" - }, - "413": { - "$ref": "#/components/responses/FileTooLarge" - }, - "415": { - "$ref": "#/components/responses/UnsupportedFileType" - } - } - } - }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { - "post": { - "tags": [ - "Documents" - ], - "summary": "Update a Document with Text", - "description": "Updates an existing document's content or settings using text.", - "operationId": "updateDocumentByText", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "The ID of the knowledge base containing the document.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "The ID of the document to update.", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateDocumentByTextRequest" - } - } } }, "responses": { "200": { - "description": "Document updated successfully.", + "description": "Document created successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "Batch ID for tracking indexing progress." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist. / indexing_technique is required.", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + } } } } @@ -419,34 +1038,24 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { + "/datasets/{dataset_id}/document/create-by-file": { "post": { "tags": [ "Documents" ], - "summary": "Update a Document with a File", - "description": "Updates an existing document by uploading a new file, replacing its content.", - "operationId": "updateDocumentByFile", + "summary": "Create Document by File", + "description": "Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", + "operationId": "createDocumentByFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base containing the document.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "The ID of the document to update.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "requestBody": { @@ -455,16 +1064,19 @@ "multipart/form-data": { "schema": { "type": "object", + "required": [ + "file" + ], "properties": { - "data": { - "type": "string", - "description": "A JSON string containing optional document name and processing rules. See `UpdateDocumentByFileRequestData` schema.", - "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" - }, "file": { "type": "string", "format": "binary", - "description": "The new file to upload." + "description": "File to upload." + }, + "data": { + "type": "string", + "description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/api-reference/documents/create-document-by-text) (`indexing_technique`, `doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } @@ -473,11 +1085,173 @@ }, "responses": { "200": { - "description": "Document updated successfully.", + "description": "Document created successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "Batch ID for tracking indexing progress." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : Please upload your file.\n- `too_many_files` : Only one file is allowed.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist.", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param (indexing_technique)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + }, + "invalid_param_process_rule": { + "summary": "invalid_param (process_rule)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "process_rule is required." + } + } + } + } + } + }, + "413": { + "description": "- `file_too_large` : File size exceeded.", + "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` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } } } } @@ -485,38 +1259,64 @@ } } }, - "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "/datasets/{dataset_id}/documents": { "get": { "tags": [ "Documents" ], - "summary": "Get Document Embedding Status (Progress)", - "description": "Retrieves the indexing status for a batch of documents, showing the progress of embedding and processing.", - "operationId": "getDocumentIndexingStatus", + "summary": "List Documents", + "description": "Returns a paginated list of documents in the knowledge base. Supports filtering by keyword and indexing status.", + "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { - "name": "batch", - "in": "path", - "required": true, - "description": "The batch number returned from the document creation endpoint.", + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "description": "Page number." + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "Number of items per page." + }, + { + "name": "keyword", + "in": "query", "schema": { "type": "string" - } + }, + "description": "Search keyword to filter by document name." + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "string", + "enum": ["queuing", "indexing", "paused", "error", "available", "disabled", "archived"] + }, + "description": "Filter by display status." } ], "responses": { "200": { - "description": "Indexing status of the documents in the batch.", + "description": "List of documents.", "content": { "application/json": { "schema": { @@ -524,9 +1324,94 @@ "properties": { "data": { "type": "array", + "description": "Array of knowledge base objects.", "items": { - "$ref": "#/components/schemas/IndexingStatus" + "$ref": "#/components/schemas/Document" } + }, + "has_more": { + "type": "boolean", + "description": "Whether more items exist on the next page." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of matching items." + }, + "page": { + "type": "integer", + "description": "Current page number." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Knowledge base not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." } } } @@ -541,34 +1426,33 @@ "tags": [ "Documents" ], - "summary": "Get Document Detail", - "description": "Retrieves detailed information about a single document, including its processing rules and status.", - "operationId": "getDocumentDetail", + "summary": "Get Document", + "description": "Retrieve detailed information about a specific document, including its indexing status, metadata, and processing statistics.", + "operationId": "getDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "metadata", "in": "query", - "description": "Metadata filter: `all` returns all metadata, `only` returns only custom metadata, `without` returns no metadata.", "schema": { "type": "string", "enum": [ @@ -577,311 +1461,607 @@ "without" ], "default": "all" - } + }, + "description": "`all` returns all fields including metadata. `only` returns only `id`, `doc_type`, and `doc_metadata`. `without` returns all fields except `doc_metadata`." } ], "responses": { "200": { - "description": "Detailed information about the document.", + "description": "Document details. The response shape varies based on the `metadata` query parameter. When `metadata` is `only`, only `id`, `doc_type`, and `doc_metadata` are returned. When `metadata` is `without`, `doc_type` and `doc_metadata` are omitted.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentDetail" - } - } - } - } - } - }, - "delete": { - "tags": [ - "Documents" - ], - "summary": "Delete a Document", - "description": "Deletes a specific document from a knowledge base.", - "operationId": "deleteDocument", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "The ID of the knowledge base.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "The ID of the document to delete.", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "responses": { - "204": { - "description": "Successfully deleted the document." - } - } - } - }, - "/datasets/{dataset_id}/documents": { - "get": { - "tags": [ - "Documents" - ], - "summary": "Get the Document List of a Knowledge Base", - "description": "Retrieves a paginated list of all documents within a specified knowledge base.", - "operationId": "listDocuments", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "The ID of the knowledge base.", - "schema": { - "type": "string", - "format": "uuid" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Document identifier." + }, + "position": { + "type": "integer", + "description": "Position index within the knowledge base." + }, + "data_source_type": { + "type": "string", + "description": "How the document was uploaded. `upload_file` for file uploads, `notion_import` for Notion imports." + }, + "data_source_info": { + "type": "object", + "description": "Raw data source information." + }, + "dataset_process_rule_id": { + "type": "string", + "description": "ID of the processing rule applied to this document." + }, + "dataset_process_rule": { + "type": "object", + "description": "Knowledge-base-level processing rule configuration." + }, + "document_process_rule": { + "type": "object", + "description": "Document-level processing rule configuration." + }, + "name": { + "type": "string", + "description": "Document name." + }, + "created_from": { + "type": "string", + "description": "Origin of the document. `api` for API creation, `web` for UI creation." + }, + "created_by": { + "type": "string", + "description": "ID of the user who created the document." + }, + "created_at": { + "type": "number", + "description": "Unix timestamp of document creation." + }, + "tokens": { + "type": "integer", + "description": "Number of tokens in the document." + }, + "indexing_status": { + "type": "string", + "description": "Current indexing status, e.g. `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, `error`, `paused`." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if indexing failed, `null` otherwise." + }, + "enabled": { + "type": "boolean", + "description": "Whether the document is enabled for retrieval." + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "Unix timestamp when the document was disabled, `null` if enabled." + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "ID of the user who disabled the document, `null` if enabled." + }, + "archived": { + "type": "boolean", + "description": "Whether the document is archived." + }, + "display_status": { + "type": "string", + "description": "Display-friendly indexing status for the UI." + }, + "word_count": { + "type": "integer", + "description": "Total word count of the document." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this document has been retrieved." + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode. `text_model` for standard text, `hierarchical_model` for parent-child, `qa_model` for QA pairs." + }, + "doc_language": { + "type": "string", + "description": "Language of the document content." + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "Document type classification, `null` if not set." + }, + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field type." + }, + "value": { + "type": "string", + "description": "Metadata field value for this document." + } + } + } + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "Unix timestamp when processing completed, `null` if not yet completed." + }, + "updated_at": { + "type": "number", + "nullable": true, + "description": "Unix timestamp of last update, `null` if never updated." + }, + "indexing_latency": { + "type": "number", + "nullable": true, + "description": "Time taken for indexing in seconds, `null` if not completed." + }, + "segment_count": { + "type": "integer", + "description": "Number of chunks in the document." + }, + "average_segment_length": { + "type": "number", + "description": "Average character length of chunks." + }, + "summary_index_status": { + "type": "string", + "nullable": true, + "description": "Status of summary indexing, `null` if summary index is not enabled." + }, + "need_summary": { + "type": "boolean", + "description": "Whether the document needs summary generation." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "dataset_process_rule": { + "id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "mode": "custom" + }, + "document_process_rule": { + "mode": "custom", + "rules": { + "pre_processing_rules": [], + "segmentation": { + "separator": "###", + "max_tokens": 500, + "chunk_overlap": 50 + } + } + }, + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_language": "English", + "doc_type": null, + "doc_metadata": [], + "completed_at": 1741267260, + "updated_at": 1741267260, + "indexing_latency": 60.0, + "segment_count": 5, + "average_segment_length": 70.0, + "summary_index_status": null, + "need_summary": false + } + } + } + } } }, - { - "name": "keyword", - "in": "query", - "description": "Keyword to search for in document names.", - "schema": { - "type": "string" + "400": { + "description": "- `invalid_metadata` : Invalid metadata value for the specified key.", + "content": { + "application/json": { + "examples": { + "invalid_metadata": { + "summary": "invalid_metadata", + "value": { + "status": 400, + "code": "invalid_metadata", + "message": "Invalid metadata value: {metadata_key}" + } + } + } + } } }, - { - "name": "page", - "in": "query", - "description": "Page number for pagination.", - "schema": { - "type": "integer", - "default": 1 + "403": { + "description": "- `forbidden` : No permission.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } } }, - { - "name": "limit", - "in": "query", - "description": "Number of items to return per page.", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } - } - ], - "responses": { - "200": { - "description": "A paginated list of documents.", + "404": { + "description": "- `not_found` : Document not found.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentListResponse" + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } } } - } - }, - "/datasets/{dataset_id}/documents/status/{action}": { - "patch": { + }, + "delete": { "tags": [ "Documents" ], - "summary": "Update Document Status", - "description": "Performs a batch action to update the status of one or more documents (e.g., enable, disable, archive).", - "operationId": "batchUpdateDocumentStatus", + "summary": "Delete Document", + "description": "Permanently delete a document and all its chunks from the knowledge base.", + "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { - "name": "action", + "name": "document_id", "in": "path", "required": true, - "description": "The action to perform on the documents.", "schema": { "type": "string", - "enum": [ - "enable", - "disable", - "archive", - "un_archive" - ] - } + "format": "uuid" + }, + "description": "Document ID." } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "document_ids" - ], - "properties": { - "document_ids": { - "type": "array", - "description": "A list of document IDs to perform the action on.", - "items": { - "type": "string", - "format": "uuid" + "responses": { + "204": { + "description": "Success." + }, + "400": { + "description": "- `document_indexing` : Cannot delete document during indexing.", + "content": { + "application/json": { + "examples": { + "document_indexing": { + "summary": "document_indexing", + "value": { + "status": 400, + "code": "document_indexing", + "message": "Cannot delete document during indexing." + } + } + } + } + } + }, + "403": { + "description": "- `archived_document_immutable` : The archived document is not editable.", + "content": { + "application/json": { + "examples": { + "archived_document_immutable": { + "summary": "archived_document_immutable", + "value": { + "status": 403, + "code": "archived_document_immutable", + "message": "The archived document is not editable." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Document Not Exists.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document Not Exists." } } } } } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" } } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments": { - "post": { + "/datasets/{dataset_id}/documents/{document_id}/download": { + "get": { "tags": [ - "Chunks" + "Documents" ], - "summary": "Add Chunks to a Document", - "description": "Adds one or more new chunks (segments) to a specific document. This is useful for manually adding curated content.", - "operationId": "createSegments", + "summary": "Download Document", + "description": "Get a signed download URL for a document's original uploaded file.", + "operationId": "downloadDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateSegmentsRequest" - } - } - } - }, "responses": { "200": { - "description": "List of newly created segments.", + "description": "Download URL generated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentListResponse" + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "Signed URL to download the original uploaded file." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600" + } + } + } + } + } + }, + "403": { + "description": "- `forbidden` : No permission to access this document.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Document not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } } } - }, + } + }, + "/datasets/{dataset_id}/documents/{batch}/indexing-status": { "get": { "tags": [ - "Chunks" + "Documents" ], - "summary": "Get Chunks from a Document", - "description": "Retrieves a paginated list of chunks (segments) from a specific document.", - "operationId": "listSegments", + "summary": "Get Document Indexing Status", + "description": "Check the indexing progress of documents in a batch. Returns the current processing stage and chunk completion counts for each document. Poll this endpoint until `indexing_status` reaches `completed` or `error`. The status progresses through: `waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`.", + "operationId": "getDocumentIndexingStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { - "name": "document_id", + "name": "batch", "in": "path", "required": true, - "description": "The ID of the document.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "keyword", - "in": "query", - "description": "Keyword to filter segments by content.", "schema": { "type": "string" - } - }, - { - "name": "status", - "in": "query", - "description": "Filter segments by their indexing status.", - "schema": { - "type": "string", - "example": "completed" - } - }, - { - "name": "page", - "in": "query", - "description": "Page number for pagination.", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "Number of items to return per page.", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } + }, + "description": "Batch ID returned from document creation." } ], "responses": { "200": { - "description": "Paginated list of segments.", + "description": "Indexing status for documents in the batch.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentPaginatedResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Document identifier." + }, + "indexing_status": { + "type": "string", + "description": "Current indexing status: `waiting`, `parsing`, `cleaning`, `splitting`, `indexing`, `completed`, or `error`." + }, + "processing_started_at": { + "type": "number", + "description": "Unix timestamp when processing started." + }, + "parsing_completed_at": { + "type": "number", + "description": "Unix timestamp when parsing completed." + }, + "cleaning_completed_at": { + "type": "number", + "description": "Unix timestamp when cleaning completed." + }, + "splitting_completed_at": { + "type": "number", + "description": "Unix timestamp when splitting completed." + }, + "completed_at": { + "type": "number", + "description": "Unix timestamp when indexing completed." + }, + "paused_at": { + "type": "number", + "nullable": true + }, + "error": { + "type": "string", + "nullable": true + }, + "stopped_at": { + "type": "number", + "nullable": true + }, + "completed_segments": { + "type": "integer", + "description": "Number of chunks that have been indexed." + }, + "total_segments": { + "type": "integer", + "description": "Total number of chunks to be indexed." + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "indexing_status": "completed", + "processing_started_at": 1741267200, + "parsing_completed_at": 1741267200, + "cleaning_completed_at": 1741267200, + "splitting_completed_at": 1741267200, + "completed_at": 1741267200, + "paused_at": null, + "error": null, + "stopped_at": null, + "completed_segments": 5, + "total_segments": 5 + } + ] + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Knowledge base not found. / Documents not found.", + "content": { + "application/json": { + "examples": { + "dataset_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + }, + "documents_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Documents not found." + } + } } } } @@ -889,185 +2069,442 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { - "get": { + "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { + "post": { "tags": [ - "Chunks" + "Documents" ], - "summary": "Get a Chunk Details in a Document", - "description": "Retrieves the details of a specific chunk (segment) within a document.", - "operationId": "getSegmentDetail", + "summary": "Update Document by Text", + "description": "Update an existing document's text content, name, or processing configuration. Re-triggers indexing if content changes — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", + "operationId": "updateDocumentByText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "The ID of the segment.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Document name. Required when `text` is provided." + }, + "text": { + "type": "string", + "description": "Document text content." + }, + "process_rule": { + "type": "object", + "description": "Processing rules for chunking.", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "Processing mode. `automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`)." + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": ["remove_stopwords", "remove_extra_spaces", "remove_urls_emails"], + "description": "Rule identifier." + }, + "enabled": { + "type": "boolean", + "description": "Whether this preprocessing rule is enabled." + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "Custom separator for splitting text." + }, + "max_tokens": { + "type": "integer", + "description": "Maximum token count per chunk." + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "Token overlap between chunks." + } + } + } + } + } + } + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction." + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "Language of the document for processing optimization." + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + } + } + } + } + } + }, "responses": { "200": { - "description": "Detailed information about the segment.", + "description": "Document updated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "Batch ID for tracking indexing progress." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist.", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + } } } } } } - }, + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { "post": { "tags": [ - "Chunks" + "Documents" ], - "summary": "Update a Chunk in a Document", - "description": "Updates the content, keywords, or status of a specific chunk (segment).", - "operationId": "updateSegment", + "summary": "Update Document by File", + "description": "Update an existing document by uploading a new file. Re-triggers indexing — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", + "operationId": "updateDocumentByFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "The ID of the segment to update.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "requestBody": { "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/UpdateSegmentRequest" + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "File to upload." + }, + "data": { + "type": "string", + "description": "JSON string containing configuration. Accepts the same fields as [Create Document by Text](/api-reference/documents/create-document-by-text) (`indexing_technique`, `doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" + } + } } } } }, "responses": { "200": { - "description": "Updated segment details.", + "description": "Document updated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "Batch ID for tracking indexing progress." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } } } } - } - } - }, - "delete": { - "tags": [ - "Chunks" - ], - "summary": "Delete a Chunk in a Document", - "description": "Deletes a specific chunk (segment) from a document.", - "operationId": "deleteSegment", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "The ID of the knowledge base.", - "schema": { - "type": "string", - "format": "uuid" + }, + "400": { + "description": "- `too_many_files` : Only one file is allowed.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist.", + "content": { + "application/json": { + "examples": { + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + } + } + } } }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "The ID of the document.", - "schema": { - "type": "string", - "format": "uuid" + "413": { + "description": "- `file_too_large` : File size exceeded.", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } } }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "The ID of the segment to delete.", - "schema": { - "type": "string", - "format": "uuid" + "415": { + "description": "- `unsupported_file_type` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } } } - ], - "responses": { - "204": { - "description": "Successfully deleted the segment." - } } } }, - "/datasets/{dataset_id}/retrieve": { + "/datasets/{dataset_id}/documents/download-zip": { "post": { "tags": [ - "Datasets" + "Documents" ], - "summary": "Retrieve Chunks from a Knowledge Base / Test Retrieval", - "description": "Performs a search query against a knowledge base to retrieve the most relevant chunks (segments). This endpoint can be used for both production retrieval and test retrieval.", - "operationId": "retrieveSegments", + "summary": "Download Documents as ZIP", + "description": "Download multiple uploaded-file documents as a single ZIP archive. Accepts up to `100` document IDs.", + "operationId": "downloadDocumentsZip", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base to retrieve from.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." } ], "requestBody": { @@ -1075,46 +2512,203 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RetrieveRequest" + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "minItems": 1, + "maxItems": 100, + "items": { + "type": "string", + "format": "uuid" + }, + "description": "Array of document IDs to include in the ZIP archive." + } + } } } } }, "responses": { "200": { - "description": "List of retrieved segments matching the query.", + "description": "ZIP archive containing the requested documents.", "content": { - "application/json": { + "application/zip": { "schema": { - "$ref": "#/components/schemas/RetrieveResponse" + "type": "string", + "format": "binary", + "description": "ZIP archive binary stream." } } } - } + }, + "403": { + "description": "- `forbidden` : Insufficient permissions.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Document or dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } + } + } + } + } } } }, - "/workspaces/current/models/model-types/text-embedding": { - "get": { + "/datasets/{dataset_id}/documents/status/{action}": { + "patch": { "tags": [ - "Models" + "Documents" + ], + "summary": "Update Document Status in Batch", + "description": "Enable, disable, archive, or unarchive multiple documents at once.", + "operationId": "batchUpdateDocumentStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable", + "archive", + "un_archive" + ] + }, + "description": "`enable` to activate, `disable` to deactivate, `archive` to archive, `un_archive` to restore from archive." + } ], - "summary": "Get available embedding models", - "description": "Fetches a list of all available text embedding models that can be used for creating and querying knowledge bases.", - "operationId": "getAvailableEmbeddingModels", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of document IDs to update." + } + } + } + } + } + }, "responses": { "200": { - "description": "A list of available embedding models grouped by provider.", + "description": "Documents updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ModelProvider" - } + "result": { + "type": "string", + "description": "Operation result." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + }, + "400": { + "description": "- `invalid_action` : Invalid action.", + "content": { + "application/json": { + "examples": { + "invalid_action": { + "summary": "invalid_action", + "value": { + "status": 400, + "code": "invalid_action", + "message": "Invalid action." + } + } + } + } + } + }, + "403": { + "description": "- `forbidden` : Insufficient permissions.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Knowledge base not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." } } } @@ -1124,44 +2718,34 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { + "/datasets/{dataset_id}/documents/{document_id}/segments": { "post": { "tags": [ "Chunks" ], - "summary": "Create Child Chunk", - "description": "Creates a new child chunk under a parent segment in a document using the hierarchical mode.", - "operationId": "createChildChunk", + "summary": "Create Chunks", + "description": "Create one or more chunks within a document. Each chunk can include optional keywords and an answer field (for QA-mode documents).", + "operationId": "createChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "requestBody": { @@ -1169,18 +2753,109 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateChildChunkRequest" + "type": "object", + "required": [ + "segments" + ], + "properties": { + "segments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "Chunk text content." + }, + "answer": { + "type": "string", + "description": "Answer content for QA mode." + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Keywords for the chunk." + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Attachment file IDs." + } + } + }, + "description": "Array of chunk objects to create." + } + } } } } }, "responses": { "200": { - "description": "Successfully created child chunk.", + "description": "Chunks created successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode used by this document." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model" + } + } } } } @@ -1191,75 +2866,152 @@ "tags": [ "Chunks" ], - "summary": "Get Child Chunks", - "description": "Retrieves a list of child chunks for a specific parent segment.", - "operationId": "getChildChunks", + "summary": "List Chunks", + "description": "Returns a paginated list of chunks within a document. Supports filtering by keyword and status.", + "operationId": "listChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { - "name": "segment_id", - "in": "path", - "required": true, - "description": "The ID of the parent segment.", + "name": "page", + "in": "query", "schema": { - "type": "string", - "format": "uuid" - } + "type": "integer", + "default": 1 + }, + "description": "Page number." }, { - "name": "keyword", + "name": "limit", "in": "query", - "description": "Search keyword to filter child chunks.", "schema": { - "type": "string" - } + "type": "integer", + "default": 20 + }, + "description": "Number of items per page." }, { - "name": "page", + "name": "status", "in": "query", - "description": "Page number for pagination.", "schema": { - "type": "integer", - "default": 1 - } + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "Filter chunks by indexing status, e.g. `completed`, `indexing`, `error`." }, { - "name": "limit", + "name": "keyword", "in": "query", - "description": "Number of items to return per page.", "schema": { - "type": "integer", - "default": 20, - "maximum": 100 - } + "type": "string" + }, + "description": "Search keyword." } ], "responses": { "200": { - "description": "A paginated list of child chunks.", + "description": "List of chunks.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode used by this document." + }, + "total": { + "type": "integer", + "description": "Total number of matching chunks." + }, + "has_more": { + "type": "boolean", + "description": "Whether more items exist on the next page." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "page": { + "type": "integer", + "description": "Current page number." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model", + "total": 1, + "has_more": false, + "limit": 20, + "page": 1 + } + } } } } @@ -1267,155 +3019,199 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { - "patch": { + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { + "get": { "tags": [ "Chunks" ], - "summary": "Update Child Chunk", - "description": "Updates the content of a specific child chunk.", - "operationId": "updateChildChunk", + "summary": "Get Chunk", + "description": "Retrieve detailed information about a specific chunk, including its content, keywords, and indexing status.", + "operationId": "getChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "The ID of the parent segment.", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "child_chunk_id", - "in": "path", - "required": true, - "description": "The ID of the child chunk to update.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateChildChunkRequest" - } - } - } - }, "responses": { "200": { - "description": "Successfully updated child chunk.", + "description": "Chunk details.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode used by this document." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } } } }, - "delete": { + "post": { "tags": [ "Chunks" ], - "summary": "Delete Child Chunk", - "description": "Deletes a specific child chunk.", - "operationId": "deleteChildChunk", + "summary": "Update Chunk", + "description": "Update a chunk's content, keywords, or answer. Re-triggers indexing for the modified chunk.", + "operationId": "updateChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Knowledge base ID." }, { "name": "document_id", "in": "path", "required": true, - "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" - } - }, - { - "name": "child_chunk_id", - "in": "path", - "required": true, - "description": "The ID of the child chunk to delete.", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "responses": { - "204": { - "description": "Successfully deleted the child chunk." + }, + "description": "Chunk ID." } - } - } - }, - "/datasets/tags": { - "post": { - "tags": [ - "Metadata & Tags" ], - "summary": "Create New Knowledge Base Type Tag", - "description": "Creates a new tag that can be used to categorize knowledge bases.", - "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": ["name"], + "required": [ + "segment" + ], "properties": { - "name": { - "type": "string", - "description": "The name of the new tag.", - "maxLength": 50 + "segment": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "Chunk text content." + }, + "answer": { + "type": "string", + "description": "Answer content for QA mode." + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Keywords for the chunk." + }, + "enabled": { + "type": "boolean", + "description": "Whether the chunk is enabled." + }, + "regenerate_child_chunks": { + "type": "boolean", + "default": false, + "description": "Whether to regenerate child chunks." + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Attachment file IDs." + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary content for summary index." + } + }, + "description": "Chunk data to update." } } } @@ -1424,64 +3220,166 @@ }, "responses": { "200": { - "description": "Successfully created tag.", + "description": "Chunk updated successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode used by this document." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } } } }, - "get": { + "delete": { "tags": [ - "Metadata & Tags" + "Chunks" + ], + "summary": "Delete Chunk", + "description": "Permanently delete a chunk from the document.", + "operationId": "deleteChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + } ], - "summary": "Get Knowledge Base Type Tags", - "description": "Retrieves a list of all available knowledge base tags.", - "operationId": "getKnowledgeTags", "responses": { - "200": { - "description": "A list of tags.", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Tag" - } - } - } - } + "204": { + "description": "Success." } } - }, - "patch": { + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { + "post": { "tags": [ - "Metadata & Tags" + "Chunks" + ], + "summary": "Create Child Chunk", + "description": "Create a child chunk under a parent chunk. Only available for documents using the `hierarchical_model` chunking mode.", + "operationId": "createChildChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + } ], - "summary": "Modify Knowledge Base Type Tag Name", - "description": "Updates the name of an existing tag.", - "operationId": "updateKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": ["tag_id", "name"], + "required": [ + "content" + ], "properties": { - "tag_id": { - "type": "string", - "description": "The ID of the tag to modify.", - "format": "uuid" - }, - "name": { + "content": { "type": "string", - "description": "The new name for the tag.", - "maxLength": 50 + "description": "Child chunk text content." } } } @@ -1490,1522 +3388,3215 @@ }, "responses": { "200": { - "description": "Successfully updated tag.", + "description": "Child chunk created successfully.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" - } - } - } - } - } - }, - "delete": { - "tags": [ - "Metadata & Tags" - ], - "summary": "Delete Knowledge Base Type Tag", - "description": "Deletes a tag. The tag must not be bound to any knowledge bases.", - "operationId": "deleteKnowledgeTag", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["tag_id"], - "properties": { - "tag_id": { - "type": "string", - "description": "The ID of the tag to delete.", - "format": "uuid" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } } - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" - } - } - } - }, - "/datasets/tags/binding": { - "post": { - "tags": [ - "Metadata & Tags" - ], - "summary": "Bind Dataset to Knowledge Base Type Tag", - "description": "Binds one or more tags to a specific knowledge base.", - "operationId": "bindTagsToDataset", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["target_id", "tag_ids"], - "properties": { - "target_id": { - "type": "string", - "description": "The ID of the dataset to bind tags to.", - "format": "uuid" - }, - "tag_ids": { - "type": "array", - "description": "A list of tag IDs to bind.", - "items": { - "type": "string", - "format": "uuid" + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } } } } } } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" - } - } - } - }, - "/datasets/tags/unbinding": { - "post": { - "tags": [ - "Metadata & Tags" - ], - "summary": "Unbind Dataset and Knowledge Base Type Tag", - "description": "Unbinds a specific tag from a knowledge base.", - "operationId": "unbindTagFromDataset", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["target_id", "tag_id"], - "properties": { - "target_id": { - "type": "string", - "description": "The ID of the dataset.", - "format": "uuid" - }, - "tag_id": { - "type": "string", - "description": "The ID of the tag to unbind.", - "format": "uuid" + }, + "400": { + "description": "- `invalid_param` : Create child chunk index failed.", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } } } } } } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" - } } - } - }, - "/datasets/{dataset_id}/tags": { + }, "get": { "tags": [ - "Metadata & Tags" + "Chunks" ], - "summary": "Query Tags Bound to a Dataset", - "description": "Retrieves all tags that are currently bound to a specific dataset.", - "operationId": "queryDatasetTags", + "summary": "List Child Chunks", + "description": "Returns a paginated list of child chunks under a specific parent chunk.", + "operationId": "listChildChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "The ID of the dataset.", "schema": { "type": "string", "format": "uuid" - } - } - ], - "responses": { - "200": { - "description": "A list of tags bound to the dataset.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" } - } - } - }, - "total": { - "type": "integer" - } - } - } - } - } - } - } - } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "API_KEY", - "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with 'Bearer '. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" - } - }, - "responses": { - "Success": { - "description": "Operation successful.", - "content": { - "application/json": { + }, + "description": "Knowledge base ID." + }, + { + "name": "document_id", + "in": "path", + "required": true, "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" - } - } - } - } - } - }, - "FileError": { - "description": "Bad request related to file upload. Could be `no_file_uploaded` or `too_many_files`.", - "content": { - "application/json": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "FileTooLarge": { - "description": "File size exceeded.", - "content": { - "application/json": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + }, + { + "name": "page", + "in": "query", "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "UnsupportedFileType": { - "description": "File type not allowed.", - "content": { - "application/json": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "Page number." + }, + { + "name": "limit", + "in": "query", "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "DatasetNameDuplicate": { - "description": "The dataset name already exists.", - "content": { - "application/json": { + "type": "integer", + "default": 20, + "minimum": 1 + }, + "description": "Number of items per page." + }, + { + "name": "keyword", + "in": "query", "schema": { - "$ref": "#/components/schemas/ErrorResponse" + "type": "string" + }, + "description": "Search keyword." + } + ], + "responses": { + "200": { + "description": "List of child chunks.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChildChunk" + } + }, + "total": { + "type": "integer", + "description": "Total number of child chunks." + }, + "total_pages": { + "type": "integer", + "description": "Total number of pages." + }, + "page": { + "type": "integer", + "description": "Current page number." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + ], + "total": 1, + "total_pages": 1, + "page": 1, + "limit": 20 + } + } + } + } } } } } }, - "schemas": { - "ErrorResponse": { - "type": "object", - "properties": { - "code": { - "type": "string", - "description": "A machine-readable error code." - }, - "message": { - "type": "string", - "description": "A human-readable error message." - }, - "status": { - "type": "integer", - "description": "The HTTP status code." - } - }, - "example": { - "code": "no_file_uploaded", - "message": "Please upload your file.", - "status": 400 - } - }, - "RetrievalModel": { - "type": "object", - "properties": { - "search_method": { - "type": "string", - "description": "The search method to use for retrieval.", - "enum": [ - "hybrid_search", - "semantic_search", - "full_text_search", - "keyword_search" - ] - }, - "reranking_enable": { - "type": "boolean", - "description": "Whether to enable a rerank model to improve search results." - }, - "reranking_mode": { - "type": "string", - "description": "The reranking mode.", - "default": "reranking_model", - "enum": [ - "reranking_model", - "weighted_score" - ] - }, - "reranking_model": { - "type": "object", - "description": "Configuration for the rerank model.", - "properties": { - "reranking_provider_name": { - "type": "string", - "description": "The provider of the rerank model." - }, - "reranking_model_name": { - "type": "string", - "description": "The name of the rerank model." - } + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { + "patch": { + "tags": [ + "Chunks" + ], + "summary": "Update Child Chunk", + "description": "Update the content of an existing child chunk.", + "operationId": "updateChildChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" }, - "nullable": true + "description": "Knowledge base ID." }, - "top_k": { - "type": "integer", - "description": "The number of top matching results to return." - }, - "score_threshold_enabled": { - "type": "boolean", - "description": "Whether to apply a score threshold to filter results." + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." }, - "score_threshold": { - "type": "number", - "format": "float", - "description": "The minimum score for a result to be included.", - "nullable": true + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." }, - "weights": { - "type": "number", - "format": "float", - "description": "The weight of semantic search in a hybrid search mode.", - "nullable": true + { + "name": "child_chunk_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Child chunk ID." } - } - }, - "SummaryIndexSetting": { - "type": "object", - "description": "Configuration for Summary Auto-Gen.", - "properties": { - "enable": { - "type": "boolean", - "description": "Whether to enable Summary Auto-Gen." - }, - "model_name": { - "type": "string", - "description": "Name of the model to use for generating summaries." - }, - "model_provider_name": { - "type": "string", - "description": "Provider of the summary model." - }, - "summary_prompt": { - "type": "string", - "description": "Prompt template for generating summaries." + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "Child chunk text content." + } + } + } + } } }, - "required": [ - "enable" - ] - }, - "PreprocessingRule": { - "type": "object", - "description": "A rule for preprocessing document content.", - "properties": { - "id": { - "type": "string", - "description": "The unique identifier for the preprocessing rule.", - "enum": [ - "remove_extra_spaces", - "remove_urls_emails" - ] - }, - "enabled": { - "type": "boolean", - "description": "Whether this rule is enabled." - } - } - }, - "SegmentationRule": { - "type": "object", - "description": "Rules for segmenting document content into chunks.", - "properties": { - "separator": { - "type": "string", - "description": "The custom delimiter used to separate segments." + "responses": { + "200": { + "description": "Child chunk updated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } + } + } + } }, - "max_tokens": { - "type": "integer", - "description": "The maximum number of tokens allowed in a single segment." + "400": { + "description": "- `invalid_param` : Update child chunk index failed.", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } + } + } + } + } } } }, - "SubChunkSegmentationRule": { - "type": "object", - "description": "Rules for segmenting parent chunks into smaller child chunks (for hierarchical mode).", - "properties": { - "separator": { - "type": "string", - "description": "The delimiter for sub-chunking." - }, - "max_tokens": { - "type": "integer", - "description": "The maximum token length for a sub-chunk." - }, - "chunk_overlap": { - "type": "integer", - "description": "The number of overlapping tokens between adjacent sub-chunks." + "delete": { + "tags": [ + "Chunks" + ], + "summary": "Delete Child Chunk", + "description": "Permanently delete a child chunk from its parent chunk.", + "operationId": "deleteChildChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + }, + { + "name": "child_chunk_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Child chunk ID." + } + ], + "responses": { + "204": { + "description": "Success." + }, + "400": { + "description": "- `invalid_param` : Delete child chunk index failed.", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Delete child chunk index failed: {error details}" + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/retrieve": { + "post": { + "tags": [ + "Knowledge Bases" + ], + "summary": "Retrieve Chunks from a Knowledge Base / Test Retrieval", + "description": "Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used for both production retrieval and test retrieval.", + "operationId": "searchKnowledgeBase", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "maxLength": 250, + "description": "Search query text." + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base." + }, + "external_retrieval_model": { + "type": "object", + "description": "Retrieval settings for external knowledge bases.", + "properties": { + "top_k": { + "type": "integer", + "description": "Maximum number of results to return." + }, + "score_threshold": { + "type": "number", + "description": "Minimum relevance score threshold for filtering results." + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + } + } + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "List of attachment IDs to include in the retrieval context." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Retrieval results.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "query": { + "type": "object", + "description": "The original query object.", + "properties": { + "content": { + "type": "string", + "description": "The query text." + } + } + }, + "records": { + "type": "array", + "items": { + "type": "object", + "properties": { + "segment": { + "type": "object", + "description": "Matched chunk from the knowledge base.", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the chunk." + }, + "position": { + "type": "integer", + "description": "Position of the chunk within the document." + }, + "document_id": { + "type": "string", + "description": "ID of the document this chunk belongs to." + }, + "content": { + "type": "string", + "description": "Text content of the chunk." + }, + "sign_content": { + "type": "string", + "description": "Signed content hash for integrity verification." + }, + "answer": { + "type": "string", + "description": "Answer content, used in Q&A mode documents." + }, + "word_count": { + "type": "integer", + "description": "Word count of the chunk content." + }, + "tokens": { + "type": "integer", + "description": "Token count of the chunk content." + }, + "keywords": { + "type": "array", + "description": "Keywords associated with this chunk for keyword-based retrieval.", + "items": { + "type": "string" + } + }, + "index_node_id": { + "type": "string", + "description": "ID of the index node in the vector store." + }, + "index_node_hash": { + "type": "string", + "description": "Hash of the indexed content, used to detect changes." + }, + "hit_count": { + "type": "integer", + "description": "Number of times this chunk has been matched in retrieval queries." + }, + "enabled": { + "type": "boolean", + "description": "Whether the chunk is enabled for retrieval." + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when the chunk was disabled. `null` if enabled." + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "ID of the user who disabled the chunk. `null` if enabled." + }, + "status": { + "type": "string", + "description": "Indexing status of the chunk." + }, + "created_by": { + "type": "string", + "description": "ID of the user who created the chunk." + }, + "created_at": { + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." + }, + "indexing_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing started. `null` if not yet started." + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing completed. `null` if not yet completed." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if indexing failed. `null` when no error." + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing was stopped. `null` if not stopped." + }, + "document": { + "type": "object", + "description": "Parent document information for the matched chunk.", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the document." + }, + "data_source_type": { + "type": "string", + "description": "How the document was created." + }, + "name": { + "type": "string", + "description": "Document name." + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "Document type classification. `null` if not set." + }, + "doc_metadata": { + "type": "object", + "nullable": true, + "description": "Metadata values for the document. `null` if no metadata is configured." + } + } + } + } + }, + "child_chunks": { + "type": "array", + "description": "Matched child chunks within the chunk, if using hierarchical indexing.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the child chunk." + }, + "content": { + "type": "string", + "description": "Text content of the child chunk." + }, + "position": { + "type": "integer", + "description": "Position of the child chunk within the parent chunk." + }, + "score": { + "type": "number", + "description": "Relevance score of the child chunk." + } + } + } + }, + "score": { + "type": "number", + "description": "Relevance score." + }, + "tsne_position": { + "type": "object", + "nullable": true, + "description": "t-SNE visualization position." + }, + "files": { + "type": "array", + "description": "Files attached to this chunk.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Attachment file identifier." + }, + "name": { + "type": "string", + "description": "Original file name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "description": "File extension." + }, + "mime_type": { + "type": "string", + "description": "MIME type of the file." + }, + "source_url": { + "type": "string", + "description": "URL to access the attachment." + } + } + } + }, + "summary": { + "type": "string", + "nullable": true, + "description": "Summary content if retrieved via summary index." + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "query": { + "content": "What is Dify?" + }, + "records": [ + { + "segment": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 1, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "data_source_type": "upload_file", + "name": "guide.txt", + "doc_type": null, + "doc_metadata": null + } + }, + "child_chunks": [], + "score": 0.92, + "tsne_position": null, + "files": [], + "summary": null + } + ] + } + } + } + } + } + }, + "400": { + "description": "- `dataset_not_initialized` : The dataset is still being initialized or indexing. Please wait a moment.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "dataset_not_initialized": { + "summary": "dataset_not_initialized", + "value": { + "status": 400, + "code": "dataset_not_initialized", + "message": "The dataset is still being initialized or indexing. Please wait a moment." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Invalid parameter value." + } + } + } + } + } + }, + "403": { + "description": "- `forbidden` : Insufficient permissions.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : Knowledge base not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } + }, + "500": { + "description": "- `internal_server_error` : An internal error occurred during retrieval.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "An internal error occurred." + } + } + } + } + } + } + } + } + }, + "/datasets/tags": { + "post": { + "tags": [ + "Tags" + ], + "summary": "Create Knowledge Tag", + "description": "Create a new tag for organizing knowledge bases.", + "operationId": "createKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "Tag name." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Tag created successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Tag identifier." + }, + "name": { + "type": "string", + "description": "Tag display name." + }, + "type": { + "type": "string", + "description": "Tag type. Always `knowledge` for knowledge base tags." + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "Number of knowledge bases bound to this tag." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } + } + } + } } } }, - "ProcessRule": { - "type": "object", - "description": "A set of rules for processing a document, including cleaning and segmentation.", - "properties": { - "mode": { - "type": "string", - "description": "The processing mode: automatic, custom, or hierarchical.", - "enum": [ - "automatic", - "custom", - "hierarchical" - ] + "get": { + "tags": [ + "Tags" + ], + "summary": "List Knowledge Tags", + "description": "Returns the list of all knowledge base tags in the workspace.", + "operationId": "listKnowledgeTags", + "responses": { + "200": { + "description": "List of tags.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Tag identifier." + }, + "name": { + "type": "string", + "description": "Tag display name." + }, + "type": { + "type": "string", + "description": "Tag type. Always `knowledge` for knowledge base tags." + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "Number of knowledge bases bound to this tag." + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + ] + } + } + } + } + } + } + }, + "patch": { + "tags": [ + "Tags" + ], + "summary": "Update Knowledge Tag", + "description": "Rename an existing knowledge base tag.", + "operationId": "updateKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_id", + "name" + ], + "properties": { + "tag_id": { + "type": "string", + "description": "Tag ID to update." + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "New tag name." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Tag updated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Tag identifier." + }, + "name": { + "type": "string", + "description": "Tag display name." + }, + "type": { + "type": "string", + "description": "Tag type. Always `knowledge` for knowledge base tags." + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "Number of knowledge bases bound to this tag." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } + } + } + } + } + } + }, + "delete": { + "tags": [ + "Tags" + ], + "summary": "Delete Knowledge Tag", + "description": "Permanently delete a knowledge base tag. Does not delete the knowledge bases that were tagged.", + "operationId": "deleteKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_id" + ], + "properties": { + "tag_id": { + "type": "string", + "description": "Tag ID to delete." + } + } + } + } + } + }, + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/tags/binding": { + "post": { + "tags": [ + "Tags" + ], + "summary": "Create Tag Binding", + "description": "Bind one or more tags to a knowledge base. A knowledge base can have multiple tags.", + "operationId": "bindKnowledgeTags", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_ids", + "target_id" + ], + "properties": { + "tag_ids": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "description": "Tag IDs to bind." + }, + "target_id": { + "type": "string", + "description": "Knowledge base ID." + } + } + } + } + } + }, + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/tags/unbinding": { + "post": { + "tags": [ + "Tags" + ], + "summary": "Delete Tag Binding", + "description": "Remove a tag binding from a knowledge base.", + "operationId": "unbindKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_id", + "target_id" + ], + "properties": { + "tag_id": { + "type": "string", + "description": "Tag ID to unbind." + }, + "target_id": { + "type": "string", + "description": "Knowledge base ID." + } + } + } + } + } + }, + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/{dataset_id}/tags": { + "get": { + "tags": [ + "Tags" + ], + "summary": "Get Knowledge Base Tags", + "description": "Returns the list of tags bound to a specific knowledge base.", + "operationId": "getKnowledgeBaseTags", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "responses": { + "200": { + "description": "Tags bound to the knowledge base.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Tag identifier." + }, + "name": { + "type": "string", + "description": "Tag display name." + } + } + } + }, + "total": { + "type": "integer", + "description": "Total number of tags bound to this knowledge base." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs" + } + ], + "total": 1 + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata": { + "post": { + "tags": [ + "Metadata" + ], + "summary": "Create Metadata Field", + "description": "Create a custom metadata field for the knowledge base. Metadata fields can be used to annotate documents with structured information.", + "operationId": "createMetadataField", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "string", + "number", + "time" + ], + "description": "`string` for text values, `number` for numeric values, `time` for date/time values." + }, + "name": { + "type": "string", + "description": "Metadata field name." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Metadata field created successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field type." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "get": { + "tags": [ + "Metadata" + ], + "summary": "List Metadata Fields", + "description": "Returns the list of all metadata fields (both custom and built-in) for the knowledge base, along with the count of documents using each field.", + "operationId": "listMetadataFields", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "responses": { + "200": { + "description": "Metadata fields for the knowledge base.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field type." + }, + "count": { + "type": "integer", + "description": "Number of documents using this metadata field." + } + } + } + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "Whether built-in metadata fields are enabled for this knowledge base." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "doc_metadata": [ + { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string", + "count": 3 + } + ], + "built_in_field_enabled": true + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/{metadata_id}": { + "patch": { + "tags": [ + "Metadata" + ], + "summary": "Update Metadata Field", + "description": "Rename a custom metadata field.", + "operationId": "updateMetadataField", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Metadata field ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "New metadata field name." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Metadata field updated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field type." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "delete": { + "tags": [ + "Metadata" + ], + "summary": "Delete Metadata Field", + "description": "Permanently delete a custom metadata field. Documents using this field will lose their metadata values for it.", + "operationId": "deleteMetadataField", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Metadata field ID." + } + ], + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in": { + "get": { + "tags": [ + "Metadata" + ], + "summary": "Get Built-in Metadata Fields", + "description": "Returns the list of built-in metadata fields provided by the system (e.g., document type, source URL).", + "operationId": "getBuiltInMetadataFields", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "responses": { + "200": { + "description": "Built-in metadata fields.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "fields": { + "type": "array", + "description": "List of system-provided metadata fields.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Built-in field identifier. `document_name` for the document title, `uploader` for the creator, `upload_date` for creation time, `last_update_date` for last modification time, `source` for the document origin." + }, + "type": { + "type": "string", + "description": "Field data type. `string` for text values, `time` for date/time values." + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "fields": [ + { + "name": "document_name", + "type": "string" + }, + { + "name": "uploader", + "type": "string" + }, + { + "name": "upload_date", + "type": "time" + }, + { + "name": "last_update_date", + "type": "time" + }, + { + "name": "source", + "type": "string" + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in/{action}": { + "post": { + "tags": [ + "Metadata" + ], + "summary": "Update Built-in Metadata Field", + "description": "Enable or disable built-in metadata fields for the knowledge base.", + "operationId": "toggleBuiltInMetadataField", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + }, + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + }, + "description": "`enable` to activate built-in metadata fields, `disable` to deactivate them." + } + ], + "responses": { + "200": { + "description": "Built-in metadata field toggled successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Operation result." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/metadata": { + "post": { + "tags": [ + "Metadata" + ], + "summary": "Update Document Metadata in Batch", + "description": "Update metadata values for multiple documents at once. Each document in the request receives the specified metadata key-value pairs.", + "operationId": "batchUpdateDocumentMetadata", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "operation_data" + ], + "properties": { + "operation_data": { + "type": "array", + "items": { + "type": "object", + "required": [ + "document_id", + "metadata_list" + ], + "properties": { + "document_id": { + "type": "string", + "description": "ID of the document whose metadata to update." + }, + "metadata_list": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { + "type": "string", + "description": "Metadata field ID." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "value": { + "description": "Metadata value. Can be a string, number, or `null`." + } + } + } + }, + "partial_update": { + "type": "boolean", + "default": false, + "description": "Whether to partially update metadata, keeping existing values for unspecified fields." + } + } + }, + "description": "Array of document metadata update operations. Each entry maps a document ID to its metadata key-value pairs." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Document metadata updated successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "Operation result." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/workspaces/current/models/model-types/{model_type}": { + "get": { + "tags": [ + "Models" + ], + "summary": "Get Available Models", + "description": "Retrieve the list of available models by type. Primarily used to query `text-embedding` and `rerank` models for knowledge base configuration.", + "operationId": "getAvailableModels", + "parameters": [ + { + "name": "model_type", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "text-embedding", + "rerank", + "llm", + "tts", + "speech2text", + "moderation" + ] + }, + "description": "Type of model to retrieve. For knowledge base configuration, use `text-embedding` for embedding models or `rerank` for reranking models." + } + ], + "responses": { + "200": { + "description": "Available models for the specified type.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "List of model providers with their available models.", + "items": { + "type": "object", + "properties": { + "provider": { + "type": "string", + "description": "Model provider identifier, e.g. `openai`, `cohere`." + }, + "label": { + "type": "object", + "description": "Localized display name of the provider.", + "properties": { + "en_US": { + "type": "string" + }, + "zh_Hans": { + "type": "string" + } + } + }, + "icon_small": { + "type": "object", + "description": "URL of the provider's small icon.", + "properties": { + "en_US": { + "type": "string" + } + } + }, + "icon_large": { + "type": "object", + "description": "URL of the provider's large icon.", + "properties": { + "en_US": { + "type": "string" + } + } + }, + "status": { + "type": "string", + "description": "Provider status. `active` when credentials are configured and valid." + }, + "models": { + "type": "array", + "description": "List of available models from this provider.", + "items": { + "type": "object", + "properties": { + "model": { + "type": "string", + "description": "Model identifier. Use this as the `embedding_model` value when creating or updating a knowledge base." + }, + "label": { + "type": "object", + "description": "Localized display name of the model.", + "properties": { + "en_US": { + "type": "string" + }, + "zh_Hans": { + "type": "string" + } + } + }, + "model_type": { + "type": "string", + "description": "Type of the model, matching the `model_type` path parameter." + }, + "features": { + "type": "array", + "nullable": true, + "description": "Supported features of the model, `null` if none.", + "items": { + "type": "string" + } + }, + "fetch_from": { + "type": "string", + "description": "Where the model definition comes from. `predefined-model` for built-in models, `customizable-model` for user-configured models." + }, + "model_properties": { + "type": "object", + "description": "Model-specific properties such as `context_size`." + }, + "status": { + "type": "string", + "description": "Model availability status. `active` when ready to use." + } + } + } + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "data": [ + { + "provider": "openai", + "label": { + "en_US": "OpenAI", + "zh_Hans": "OpenAI" + }, + "icon_small": { + "en_US": "https://example.com/openai-small.svg" + }, + "icon_large": { + "en_US": "https://example.com/openai-large.svg" + }, + "status": "active", + "models": [ + { + "model": "text-embedding-3-small", + "label": { + "en_US": "text-embedding-3-small", + "zh_Hans": "text-embedding-3-small" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8191 + }, + "status": "active" + } + ] + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/pipeline/file-upload": { + "post": { + "tags": [ + "Knowledge Pipeline" + ], + "summary": "Upload Pipeline File", + "description": "Upload a file for use in a knowledge pipeline. Accepts a single file via `multipart/form-data`.", + "operationId": "uploadPipelineFile", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "The file to upload." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "File uploaded successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the uploaded file." + }, + "name": { + "type": "string", + "description": "Original file name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "description": "File extension." + }, + "mime_type": { + "type": "string", + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "string", + "description": "Upload timestamp in ISO 8601 format." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "report.pdf", + "size": 524288, + "extension": "pdf", + "mime_type": "application/pdf", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": "2025-03-06T12:00:00" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : Please upload your file.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `too_many_files` : Only one file is allowed.", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + } + } + } + } }, - "rules": { - "type": "object", - "description": "The specific rules to apply, used when mode is 'custom' or 'hierarchical'.", - "properties": { - "pre_processing_rules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PreprocessingRule" + "413": { + "description": "- `file_too_large` : File size exceeded.", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } } - }, - "segmentation": { - "$ref": "#/components/schemas/SegmentationRule" - }, - "parent_mode": { - "type": "string", - "description": "Retrieval mode for parent chunks in hierarchical mode.", - "enum": [ - "full-doc", - "paragraph" - ] - }, - "subchunk_segmentation": { - "$ref": "#/components/schemas/SubChunkSegmentationRule" } - }, - "nullable": true + } + }, + "415": { + "description": "- `unsupported_file_type` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } } } - }, - "CreateDocumentByTextRequest": { - "type": "object", - "required": [ - "name", - "text" + } + }, + "/datasets/{dataset_id}/pipeline/datasource-plugins": { + "get": { + "tags": [ + "Knowledge Pipeline" ], - "properties": { - "name": { - "type": "string", - "description": "Name of the document." - }, - "text": { - "type": "string", - "description": "Full text content of the document." - }, - "indexing_technique": { - "type": "string", - "description": "Indexing technique for the document.", - "enum": [ - "high_quality", - "economy" - ] - }, - "doc_form": { - "type": "string", - "description": "Format of the indexed content.", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] - }, - "doc_language": { - "type": "string", - "description": "Language of the document, important for Q&A mode.", - "example": "English" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { - "type": "string", - "description": "Name of the embedding model to use." - }, - "embedding_model_provider": { - "type": "string", - "description": "Provider of the embedding model." + "summary": "List Datasource Plugins", + "description": "List all datasource plugins available for a knowledge pipeline. Returns published or draft plugins depending on the `is_published` query parameter.", + "operationId": "listDatasourcePlugins", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Configuration for Summary Auto-Gen." + { + "name": "is_published", + "in": "query", + "schema": { + "type": "boolean", + "default": true + }, + "description": "Whether to retrieve published or draft datasource plugins. `true` returns published plugins, `false` returns draft plugins." } - } - }, - "CreateDocumentByFileRequestData": { - "type": "object", - "description": "Metadata and rules for creating a document from a file.", - "properties": { - "original_document_id": { - "type": "string", - "description": "ID of an existing document to re-upload or modify.", - "format": "uuid" - }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] - }, - "doc_form": { - "type": "string", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] - }, - "doc_language": { - "type": "string", - "example": "English" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { - "type": "string" - }, - "embedding_model_provider": { - "type": "string" + ], + "responses": { + "200": { + "description": "List of datasource plugins.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the datasource plugin." + }, + "name": { + "type": "string", + "description": "Display name of the datasource plugin." + }, + "type": { + "type": "string", + "description": "Type of the datasource plugin." + } + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": [ + { + "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", + "name": "Web Scraper", + "type": "online_document" + } + ] + } + } + } + } }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Configuration for Summary Auto-Gen." + "404": { + "description": "- `not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } - }, - "UpdateDocumentByTextRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "New name for the document (optional)." - }, - "text": { - "type": "string", - "description": "New text content for the document (optional)." + } + }, + "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": { + "post": { + "tags": [ + "Knowledge Pipeline" + ], + "summary": "Run Datasource Node", + "description": "Execute a single datasource node within the knowledge pipeline. Returns a streaming response with the node execution results.", + "operationId": "runDatasourceNode", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + { + "name": "node_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "ID of the datasource node to execute." } - } - }, - "UpdateDocumentByFileRequestData": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "New name for the document (optional)." - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "is_published" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the datasource node." + }, + "datasource_type": { + "type": "string", + "enum": ["online_document", "local_file", "website_crawl", "online_drive"], + "description": "Type of the datasource." + }, + "credential_id": { + "type": "string", + "nullable": true, + "description": "ID of the credential to use for authentication with the datasource." + }, + "is_published": { + "type": "boolean", + "description": "Whether to run the published or draft version of the node. `true` runs the published version, `false` runs the draft." + } + } + } + } } - } - }, - "Document": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "position": { - "type": "integer" - }, - "data_source_type": { - "type": "string" - }, - "data_source_info": { - "type": "object", - "nullable": true - }, - "dataset_process_rule_id": { - "type": "string", - "format": "uuid", - "nullable": true - }, - "name": { - "type": "string" - }, - "created_from": { - "type": "string" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - }, - "tokens": { - "type": "integer" - }, - "indexing_status": { - "type": "string" - }, - "error": { - "type": "string", - "nullable": true - }, - "enabled": { - "type": "boolean" - }, - "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true - }, - "disabled_by": { - "type": "string", - "format": "uuid", - "nullable": true - }, - "archived": { - "type": "boolean" - }, - "display_status": { - "type": "string" - }, - "word_count": { - "type": "integer" - }, - "hit_count": { - "type": "integer" + }, + "responses": { + "200": { + "description": "Streaming response with node execution events.", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "Server-Sent Events stream containing node execution progress and results." + } + } + } }, - "doc_form": { - "type": "string" + "404": { + "description": "- `not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } - }, - "DocumentCreationResponse": { - "type": "object", - "properties": { - "document": { - "$ref": "#/components/schemas/Document" - }, - "batch": { - "type": "string", - "description": "A batch identifier for tracking indexing progress." + } + }, + "/datasets/{dataset_id}/pipeline/run": { + "post": { + "tags": [ + "Knowledge Pipeline" + ], + "summary": "Run Pipeline", + "description": "Execute the full knowledge pipeline for a knowledge base. Supports both streaming and blocking response modes.", + "operationId": "runPipeline", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Knowledge base ID." } - } - }, - "CreateDatasetRequest": { - "type": "object", - "required": [ - "name" ], - "properties": { - "name": { - "type": "string", - "description": "Name of the knowledge base." - }, - "description": { - "type": "string", - "description": "Description of the knowledge base (optional)." - }, - "indexing_technique": { - "type": "string", - "description": "The indexing technique to use.", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "description": "Access permissions for the knowledge base.", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "provider": { - "type": "string", - "description": "The provider of the knowledge base.", - "enum": [ - "vendor", - "external" - ] - }, - "external_knowledge_api_id": { - "type": "string", - "description": "ID of the external knowledge API (if provider is 'external')." - }, - "external_knowledge_id": { - "type": "string", - "description": "ID of the external knowledge (if provider is 'external')." - }, - "embedding_model": { - "type": "string", - "description": "Name of the embedding model." + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "datasource_info_list", + "start_node_id", + "is_published", + "response_mode" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the pipeline." + }, + "datasource_type": { + "type": "string", + "enum": ["online_document", "local_file", "website_crawl", "online_drive"], + "description": "Type of the datasource." + }, + "datasource_info_list": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "List of datasource information objects for the pipeline to process." + }, + "start_node_id": { + "type": "string", + "description": "ID of the node to start pipeline execution from." + }, + "is_published": { + "type": "boolean", + "description": "Whether to run the published or draft version of the pipeline. `true` runs the published version, `false` runs the draft." + }, + "response_mode": { + "type": "string", + "enum": ["streaming", "blocking"], + "description": "Response mode for the pipeline execution. `streaming` returns a Server-Sent Events stream, `blocking` waits and returns the complete result." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Pipeline execution result. Format depends on `response_mode`: streaming returns a `text/event-stream`, blocking returns a JSON object.", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "Server-Sent Events stream containing pipeline execution progress and results. Returned when `response_mode` is `streaming`." + } + }, + "application/json": { + "schema": { + "type": "object", + "description": "Complete pipeline execution result. Returned when `response_mode` is `blocking`.", + "additionalProperties": true + }, + "examples": { + "success": { + "summary": "Blocking Response Example", + "value": { + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "data": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "status": "succeeded", + "outputs": {}, + "created_at": 1741267200, + "finished_at": 1741267210 + } + } + } + } + } + } }, - "embedding_model_provider": { - "type": "string", - "description": "Provider of the embedding model." + "403": { + "description": "- `forbidden` : Forbidden.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" + "404": { + "description": "- `not_found` : Dataset not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Configuration for Summary Auto-Gen." + "500": { + "description": "- `pipeline_run_error` : Pipeline execution failed.", + "content": { + "application/json": { + "examples": { + "pipeline_run_error": { + "summary": "pipeline_run_error", + "value": { + "status": 500, + "code": "pipeline_run_error", + "message": "Pipeline execution failed: connection timeout" + } + } + } + } + } } } - }, + } + } + }, + "components": { + "schemas": { "Dataset": { "type": "object", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "Unique identifier of the knowledge base." }, "name": { - "type": "string" + "type": "string", + "description": "Display name of the knowledge base. Unique within the workspace." }, "description": { "type": "string", - "nullable": true + "description": "Optional text describing the purpose or contents of the knowledge base." }, "provider": { - "type": "string" + "type": "string", + "description": "Provider type. `vendor` for internally managed, `external` for external knowledge base connections." }, "permission": { - "type": "string" + "type": "string", + "description": "Controls who can access this knowledge base. Possible values: `only_me`, `all_team_members`, `partial_members`." }, "data_source_type": { "type": "string", - "nullable": true + "description": "Data source type of the documents, `null` if not yet configured." }, "indexing_technique": { "type": "string", - "nullable": true + "description": "`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing." }, "app_count": { - "type": "integer" + "type": "integer", + "description": "Number of applications currently using this knowledge base." }, "document_count": { - "type": "integer" + "type": "integer", + "description": "Total number of documents in the knowledge base." }, "word_count": { - "type": "integer" + "type": "integer", + "description": "Total word count across all documents." }, "created_by": { "type": "string", - "format": "uuid" + "description": "ID of the user who created the knowledge base." + }, + "author_name": { + "type": "string", + "description": "Display name of the creator." }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." }, "updated_by": { "type": "string", - "format": "uuid" + "description": "ID of the user who last updated the knowledge base." }, "updated_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "Last update timestamp (Unix epoch in seconds)." }, "embedding_model": { "type": "string", - "nullable": true + "description": "Name of the embedding model used for indexing." }, "embedding_model_provider": { "type": "string", - "nullable": true + "description": "Embedding model provider. Use the `provider` field from [Get Available Models](/api-reference/models/get-available-models) with `model_type=text-embedding`." }, "embedding_available": { "type": "boolean", - "nullable": true - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Summary Auto-Gen configurations for this dataset.", - "nullable": true - } - } - }, - "DatasetListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Dataset" - } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" + "description": "Whether the configured embedding model is currently available." }, - "page": { - "type": "integer" - } - } - }, - "DatasetDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Dataset" - }, - { + "retrieval_model_dict": { "type": "object", + "description": "Retrieval configuration for the knowledge base.", "properties": { - "retrieval_model_dict": { - "$ref": "#/components/schemas/RetrievalModel" + "search_method": { + "type": "string", + "description": "Search method used for retrieval. `keyword_search` for keyword matching, `semantic_search` for embedding-based similarity, `full_text_search` for full-text indexing, `hybrid_search` for a combination of semantic and keyword approaches." }, - "tags": { - "type": "array", - "items": { - "type": "object" - } + "reranking_enable": { + "type": "boolean", + "description": "Whether reranking is enabled." }, - "doc_form": { + "reranking_mode": { "type": "string", - "nullable": true - } - } - } - ] - }, - "UpdateDatasetRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "New name for the knowledge base." - }, - "description": { - "type": "string", - "description": "New description for the knowledge base." - }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "embedding_model_provider": { - "type": "string" - }, - "embedding_model": { - "type": "string" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "Configuration for Summary Auto-Gen." - }, - "partial_member_list": { - "type": "array", - "description": "List of members for 'partial_members' permission.", - "items": { - "type": "object", - "required": [ - "user_id" - ], - "properties": { - "user_id": { - "type": "string", - "description": "User ID of the member." - } - } - } - } - } - }, - "IndexingStatus": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "indexing_status": { - "type": "string" - }, - "processing_started_at": { - "type": "number", - "format": "float" - }, - "parsing_completed_at": { - "type": "number", - "format": "float" - }, - "cleaning_completed_at": { - "type": "number", - "format": "float" - }, - "splitting_completed_at": { - "type": "number", - "format": "float" - }, - "completed_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "paused_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "error": { - "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "completed_segments": { - "type": "integer" - }, - "total_segments": { - "type": "integer" - } - } - }, - "DocumentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" - } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" - } - } - }, - "DocumentDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Document" - }, - { - "type": "object", - "properties": { - "dataset_process_rule": { - "$ref": "#/components/schemas/ProcessRule" + "nullable": true, + "description": "Reranking mode. `reranking_model` for model-based reranking, `weighted_score` for score-based weighting. `null` if reranking is disabled." + }, + "reranking_model": { + "type": "object", + "description": "Reranking model configuration.", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "Provider name of the reranking model." + }, + "reranking_model_name": { + "type": "string", + "description": "Name of the reranking model." + } + } }, - "document_process_rule": { - "allOf": [ - { - "$ref": "#/components/schemas/ProcessRule" + "weights": { + "type": "object", + "nullable": true, + "description": "Weight configuration for hybrid search.", + "properties": { + "weight_type": { + "type": "string", + "description": "Strategy for balancing semantic and keyword search weights." }, - { + "vector_setting": { "type": "object", + "description": "Semantic search weight settings.", "properties": { - "id": { - "type": "string" + "vector_weight": { + "type": "number", + "description": "Weight assigned to semantic (vector) search results." + }, + "embedding_provider_name": { + "type": "string", + "description": "Provider of the embedding model used for vector search." }, - "dataset_id": { - "type": "string" + "embedding_model_name": { + "type": "string", + "description": "Name of the embedding model used for vector search." + } + } + }, + "keyword_setting": { + "type": "object", + "description": "Keyword search weight settings.", + "properties": { + "keyword_weight": { + "type": "number", + "description": "Weight assigned to keyword search results." } } } - ] + } + }, + "top_k": { + "type": "integer", + "description": "Maximum number of results to return." }, - "indexing_latency": { + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + }, + "score_threshold": { "type": "number", - "format": "float", - "nullable": true + "description": "Minimum relevance score for results. Only effective when `score_threshold_enabled` is `true`." + } + } + }, + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "Summary index configuration.", + "properties": { + "enable": { + "type": "boolean", + "description": "Whether summary indexing is enabled." }, - "segment_count": { - "type": "integer" + "model_name": { + "type": "string", + "description": "Name of the model used for generating summaries." }, - "average_segment_length": { - "type": "integer" + "model_provider_name": { + "type": "string", + "description": "Provider of the summary generation model." }, - "doc_language": { + "summary_prompt": { "type": "string", - "nullable": true + "description": "Prompt template used for summary generation." } } - } - ] - }, - "Segment": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "position": { - "type": "integer" - }, - "document_id": { - "type": "string", - "format": "uuid" - }, - "content": { - "type": "string" - }, - "answer": { - "type": "string", - "nullable": true - }, - "word_count": { - "type": "integer" - }, - "tokens": { - "type": "integer" - }, - "keywords": { - "type": "array", - "items": { - "type": "string" - } - }, - "index_node_id": { - "type": "string" - }, - "index_node_hash": { - "type": "string" - }, - "hit_count": { - "type": "integer" - }, - "enabled": { - "type": "boolean" - }, - "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true - }, - "disabled_by": { - "type": "string", - "format": "uuid", - "nullable": true - }, - "status": { - "type": "string" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - }, - "indexing_at": { - "type": "integer", - "format": "int64" - }, - "completed_at": { - "type": "integer", - "format": "int64" - }, - "error": { - "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true }, - "summary": { - "type": "string", - "nullable": true - } - } - }, - "CreateSegmentsRequest": { - "type": "object", - "properties": { - "segments": { + "tags": { "type": "array", + "description": "Tags associated with this knowledge base.", "items": { "type": "object", - "required": [ - "content" - ], "properties": { - "content": { + "id": { "type": "string", - "description": "The text content of the chunk (or question in Q&A mode)." + "description": "Tag identifier." }, - "answer": { + "name": { "type": "string", - "description": "The answer content, required if the document is in Q&A mode." + "description": "Tag name." }, - "keywords": { - "type": "array", - "description": "Keywords associated with the chunk.", - "items": { - "type": "string" - } + "type": { + "type": "string", + "description": "Tag type. Always `knowledge` for knowledge base tags." } } } - } - } - }, - "SegmentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Segment" - } }, "doc_form": { - "type": "string" - } - } - }, - "SegmentPaginatedResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/SegmentListResponse" + "type": "string", + "description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction." }, - { + "external_knowledge_info": { "type": "object", + "nullable": true, + "description": "Connection details for external knowledge bases. Present when `provider` is `external`.", "properties": { - "has_more": { - "type": "boolean" + "external_knowledge_id": { + "type": "string", + "description": "ID of the external knowledge base." }, - "limit": { - "type": "integer" + "external_knowledge_api_id": { + "type": "string", + "description": "ID of the external knowledge API connection." }, - "total": { - "type": "integer" + "external_knowledge_api_name": { + "type": "string", + "description": "Display name of the external knowledge API." }, - "page": { - "type": "integer" + "external_knowledge_api_endpoint": { + "type": "string", + "description": "Endpoint URL of the external knowledge API." } } - } - ] - }, - "SegmentDetailResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Segment" }, - "doc_form": { - "type": "string" - } - } - }, - "UpdateSegmentRequest": { - "type": "object", - "properties": { - "segment": { + "external_retrieval_model": { "type": "object", - "required": [ - "content" - ], + "nullable": true, + "description": "Retrieval settings for external knowledge bases. `null` for internal knowledge bases.", "properties": { - "content": { - "type": "string" + "top_k": { + "type": "integer", + "description": "Maximum number of results to return from the external knowledge base." }, - "answer": { - "type": "string" + "score_threshold": { + "type": "number", + "description": "Minimum relevance score threshold." }, - "keywords": { - "type": "array", - "items": { - "type": "string" + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + } + } + }, + "doc_metadata": { + "type": "array", + "description": "Metadata field definitions for the knowledge base.", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field value type." } + } + } + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "Whether built-in metadata fields (e.g., `document_name`, `uploader`) are enabled." + }, + "pipeline_id": { + "type": "string", + "nullable": true, + "description": "Pipeline ID, if a custom processing pipeline is configured." + }, + "runtime_mode": { + "type": "string", + "nullable": true, + "description": "Runtime processing mode." + }, + "chunk_structure": { + "type": "string", + "nullable": true, + "description": "Chunk structure configuration." + }, + "icon_info": { + "type": "object", + "nullable": true, + "description": "Icon display configuration for the knowledge base.", + "properties": { + "icon_type": { + "type": "string", + "description": "Type of icon." }, - "summary": { + "icon": { "type": "string", - "nullable": true + "description": "Icon identifier or emoji." }, - "enabled": { - "type": "boolean" + "icon_background": { + "type": "string", + "description": "Background color for the icon." }, - "regenerate_child_chunks": { - "type": "boolean", - "description": "Whether to regenerate child chunks (hierarchical mode)." + "icon_url": { + "type": "string", + "description": "URL of a custom icon image." } } + }, + "is_published": { + "type": "boolean", + "description": "Whether the knowledge base is published." + }, + "total_documents": { + "type": "integer", + "description": "Total number of documents." + }, + "total_available_documents": { + "type": "integer", + "description": "Number of documents that are enabled and available." + }, + "enable_api": { + "type": "boolean", + "description": "Whether API access is enabled for this knowledge base." + }, + "is_multimodal": { + "type": "boolean", + "description": "Whether multimodal content processing is enabled." } } }, - "RetrieveRequest": { + "Document": { "type": "object", - "required": [ - "query" - ], "properties": { - "query": { + "id": { "type": "string", - "description": "The search query string." + "description": "Unique identifier of the document." }, - "retrieval_model": { - "allOf": [ - { - "$ref": "#/components/schemas/RetrievalModel" - }, - { - "type": "object", - "properties": { - "metadata_filtering_conditions": { - "type": "object", - "description": "Conditions for filtering results based on metadata.", - "properties": { - "logical_operator": { - "type": "string", - "enum": [ - "and", - "or" - ] - }, - "conditions": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the metadata field." - }, - "comparison_operator": { - "type": "string", - "description": "The operator for comparison." - }, - "value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } - ], - "nullable": true, - "description": "The value to compare against." - } - } - } - } - } - } - } - } - ] - } - } - }, - "RetrievedSegment": { - "type": "object", - "properties": { - "segment": { - "allOf": [ - { - "$ref": "#/components/schemas/Segment" - }, - { - "type": "object", - "properties": { - "document": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "data_source_type": { - "type": "string" - }, - "name": { - "type": "string" - } - } - } - } - } - ] + "position": { + "type": "integer", + "description": "Display position of the document in the list." + }, + "data_source_type": { + "type": "string", + "description": "How the document was created. `upload_file` for file uploads, `notion_import` for Notion imports." + }, + "data_source_info": { + "type": "object", + "description": "Raw data source information, varies by `data_source_type`." + }, + "data_source_detail_dict": { + "type": "object", + "description": "Detailed data source information including file details." + }, + "dataset_process_rule_id": { + "type": "string", + "description": "ID of the processing rule applied to this document." + }, + "name": { + "type": "string", + "description": "Document name." + }, + "created_from": { + "type": "string", + "description": "Origin of the document. `api` for API creation, `web` for UI creation." + }, + "created_by": { + "type": "string", + "description": "ID of the user who created the document." + }, + "created_at": { + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." + }, + "tokens": { + "type": "integer", + "description": "Total number of tokens in the document." + }, + "indexing_status": { + "type": "string", + "description": "Current indexing status. `waiting` for queued, `parsing` while extracting content, `cleaning` while removing noise, `splitting` while chunking, `indexing` while building vectors, `completed` when ready, `error` if failed, `paused` if manually paused." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if indexing failed. `null` when no error." + }, + "enabled": { + "type": "boolean", + "description": "Whether the document is enabled for retrieval." }, - "score": { + "disabled_at": { "type": "number", - "format": "float" - } - } - }, - "RetrieveResponse": { - "type": "object", - "properties": { - "query": { - "type": "object", - "properties": { - "content": { - "type": "string" - } - } + "nullable": true, + "description": "Timestamp when the document was disabled. `null` if enabled." + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "ID of the user who disabled the document. `null` if enabled." + }, + "archived": { + "type": "boolean", + "description": "Whether the document is archived." + }, + "display_status": { + "type": "string", + "description": "User-facing display status derived from `indexing_status` and `enabled` state." + }, + "word_count": { + "type": "integer", + "description": "Total word count of the document." }, - "records": { + "hit_count": { + "type": "integer", + "description": "Number of times the document has been matched in retrieval queries." + }, + "doc_form": { + "type": "string", + "description": "Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction." + }, + "doc_metadata": { "type": "array", + "description": "Metadata values assigned to this document.", "items": { - "$ref": "#/components/schemas/RetrievedSegment" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Metadata field identifier." + }, + "name": { + "type": "string", + "description": "Metadata field name." + }, + "type": { + "type": "string", + "description": "Metadata field value type." + }, + "value": { + "type": "string", + "description": "Metadata value for this document." + } + } } + }, + "summary_index_status": { + "type": "string", + "nullable": true, + "description": "Status of the summary index for this document. `null` if summary indexing is not configured." + }, + "need_summary": { + "type": "boolean", + "description": "Whether a summary needs to be generated for this document." } } }, - "Model": { + "Segment": { "type": "object", "properties": { - "model": { - "type": "string" + "id": { + "type": "string", + "description": "Unique identifier of the chunk." }, - "label": { - "type": "object", - "additionalProperties": { + "position": { + "type": "integer", + "description": "Position of the chunk within the document." + }, + "document_id": { + "type": "string", + "description": "ID of the document this chunk belongs to." + }, + "content": { + "type": "string", + "description": "Text content of the chunk." + }, + "sign_content": { + "type": "string", + "description": "Signed content hash for integrity verification." + }, + "answer": { + "type": "string", + "description": "Answer content, used in Q&A mode documents." + }, + "word_count": { + "type": "integer", + "description": "Word count of the chunk content." + }, + "tokens": { + "type": "integer", + "description": "Token count of the chunk content." + }, + "keywords": { + "type": "array", + "description": "Keywords associated with this chunk for keyword-based retrieval.", + "items": { "type": "string" } }, - "model_type": { - "type": "string" + "index_node_id": { + "type": "string", + "description": "ID of the index node in the vector store." }, - "features": { - "type": "array", - "items": {}, - "nullable": true + "index_node_hash": { + "type": "string", + "description": "Hash of the indexed content, used to detect changes." }, - "fetch_from": { - "type": "string" + "hit_count": { + "type": "integer", + "description": "Number of times this chunk has been matched in retrieval queries." }, - "model_properties": { - "type": "object", - "properties": { - "context_size": { - "type": "integer" - } - } + "enabled": { + "type": "boolean", + "description": "Whether the chunk is enabled for retrieval." + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when the chunk was disabled. `null` if enabled." }, - "deprecated": { - "type": "boolean" + "disabled_by": { + "type": "string", + "nullable": true, + "description": "ID of the user who disabled the chunk. `null` if enabled." }, "status": { - "type": "string" + "type": "string", + "description": "Current indexing status of the chunk, e.g. `completed`, `indexing`, `error`." }, - "load_balancing_enabled": { - "type": "boolean" - } - } - }, - "ModelProvider": { - "type": "object", - "properties": { - "provider": { - "type": "string" + "created_by": { + "type": "string", + "description": "ID of the user who created the chunk." }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } + "created_at": { + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." }, - "icon_small": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } + "updated_at": { + "type": "number", + "description": "Last update timestamp (Unix epoch in seconds)." }, - "icon_large": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } + "updated_by": { + "type": "string", + "description": "ID of the user who last updated the chunk." }, - "status": { - "type": "string" + "indexing_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing started. `null` if not yet started." + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing completed. `null` if not yet completed." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if indexing failed. `null` when no error." + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "Timestamp when indexing was stopped. `null` if not stopped." + }, + "child_chunks": { + "type": "array", + "description": "Child chunks belonging to this chunk. Only present for hierarchical mode documents.", + "items": { + "$ref": "#/components/schemas/ChildChunk" + } }, - "models": { + "attachments": { "type": "array", + "description": "Files attached to this chunk.", "items": { - "$ref": "#/components/schemas/Model" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Attachment file identifier." + }, + "name": { + "type": "string", + "description": "Original file name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "description": "File extension." + }, + "mime_type": { + "type": "string", + "description": "MIME type of the file." + }, + "source_url": { + "type": "string", + "description": "URL to access the attachment." + } + } } + }, + "summary": { + "type": "string", + "nullable": true, + "description": "AI-generated summary of the chunk content. `null` if summary indexing is not enabled." } } }, "ChildChunk": { "type": "object", - "description": "Represents a child chunk in a hierarchical segmentation.", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "segment_id": { "type": "string", "format": "uuid" }, - "content": { "type": "string" }, - "word_count": { "type": "integer" }, - "tokens": { "type": "integer" }, - "index_node_id": { "type": "string" }, - "index_node_hash": { "type": "string" }, - "status": { "type": "string" }, - "created_by": { "type": "string", "format": "uuid" }, - "created_at": { "type": "integer", "format": "int64" }, - "indexing_at": { "type": "integer", "format": "int64" }, - "completed_at": { "type": "integer", "format": "int64" }, - "error": { "type": "string", "nullable": true }, - "stopped_at": { "type": "integer", "format": "int64", "nullable": true } - } - }, - "CreateChildChunkRequest": { - "type": "object", - "required": ["content"], "properties": { - "content": { + "id": { "type": "string", - "description": "The content of the child chunk." - } - } - }, - "UpdateChildChunkRequest": { - "type": "object", - "required": ["content"], - "properties": { + "description": "Unique identifier of the child chunk." + }, + "segment_id": { + "type": "string", + "description": "ID of the parent chunk this child chunk belongs to." + }, "content": { "type": "string", - "description": "The updated content for the child chunk." - } - } - }, - "ChildChunkResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ChildChunk" + "description": "Text content of the child chunk." + }, + "position": { + "type": "integer", + "description": "Position of the child chunk within the parent chunk." + }, + "word_count": { + "type": "integer", + "description": "Word count of the child chunk content." + }, + "type": { + "type": "string", + "description": "How the child chunk was created. `automatic` for system-generated, `custom` for manually created." + }, + "created_at": { + "type": "number", + "description": "Creation timestamp (Unix epoch in seconds)." + }, + "updated_at": { + "type": "number", + "description": "Last update timestamp (Unix epoch in seconds)." } } }, - "ChildChunkListResponse": { + "RetrievalModel": { "type": "object", + "required": [ + "search_method", + "reranking_enable", + "top_k", + "score_threshold_enabled" + ], "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ChildChunk" + "search_method": { + "type": "string", + "description": "Search method used for retrieval.", + "enum": [ + "keyword_search", + "semantic_search", + "full_text_search", + "hybrid_search" + ] + }, + "reranking_enable": { + "type": "boolean", + "description": "Whether reranking is enabled." + }, + "reranking_model": { + "type": "object", + "description": "Reranking model configuration.", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "Provider name of the reranking model." + }, + "reranking_model_name": { + "type": "string", + "description": "Name of the reranking model." + } } }, - "total": { "type": "integer" }, - "total_pages": { "type": "integer" }, - "page": { "type": "integer" }, - "limit": { "type": "integer" } - } - }, - "UploadFileResponse": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" }, - "size": { "type": "integer" }, - "extension": { "type": "string" }, - "url": { "type": "string", "format": "uri", "description": "Preview URL for the file." }, - "download_url": { "type": "string", "format": "uri", "description": "Download URL for the file." }, - "mime_type": { "type": "string" }, - "created_by": { "type": "string", "format": "uuid" }, - "created_at": { "type": "integer", "format": "int64" } - } - }, - "Tag": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "name": { "type": "string" }, - "type": { "type": "string", "example": "knowledge" }, - "binding_count": { "type": "integer" } + "reranking_mode": { + "type": "string", + "enum": ["reranking_model", "weighted_score"], + "nullable": true, + "description": "Reranking mode. Required when `reranking_enable` is `true`." + }, + "top_k": { + "type": "integer", + "description": "Maximum number of results to return." + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "Whether score threshold filtering is enabled." + }, + "score_threshold": { + "type": "number", + "nullable": true, + "description": "Minimum relevance score for results. Only effective when `score_threshold_enabled` is `true`." + }, + "weights": { + "type": "object", + "nullable": true, + "description": "Weight configuration for hybrid search.", + "properties": { + "weight_type": { + "type": "string", + "description": "Strategy for balancing semantic and keyword search weights.", + "enum": [ + "semantic_first", + "keyword_first", + "customized" + ] + }, + "vector_setting": { + "type": "object", + "description": "Semantic search weight settings.", + "properties": { + "vector_weight": { + "type": "number", + "description": "Weight assigned to semantic (vector) search results." + }, + "embedding_provider_name": { + "type": "string", + "description": "Provider of the embedding model used for vector search." + }, + "embedding_model_name": { + "type": "string", + "description": "Name of the embedding model used for vector search." + } + } + }, + "keyword_setting": { + "type": "object", + "description": "Keyword search weight settings.", + "properties": { + "keyword_weight": { + "type": "number", + "description": "Weight assigned to keyword search results." + } + } + } + } + } } } + }, + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" + } } } } diff --git a/en/api-reference/openapi_workflow.json b/en/api-reference/openapi_workflow.json index 6306b7d1f..72e5c3ac1 100644 --- a/en/api-reference/openapi_workflow.json +++ b/en/api-reference/openapi_workflow.json @@ -2,7 +2,7 @@ "openapi": "3.0.1", "info": { "title": "Workflow App API", - "description": "Workflow applications offers non-session support and is ideal for translation, article writing, summarization AI, and more.", + "description": "Workflow applications offer non-session support and are ideal for translation, article writing, summarization AI, and more.", "version": "1.0.0" }, "servers": [ @@ -25,10 +25,12 @@ "paths": { "/workflows/run": { "post": { - "summary": "Execute Workflow", - "description": "Execute workflow. Cannot be executed without a published workflow.", - "operationId": "executeWorkflow", - "tags": ["Workflow Execution"], + "summary": "Run Workflow", + "description": "Execute a workflow. Cannot be executed without a published workflow.", + "operationId": "runWorkflow", + "tags": [ + "Workflows" + ], "requestBody": { "required": true, "content": { @@ -37,25 +39,35 @@ "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { - "basic_execution": { - "summary": "Basic workflow execution", + "streaming_example": { + "summary": "Request Example - Streaming mode", "value": { "inputs": { - "query": "Summarize this text: ..." + "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", "user": "user_workflow_123" } }, - "with_file_array_variable":{ - "summary": "Example with a file array input variable", + "blocking_example": { + "summary": "Request Example - Blocking mode", + "value": { + "inputs": { + "query": "Translate this to French: Hello world" + }, + "response_mode": "blocking", + "user": "user_workflow_456" + } + }, + "with_file_array_variable": { + "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", - "upload_file_id": "uploaded_file_id_abc" + "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", @@ -65,7 +77,196 @@ ] }, "response_mode": "blocking", - "user": "user_workflow_456" + "user": "user_workflow_789" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "Response Example - Blocking mode", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Bonjour le monde" + }, + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630 + } + } + } + } + }, + "text/event-stream": { + "schema": { + "type": "string", + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkWorkflowEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `workflow_finished` or `error` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." + }, + "examples": { + "streamingResponse": { + "summary": "Response Example - Streaming mode", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" + } + } + } + } + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", + "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` : 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." + } + } + } + } + } + } + } + } + }, + "/workflows/{workflow_id}/run": { + "post": { + "summary": "Run Workflow by ID", + "description": "Execute a specific workflow version identified by its ID. Useful for running a particular published version of the workflow.", + "operationId": "runWorkflowById", + "tags": [ + "Workflows" + ], + "parameters": [ + { + "name": "workflow_id", + "in": "path", + "required": true, + "description": "Workflow ID of the specific version to execute. This value is returned in the `workflow_id` field of [Run Workflow](/api-reference/workflows/run-workflow) responses and [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowExecutionRequest" + }, + "examples": { + "example": { + "summary": "Request Example", + "value": { + "inputs": { + "query": "Summarize this article" + }, + "response_mode": "blocking", + "user": "user_workflow_123" } } } @@ -74,23 +275,168 @@ }, "responses": { "200": { - "description": "Successful workflow execution. Structure depends on `response_mode`.\n- `blocking`: `application/json` with `WorkflowCompletionResponse`.\n- `streaming`: `text/event-stream` with `ChunkWorkflowEvent` stream.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowCompletionResponse" + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "Response Example - Blocking mode", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Article summary here" + }, + "error": null, + "elapsed_time": 2.45, + "total_tokens": 280, + "total_steps": 4, + "created_at": 1705407629, + "finished_at": 1705407631 + } + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "A stream of Server-Sent Events. See `ChunkWorkflowEvent` for structures." + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkWorkflowEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `workflow_finished` or `error` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." + } + } + } + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Required parameter missing or invalid.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Workflow is a draft and cannot be executed." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Workflow not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", + "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" + } + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestWorkflow" }, - "500": { "$ref": "#/components/responses/InternalServerError" } + "500": { + "description": "`internal_server_error` : 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." + } + } + } + } + } + } } } }, @@ -99,14 +445,18 @@ "summary": "Get Workflow Run Detail", "description": "Retrieve the current execution results of a workflow task based on the workflow execution ID.", "operationId": "getWorkflowRunDetail", - "tags": ["Workflow Execution"], + "tags": [ + "Workflows" + ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, - "description": "Workflow Run ID, can be obtained from workflow execution response or streaming events.", - "schema": { "type": "string", "format": "uuid" } + "description": "Workflow run ID, can be obtained from the workflow execution response or streaming events.", + "schema": { + "type": "string" + } } ], "responses": { @@ -114,27 +464,227 @@ "description": "Successfully retrieved workflow run details.", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponse" } + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "Response Example", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } + } + } + }, + "400": { + "description": "`not_workflow_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Workflow run not found.", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } } } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "List Workflow Logs", + "description": "Retrieve paginated workflow execution logs with filtering options.", + "operationId": "listWorkflowLogs", + "tags": [ + "Workflows" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "Keyword to search in logs.", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "Filter by execution status.", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "Page number for pagination.", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of items per page.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "Filter logs created before this ISO 8601 timestamp.", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "Filter logs created after this ISO 8601 timestamp.", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "Filter by end user session ID.", + "schema": { + "type": "string" + } }, - "404": {"description": "Workflow run not found."} + { + "name": "created_by_account", + "in": "query", + "description": "Filter by account ID.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved workflow logs.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "Response Example", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0 + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_workflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } } } }, "/workflows/tasks/{task_id}/stop": { "post": { - "summary": "Stop Workflow Task Generation", - "description": "Stops a workflow task generation. Only supported in streaming mode.", - "operationId": "stopWorkflowTaskGeneration", - "tags": ["Workflow Execution"], + "summary": "Stop Workflow Task", + "description": "Stop a running workflow task. Only supported in `streaming` mode.", + "operationId": "stopWorkflowTask", + "tags": [ + "Workflows" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "Task ID from the streaming chunk.", - "schema": { "type": "string", "format": "uuid" } + "description": "Task ID, can be obtained from the streaming chunk return of the [Run Workflow](/api-reference/workflows/run-workflow) API.", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -143,393 +693,3178 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { - "user": { "type": "string", "description": "User identifier." } + "user": { + "type": "string", + "description": "User identifier, must be consistent with the user passed in the [Run Workflow](/api-reference/workflows/run-workflow) request." + } + } + }, + "examples": { + "example": { + "summary": "Request Example", + "value": { + "user": "user_workflow_123" + } } } } } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `invalid_param` : Required parameter missing or invalid.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + } } } }, "/files/upload": { "post": { - "summary": "File Upload for Workflow", - "description": "Upload a file for use in workflows. Supports any formats supported by your workflow. Uploaded files are for the current end-user only.", "operationId": "uploadWorkflowFile", - "tags": ["Files"], + "tags": [ + "Files" + ], + "summary": "Upload File", + "description": "Upload a file for use when sending messages, enabling multimodal understanding of images, documents, audio, and video. Uploaded files are for use by the current end-user only.", "requestBody": { + "description": "File upload request. Requires multipart/form-data.", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "file" + ], "properties": { - "file": { "type": "string", "format": "binary", "description": "The file to be uploaded." }, - "user": { "type": "string", "description": "User identifier." } + "file": { + "type": "string", + "format": "binary", + "description": "The file to be uploaded. Supported types include images, documents, audio, and video." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer's rules, must be unique within the application." + } } } } } }, "responses": { - "200": { + "201": { "description": "File uploaded successfully.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileUploadResponse" + }, + "examples": { + "uploadSuccess": { + "summary": "Response Example", + "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" + } + } + } + } + } }, - "201": { - "description": "File created successfully (alternative success code).", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } + "400": { + "description": "- `no_file_uploaded` : No file was provided in the request.\n- `too_many_files` : Only one file is allowed per request.\n- `filename_not_exists_error` : The uploaded file has no filename.", + "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` : File size exceeded.", + "content": { + "application/json": { + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } + } + } }, - "400": { "$ref": "#/components/responses/BadRequestFile" }, - "413": { "$ref": "#/components/responses/FileTooLarge" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFile" }, - "503": { "$ref": "#/components/responses/S3ErrorFile" }, - "500": { "$ref": "#/components/responses/InternalServerError" } + "415": { + "description": "`unsupported_file_type` : File type not allowed.", + "content": { + "application/json": { + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { + "/files/{file_id}/preview": { "get": { - "summary": "Get End User", - "description": "Retrieve an end user by ID.\n\nThis is useful when other APIs return an end-user ID (e.g. `created_by` from File Upload).", - "operationId": "getEndUserWorkflow", - "tags": ["End Users"], + "operationId": "downloadWorkflowFile", + "tags": [ + "Files" + ], + "summary": "Download File", + "description": "Preview or download uploaded files previously uploaded via the [File Upload](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", "parameters": [ { - "name": "end_user_id", + "name": "file_id", "in": "path", "required": true, - "description": "End user ID.", - "schema": { "type": "string", "format": "uuid" } + "description": "The unique identifier of the file to preview, obtained from the [File Upload](/api-reference/files/upload-file) API response.", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "If `true`, forces the file to download as an attachment instead of previewing in browser.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "User identifier, used for end-user context.", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "End user retrieved successfully.", + "description": "Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If `as_attachment` is `true`, the file is returned as a download with `Content-Disposition: attachment`.", "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetail" } + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } - } - } - }, - "/workflows/logs": { - "get": { - "summary": "Get Workflow Logs", - "description": "Returns workflow logs, with the first page returning the latest `{limit}` messages, i.e., in reverse order.", - "operationId": "getWorkflowLogs", - "tags": ["Workflow Execution"], - "parameters": [ - { "name": "keyword", "in": "query", "description": "Keyword to search.", "schema": { "type": "string" } }, - { "name": "status", "in": "query", "description": "Filter by status.", "schema": { "type": "string", "enum": ["succeeded", "failed", "stopped", "running"] } }, - { "name": "page", "in": "query", "description": "Current page.", "schema": { "type": "integer", "default": 1 } }, - { "name": "limit", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer", "default": 20 } } - ], - "responses": { - "200": { - "description": "Successfully retrieved workflow logs.", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponse" } } } + "403": { + "description": "`file_access_denied` : Access to the requested file is 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` : The requested file was not found.", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } + } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "operationId": "getWorkflowEndUser", + "tags": [ + "End Users" + ], + "summary": "Get End User", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "End user ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "End user retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "Response Example", + "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` : 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." + } + } + } + } + } + } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "workflowAudioToText", + "tags": [ + "TTS" + ], + "summary": "Convert Audio to Text", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `15 MB`.", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully converted audio to text.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "Response Example", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `no_audio_uploaded` : No audio file was uploaded.\n- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Speech recognition request failed.", + "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` : Audio file size exceeded the limit.", + "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` : Audio type is not allowed.", + "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` : Internal server error.", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/text-to-audio": { + "post": { + "operationId": "workflowTextToAudio", + "tags": [ + "TTS" + ], + "summary": "Convert Text to Audio", + "description": "Convert text to speech.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "Request Example", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the generated audio file. The `Content-Type` header is set to the audio MIME type (e.g., `audio/wav`, `audio/mp3`). If `streaming` is `true`, the audio is streamed as chunked transfer encoding.", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : App unavailable or misconfigured.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model does not support this operation.\n- `completion_request_error` : Text-to-speech request failed.", + "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." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : Audio file size exceeded.", + "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` : Audio type not allowed.", + "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` : 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": "Get Application Basic Information", "operationId": "getWorkflowAppInfo", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App Info", + "description": "Retrieve basic information about this application, including name, description, tags, and mode.", "responses": { - "200": { "description": "Basic application information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponse" } } } } + "200": { + "description": "Basic information of the application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "Response Example", + "value": { + "name": "My Workflow App", + "description": "A helpful customer service chatbot.", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "workflow", + "author_name": "Dify Team" + } + } + } + } + } + } } } }, "/parameters": { "get": { - "summary": "Get Application Parameters Information", "operationId": "getWorkflowAppParameters", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App Parameters", + "description": "Retrieve the application's input form configuration, including feature switches, input parameter names, types, and default values.", + "responses": { + "200": { + "description": "Application parameters information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "Response Example", + "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` : App unavailable or misconfigured.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getWorkflowAppMeta", + "tags": [ + "Applications" + ], + "summary": "Get App Meta", + "description": "Retrieve metadata about this application, including tool icons and other configuration details.", "responses": { - "200": { "description": "Application parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowAppParametersResponse" } } } } + "200": { + "description": "Successfully retrieved application meta information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "Response Example", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } } } }, "/site": { "get": { - "summary": "Get Application WebApp Settings", "operationId": "getWorkflowWebAppSettings", - "tags": ["Application"], + "tags": [ + "Applications" + ], + "summary": "Get App WebApp Settings", + "description": "Retrieve the WebApp settings of this application, including site configuration, theme, and customization options.", "responses": { - "200": { "description": "WebApp settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWebAppSettingsResponse" } } } } + "200": { + "description": "WebApp settings of the application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "Response Example", + "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": "A helpful customer service chatbot.", + "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` : Site not found for this application or the workspace has been archived.", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API Key authentication." } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key authentication." + } }, "responses": { - "BadRequestWorkflow": { "description": "Bad Request for workflow operation. Possible error codes: invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, workflow_request_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "BadRequestFile": { "description": "Bad Request for file operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "FileTooLarge": { "description": "File is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "UnsupportedFileTypeFile": { "description": "Unsupported file type for upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "S3ErrorFile": { "description": "S3 storage error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "InternalServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "SuccessResult": { "description": "Operation successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "EndUserNotFound": { "description": "End user not found. Error code: `end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } + "SuccessResult": { + "description": "Operation successful.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "success" + ], + "description": "Operation result." + } + } + }, + "examples": { + "success": { + "summary": "Response Example", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { "WorkflowExecutionRequest": { "type": "object", - "required": ["inputs", "response_mode", "user"], + "required": [ + "inputs", + "user" + ], "properties": { "inputs": { "type": "object", - "description": "Key/value pairs for workflow variables. Value for a file array type variable should be a list of InputFileObjectWorkflow.", + "description": "Key-value pairs for workflow input variables. Values for file-type variables should be arrays of file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app.", "additionalProperties": { "oneOf": [ - { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, - { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectWorkflow" } } + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "object" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + } + } ] + } + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "default": "blocking", + "description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events." + }, + "user": { + "type": "string", + "description": "User identifier, defined by the developer's rules, must be unique within the application. This identifier scopes data access — workflow runs and files are only visible when queried with the same `user` value." + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" }, - "example": { "user_query": "Translate this for me.", "target_language": "French" } + "nullable": true, + "description": "File list. Suitable when files need to be combined with text for input, available only when the model supports Vision capability. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`." + } + } + }, + "InputFileObject": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "document", + "image", + "audio", + "video", + "custom" + ], + "description": "File type." + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "Transfer method: `remote_url` for file URL, `local_file` for uploaded file." + }, + "url": { + "type": "string", + "format": "url", + "description": "File URL (when `transfer_method` is `remote_url`)." }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "description": "Response mode. Cloudflare timeout is 100s for blocking." }, - "user": { "type": "string", "description": "User identifier." } + "upload_file_id": { + "type": "string", + "description": "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (when `transfer_method` is `local_file`)." + } } }, - "InputFileObjectWorkflow": { + "WorkflowBlockingResponse": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/api-reference/workflows/stop-workflow-task) to cancel a running workflow. Only valid during execution." + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." + }, + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } + } + }, + "ChunkWorkflowEvent": { + "type": "object", + "required": [ + "event" + ], + "properties": { + "event": { + "type": "string", + "enum": [ + "workflow_started", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "text_chunk", + "text_replace", + "workflow_finished", + "tts_message", + "tts_message_end", + "workflow_paused", + "agent_log", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "error", + "ping" + ] + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "text_chunk": "#/components/schemas/StreamEventTextChunk", + "text_replace": "#/components/schemas/StreamEventTextReplace", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "tts_message": "#/components/schemas/StreamEventTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", + "error": "#/components/schemas/StreamEventError", + "ping": "#/components/schemas/StreamEventPing", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout" + } + } + }, + "StreamEventBase": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID for the in-progress execution. Use this with [Stop Workflow Task](/api-reference/workflows/stop-workflow-task) to cancel a running workflow. Only valid during execution." + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for this workflow run." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run started." + }, + "reason": { + "type": "string", + "description": "Reason for the workflow start. `initial` for a new execution, `resumption` when resuming from a paused state." + } + } + } + } + } + ] + }, + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type (e.g., `llm`, `code`, `template-transform`)." + }, + "title": { + "type": "string", + "description": "Display name of the node." + }, + "index": { + "type": "integer", + "description": "Execution sequence index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node, if any." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Input variables for this node." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the node execution started." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata for the node execution." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Parent iteration ID if this node runs inside an iteration." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Parent loop ID if this node runs inside a loop." + } + } + } + } + } + ] + }, + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Display name of the node." + }, + "index": { + "type": "integer", + "description": "Execution sequence index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node, if any." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Input variables for this node." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Processing data generated during node execution." + }, + "process_data_truncated": { + "type": "boolean", + "description": "Whether the `process_data` was truncated." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Output data from the node." + }, + "outputs_truncated": { + "type": "boolean", + "description": "Whether the `outputs` data was truncated." + }, + "status": { + "type": "string", + "description": "Node execution status. `running` for in-progress, `succeeded` when completed, `failed` on error, `stopped` when manually halted, `exception` on unexpected failure." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the node failed." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Time elapsed in seconds." + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "description": "Execution metadata including token usage.", + "properties": { + "total_tokens": { + "type": "integer", + "nullable": true, + "description": "Total tokens consumed by this node." + }, + "total_price": { + "type": "number", + "format": "float", + "nullable": true, + "description": "Total cost for this node execution." + }, + "currency": { + "type": "string", + "nullable": true, + "description": "Currency of the cost (e.g., `USD`)." + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the node execution started." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the node execution finished." + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files generated by this node." + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "Parent iteration ID if this node runs inside an iteration." + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "Parent loop ID if this node runs inside a loop." + } + } + } + } + } + ] + }, + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Display name of the node." + }, + "index": { + "type": "integer", + "description": "Execution sequence index." + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "ID of the predecessor node, if any." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Processing data generated during node execution." + }, + "process_data_truncated": { + "type": "boolean", + "description": "Whether the `process_data` was truncated." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "Whether the `outputs` data was truncated." + }, + "status": { + "type": "string", + "description": "Node execution status at the retry point." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message that triggered the retry." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Time elapsed in seconds." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "retry_index": { + "type": "integer", + "description": "Zero-based retry attempt index." + }, + "iteration_id": { + "type": "string", + "nullable": true + }, + "loop_id": { + "type": "string", + "nullable": true + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Metadata from the node execution." + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Files produced by the node during execution." + } + } + } + } + } + ] + }, + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Node execution ID." + }, + "node_id": { + "type": "string", + "description": "Iteration node ID." + }, + "node_type": { + "type": "string", + "description": "Node type (always `iteration`)." + }, + "title": { + "type": "string", + "description": "Display name of the iteration node." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the iteration." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Iteration metadata." + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "Current iteration index (zero-based)." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "Whether the `outputs` data was truncated." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Input variables for the iteration." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the iteration started." + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Additional metadata for the iteration." + }, + "status": { + "type": "string", + "description": "Iteration completion status." + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "Execution metadata including token usage." + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "Number of iteration steps completed." + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "metadata": { + "type": "object", + "additionalProperties": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "Current loop iteration index (zero-based)." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "pre_loop_output": { + "description": "Output from the previous loop iteration.", + "nullable": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "Whether the `outputs` data was truncated." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Input variables for the loop." + }, + "inputs_truncated": { + "type": "boolean", + "description": "Whether the `inputs` data was truncated." + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Additional metadata for the loop." + }, + "status": { + "type": "string", + "description": "Loop completion status." + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "Execution metadata including token usage." + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "Number of loop iterations completed." + } + } + } + } + } + ] + }, + "StreamEventTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The text content chunk." + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "Source path of the text variable in the workflow." + } + } + } + } + } + ] + }, + "StreamEventTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The replacement text content." + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } + } + } + ] + }, + "StreamEventTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64-encoded MP3 audio chunk. Decode and concatenate all chunks in order to produce a complete audio file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when this audio chunk was generated." + } + } + } + ] + }, + "StreamEventTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "description": "Empty string. Signals the end of the audio stream." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the audio stream ended." + } + } + } + ] + }, + "StreamEventError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code of the error." + }, + "code": { + "type": "string", + "description": "Error code." + }, + "message": { + "type": "string", + "description": "Error message." + } + } + } + ] + }, + "StreamEventPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "type": "object", + "description": "Keep-alive ping event. No additional properties." + } + ] + }, + "WorkflowFinishedData": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Output data from the workflow." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total time elapsed in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed across all nodes." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "created_by": { + "type": "object", + "additionalProperties": true, + "description": "Creator information. Only present in streaming `workflow_finished` events." + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "Number of exceptions encountered during execution. Only present in streaming `workflow_finished` events." + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "nullable": true, + "description": "Files generated during workflow execution. Only present in streaming `workflow_finished` events." + } + } + }, + "WorkflowRunDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the workflow run." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Output data from the workflow." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "Total time elapsed in seconds." + } + } + }, + "FileUploadResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique file ID." + }, + "name": { + "type": "string", + "description": "File name." + }, + "size": { + "type": "integer", + "description": "File size in bytes." + }, + "extension": { + "type": "string", + "nullable": true, + "description": "File extension." + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "MIME type of the file." + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the user who uploaded the file." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Upload timestamp (Unix epoch seconds)." + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "Preview URL for the file." + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "Source URL of the file." + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "Original URL of the file." + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated user." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated tenant." + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "ID of the associated conversation." + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "Storage key for the file." + } + } + }, + "EndUserDetail": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "Tenant ID." + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Application ID." + }, + "type": { + "type": "string", + "description": "End user type. Always `service_api` for Service API users." + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/api-reference/chats/send-chat-message))." + }, + "name": { + "type": "string", + "nullable": true, + "description": "End user name." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the user is anonymous. `true` when no `user` identifier was provided in the original API request." + }, + "session_id": { + "type": "string", + "description": "Session identifier. Defaults to the `external_user_id` value." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp." + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp." + } + } + }, + "WorkflowLogsResponse": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "description": "Current page number." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of log entries." + }, + "has_more": { + "type": "boolean", + "description": "Whether more pages are available." + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "List of workflow log entries." + } + } + }, + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Log entry ID." + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "Source of the workflow run (e.g., `service-api`)." + }, + "created_by_role": { + "type": "string", + "description": "Role of the creator (e.g., `end_user`, `account`)." + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "Account details if created by an admin user.", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the log entry was created." + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Additional details for the log entry." + } + } + }, + "WorkflowRunSummary": { "type": "object", - "required": ["type", "transfer_method"], "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "Type of file." }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "Transfer method, `remote_url` for image URL / `local_file` for file upload" }, - "url": { "type": "string", "format": "url", "description": "Image URL (when the transfer method is `remote_url`)" }, - "upload_file_id": { "type": "string", "description": "Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`)" } - }, - "anyOf": [ - { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." }, - { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "version": { + "type": "string", + "description": "Workflow version identifier." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total time elapsed in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "exceptions_count": { + "type": "integer", + "description": "Number of exceptions that occurred during execution." + }, + "triggered_from": { + "type": "string", + "description": "Source that triggered the workflow run. `debugging` for test runs from the editor, `app` for API or app-initiated runs." } - ] + } }, - "WorkflowCompletionResponse": { + "EndUserSummary": { "type": "object", - "description": "Response for blocking mode workflow execution.", "properties": { - "workflow_run_id": { "type": "string", "format": "uuid" }, - "task_id": { "type": "string", "format": "uuid" }, - "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "type": { + "type": "string", + "description": "End user type." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the end user is anonymous." + }, + "session_id": { + "type": "string", + "description": "Session identifier." + } } }, - "ChunkWorkflowEvent": { + "AudioToTextRequest": { "type": "object", - "required": ["event"], + "description": "Request body for audio-to-text conversion.", + "required": [ + "file" + ], "properties": { - "event": { "type": "string", "enum": ["workflow_started", "node_started", "text_chunk", "node_finished", "workflow_finished", "tts_message", "tts_message_end", "ping"] } - }, - "discriminator": { - "propertyName": "event", - "mapping": { - "workflow_started": "#/components/schemas/StreamEventWfWorkflowStarted", - "node_started": "#/components/schemas/StreamEventWfNodeStarted", - "text_chunk": "#/components/schemas/StreamEventWfTextChunk", - "node_finished": "#/components/schemas/StreamEventWfNodeFinished", - "workflow_finished": "#/components/schemas/StreamEventWfWorkflowFinished", - "tts_message": "#/components/schemas/StreamEventWfTtsMessage", - "tts_message_end": "#/components/schemas/StreamEventWfTtsMessageEnd", - "ping": "#/components/schemas/StreamEventWfPing" + "file": { + "type": "string", + "format": "binary", + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `15 MB`." + }, + "user": { + "type": "string", + "description": "User identifier." } } }, - "StreamEventBaseWf": { + "AudioToTextResponse": { "type": "object", "properties": { - "task_id": { "type": "string", "format": "uuid" }, - "workflow_run_id": { "type": "string", "format": "uuid" } + "text": { + "type": "string", + "description": "Output text from speech recognition." + } } }, - "StreamEventWfWorkflowStarted": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowStartedData" } } } ] - }, - "WorkflowStartedData": { - "type": "object", "required": ["id", "workflow_id", "sequence_number", "created_at"], - "properties": { "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "sequence_number": { "type": "integer" }, "created_at": { "type": "integer", "format": "int64" } } - }, - "StreamEventWfNodeStarted": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeStartedData" } } } ] - }, - "NodeStartedData": { - "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], - "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "format": "uuid" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true }, "inputs": { "type": "object", "additionalProperties": true }, "created_at": { "type": "integer", "format": "int64" } } - }, - "StreamEventWfTextChunk": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/TextChunkData" } } } ] - }, - "TextChunkData": { - "type": "object", "required": ["text", "from_variable_selector"], - "properties": { "text": { "type": "string" }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "description": "Text source path." } } - }, - "StreamEventWfNodeFinished": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeFinishedData" } } } ] - }, - "NodeFinishedData": { - "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "status", "created_at"], - "properties": { "id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "format": "uuid" }, "node_type": { "type": "string" }, "title": { "type": "string" }, "index": { "type": "integer" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float", "nullable": true }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadata" , "nullable": true }, "created_at": { "type": "integer", "format": "int64" } } - }, - "NodeExecutionMetadata": { - "type": "object", "properties": { "total_tokens": { "type": "integer", "nullable": true }, "total_price": { "type": "number", "format": "float", "nullable": true }, "currency": { "type": "string", "nullable": true, "example": "USD" } } - }, - "StreamEventWfWorkflowFinished": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedData" } } } ] - }, - "WorkflowFinishedData": { - "type": "object", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], - "properties": { "id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true }, "error": { "type": "string", "nullable": true }, "elapsed_time": { "type": "number", "format": "float", "nullable": true }, "total_tokens": { "type": "integer", "nullable": true }, "total_steps": { "type": "integer", "default": 0 }, "created_at": { "type": "integer", "format": "int64" }, "finished_at": { "type": "integer", "format": "int64" } } - }, - "StreamEventWfTtsMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "format": "byte" }, "message_id": {"type": "string", "format": "uuid"}, "created_at": {"type": "integer", "format":"int64"} } } - ] - }, - "StreamEventWfTtsMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "$ref": "#/components/schemas/StreamEventBaseWf" }, - { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string" }, "message_id": {"type": "string", "format": "uuid"}, "created_at": {"type": "integer", "format":"int64"} } } - ] - }, - "StreamEventWfPing": { - "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEvent" }, { "type": "object" } ] - }, - "WorkflowRunDetailResponse": { + "TextToAudioRequest": { "type": "object", + "description": "Request body for text-to-audio conversion. Provide either `message_id` or `text`.", "properties": { - "id": { "type": "string", "format": "uuid" }, - "workflow_id": { "type": "string", "format": "uuid" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, - "inputs": { "type": "string", "description": "JSON string of input content." }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "JSON object of output content." }, - "error": { "type": "string", "nullable": true }, - "total_steps": { "type": "integer" }, - "total_tokens": { "type": "integer" }, - "created_at": { "type": "integer", "format": "int64" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true } + "message_id": { + "type": "string", + "format": "uuid", + "description": "Message ID. Takes priority over `text` when both are provided." + }, + "text": { + "type": "string", + "description": "Speech content to convert." + }, + "user": { + "type": "string", + "description": "User identifier." + }, + "voice": { + "type": "string", + "description": "Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Use the `voice` value from [Get App Parameters](/api-reference/applications/get-app-parameters) → `text_to_speech.voice` for the default." + }, + "streaming": { + "type": "boolean", + "description": "Whether to enable streaming response." + } } }, - "FileUploadResponse": { - "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "size": { "type": "integer" }, "extension": { "type": "string" }, "mime_type": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" } } - }, - "EndUserDetail": { + "AppInfoResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "name": { + "type": "string", + "description": "Application name." + }, + "description": { + "type": "string", + "description": "Application description." + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Application tags." + }, + "mode": { + "type": "string", + "description": "Application mode. `completion` for text generation apps, `chat` for basic chat apps, `agent-chat` for agent-based apps, `advanced-chat` for chatflow apps, `workflow` for workflow apps." + }, + "author_name": { + "type": "string", + "description": "Name of the application author." + } } }, - "WorkflowLogsResponse": { + "WorkflowAppParametersResponse": { "type": "object", "properties": { - "page": { "type": "integer" }, - "limit": { "type": "integer" }, - "total": { "type": "integer" }, - "has_more": { "type": "boolean" }, - "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowLogItem" } } + "opening_statement": { + "type": "string", + "nullable": true, + "description": "Opening statement text." + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of suggested questions." + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "Configuration for suggested questions after an answer.", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "Speech-to-text feature configuration.", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "Text-to-speech feature configuration.", + "properties": { + "enabled": { + "type": "boolean" + }, + "voice": { + "type": "string" + }, + "language": { + "type": "string" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "Knowledge retrieval citation resource configuration.", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "Annotation reply feature configuration.", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "more_like_this": { + "type": "object", + "description": "More-like-this feature configuration.", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "Content moderation feature configuration.", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "user_input_form": { + "type": "array", + "items": { + "type": "object", + "oneOf": [ + { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "Display label for the input field." + }, + "variable": { + "type": "string", + "description": "Variable name used in the workflow." + }, + "required": { + "type": "boolean", + "description": "Whether this field is required." + }, + "default": { + "type": "string", + "description": "Default value for the input field." + } + } + } + } + }, + { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "Display label for the paragraph field." + }, + "variable": { + "type": "string", + "description": "Variable name used in the workflow." + }, + "required": { + "type": "boolean", + "description": "Whether this field is required." + }, + "default": { + "type": "string", + "description": "Default value for the paragraph field." + } + } + } + } + }, + { + "title": "Select", + "type": "object", + "properties": { + "select": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "Display label for the select field." + }, + "variable": { + "type": "string", + "description": "Variable name used in the workflow." + }, + "required": { + "type": "boolean", + "description": "Whether this field is required." + }, + "default": { + "type": "string", + "description": "Default selected value." + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of selectable values for this form control." + } + } + } + } + } + ] + }, + "description": "User input form configuration." + }, + "file_upload": { + "type": "object", + "description": "File upload configuration.", + "properties": { + "image": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether image upload is enabled." + }, + "number_limits": { + "type": "integer", + "description": "Maximum number of images that can be uploaded." + }, + "detail": { + "type": "string", + "description": "Image detail level for vision models." + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Allowed transfer methods for image upload. `remote_url` for file URL, `local_file` for uploaded file." + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "System-level parameter limits.", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "Maximum general file size in MB." + }, + "image_file_size_limit": { + "type": "integer", + "description": "Maximum image file size in MB." + }, + "audio_file_size_limit": { + "type": "integer", + "description": "Maximum audio file size in MB." + }, + "video_file_size_limit": { + "type": "integer", + "description": "Maximum video file size in MB." + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "Maximum number of files per workflow execution." + } + } + } } }, - "WorkflowLogItem": { + "ToolIconDetail": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "workflow_run": { "$ref": "#/components/schemas/WorkflowRunSummary" }, - "created_from": { "type": "string" }, - "created_by_role": { "type": "string" }, - "created_by_account": { "type": "string", "format": "uuid", "nullable": true }, - "created_by_end_user": { "$ref": "#/components/schemas/EndUserSummary" }, - "created_at": { "type": "integer", "format": "int64" } + "background": { + "type": "string", + "description": "Background color of the tool icon." + }, + "content": { + "type": "string", + "description": "Emoji or icon content." + } } }, - "WorkflowRunSummary": { + "AppMetaResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "version": { "type": "string" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"] }, - "error": { "type": "string", "nullable": true }, - "elapsed_time": { "type": "number", "format": "float" }, - "total_tokens": { "type": "integer" }, - "total_steps": { "type": "integer" }, - "created_at": { "type": "integer", "format": "int64" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true } + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "URL of the icon." + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "Tool icons. Keys are tool names." + } } }, - "EndUserSummary": { + "WebAppSettingsResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "type": { "type": "string" }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" } + "title": { + "type": "string", + "description": "WebApp title." + }, + "chat_color_theme": { + "type": "string", + "description": "Chat color theme." + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "Whether the chat color theme is inverted." + }, + "icon_type": { + "type": "string", + "description": "Type of icon used. `emoji` for emoji icons, `image` for uploaded image icons." + }, + "icon": { + "type": "string", + "description": "Icon content (emoji or image ID)." + }, + "icon_background": { + "type": "string", + "description": "Icon background color." + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "URL of the icon image." + }, + "description": { + "type": "string", + "description": "WebApp description." + }, + "copyright": { + "type": "string", + "description": "Copyright text." + }, + "privacy_policy": { + "type": "string", + "description": "Privacy policy URL." + }, + "custom_disclaimer": { + "type": "string", + "description": "Custom disclaimer text." + }, + "default_language": { + "type": "string", + "description": "Default language code." + }, + "show_workflow_steps": { + "type": "boolean", + "description": "Whether to show workflow steps." + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "Whether to use the app icon as the answer icon." + } } }, - "AppInfoResponse": { - "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of paused node IDs." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "Partial outputs at pause time." + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Reasons for pausing." + }, + "status": { + "type": "string", + "description": "Workflow execution status." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total elapsed time in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total steps executed." + } + } + } + } + } + ] }, - "WorkflowAppParametersResponse": { - "type": "object", "properties": { "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItem" } }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } } } } }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer" }, "image_file_size_limit": { "type": "integer" }, "audio_file_size_limit": { "type": "integer" }, "video_file_size_limit": { "type": "integer" } } } } - }, - "UserInputFormItem": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapper" }, { "$ref": "#/components/schemas/ParagraphControlWrapper" }, { "$ref": "#/components/schemas/SelectControlWrapper" } ] }, - "TextInputControlWrapper": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } }, "required":["text-input"] }, - "ParagraphControlWrapper": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } }, "required":["paragraph"] }, - "SelectControlWrapper": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } }, "required":["select"] }, - "TextInputControl": { "type": "object", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } }, - "ParagraphControl": { "type": "object", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" } } }, - "SelectControl": { "type": "object", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string" }, "variable": { "type": "string" }, "required": { "type": "boolean" }, "default": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } } }, - "WorkflowWebAppSettingsResponse": { - "type": "object", "properties": { "title": { "type": "string" }, "icon_type": { "type": "string", "enum": ["emoji", "image"] }, "icon": { "type": "string" }, "icon_background": { "type": "string" }, "icon_url": { "type": "string", "format": "url", "nullable": true }, "description": { "type": "string" }, "copyright": { "type": "string" }, "privacy_policy": { "type": "string" }, "custom_disclaimer": { "type": "string" }, "default_language": { "type": "string" }, "show_workflow_steps": { "type": "boolean" } } - }, - "ErrorResponse": { "type": "object", "properties": { "status": { "type": "integer", "nullable": true }, "code": { "type": "string", "nullable": true }, "message": { "type": "string" } } } + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "Node execution ID." + }, + "id": { + "type": "string", + "description": "Agent log entry ID." + }, + "label": { + "type": "string", + "description": "Log label." + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "Parent log entry ID." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the agent step failed." + }, + "status": { + "type": "string", + "description": "Agent step status." + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "Agent step data." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Agent step metadata." + }, + "node_id": { + "type": "string", + "description": "Node ID." + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "Form ID." + }, + "node_id": { + "type": "string", + "description": "Node ID requesting input." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "form_content": { + "type": "string", + "description": "Form content description." + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Form input field definitions." + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Available user actions." + }, + "display_in_ui": { + "type": "boolean", + "description": "Whether to display the form in the UI." + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "Token for form submission." + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "Pre-resolved default values for form fields." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in seconds when the form expires." + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "Rendered content after form submission." + }, + "action_id": { + "type": "string", + "description": "ID of the action taken." + }, + "action_text": { + "type": "string", + "description": "Text of the action taken." + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp when the form expired." + } + } + } + } + } + ] + } } }, "tags": [ - { "name": "Workflow Execution", "description": "Operations related to executing and managing workflows." }, - { "name": "Files", "description": "File upload and preview operations specific to workflows." }, - { "name": "End Users", "description": "Operations related to end user information." }, - { "name": "Application", "description": "Application settings and info for workflow apps." } + { + "name": "Workflows", + "description": "Operations for executing and managing workflows." + }, + { + "name": "Files", + "description": "File upload and download operations." + }, + { + "name": "End Users", + "description": "Operations related to end user information." + }, + { + "name": "TTS", + "description": "Audio-to-text and text-to-audio conversion." + }, + { + "name": "Applications", + "description": "Application settings, parameters, and metadata." + } ] } From 5f28a4c1b6010c0fd1c52b210aaf50f7cf471af7 Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Thu, 19 Mar 2026 22:29:04 +0800 Subject: [PATCH 2/6] final check and add zh/ja docs --- docs.json | 2 +- en/api-reference/openapi_chat.json | 43 +- en/api-reference/openapi_chatflow.json | 1010 ++- en/api-reference/openapi_completion.json | 57 +- en/api-reference/openapi_knowledge.json | 259 +- en/api-reference/openapi_workflow.json | 46 +- ja/api-reference/openapi_chat.json | 4701 +++++++++++-- ja/api-reference/openapi_chatflow.json | 6517 +++++++++++++++++-- ja/api-reference/openapi_completion.json | 2652 +++++++- ja/api-reference/openapi_knowledge.json | 7514 +++++++++++++++------ ja/api-reference/openapi_workflow.json | 3892 ++++++++++- zh/api-reference/openapi_chat.json | 4755 ++++++++++++-- zh/api-reference/openapi_chatflow.json | 6599 +++++++++++++++++-- zh/api-reference/openapi_completion.json | 2787 ++++++-- zh/api-reference/openapi_knowledge.json | 7596 ++++++++++++++++------ zh/api-reference/openapi_workflow.json | 3897 ++++++++++- 16 files changed, 44518 insertions(+), 7809 deletions(-) diff --git a/docs.json b/docs.json index c44335a27..30e348d94 100644 --- a/docs.json +++ b/docs.json @@ -677,7 +677,7 @@ "openapi": "zh/api-reference/openapi_chat.json" }, { - "group": "Chatflow", + "group": "对话流", "openapi": "zh/api-reference/openapi_chatflow.json" }, { diff --git a/en/api-reference/openapi_chat.json b/en/api-reference/openapi_chat.json index 182599e78..45dc1b960 100644 --- a/en/api-reference/openapi_chat.json +++ b/en/api-reference/openapi_chat.json @@ -870,7 +870,7 @@ { "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", - "conversation_id": "56812a93-9229-5cd6-9f0c-75673b6666g3", + "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.", @@ -1596,7 +1596,7 @@ "/audio-to-text": { "post": { "summary": "Convert Audio to Text", - "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `15 MB`.", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", "operationId": "chatAudioToText", "tags": [ "TTS" @@ -1839,40 +1839,6 @@ } } }, - "413": { - "description": "`audio_too_large` : Audio file size exceeded.", - "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` : Audio type not allowed.", - "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` : Internal server error.", "content": { @@ -2611,8 +2577,7 @@ "streaming", "blocking" ], - "default": "blocking", - "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes; not supported in Agent Assistant mode). Cloudflare timeout is `100 s`." + "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes; not supported in Agent Assistant mode). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior." }, "user": { "type": "string", @@ -3816,7 +3781,7 @@ "file": { "type": "string", "format": "binary", - "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `15 MB`." + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `30 MB`." }, "user": { "type": "string", diff --git a/en/api-reference/openapi_chatflow.json b/en/api-reference/openapi_chatflow.json index b8eac2fde..5de360e1f 100644 --- a/en/api-reference/openapi_chatflow.json +++ b/en/api-reference/openapi_chatflow.json @@ -128,7 +128,7 @@ "text/event-stream": { "schema": { "type": "string", - "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkChatEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. The stream ends when a `message_end` event is received. Ignore `ping` events (sent every 10 seconds to keep the connection alive). If an `error` event is received mid-stream, the stream terminates — parse the error object for details. Note that the HTTP status code is always `200` even when an error event occurs within the stream." + "description": "A stream of Server-Sent Events (SSE). Each event is a JSON object prefixed with `data: ` and terminated by two newlines. See `ChunkChatEvent` for possible event structures.\n\n**SSE Parsing Guide:** Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\\n\\n`. Strip the `data: ` prefix before parsing JSON. The `event` field inside the JSON determines the event type. `message_end` marks the end of the chat message, but the stream may continue with workflow lifecycle events such as `workflow_finished` or `workflow_paused`. The stream ends when a terminal workflow event is received, or when an `error` event terminates the stream. Ignore `ping` events (sent every 10 seconds to keep the connection alive). Note that the HTTP status code is always `200` even when an error event occurs within the stream." }, "examples": { "streamingResponseBasic": { @@ -137,7 +137,7 @@ }, "streamingResponseWorkflow": { "summary": "Response Example - Streaming (Workflow)", - "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}}" + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}" } } } @@ -894,7 +894,7 @@ { "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", - "conversation_id": "56812a93-9229-5cd6-9f0c-75673b6666g3", + "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.", @@ -1623,7 +1623,7 @@ "TTS" ], "summary": "Convert Audio to Text", - "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `15 MB`.", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", "requestBody": { "required": true, "content": { @@ -1862,40 +1862,6 @@ } } }, - "413": { - "description": "`audio_too_large` : Audio file size exceeded.", - "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` : Audio type not allowed.", - "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` : Internal server error.", "content": { @@ -2573,6 +2539,234 @@ } } } + }, + "/workflows/run/{workflow_run_id}": { + "get": { + "summary": "Get Workflow Run Detail", + "description": "Retrieve the current execution results of a workflow task based on the workflow execution ID.", + "operationId": "getChatflowWorkflowRunDetail", + "tags": [ + "Workflow Runs" + ], + "parameters": [ + { + "name": "workflow_run_id", + "in": "path", + "required": true, + "description": "Workflow run ID, can be obtained from the streaming events or message metadata.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved workflow run details.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "Response Example", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } + } + } + }, + "400": { + "description": "`not_workflow_app` : App mode does not match the API route.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : Workflow run not found.", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } + } + } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "List Workflow Logs", + "description": "Retrieve paginated workflow execution logs with filtering options.", + "operationId": "listChatflowWorkflowLogs", + "tags": [ + "Workflow Runs" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "Keyword to search in logs.", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "Filter by execution status.", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "Page number for pagination.", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "Number of items per page.", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "Filter logs created before this ISO 8601 timestamp.", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "Filter logs created after this ISO 8601 timestamp.", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "Filter by end user session ID.", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "Filter by account ID.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successfully retrieved workflow logs.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "Response Example", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0 + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_chatflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } + } + } } }, "components": { @@ -2634,8 +2828,7 @@ "streaming", "blocking" ], - "default": "blocking", - "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`." + "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior." }, "user": { "type": "string", @@ -2780,8 +2973,13 @@ "loop_started", "loop_next", "loop_completed", + "workflow_paused", "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", "agent_log", + "text_chunk", + "text_replace", "error", "ping" ] @@ -2807,8 +3005,13 @@ "loop_started": "#/components/schemas/StreamEventLoopStarted", "loop_next": "#/components/schemas/StreamEventLoopNext", "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout", "agent_log": "#/components/schemas/StreamEventAgentLog", + "text_chunk": "#/components/schemas/StreamEventChatTextChunk", + "text_replace": "#/components/schemas/StreamEventChatTextReplace", "error": "#/components/schemas/StreamEventChatError", "ping": "#/components/schemas/StreamEventChatPing" } @@ -3522,6 +3725,13 @@ "type": "integer", "format": "int64", "description": "Creation timestamp (Unix epoch seconds)." + }, + "extra_contents": { + "type": "array", + "description": "Additional execution content associated with this message, such as human input form data from Human Input nodes in chatflow workflows.", + "items": { + "$ref": "#/components/schemas/HumanInputContent" + } } } }, @@ -3795,7 +4005,7 @@ "file": { "type": "string", "format": "binary", - "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `15 MB`." + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `30 MB`." }, "user": { "type": "string", @@ -4432,6 +4642,10 @@ "type": "integer", "format": "int64", "description": "Start timestamp (Unix epoch seconds)." + }, + "reason": { + "type": "string", + "description": "Reason for workflow start. `initial` for first start, `resumption` when resuming after a pause (e.g., after human input)." } } } @@ -4468,14 +4682,7 @@ }, "status": { "type": "string", - "enum": [ - "running", - "succeeded", - "failed", - "stopped", - "partial-succeeded" - ], - "description": "Execution status." + "description": "Execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `stopped` if manually stopped, `partial-succeeded` if partially completed, `paused` when waiting for human input." }, "outputs": { "type": "object", @@ -4514,7 +4721,6 @@ "exceptions_count": { "type": "integer", "nullable": true, - "default": 0, "description": "Number of exceptions during execution." }, "files": { @@ -4672,13 +4878,7 @@ }, "status": { "type": "string", - "enum": [ - "running", - "succeeded", - "failed", - "exception" - ], - "description": "Node execution status." + "description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred." }, "error": { "type": "string", @@ -4794,13 +4994,7 @@ }, "status": { "type": "string", - "enum": [ - "running", - "succeeded", - "failed", - "exception" - ], - "description": "Node execution status." + "description": "Node execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred." }, "error": { "type": "string", @@ -4848,8 +5042,7 @@ }, "retry_index": { "type": "integer", - "default": 0, - "description": "Retry attempt index (0-based)." + "description": "Retry attempt index, starts at `0`." } } } @@ -5016,13 +5209,7 @@ }, "status": { "type": "string", - "enum": [ - "running", - "succeeded", - "failed", - "exception" - ], - "description": "Iteration execution status." + "description": "Iteration execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred." }, "error": { "type": "string", @@ -5219,13 +5406,7 @@ }, "status": { "type": "string", - "enum": [ - "running", - "succeeded", - "failed", - "exception" - ], - "description": "Loop execution status." + "description": "Loop execution status. `running` while in progress, `succeeded` on success, `failed` on failure, `exception` if an exception occurred." }, "error": { "type": "string", @@ -5327,7 +5508,7 @@ } ] }, - "StreamEventAgentLog": { + "StreamEventWorkflowPaused": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEvent" @@ -5337,64 +5518,651 @@ }, { "type": "object", - "description": "Agent log from an agent node within the workflow.", "properties": { "data": { "type": "object", "properties": { - "node_execution_id": { - "type": "string", - "description": "Node execution ID." - }, - "id": { + "workflow_run_id": { "type": "string", - "description": "Log entry ID." + "format": "uuid", + "description": "Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution." }, - "label": { - "type": "string", - "description": "Log entry label." + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of paused node IDs." }, - "parent_id": { - "type": "string", - "nullable": true, - "description": "Parent log entry ID for nested entries." + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "Partial outputs at pause time." }, - "error": { - "type": "string", - "nullable": true, - "description": "Error message if applicable." + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "Reasons for pausing." }, "status": { "type": "string", - "description": "Log entry status." + "description": "Workflow execution status." }, - "data": { - "type": "object", - "additionalProperties": true, - "description": "Log entry data." + "created_at": { + "type": "integer", + "format": "int64", + "description": "Creation timestamp." }, - "metadata": { - "type": "object", - "additionalProperties": true, - "description": "Additional metadata." + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total elapsed time in seconds." }, - "node_id": { - "type": "string", - "description": "Node ID in the workflow graph." + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total steps executed." } } } } } ] - } - } - }, - "tags": [ - { - "name": "Chats", - "description": "Operations related to chat messages and interactions." - }, + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "Rendered content after form submission." + }, + "action_id": { + "type": "string", + "description": "ID of the action taken." + }, + "action_text": { + "type": "string", + "description": "Text of the action taken." + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "Workflow execution run ID." + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp when the form expired." + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "Agent log from an agent node within the workflow.", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "Node execution ID." + }, + "id": { + "type": "string", + "description": "Log entry ID." + }, + "label": { + "type": "string", + "description": "Log entry label." + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "Parent log entry ID for nested entries." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if applicable." + }, + "status": { + "type": "string", + "description": "Log entry status." + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "Log entry data." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Additional metadata." + }, + "node_id": { + "type": "string", + "description": "Node ID in the workflow graph." + } + } + } + } + } + ] + }, + "StreamEventChatTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The text content chunk." + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "Source path of the text variable in the workflow." + } + } + } + } + } + ] + }, + "StreamEventChatTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "The replacement text content." + } + } + } + } + } + ] + }, + "WorkflowRunDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "Input variables for the workflow run." + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Output data from the workflow." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "Total time elapsed in seconds." + } + } + }, + "WorkflowLogsResponse": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "description": "Current page number." + }, + "limit": { + "type": "integer", + "description": "Number of items per page." + }, + "total": { + "type": "integer", + "description": "Total number of log entries." + }, + "has_more": { + "type": "boolean", + "description": "Whether more pages are available." + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "List of workflow log entries." + } + } + }, + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Log entry ID." + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "Source of the workflow run (e.g., `service-api`)." + }, + "created_by_role": { + "type": "string", + "description": "Role of the creator (e.g., `end_user`, `account`)." + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "Account details if created by an admin user.", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the log entry was created." + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "Additional details for the log entry." + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "version": { + "type": "string", + "description": "Workflow version identifier." + }, + "status": { + "type": "string", + "description": "Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input." + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message if the workflow failed." + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "Total time elapsed in seconds." + }, + "total_tokens": { + "type": "integer", + "description": "Total tokens consumed." + }, + "total_steps": { + "type": "integer", + "description": "Total number of workflow steps executed." + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp of when the workflow run was created." + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "Unix timestamp of when the workflow run finished." + }, + "exceptions_count": { + "type": "integer", + "description": "Number of exceptions that occurred during execution." + }, + "triggered_from": { + "type": "string", + "description": "Source that triggered the workflow run. `debugging` for test runs from the editor, `app` for API or app-initiated runs." + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "End user ID." + }, + "type": { + "type": "string", + "description": "End user type." + }, + "is_anonymous": { + "type": "boolean", + "description": "Whether the end user is anonymous." + }, + "session_id": { + "type": "string", + "description": "Session identifier." + } + } + }, + "HumanInputContent": { + "type": "object", + "description": "Execution content from a Human Input node, including form definition and submission data.", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ID of the workflow run this content belongs to." + }, + "submitted": { + "type": "boolean", + "description": "Whether the human input form has been submitted." + }, + "type": { + "type": "string", + "description": "`human_input` for human input content." + }, + "form_definition": { + "nullable": true, + "description": "Form definition from the Human Input node. `null` when the content represents a submission response.", + "$ref": "#/components/schemas/HumanInputFormDefinition" + }, + "form_submission_data": { + "nullable": true, + "description": "Submitted form data. `null` when the form has not been submitted yet.", + "$ref": "#/components/schemas/HumanInputFormSubmissionData" + } + } + }, + "HumanInputFormDefinition": { + "type": "object", + "description": "Definition of a human input form rendered by a Human Input node.", + "properties": { + "form_id": { + "type": "string", + "description": "Unique form identifier." + }, + "node_id": { + "type": "string", + "description": "ID of the Human Input node that generated this form." + }, + "node_title": { + "type": "string", + "description": "Title of the Human Input node." + }, + "form_content": { + "type": "string", + "description": "Markdown or text content displayed with the form." + }, + "inputs": { + "type": "array", + "description": "Input fields in the form.", + "items": { + "$ref": "#/components/schemas/FormInput" + } + }, + "actions": { + "type": "array", + "description": "Action buttons available on the form.", + "items": { + "$ref": "#/components/schemas/UserAction" + } + }, + "display_in_ui": { + "type": "boolean", + "description": "Whether the form should be displayed in the UI." + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "Token for form submission authentication." + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "Resolved default values for form inputs, keyed by output variable name." + }, + "expiration_time": { + "type": "integer", + "description": "Unix timestamp when the form expires." + } + } + }, + "HumanInputFormSubmissionData": { + "type": "object", + "description": "Data from a submitted human input form.", + "properties": { + "node_id": { + "type": "string", + "description": "ID of the Human Input node." + }, + "node_title": { + "type": "string", + "description": "Title of the Human Input node." + }, + "rendered_content": { + "type": "string", + "description": "Rendered content of the form submission." + }, + "action_id": { + "type": "string", + "description": "ID of the action button that was clicked." + }, + "action_text": { + "type": "string", + "description": "Display text of the action button that was clicked." + } + } + }, + "FormInput": { + "type": "object", + "description": "A form input field definition.", + "properties": { + "type": { + "type": "string", + "description": "`text_input` for single-line text, `paragraph` for multi-line text." + }, + "output_variable_name": { + "type": "string", + "description": "Variable name where the input value is stored." + }, + "default": { + "nullable": true, + "description": "Default value configuration for this input.", + "$ref": "#/components/schemas/FormInputDefault" + } + } + }, + "FormInputDefault": { + "type": "object", + "description": "Default value configuration for a form input.", + "properties": { + "type": { + "type": "string", + "description": "`variable` for dynamic values from workflow variables, `constant` for static values." + }, + "selector": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Variable selector path when `type` is `variable`." + }, + "value": { + "type": "string", + "description": "Static value when `type` is `constant`." + } + } + }, + "UserAction": { + "type": "object", + "description": "An action button on a human input form.", + "properties": { + "id": { + "type": "string", + "description": "Unique action identifier." + }, + "title": { + "type": "string", + "description": "Button display text." + }, + "button_style": { + "type": "string", + "description": "`primary`, `default`, `accent`, or `ghost`." + } + } + } + } + }, + "tags": [ + { + "name": "Chats", + "description": "Operations related to chat messages and interactions." + }, { "name": "Files", "description": "File upload and preview operations." @@ -5422,6 +6190,10 @@ { "name": "Annotations", "description": "Operations related to managing annotations for direct replies." + }, + { + "name": "Workflow Runs", + "description": "Operations related to workflow execution details and logs." } ] } diff --git a/en/api-reference/openapi_completion.json b/en/api-reference/openapi_completion.json index 5af6289dc..c18cfeeca 100644 --- a/en/api-reference/openapi_completion.json +++ b/en/api-reference/openapi_completion.json @@ -176,7 +176,7 @@ } }, "429": { - "description": "- `too_many_requests` : Too many concurrent requests for this app.\n- `rate_limit_error` : The upstream model provider rate limit was exceeded.", + "description": "`too_many_requests` : Too many concurrent requests for this app.", "content": { "application/json": { "examples": { @@ -187,14 +187,6 @@ "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" - } } } } @@ -415,7 +407,7 @@ { "id": "c8f3a9b2-4d5e-6f70-8901-bcdef2345678", "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", - "conversation_id": "56812a93-9229-5cd6-9f0c-75673b6666g3", + "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.", @@ -733,7 +725,7 @@ "TTS" ], "summary": "Convert Audio to Text", - "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `15 MB`.", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", "requestBody": { "required": true, "content": { @@ -972,40 +964,6 @@ } } }, - "413": { - "description": "`audio_too_large` : Audio file size exceeded.", - "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` : Audio type not allowed.", - "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` : Internal server error.", "content": { @@ -1269,7 +1227,7 @@ "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", - "description": "API Key authentication. For all API requests, include your API Key in the Authorization HTTP Header, prefixed with 'Bearer '. Example: Authorization: Bearer {API_KEY}. Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences." + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" } }, "responses": { @@ -1322,8 +1280,7 @@ "streaming", "blocking" ], - "default": "blocking", - "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`." + "description": "Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior." }, "user": { "type": "string", @@ -1958,7 +1915,7 @@ "external_user_id": { "type": "string", "nullable": true, - "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Chat Message](/api-reference/chats/send-chat-message))." + "description": "The `user` identifier provided in API requests (e.g., the `user` field in [Send Completion Message](/api-reference/completions/send-completion-message))." }, "name": { "type": "string", @@ -2095,7 +2052,7 @@ "file": { "type": "string", "format": "binary", - "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `15 MB`." + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `30 MB`." }, "user": { "type": "string", diff --git a/en/api-reference/openapi_knowledge.json b/en/api-reference/openapi_knowledge.json index c767d23ce..fd28026c9 100644 --- a/en/api-reference/openapi_knowledge.json +++ b/en/api-reference/openapi_knowledge.json @@ -225,7 +225,7 @@ } }, "409": { - "description": "- `dataset_name_duplicate` : The dataset name already exists. Please modify your dataset name.", + "description": "`dataset_name_duplicate` : The dataset name already exists. Please modify your dataset name.", "content": { "application/json": { "examples": { @@ -487,7 +487,7 @@ } }, "403": { - "description": "- `forbidden` : Insufficient permissions to access this knowledge base.", + "description": "`forbidden` : Insufficient permissions to access this knowledge base.", "content": { "application/json": { "examples": { @@ -504,7 +504,7 @@ } }, "404": { - "description": "- `not_found` : Dataset not found.", + "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { @@ -699,7 +699,7 @@ } }, "403": { - "description": "- `forbidden` : Insufficient permissions to access this knowledge base.", + "description": "`forbidden` : Insufficient permissions to access this knowledge base.", "content": { "application/json": { "examples": { @@ -716,7 +716,7 @@ } }, "404": { - "description": "- `not_found` : Dataset not found.", + "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { @@ -758,7 +758,7 @@ "description": "Success." }, "404": { - "description": "- `not_found` : Dataset not found.", + "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { @@ -775,7 +775,7 @@ } }, "409": { - "description": "- `dataset_in_use` : The knowledge base is being used by some apps. Please remove it from the apps before deleting.", + "description": "`dataset_in_use` : The knowledge base is being used by some apps. Please remove it from the apps before deleting.", "content": { "application/json": { "examples": { @@ -882,7 +882,11 @@ "properties": { "id": { "type": "string", - "enum": ["remove_stopwords", "remove_extra_spaces", "remove_urls_emails"], + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], "description": "Rule identifier." }, "enabled": { @@ -1150,7 +1154,7 @@ } }, "400": { - "description": "- `no_file_uploaded` : Please upload your file.\n- `too_many_files` : Only one file is allowed.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist.", + "description": "- `no_file_uploaded` : Please upload your file.\n- `too_many_files` : Only one file is allowed.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist, external datasets not supported, file too large, unsupported file type, or missing required fields.", "content": { "application/json": { "examples": { @@ -1202,6 +1206,22 @@ "message": "External datasets are not supported." } }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + }, "invalid_param_indexing": { "summary": "invalid_param (indexing_technique)", "value": { @@ -1221,40 +1241,6 @@ } } } - }, - "413": { - "description": "- `file_too_large` : File size exceeded.", - "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` : File type not allowed.", - "content": { - "application/json": { - "examples": { - "unsupported_file_type": { - "summary": "unsupported_file_type", - "value": { - "status": 415, - "code": "unsupported_file_type", - "message": "File type not allowed." - } - } - } - } - } } } } @@ -1294,7 +1280,7 @@ "type": "integer", "default": 20 }, - "description": "Number of items per page." + "description": "Number of items per page. Server caps at `100`." }, { "name": "keyword", @@ -1309,7 +1295,15 @@ "in": "query", "schema": { "type": "string", - "enum": ["queuing", "indexing", "paused", "error", "available", "disabled", "archived"] + "enum": [ + "queuing", + "indexing", + "paused", + "error", + "available", + "disabled", + "archived" + ] }, "description": "Filter by display status." } @@ -1402,7 +1396,7 @@ } }, "404": { - "description": "- `not_found` : Knowledge base not found.", + "description": "`not_found` : Knowledge base not found.", "content": { "application/json": { "examples": { @@ -1689,7 +1683,7 @@ } }, "400": { - "description": "- `invalid_metadata` : Invalid metadata value for the specified key.", + "description": "`invalid_metadata` : Invalid metadata value for the specified key.", "content": { "application/json": { "examples": { @@ -1706,7 +1700,7 @@ } }, "403": { - "description": "- `forbidden` : No permission.", + "description": "`forbidden` : No permission.", "content": { "application/json": { "examples": { @@ -1723,7 +1717,7 @@ } }, "404": { - "description": "- `not_found` : Document not found.", + "description": "`not_found` : Document not found.", "content": { "application/json": { "examples": { @@ -1775,7 +1769,7 @@ "description": "Success." }, "400": { - "description": "- `document_indexing` : Cannot delete document during indexing.", + "description": "`document_indexing` : Cannot delete document during indexing.", "content": { "application/json": { "examples": { @@ -1792,7 +1786,7 @@ } }, "403": { - "description": "- `archived_document_immutable` : The archived document is not editable.", + "description": "`archived_document_immutable` : The archived document is not editable.", "content": { "application/json": { "examples": { @@ -1809,7 +1803,7 @@ } }, "404": { - "description": "- `not_found` : Document Not Exists.", + "description": "`not_found` : Document Not Exists.", "content": { "application/json": { "examples": { @@ -1884,7 +1878,7 @@ } }, "403": { - "description": "- `forbidden` : No permission to access this document.", + "description": "`forbidden` : No permission to access this document.", "content": { "application/json": { "examples": { @@ -1901,7 +1895,7 @@ } }, "404": { - "description": "- `not_found` : Document not found.", + "description": "`not_found` : Document not found.", "content": { "application/json": { "examples": { @@ -2042,7 +2036,7 @@ } }, "404": { - "description": "- `not_found` : Knowledge base not found. / Documents not found.", + "description": "`not_found` : Knowledge base not found. / Documents not found.", "content": { "application/json": { "examples": { @@ -2140,7 +2134,11 @@ "properties": { "id": { "type": "string", - "enum": ["remove_stopwords", "remove_extra_spaces", "remove_urls_emails"], + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], "description": "Rule identifier." }, "enabled": { @@ -2264,7 +2262,7 @@ } }, "400": { - "description": "- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist.", + "description": "- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist, or name is required when text is provided.", "content": { "application/json": { "examples": { @@ -2283,6 +2281,14 @@ "code": "invalid_param", "message": "Dataset does not exist." } + }, + "invalid_param_name_required": { + "summary": "invalid_param (name required)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "name is required when text is provided." + } } } } @@ -2410,7 +2416,7 @@ } }, "400": { - "description": "- `too_many_files` : Only one file is allowed.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist.", + "description": "- `too_many_files` : Only one file is allowed.\n- `filename_not_exists_error` : The specified filename does not exist.\n- `provider_not_initialize` : No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.\n- `invalid_param` : Knowledge base does not exist, external datasets not supported, file too large, or unsupported file type.", "content": { "application/json": { "examples": { @@ -2439,44 +2445,34 @@ } }, "invalid_param_dataset": { - "summary": "invalid_param", + "summary": "invalid_param (dataset)", "value": { "status": 400, "code": "invalid_param", "message": "Dataset does not exist." } - } - } - } - } - }, - "413": { - "description": "- `file_too_large` : File size exceeded.", - "content": { - "application/json": { - "examples": { - "file_too_large": { - "summary": "file_too_large", + }, + "invalid_param_external": { + "summary": "invalid_param (external)", "value": { - "status": 413, - "code": "file_too_large", + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", "message": "File size exceeded." } - } - } - } - } - }, - "415": { - "description": "- `unsupported_file_type` : File type not allowed.", - "content": { - "application/json": { - "examples": { - "unsupported_file_type": { - "summary": "unsupported_file_type", + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", "value": { - "status": 415, - "code": "unsupported_file_type", + "status": 400, + "code": "invalid_param", "message": "File type not allowed." } } @@ -2546,7 +2542,7 @@ } }, "403": { - "description": "- `forbidden` : Insufficient permissions.", + "description": "`forbidden` : Insufficient permissions.", "content": { "application/json": { "examples": { @@ -2563,7 +2559,7 @@ } }, "404": { - "description": "- `not_found` : Document or dataset not found.", + "description": "`not_found` : Document or dataset not found.", "content": { "application/json": { "examples": { @@ -2665,7 +2661,7 @@ } }, "400": { - "description": "- `invalid_action` : Invalid action.", + "description": "`invalid_action` : Invalid action.", "content": { "application/json": { "examples": { @@ -2682,7 +2678,7 @@ } }, "403": { - "description": "- `forbidden` : Insufficient permissions.", + "description": "`forbidden` : Insufficient permissions.", "content": { "application/json": { "examples": { @@ -2699,7 +2695,7 @@ } }, "404": { - "description": "- `not_found` : Knowledge base not found.", + "description": "`not_found` : Knowledge base not found.", "content": { "application/json": { "examples": { @@ -2859,6 +2855,31 @@ } } } + }, + "404": { + "description": "`not_found` : Document is not completed or is disabled.", + "content": { + "application/json": { + "examples": { + "not_found_not_completed": { + "summary": "not_found (not completed)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is not completed." + } + }, + "not_found_disabled": { + "summary": "not_found (disabled)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is disabled." + } + } + } + } + } } } }, @@ -2906,7 +2927,7 @@ "type": "integer", "default": 20 }, - "description": "Number of items per page." + "description": "Number of items per page. Server caps at `100`." }, { "name": "status", @@ -3420,7 +3441,7 @@ } }, "400": { - "description": "- `invalid_param` : Create child chunk index failed.", + "description": "`invalid_param` : Create child chunk index failed.", "content": { "application/json": { "examples": { @@ -3494,7 +3515,7 @@ "default": 20, "minimum": 1 }, - "description": "Number of items per page." + "description": "Number of items per page. Server caps at `100`." }, { "name": "keyword", @@ -3669,7 +3690,7 @@ } }, "400": { - "description": "- `invalid_param` : Update child chunk index failed.", + "description": "`invalid_param` : Update child chunk index failed.", "content": { "application/json": { "examples": { @@ -3741,7 +3762,7 @@ "description": "Success." }, "400": { - "description": "- `invalid_param` : Delete child chunk index failed.", + "description": "`invalid_param` : Delete child chunk index failed.", "content": { "application/json": { "examples": { @@ -4176,7 +4197,7 @@ } }, "403": { - "description": "- `forbidden` : Insufficient permissions.", + "description": "`forbidden` : Insufficient permissions.", "content": { "application/json": { "examples": { @@ -4193,7 +4214,7 @@ } }, "404": { - "description": "- `not_found` : Knowledge base not found.", + "description": "`not_found` : Knowledge base not found.", "content": { "application/json": { "examples": { @@ -4210,7 +4231,7 @@ } }, "500": { - "description": "- `internal_server_error` : An internal error occurred during retrieval.", + "description": "`internal_server_error` : An internal error occurred during retrieval.", "content": { "application/json": { "examples": { @@ -5450,7 +5471,7 @@ } }, "413": { - "description": "- `file_too_large` : File size exceeded.", + "description": "`file_too_large` : File size exceeded.", "content": { "application/json": { "examples": { @@ -5467,7 +5488,7 @@ } }, "415": { - "description": "- `unsupported_file_type` : File type not allowed.", + "description": "`unsupported_file_type` : File type not allowed.", "content": { "application/json": { "examples": { @@ -5556,7 +5577,7 @@ } }, "404": { - "description": "- `not_found` : Dataset not found.", + "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { @@ -5623,7 +5644,12 @@ }, "datasource_type": { "type": "string", - "enum": ["online_document", "local_file", "website_crawl", "online_drive"], + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], "description": "Type of the datasource." }, "credential_id": { @@ -5653,7 +5679,7 @@ } }, "404": { - "description": "- `not_found` : Dataset not found.", + "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { @@ -5714,7 +5740,12 @@ }, "datasource_type": { "type": "string", - "enum": ["online_document", "local_file", "website_crawl", "online_drive"], + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], "description": "Type of the datasource." }, "datasource_info_list": { @@ -5735,7 +5766,10 @@ }, "response_mode": { "type": "string", - "enum": ["streaming", "blocking"], + "enum": [ + "streaming", + "blocking" + ], "description": "Response mode for the pipeline execution. `streaming` returns a Server-Sent Events stream, `blocking` waits and returns the complete result." } } @@ -5779,7 +5813,7 @@ } }, "403": { - "description": "- `forbidden` : Forbidden.", + "description": "`forbidden` : Forbidden.", "content": { "application/json": { "examples": { @@ -5796,7 +5830,7 @@ } }, "404": { - "description": "- `not_found` : Dataset not found.", + "description": "`not_found` : Dataset not found.", "content": { "application/json": { "examples": { @@ -5813,7 +5847,7 @@ } }, "500": { - "description": "- `pipeline_run_error` : Pipeline execution failed.", + "description": "`pipeline_run_error` : Pipeline execution failed.", "content": { "application/json": { "examples": { @@ -6526,7 +6560,10 @@ }, "reranking_mode": { "type": "string", - "enum": ["reranking_model", "weighted_score"], + "enum": [ + "reranking_model", + "weighted_score" + ], "nullable": true, "description": "Reranking mode. Required when `reranking_enable` is `true`." }, diff --git a/en/api-reference/openapi_workflow.json b/en/api-reference/openapi_workflow.json index 72e5c3ac1..787900288 100644 --- a/en/api-reference/openapi_workflow.json +++ b/en/api-reference/openapi_workflow.json @@ -645,7 +645,8 @@ "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630, - "exceptions_count": 0 + "exceptions_count": 0, + "triggered_from": "app" }, "created_from": "service-api", "created_by_role": "end_user", @@ -1044,7 +1045,7 @@ "TTS" ], "summary": "Convert Audio to Text", - "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `15 MB`.", + "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", "requestBody": { "required": true, "content": { @@ -1283,40 +1284,6 @@ } } }, - "413": { - "description": "`audio_too_large` : Audio file size exceeded.", - "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` : Audio type not allowed.", - "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` : Internal server error.", "content": { @@ -1580,7 +1547,7 @@ "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", - "description": "API Key authentication." + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" } }, "responses": { @@ -1652,8 +1619,7 @@ "streaming", "blocking" ], - "default": "blocking", - "description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events." + "description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events. When omitted, defaults to blocking behavior." }, "user": { "type": "string", @@ -3163,7 +3129,7 @@ "file": { "type": "string", "format": "binary", - "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `15 MB`." + "description": "Audio file. Supported: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. Limit: `30 MB`." }, "user": { "type": "string", diff --git a/ja/api-reference/openapi_chat.json b/ja/api-reference/openapi_chat.json index ee41edfa1..f951fd298 100644 --- a/ja/api-reference/openapi_chat.json +++ b/ja/api-reference/openapi_chat.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "チャットアプリAPI", - "description": "チャットアプリケヌションはセッションの持続性をサポヌトしおおり、以前のチャット履歎を応答のコンテキストずしお䜿甚できたす。これは、チャットボットやカスタマヌサヌビスAIなどに適甚できたす。", + "description": "チャットアプリケヌションはセッションの氞続化をサポヌトしおおり、以前のチャット履歎をレスポンスのコンテキストずしお䜿甚できたす。チャットボットやカスタマヌサヌビス AI などに適甚できたす。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "APIのベヌスURL。{api_base_url}をアプリケヌション提䟛の実際のAPIベヌスURLに眮き換えおください。", + "description": "チャットアプリ API のベヌス URL です。{api_base_url} をアプリケヌションに提䟛された実際の API ベヌス URL に眮き換えおください。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "実際のAPIベヌスURL" + "description": "API の実際のベヌス URL" } } } @@ -27,26 +27,28 @@ "post": { "summary": "チャットメッセヌゞを送信", "description": "チャットアプリケヌションにリク゚ストを送信したす。", - "operationId": "sendBasicChatMessageJa", - "tags": ["チャットメッセヌゞ"], + "operationId": "createChatMessageJa", + "tags": [ + "チャットメッセヌゞ" + ], "requestBody": { - "description": "チャットメッセヌゞ送信リク゚ストボディ。", + "description": "チャットメッセヌゞを送信するためのリク゚ストボディ。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BasicChatRequestJa" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file_ja": { - "summary": "ファむルずカスタム入力を含むストリヌミングリク゚ストの䟋", + "streaming_example": { + "summary": "リク゚スト䟋 - ストリヌミングモヌド", "value": { "inputs": { - "name": "dify" + "city": "San Francisco" }, - "query": "iPhone 13 Pro Maxの仕様は䜕ですか", + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "conversation_id": "", "user": "abc-123", "files": [ { @@ -56,6 +58,16 @@ } ] } + }, + "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" + } } } } @@ -63,101 +75,534 @@ }, "responses": { "200": { - "description": "リク゚スト成功。応答のコンテンツタむプず構造はリク゚ストの`response_mode`パラメヌタに䟝存したす。\n- `response_mode`が`blocking`の堎合、`application/json`圢匏の`ChatCompletionResponseJa`オブゞェクトを返したす。\n- `response_mode`が`streaming`の堎合、`text/event-stream`圢匏の`ChunkBasicChatEventJa`オブゞェクトストリヌムを返したす。", + "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/ChatCompletionResponseJa" + "$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: 'で始たり、'\\n\\n'で終わりたす。詳现な構造は`ChunkBasicChatEventJa`を参照しおください。" + "description": "サヌバヌ送信むベント (SSE) のストリヌムです。各むベントは `data: ` プレフィックス付きの JSON オブゞェクトで、2 ぀の改行で終了したす。\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" + } + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestGenericJa" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundJa" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJa" } + "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": { + "/chat-messages/{task_id}/stop": { "post": { - "summary": "ファむルアップロヌド", - "description": "メッセヌゞ送信時に䜿甚するためのファむルをアップロヌドしたす珟圚は画像のみサポヌト。画像ずテキストのマルチモヌダル理解を可胜にしたす。png、jpg、jpeg、webp、gif圢匏をサポヌトしおいたす。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", - "operationId": "uploadBasicChatFileJa", - "tags": ["ファむル操䜜"], + "summary": "生成を停止", + "description": "チャットメッセヌゞ生成タスクを停止したす。`streaming` モヌドでのみサポヌトされたす。", + "operationId": "stopChatMessageJa", + "tags": [ + "チャットメッセヌゞ" + ], + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "description": "タスク ID です。[チャットメッセヌゞ送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) API のストリヌミングチャンクレスポンスから取埗できたす。", + "schema": { + "type": "string" + } + } + ], "requestBody": { - "description": "ファむルアップロヌドリク゚スト。`multipart/form-data`リク゚ストが必芁です。", "required": true, "content": { - "multipart/form-data": { + "application/json": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "user" + ], "properties": { - "file": { "type": "string", "format": "binary", "description": "アップロヌドするファむル。" }, - "user": { "type": "string", "description": "ナヌザヌ識別子。メッセヌゞ送信むンタヌフェヌスで枡されたナヌザヌず䞀臎しおいる必芁がありたす。**重芁な泚意事項**: Service API は WebApp で䜜成された察話を共有したせん。API を通じお䜜成された察話は、WebApp むンタヌフェヌスで䜜成されたものずは分離されおいたす。" } + "user": { + "type": "string", + "description": "ナヌザヌ識別子。メッセヌゞ送信むンタヌフェヌスで枡された user ず䞀臎する必芁がありたす。" + } + } + }, + "examples": { + "example": { + "summary": "リク゚スト䟋", + "value": { + "user": "abc-123" + } } } } } }, "responses": { - "200": { "description": "ファむルアップロヌド成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJa" } } } }, - "201": { "description": "ファむル䜜成成功代替成功コヌド。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJa" } } } }, - "400": { "$ref": "#/components/responses/BadRequestFileJa" }, - "413": { "$ref": "#/components/responses/FileTooLargeJa" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileJa" }, - "503": { "$ref": "#/components/responses/S3ErrorFileJa" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJa" } + "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." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { + "/messages/{message_id}/suggested": { "get": { - "summary": "゚ンドナヌザヌ取埗", - "description": "IDで゚ンドナヌザヌを取埗したす。\n\n他のAPIが゚ンドナヌザヌID䟋ファむルアップロヌドの `created_by`を返す堎合に利甚できたす。", - "operationId": "getEndUserChatJa", - "tags": ["゚ンドナヌザヌ"], + "summary": "次の掚奚質問", + "description": "珟圚のメッセヌゞに察する次の質問の提案を取埗したす。", + "operationId": "getChatSuggestedQuestionsJa", + "tags": [ + "チャットメッセヌゞ" + ], "parameters": [ { - "name": "end_user_id", + "name": "message_id", "in": "path", "required": true, - "description": "゚ンドナヌザヌID。", - "schema": { "type": "string", "format": "uuid" } + "description": "メッセヌゞ ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": true, + "description": "ナヌザヌ識別子。", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "゚ンドナヌザヌの取埗に成功したした。", + "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": "uploadChatFileJa", + "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` : 1 回のリク゚ストに぀き 1 ファむルのみ蚱可されおいたす。\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": { - "schema": { "$ref": "#/components/schemas/EndUserDetailJa" } + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFoundJa" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJa" } + "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を通じお事前にアップロヌドされたファむルにアクセスするこずができたす。ファむルは、リク゚ストしおいるアプリケヌション内のメッセヌゞに属しおいる堎合のみアクセス可胜です。", - "operationId": "previewBasicChatFileJa", - "tags": ["ファむル操䜜"], + "summary": "ファむルダりンロヌド", + "description": "以前[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", + "operationId": "previewChatFileJa", + "tags": [ + "ファむル操䜜" + ], "parameters": [ { "name": "file_id", "in": "path", "required": true, - "description": "プレビュヌするファむルの䞀意識別子、ファむルアップロヌドAPIのレスポンスから取埗されたす。", + "description": "プレビュヌするファむルの䞀意の識別子です。[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API のレスポンスから取埗したす。", "schema": { "type": "string", "format": "uuid" @@ -167,470 +612,3810 @@ "name": "as_attachment", "in": "query", "required": false, - "description": "ファむルを添付ファむルずしお匷制ダりンロヌドするかどうか。デフォルトは`false`ブラりザでプレビュヌです。", + "description": "`true` の堎合、ブラりザでプレビュヌする代わりにファむルを添付ファむルずしお匷制ダりンロヌドしたす。", "schema": { "type": "boolean", "default": false } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "ナヌザヌ識別子。゚ンドナヌザヌのコンテキストに䜿甚されたす。", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "ファむルコンテンツが正垞に返されたした。ヘッダヌはファむルタむプずリク゚ストパラメヌタに基づいお蚭定されたす。", + "description": "生のファむルコンテンツを返したす。`Content-Type` ヘッダヌはファむルの MIME タむプに蚭定されたす。`as_attachment` が `true` の堎合、ファむルは `Content-Disposition: attachment` ずしおダりンロヌド圢匏で返されたす。", "content": { - "image/png": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } - }, - "headers": { - "Content-Type": { - "description": "ファむルのMIMEタむプ", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "ファむルサむズバむト単䜍、利甚可胜な堎合", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "as_attachment=trueの堎合、'attachment'に蚭定されたす", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "パフォヌマンス甚キャッシュヘッダヌ", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "オヌディオ/ビデオファむルの堎合は'bytes'に蚭定されたす", - "schema": { - "type": "string", - "example": "bytes" - } - } } }, - "400": { - "description": "䞍正なリク゚スト。可胜な゚ラヌコヌド:\n- `invalid_param`: 異垞なパラメヌタ入力。", + "403": { + "description": "`file_access_denied` : リク゚ストされたファむルぞのアクセスが拒吊されたした。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } } } }, - "403": { - "description": "犁止。可胜な゚ラヌコヌド:\n- `file_access_denied`: ファむルアクセス拒吊たたはファむルが珟圚のアプリケヌションに属しおいたせん。", + "404": { + "description": "`file_not_found` : リク゚ストされたファむルが芋぀かりたせん。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } } } - }, - "404": { - "description": "芋぀かりたせん。可胜な゚ラヌコヌド:\n- `file_not_found`: ファむルが芋぀からないか削陀されおいたす。", + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "summary": "゚ンドナヌザヌ取埗", + "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド)の `created_by`に䟿利です。", + "operationId": "getChatEndUserJa", + "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/ErrorResponseJa" } + "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" + } + } + } } } }, - "500": { - "description": "内郚サヌバヌ゚ラヌ。", + "404": { + "description": "`end_user_not_found` : ゚ンドナヌザヌが芋぀かりたせん。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } } } } } } }, - "/chat-messages/{task_id}/stop": { - "post": { - "summary": "生成停止", - "description": "チャットメッセヌゞの生成を停止したす。ストリヌミングモヌドでのみサポヌトされおいたす。", - "operationId": "stopBasicChatMessageGenerationJa", - "tags": ["チャットメッセヌゞ"], - "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "タスクID、ストリヌミングチャンクの返り倀から取埗できたす。", "schema": { "type": "string", "format": "uuid" } } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["user"], "properties": { "user": { "type": "string", "description": "ナヌザヌ識別子。メッセヌゞ送信むンタヌフェヌスで枡されたナヌザヌず䞀臎しおいる必芁がありたす。**重芁な泚意事項**: Service API は WebApp で䜜成された察話を共有したせん。API を通じお䜜成された察話は、WebApp むンタヌフェヌスで䜜成されたものずは分離されおいたす。" } } } } } }, - "responses": { "200": { "$ref": "#/components/responses/SuccessResultJa" } } - } - }, "/messages/{message_id}/feedbacks": { "post": { "summary": "メッセヌゞフィヌドバック", - "description": "゚ンドナヌザヌはフィヌドバックメッセヌゞを提䟛でき、アプリケヌション開発者が期埅される出力を最適化するのに圹立ちたす。", - "operationId": "postBasicChatMessageFeedbackJa", - "tags": ["メッセヌゞフィヌドバック"], - "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "メッセヌゞID。", "schema": { "type": "string", "format": "uuid" } } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestJa" } } } }, - "responses": { "200": { "$ref": "#/components/responses/SuccessResultJa" } } - } - }, - "/app/feedbacks": { - "get": { - "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", - "description": "アプリの゚ンドナヌザヌからのフィヌドバックや「いいね」を取埗したす。", - "operationId": "getBasicChatAppFeedbacksJa", - "tags": ["メッセヌゞフィヌドバック"], - "parameters": [ { "$ref": "#/components/parameters/PageQueryParamJa" }, { "$ref": "#/components/parameters/LimitQueryParamJa" } ], - "responses": { "200": { "description": "アプリのフィヌドバックリストを正垞に取埗したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseJa" } } } } } - } - }, - "/messages/{message_id}/suggested": { - "get": { - "summary": "次の掚奚質問", - "description": "珟圚のメッセヌゞに察する次の質問の提案を取埗したす。", - "operationId": "getBasicChatSuggestedQuestionsJa", - "tags": ["チャットメッセヌゞ"], - "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "メッセヌゞID。", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/UserQueryParamJa" } ], - "responses": { "200": { "description": "掚奚質問リストを正垞に取埗したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponseJa" } } } } } + "description": "メッセヌゞに察するフィヌドバックを送信したす。゚ンドナヌザヌはメッセヌゞを `like` たたは `dislike` で評䟡でき、任意でテキストフィヌドバックを提䟛できたす。`rating` に `null` を枡すず、以前送信したフィヌドバックを取り消せたす。", + "operationId": "createChatMessageFeedbackJa", + "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." + } + } + } + } + } + } + } } }, - "/messages": { + "/app/feedbacks": { "get": { - "summary": "䌚話履歎メッセヌゞを取埗", - "description": "スクロヌルロヌド圢匏で過去のチャット蚘録を返し、最初のペヌゞは最新の`{limit}`メッセヌゞを返したす。぀たり、逆順です。", - "operationId": "getBasicChatConversationHistoryJa", - "tags": ["䌚話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdQueryParamJa" }, { "$ref": "#/components/parameters/UserQueryParamJa" }, { "name": "first_id", "in": "query", "description": "珟圚のペヌゞの最初のチャット蚘録のID、デフォルトはnullです。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, { "$ref": "#/components/parameters/LimitQueryParamDefault20Ja" } ], - "responses": { "200": { "description": "䌚話履歎メッセヌゞを正垞に取埗したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicConversationHistoryResponseJa" } } } } } + "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", + "description": "このアプリケヌションのメッセヌゞに察しお送信されたすべおのフィヌドバックのペヌゞネヌション付きリストを取埗したす。゚ンドナヌザヌず管理者のフィヌドバックの䞡方が含たれたす。", + "operationId": "listChatFeedbacksJa", + "tags": [ + "メッセヌゞフィヌドバック" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "ペヌゞネヌションのペヌゞ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1ペヌゞあたりのレコヌド数。", + "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": "珟圚のナヌザヌの䌚話リストを取埗し、デフォルトで最新の20件を返したす。", - "operationId": "getBasicChatConversationsListJa", - "tags": ["䌚話管理"], - "parameters": [ { "$ref": "#/components/parameters/UserQueryParamJa" }, { "$ref": "#/components/parameters/LastIdQueryParamJa" }, { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Ja" }, { "$ref": "#/components/parameters/SortByQueryParamJa" } ], - "responses": { "200": { "description": "䌚話リストを正垞に取埗したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsListResponseJa" } } } } } - } - }, - "/conversations/{conversation_id}": { - "delete": { - "summary": "䌚話を削陀", - "description": "指定された䌚話を削陀したす。", - "operationId": "deleteBasicChatConversationJa", - "tags": ["䌚話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJa" } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["user"], "properties": { "user": { "type": "string", "description": "ナヌザヌ識別子。**重芁な泚意事項**: Service API は WebApp で䜜成された察話を共有したせん。API を通じお䜜成された察話は、WebApp むンタヌフェヌスで䜜成されたものずは分離されおいたす。" } } } } } }, - "responses": { "204": { "description": "䌚話の削陀に成功したした。コンテンツはありたせん。" } } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "䌚話の名前を倉曎", - "description": "セッションの名前を倉曎したす。セッション名は、耇数のセッションをサポヌトするクラむアントでの衚瀺に䜿甚されたす。", - "operationId": "renameBasicChatConversationJa", - "tags": ["䌚話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJa" } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequestJa" } } } }, - "responses": { "200": { "description": "䌚話の名前倉曎に成功したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameResponseJa" } } } } } - } - }, - "/conversations/{conversation_id}/variables": { - "get": { - "summary": "䌚話倉数の取埗", - "description": "特定の䌚話から倉数を取埗したす。この゚ンドポむントは、䌚話䞭に取埗された構造化デヌタを抜出するのに圹立ちたす。", - "operationId": "getBasicChatConversationVariablesJa", - "tags": ["䌚話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJa" }, { "$ref": "#/components/parameters/UserQueryParamJa" }, { "$ref": "#/components/parameters/LastIdQueryParamJa" }, { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Ja" }, { "$ref": "#/components/parameters/VariableNameQueryParamJa" } ], - "responses": { "200": { "description": "䌚話倉数を正垞に取埗したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariablesResponseJa" } } } }, "404": { "$ref": "#/components/responses/ConversationNotFoundJa" } } - } - }, - "/audio-to-text": { - "post": { - "summary": "音声からテキストぞ", - "description": "オヌディオファむルをテキストに倉換したす。サポヌトされおいる圢匏mp3, mp4, mpeg, mpga, m4a, wav, webm。ファむルサむズ制限15MB。", - "operationId": "basicChatAudioToTextJa", - "tags": ["音声ずテキスト倉換"], - "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequestJa" } } } }, - "responses": { "200": { "description": "音声からテキストぞの倉換に成功したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponseJa" } } } } } - } - }, - "/text-to-audio": { - "post": { - "summary": "テキストから音声ぞ", - "description": "テキストコンテンツを音声に倉換したす。", - "operationId": "basicChatTextToAudioJa", - "tags": ["音声ずテキスト倉換"], - "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TextToAudioFormRequestJa" } } } }, - "responses": { "200": { "description": "音声ファむルの生成に成功したした。", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } } } - } - }, - "/info": { - "get": { - "summary": "アプリケヌションの基本情報を取埗", - "operationId": "getBasicChatAppInfoJa", - "tags": ["アプリケヌション蚭定"], - "responses": { "200": { "description": "アプリケヌションの基本情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseJa" } } } } } - } - }, - "/parameters": { - "get": { - "summary": "アプリケヌションのパラメヌタ情報を取埗", - "description": "ペヌゞに入る際に、機胜、入力パラメヌタ名、タむプ、デフォルト倀などの情報を取埗するために䜿甚されたす。", - "operationId": "getBasicChatAppParametersJa", - "tags": ["アプリケヌション蚭定"], - "responses": { "200": { "description": "アプリケヌションのパラメヌタ情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicChatAppParametersResponseJa" } } } } } + "description": "珟圚のナヌザヌの䌚話リストを、最近アクティブな順に取埗したす。", + "operationId": "listChatConversationsJa", + "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." + } + } + } + } + } + } + } } }, - "/meta": { + "/messages": { "get": { - "summary": "アプリケヌションのメタ情報を取埗", - "description": "このアプリケヌションのツヌルのアむコンを取埗するために䜿甚されたす。", - "operationId": "getBasicChatAppMetaJa", - "tags": ["アプリケヌション蚭定"], - "responses": { "200": { "description": "アプリケヌションのメタ情報を正垞に取埗したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponseJa" } } } } } + "summary": "䌚話履歎メッセヌゞを取埗", + "description": "スクロヌル読み蟌み圢匏で過去のチャット蚘録を返したす。最初のペヌゞは最新の `limit` 件のメッセヌゞを返したす時系列の逆順。", + "operationId": "listChatMessagesJa", + "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." + } + } + } + } + } + } + } } }, - "/site": { + "/conversations/{conversation_id}/variables": { "get": { - "summary": "アプリのWebApp蚭定を取埗", - "description": "アプリのWebApp蚭定を取埗するために䜿甚したす。", - "operationId": "getBasicChatWebAppSettingsJa", - "tags": ["アプリケヌション蚭定"], - "responses": { "200": { "description": "WebApp蚭定。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseJa" } } } } } - } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "APIキヌ認蚌。すべおのAPIリク゚ストにおいお、Authorization HTTPヘッダヌにAPIキヌを含めおください。圢匏Bearer {API_KEY}。APIキヌの挏掩を防ぐため、APIキヌはクラむアント偎で共有たたは保存せず、サヌバヌ偎で保存するこずを匷くお勧めしたす。" } - }, - "parameters": { - "PageQueryParamJa": { "name": "page", "in": "query", "description": "任意ペヌゞ番号。デフォルト倀1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamJa": { "name": "limit", "in": "query", "description": "任意1ペヌゞあたりの件数。デフォルト倀20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Ja": { "name": "limit", "in": "query", "description": "1回のリク゚ストで返すレコヌドの数、デフォルトは20です。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100Ja": { "name": "limit", "in": "query", "description": "1回のリク゚ストで返すレコヌドの数、デフォルトは20件です。最倧100、最小1。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParamJa": { "name": "user", "in": "query", "required": true, "description": "ナヌザヌ識別子。アプリケヌション内で開発者によっお䞀意に定矩される必芁がありたす。**重芁な泚意事項**: Service API は WebApp で䜜成された察話を共有したせん。API を通じお䜜成された察話は、WebApp むンタヌフェヌスで䜜成されたものずは分離されおいたす。", "schema": { "type": "string" } }, - "ConversationIdQueryParamJa": { "name": "conversation_id", "in": "query", "required": true, "description": "䌚話ID。", "schema": { "type": "string", "format": "uuid" } }, - "LastIdQueryParamJa": { "name": "last_id", "in": "query", "description": "(Optional)珟圚のペヌゞの最埌のレコヌドのID、デフォルトはnullです。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, - "SortByQueryParamJa": { "name": "sort_by", "in": "query", "description": "(Optional)゜ヌトフィヌルド、デフォルト-updated_at曎新時間で降順に゜ヌト。利甚可胜な倀created_at, -created_at, updated_at, -updated_at。フィヌルドの前の蚘号「-」は逆順を衚したす。", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParamJa": { "name": "conversation_id", "in": "path", "required": true, "description": "䌚話ID。", "schema": { "type": "string", "format": "uuid" } }, - "VariableNameQueryParamJa": { "name": "variable_name", "in": "query", "description": "(Optional)倉数名でフィルタリングしたす。", "schema": { "type": "string" } } - }, - "responses": { - "BadRequestGenericJa": { "description": "リク゚ストパラメヌタ゚ラヌ。考えられる原因invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "BadRequestFileJa": { "description": "ファむル操䜜リク゚スト゚ラヌ。考えられる原因no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "FileTooLargeJa": { "description": "ファむルが倧きすぎたす (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "UnsupportedFileTypeFileJa": { "description": "サポヌトされおいないファむルタむプ (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "S3ErrorFileJa": { "description": "S3ストレヌゞサヌビス゚ラヌ。考えられる原因s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "InternalServerErrorJa": { "description": "内郚サヌバヌ゚ラヌ。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "SuccessResultJa": { "description": "操䜜成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFoundJa": { "description": "䌚話が存圚したせん。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } }, - "EndUserNotFoundJa": { "description": "゚ンドナヌザヌが芋぀かりたせん。゚ラヌコヌド`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJa" } } } } - }, - "schemas": { - "BasicChatRequestJa": { - "type": "object", "required": ["query", "user"], - "properties": { - "query": { "type": "string", "description": "ナヌザヌ入力/質問内容。" }, - "inputs": { "type": "object", "description": "アプリで定矩されたさたざたな倉数倀の入力を蚱可したす。デフォルトは`{}`。", "additionalProperties": true, "default": {} }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "応答の返华モヌド。streaming掚奚はSSEベヌス。blockingは実行完了埌に結果を返したすCloudflareの100秒タむムアりト制限あり゚ヌゞェントアシスタントモヌドではサポヌトされおいたせん。" }, - "user": { "type": "string", "description": "ナヌザヌ識別子、アプリケヌション内で䞀意である必芁がありたす。**重芁な泚意事項**: Service API は WebApp で䜜成された察話を共有したせん。API を通じお䜜成された察話は、WebApp むンタヌフェヌスで䜜成されたものずは分離されおいたす。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "䌚話ID、以前のチャット蚘録に基づいお䌚話を続けるには、前のメッセヌゞのconversation_idを枡す必芁がありたす。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/BasicInputFileObjectJa" }, "description": "アップロヌドされたファむルリスト。珟圚は画像タむプのみサポヌト。" }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "タむトルを自動生成したす。デフォルトは`true`です。" } - } - }, - "BasicInputFileObjectJa": { - "type": "object", "required": ["type", "transfer_method"], - "properties": { - "type": { "type": "string", "enum": ["image"], "description": "サポヌトされおいるタむプ`image`珟圚は画像タむプのみサポヌト。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "転送方法。remote_url は画像URL / local_file はファむルアップロヌド甚" }, - "url": { "type": "string", "format": "url", "description": "画像URL転送方法が remote_url の堎合" }, - "upload_file_id": { "type": "string", "format":"uuid", "description": "アップロヌドされたファむルID、事前にファむルアップロヌドAPIで取埗する必芁がありたす転送方法が local_file の堎合" } - }, - "anyOf": [ + "summary": "䌚話倉数の取埗", + "description": "特定の䌚話から倉数を取埗したす。", + "operationId": "listChatConversationVariablesJa", + "tags": [ + "䌚話管理" + ], + "parameters": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "name": "conversation_id", + "in": "path", + "required": true, + "description": "䌚話 ID。", + "schema": { + "type": "string" + } }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format":"uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } - } - ] - }, - "ChatCompletionResponseJa": { - "type": "object", "description": "ブロッキングモヌドでの完党なアプリ結果。", - "properties": { - "event": { "type": "string", "example": "message", "description": "むベントタむプ、固定で `message`。" }, - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "id": { "type": "string", "format": "uuid", "description": "ナニヌクID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "䞀意のメッセヌゞID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "䌚話ID。" }, - "mode": { "type": "string", "example": "chat", "description": "アプリモヌド、`chat`ずしお固定。" }, - "answer": { "type": "string", "description": "完党な応答内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataJa" }, - "created_at": { "type": "integer", "format": "int64", "description": "メッセヌゞ䜜成タむムスタンプ。" } - } - }, - "ResponseMetadataJa": { - "type": "object", "description": "メタデヌタ。", - "properties": { "usage": { "$ref": "#/components/schemas/UsageJa" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJa" }, "description": "匕甚ず垰属リスト。" } } - }, - "ChunkBasicChatEventJa": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "agent_message", "agent_thought", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], "description": "むベントタむプ。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "message": "#/components/schemas/StreamEventChatMessageJa", "agent_message": "#/components/schemas/StreamEventAgentMessageJa", - "agent_thought": "#/components/schemas/StreamEventAgentThoughtJa", "message_file": "#/components/schemas/StreamEventMessageFileJa", - "message_end": "#/components/schemas/StreamEventMessageEndJa", "tts_message": "#/components/schemas/StreamEventTtsMessageJa", - "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndJa", "message_replace": "#/components/schemas/StreamEventMessageReplaceJa", - "error": "#/components/schemas/StreamEventErrorJa", "ping": "#/components/schemas/StreamEventPingJa" - }} - }, - "StreamEventBaseChatJa": { - "type": "object", "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": "䜜成タむムスタンプ。" } - } - }, - "StreamEventChatMessageJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLMが返したテキストチャンク内容。" } } } ] }, - "StreamEventAgentMessageJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLMが返したテキストチャンク内容゚ヌゞェントモヌド。" } } } ] }, - "StreamEventAgentThoughtJa": { - "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, - { "type": "object", "required": ["id", "task_id", "message_id", "position", "created_at", "conversation_id"], - "properties": { - "id": { "type": "string", "format": "uuid", "description": "゚ヌゞェント思考ID。" }, - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "䞀意のメッセヌゞID。" }, - "position": { "type": "integer", "description": "゚ヌゞェント思考のメッセヌゞ内での䜍眮。" }, - "thought": { "type": "string", "nullable": true, "description": "゚ヌゞェントの思考内容。" }, - "observation": { "type": "string", "nullable": true, "description": "ツヌル呌び出しからの応答。" }, - "tool": { "type": "string", "nullable": true, "description": "䜿甚されたツヌルのリスト、;で区切られたす。" }, - "tool_input": { "type": "string", "nullable": true, "description": "ツヌルの入力、JSON圢匏の文字列。" }, - "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" }, - "message_files": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "ファむルID" }, "description": "珟圚の゚ヌゞェント思考に関連するファむルIDのリスト。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "䌚話ID。" } + "name": "user", + "in": "query", + "required": false, + "description": "ナヌザヌ識別子です。", + "schema": { + "type": "string" } - } - ] - }, - "StreamEventMessageFileJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ファむル䞀意ID。" }, "type": { "type": "string", "enum": ["image"], "description": "ファむルタむプ、珟圚は'image'のみ蚱可。" }, "belongs_to": { "type": "string", "enum": ["assistant"], "description": "所属、ここでは'assistant'のみ。" }, "url": { "type": "string", "format": "url", "description": "ファむルのリモヌトURL。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "䌚話ID。" } } } ] }, - "StreamEventMessageEndJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataJa" } } } ] }, - "StreamEventTtsMessageJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64゚ンコヌドされたオヌディオブロック。" } } } ] }, - "StreamEventTtsMessageEndJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空の文字列。" } } } ] }, - "StreamEventMessageReplaceJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "$ref": "#/components/schemas/StreamEventBaseChatJa" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "眮換内容すべおのLLM返信テキストを盎接眮換。" } } } ] }, - "StreamEventErrorJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "type": "object", "required": ["task_id", "status", "code", "message"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "䞀意のメッセヌゞID゚ラヌむベントでは存圚しない堎合がありたす。" }, "status": { "type": "integer", "description": "HTTPステヌタスコヌド。" }, "code": { "type": "string", "description": "゚ラヌコヌド。" }, "message": { "type": "string", "description": "゚ラヌメッセヌゞ。" } } } ] }, - "StreamEventPingJa": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventJa" }, { "type": "object", "description": "接続を維持するために10秒ごずにpingむベントが発生したす。" } ] }, - "UsageJa": { "type": "object", "description": "モデル䜿甚情報。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceJa": { "type": "object", "description": "匕甚ず垰属情報。", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } }, - "FileUploadResponseJa": { "type": "object", "description": "ファむルアップロヌド成功埌の応答。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "ファむル名。" }, "size": { "type": "integer", "description": "ファむルサむズバむト。" }, "extension": { "type": "string", "description": "ファむル拡匵子。" }, "mime_type": { "type": "string", "description": "ファむルのMIMEタむプ。" }, "created_by": { "type": "string", "format": "uuid", "description": "゚ンドナヌザヌID。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } }, - "EndUserDetailJa": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } - } - }, - "MessageFeedbackRequestJa": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "アップボヌトは`like`、ダりンボヌトは`dislike`、アップボヌトの取り消しは`null`。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" }, "content": { "type": "string", "nullable": true, "description": "メッセヌゞのフィヌドバックです。" } } }, - "AppFeedbacksResponseJa": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemJa" }, "description": "このアプリの「いいね」ずフィヌドバックの䞀芧を返したす。" } } }, - "FeedbackItemJa": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "SuggestedQuestionsResponseJa": { "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "description": "掚奚質問のリスト。" } } }, - "BasicConversationHistoryResponseJa": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返されたアむテムの数。" }, "has_more": { "type": "boolean", "description": "次のペヌゞがあるかどうか。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BasicConversationMessageItemJa" }, "description": "メッセヌゞリスト。" } } }, - "BasicConversationMessageItemJa": { "type": "object", "description": "䌚話内の単䞀メッセヌゞ。", "properties": { "id": { "type": "string", "format": "uuid", "description": "メッセヌゞID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "䌚話ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ナヌザヌ入力パラメヌタ。" }, "query": { "type": "string", "description": "ナヌザヌ入力/質問内容。" }, "answer": { "type": "string", "description": "応答メッセヌゞ内容。" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItemJa" }, "description": "メッセヌゞファむルリスト。" }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"], "description": "アップボヌトは`like` / ダりンボヌトは`dislike`。" } }, "description": "フィヌドバック情報。" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJa" }, "description": "匕甚ず垰属リスト。" }, "agent_thoughts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentThoughtItemJa" }, "description": "゚ヌゞェントの思考基本アシスタントの堎合は空。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } }, - "AgentThoughtItemJa": { - "type": "object", "description": "゚ヌゞェントの思考ステップ。", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "゚ヌゞェント思考ID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "䞀意のメッセヌゞID。" }, - "position": { "type": "integer", "description": "゚ヌゞェント思考のメッセヌゞ内での䜍眮。" }, - "thought": { "type": "string", "nullable": true, "description": "LLMが考えおいるこず。" }, - "observation": { "type": "string", "nullable": true, "description": "ツヌル呌び出しからの応答。" }, - "tool": { "type": "string", "nullable": true, "description": "呌び出されたツヌルのリスト、;で区切られたす。" }, - "tool_input": { "type": "string", "nullable": true, "description": "ツヌルの入力、JSON圢匏。" }, - "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" }, - "message_files": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "ファむルID" }, "description": "珟圚の゚ヌゞェント思考に関連するファむルIDのリスト。" } - } - }, - "MessageFileItemJa": { "type": "object", "description": "メッセヌゞ内のファむル項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "ファむルタむプ、䟋'image'。" }, "url": { "type": "string", "format": "url", "description": "プレビュヌ画像URL。" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "所属。" } } }, - "ConversationsListResponseJa": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返された゚ントリの数。" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItemJa" }, "description": "䌚話のリスト。" } } }, - "ConversationListItemJa": { "type": "object", "description": "䌚話リスト内の単䞀項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "䌚話ID。" }, "name": { "type": "string", "description": "䌚話名。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ナヌザヌ入力パラメヌタ。" }, "status": { "type": "string", "description": "䌚話状態。" }, "introduction": { "type": "string", "nullable": true, "description": "玹介。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" }, "updated_at": { "type": "integer", "format": "int64", "description": "曎新タむムスタンプ。" } } }, - "ConversationRenameRequestJa": { "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true, "description": "(Optional)䌚話の名前。`auto_generate`が`true`の堎合、省略できたす。" }, "auto_generate": { "type": "boolean", "default": false, "description": "(Optional)タむトルを自動生成したす。デフォルトは`false`です。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" } } }, - "ConversationRenameResponseJa": { "$ref": "#/components/schemas/ConversationListItemJa" }, - "ConversationVariablesResponseJa": { "type": "object", "properties": { "limit": { "type": "integer", "description": "ペヌゞごずのアむテム数。" }, "has_more": { "type": "boolean", "description": "さらにアむテムがあるかどうか。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItemJa" }, "description": "倉数のリスト。" } } }, - "ConversationVariableItemJa": { "type": "object", "description": "䌚話内の倉数項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "倉数ID。" }, "name": { "type": "string", "description": "倉数名。" }, "value_type": { "type": "string", "description": "倉数タむプ文字列、数倀、真停倀など。" }, "value": { "type": "string", "description": "倉数倀。" }, "description": { "type": "string", "nullable": true, "description": "倉数の説明。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最終曎新タむムスタンプ。" } } }, - "AudioToTextRequestJa": { "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "オヌディオファむル。サポヌトされおいる圢匏`['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']`。ファむルサむズ制限15MB。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" } } }, - "AudioToTextResponseJa": { "type": "object", "properties": { "text": { "type": "string", "description": "出力テキスト。" } } }, - "TextToAudioFormRequestJa": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "メッセヌゞID優先。" }, "text": { "type": "string", "description": "音声生成コンテンツ。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" } }, "description": "`user`が必芁です。`message_id`たたは`text`を提䟛しおください。このバヌゞョンはmultipart/form-dataです。" }, - "AppInfoResponseJa": { "type": "object", "description": "アプリケヌションの基本情報。", "properties": { "name": { "type": "string", "description": "アプリケヌションの名前。" }, "description": { "type": "string", "description": "アプリケヌションの説明。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "アプリケヌションのタグ。" } } }, - "BasicChatAppParametersResponseJa": { "type": "object", "description": "アプリケヌションのパラメヌタ情報。", "properties": { "opening_statement": { "type": "string", "description": "開始文。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "開始時の掚奚質問のリスト。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "答えを有効にした埌の質問を提案したす。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "音声からテキストぞ。" }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" }, "voice": { "type": "string", "description": "音声タむプ。" }, "language": { "type": "string", "description": "蚀語。" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"], "description": "自動再生enabled 有効, disabled 無効。" } }, "description": "テキストから音声ぞ。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "匕甚ず垰属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "泚釈返信。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemJa" }, "description": "ナヌザヌ入力フォヌムの構成。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "画像蚭定。サポヌトされおいる画像タむプ`png`, `jpg`, `jpeg`, `webp`, `gif`。" } }, "description": "ファむルアップロヌド構成。" }, "system_parameters": { "type": "object", "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。" } }, "description": "システムパラメヌタ。" } } }, - "UserInputFormItemJa": { "type": "object", "description": "ナヌザヌ入力フォヌム内のコントロヌル項目。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperJa" }, { "$ref": "#/components/schemas/ParagraphControlWrapperJa" }, { "$ref": "#/components/schemas/SelectControlWrapperJa" } ] }, - "TextInputControlWrapperJa": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlJa" } }, "required":["text-input"] }, - "ParagraphControlWrapperJa": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlJa" } }, "required":["paragraph"] }, - "SelectControlWrapperJa": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlJa" } }, "required":["select"] }, - "TextInputControlJa": { "type": "object", "description": "テキスト入力コントロヌル。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" } } }, - "ParagraphControlJa": { "type": "object", "description": "段萜テキスト入力コントロヌル。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" } } }, - "SelectControlJa": { "type": "object", "description": "ドロップダりンコントロヌル。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "オプション倀。" } } }, - "AppMetaResponseJa": { "type": "object", "description": "アプリケヌションのメタ情報。", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url", "description": "アむコンのURL。" }, { "$ref": "#/components/schemas/ToolIconDetailJa" } ] }, "description": "ツヌルアむコン。キヌはツヌル名です。" } } }, - "ToolIconDetailJa": { "type": "object", "description": "ツヌルアむコンの詳现。", "properties": { "background": { "type": "string", "description": "背景色16進数圢匏。" }, "content": { "type": "string", "description": "絵文字。" } } }, - "WebAppSettingsResponseJa": { "type": "object", "description": "アプリのWebApp蚭定。", "properties": { "title": { "type": "string", "description": "WebApp名。" }, "chat_color_theme": { "type": "string", "description": "チャットの色テヌマ、16進数圢匏。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "チャットの色テヌマを反転するかどうか。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "アむコンタむプ。" }, "icon": { "type": "string", "description": "アむコン内容絵文字たたは画像URL。" }, "icon_background": { "type": "string", "description": "16進数圢匏の背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "アむコンのURL。" }, "description": { "type": "string", "description": "説明。" }, "copyright": { "type": "string", "description": "著䜜暩情報。" }, "privacy_policy": { "type": "string", "description": "プラむバシヌポリシヌのリンク。" }, "custom_disclaimer": { "type": "string", "description": "カスタム免責事項。" }, "default_language": { "type": "string", "description": "デフォルト蚀語。" }, "show_workflow_steps": { "type": "boolean", "description": "ワヌクフロヌの詳现を衚瀺するかどうか。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "WebAppのアむコンをチャット内の🀖に眮き換えるかどうか。" } } }, - "ErrorResponseJa": { "type": "object", "description": "゚ラヌ応答。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTPステヌタスコヌド。" }, "code": { "type": "string", "nullable": true, "description": "゚ラヌコヌド。" }, "message": { "type": "string", "description": "゚ラヌメッセヌゞ。" } } } - } - }, - "tags": [ - { "name": "チャットメッセヌゞ", "description": "チャットメッセヌゞず察話に関連する操䜜。" }, - { "name": "ファむル操䜜", "description": "ファむルアップロヌドずプレビュヌに関連する操䜜。" }, - { "name": "゚ンドナヌザヌ", "description": "゚ンドナヌザヌ情報に関連する操䜜。" }, - { "name": "メッセヌゞフィヌドバック", "description": "ナヌザヌからのメッセヌゞフィヌドバック操䜜。" }, - { "name": "䌚話管理", "description": "䌚話セッションの管理に関連する操䜜。" }, - { "name": "音声ずテキスト倉換", "description": "テキストから音声、音声からテキストぞの倉換操䜜。" }, - { "name": "アプリケヌション蚭定", "description": "アプリケヌション蚭定ず情報の取埗に関連する操䜜。" } + }, + { + "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": "renameChatConversationJa", + "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": "updateChatConversationVariableJa", + "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": "deleteChatConversationJa", + "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": "chatAudioToTextJa", + "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": "chatTextToAudioJa", + "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": "getChatAppInfoJa", + "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": "getChatAppParametersJa", + "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": "getChatAppMetaJa", + "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": "getChatWebAppSettingsJa", + "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": "createChatAnnotationJa", + "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": "listChatAnnotationsJa", + "tags": [ + "アノテヌション管理" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "ペヌゞネヌションのペヌゞ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1 ペヌゞあたりの件数です。", + "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": "updateChatAnnotationJa", + "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": "deleteChatAnnotationJa", + "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": "setChatAnnotationReplyJa", + "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": "getChatAnnotationReplyStatusJa", + "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 ヘッダヌに `Bearer ` プレフィックスを付けた API Key を含めおください。䟋`Authorization: Bearer {API_KEY}`。**API Key はサヌバヌサむドに保存し、クラむアントサむドで共有・保存しないこずを匷く掚奚したす。API Key の挏掩は深刻な結果に぀ながる可胜性がありたす。**" + } + }, + "responses": { + "SuccessResult": { + "description": "操䜜が成功したした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "結果ステヌタス。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "result": "success" + } + } + } + } + } + } + }, + "schemas": { + "ChatRequest": { + "type": "object", + "required": [ + "inputs", + "query", + "user" + ], + "properties": { + "query": { + "type": "string", + "description": "ナヌザヌの入力/質問内容です。" + }, + "inputs": { + "type": "object", + "description": "アプリで定矩されたさたざたな倉数の倀を入力できたす。キヌず倀のペアを含みたす。アプリが期埅する倉数名ず型に぀いおは、[アプリパラメヌタの取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", + "additionalProperties": true + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "レスポンスの返华モヌドです。`streaming`掚奚は SSE を䜿甚したす。`blocking` は完了埌に返したす長時間の凊理では䞭断される堎合がありたす。゚ヌゞェントアシスタントモヌドではサポヌトされおいたせん。Cloudflare のタむムアりトは `100 s` です。省略した堎合、デフォルトはブロッキング動䜜になりたす。" + }, + "user": { + "type": "string", + "description": "アプリケヌション内で䞀意のナヌザヌ識別子です。この識別子はデヌタアクセスの範囲を限定したす——䌚話、メッセヌゞ、ファむルは同じ `user` 倀でク゚リした堎合にのみ衚瀺されたす。" + }, + "conversation_id": { + "type": "string", + "description": "䌚話を継続するための䌚話 ID です。前のメッセヌゞの `conversation_id` を枡したす。新しい䌚話を開始するには、このフィヌルドを省略するか空文字列を枡したす。レスポンスで `conversation_id` が返されたす——以降のメッセヌゞでこの倀を枡すずその䌚話を継続できたす。" + }, + "files": { + "type": "array", + "description": "マルチモヌダル理解甚のファむルリストです。画像、ドキュメント、音声、動画を含みたす。ロヌカルファむルを添付するには、たず [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。", + "items": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "ファむルタむプ。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "転送方法です。ファむル URL の堎合は `remote_url`、アップロヌドファむルの堎合は `local_file` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファむル URL`transfer_method` が `remote_url` の堎合は必須です。" + }, + "upload_file_id": { + "type": "string", + "description": "[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API から取埗したアップロヌド枈みファむル ID です`transfer_method` が `local_file` の堎合は必須。" + } + } + } + }, + "auto_generate_name": { + "type": "boolean", + "description": "䌚話タむトルを自動生成したす。`false` の堎合、[䌚話のリネヌム](/api-reference/䌚話管理/䌚話の名前を倉曎) API で `auto_generate: true` を蚭定しお非同期でタむトルを生成したす。", + "default": true + } + } + }, + "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 チャンクのベヌススキヌマです。", + "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 が返したテキストチャンク゚ヌゞェントモヌドです。" + } + } + } + ] + }, + "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": "゚ヌゞェントの思考、LLM の掚論、ツヌル呌び出しの詳现゚ヌゞェントモヌドです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "゚ヌゞェント思考 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": { + "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": "フィヌドバックの゜ヌス。API 経由で゚ンドナヌザヌが送信したフィヌドバックの堎合は `user`、コン゜ヌルから送信されたフィヌドバックの堎合は `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": "1 ペヌゞあたりの件数です。" + }, + "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": "このメッセヌゞの゚ヌゞェント思考です。", + "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": "メッセヌゞ内の゚ヌゞェント思考ステップです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "゚ヌゞェント思考 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": "1 ペヌゞあたりの件数です。" + }, + "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": "1 ペヌゞあたりの件数です。" + }, + "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` よりも優先されたす。" + }, + "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` ぱヌゞェントベヌスのアプリ、`advanced-chat` は chatflow アプリを瀺したす。" + }, + "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": "絵文字を䜿甚したツヌルアむコンの詳现。", + "properties": { + "background": { + "type": "string", + "description": "16進数圢匏の背景色。" + }, + "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": "1 ペヌゞあたりの件数です。" + }, + "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": "ダむレクト返信甚のアノテヌション管理に関連する操䜜です。" + } ] -} \ No newline at end of file +} diff --git a/ja/api-reference/openapi_chatflow.json b/ja/api-reference/openapi_chatflow.json index eb6d60708..84358e0bd 100644 --- a/ja/api-reference/openapi_chatflow.json +++ b/ja/api-reference/openapi_chatflow.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "高床なチャットアプリAPI (Chatflow API)", - "description": "チャットアプリケヌションはセッションの持続性をサポヌトしおおり、以前のチャット履歎を応答のコンテキストずしお䜿甚できたす。これは、チャットボットやカスタマヌサヌビスAIなどに適甚できたす。", + "description": "Chatflow アプリケヌションはセッションの氞続化をサポヌトし、過去のチャット履歎をレスポンスのコンテキストずしお䜿甚できたす。Chatflow アプリは `advanced-chat` モヌドを䜿甚し、ノヌドの開始・完了、むテレヌション、ワヌクフロヌのラむフサむクルを含む詳现な実行远跡のためのワヌクフロヌレベルのストリヌミングむベントを提䟛したす。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "APIのベヌスURL。 {api_base_url} をアプリケヌション提䟛の実際のAPIベヌスURLに眮き換えおください。", + "description": "Chatflow アプリ API のベヌス URL です。{api_base_url} をアプリケヌションに提䟛された実際の API ベヌス URL に眮き換えおください。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "実際のAPIベヌスURL" + "description": "API の実際のベヌス URL" } } } @@ -27,26 +27,28 @@ "post": { "summary": "チャットメッセヌゞを送信", "description": "チャットアプリケヌションにリク゚ストを送信したす。", - "operationId": "sendChatflowMessageJp", - "tags": ["チャットメッセヌゞ"], + "operationId": "createChatflowMessageJa", + "tags": [ + "チャットメッセヌゞ" + ], "requestBody": { - "description": "チャットメッセヌゞ送信のリク゚ストボディ。", + "description": "チャットメッセヌゞを送信するためのリク゚ストボディ。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatflowRequestJp" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file": { - "summary": "ファむルずカスタム入力を含むストリヌミングリク゚ストの䟋", + "streaming_example": { + "summary": "リク゚スト䟋 - ストリヌミングモヌド", "value": { "inputs": { - "name": "dify" + "city": "San Francisco" }, - "query": "iPhone 13 Pro Maxの仕様は䜕ですか", + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276", + "conversation_id": "", "user": "abc-123", "files": [ { @@ -56,6 +58,16 @@ } ] } + }, + "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" + } } } } @@ -63,267 +75,436 @@ }, "responses": { "200": { - "description": "リク゚スト成功。応答のコンテントタむプず構造はリク゚ストの `response_mode` パラメヌタに䟝存したす。\n- `response_mode` が `blocking` の堎合、`application/json` 圢匏の `ChatCompletionResponseJp` オブゞェクトを返したす。\n- `response_mode` が `streaming` の堎合、`text/event-stream` 圢匏の `ChunkChatflowEventJp` オブゞェクトのストリヌムを返したす。", + "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/ChatCompletionResponseJp" + "$ref": "#/components/schemas/ChatCompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "レスポンス䟋 - ブロッキングモヌド", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "advanced-chat", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "SSEむベントストリヌム。各むベントは 'data: ' で始たり、'\\n\\n' で終わりたす。詳现な構造は `ChunkChatflowEventJp` を参照しおください。" + "description": "サヌバヌ送信むベント (SSE) のストリヌムです。各むベントは `data: ` プレフィックス付きの JSON オブゞェクトで、2 ぀の改行で終了したす。\n\n**SSE パヌスガむド**各むベントは `data: ` プレフィックス付きの JSON オブゞェクトの行で、`\\n\\n` で終了したす。JSON をパヌスする前に `data: ` プレフィックスを陀去しおください。JSON 内の `event` フィヌルドがむベントタむプを決定したす。終了むベント`message_end`、`workflow_finished`、`error` などを受信するずストリヌムは終了したす。`ping` むベント10 秒ごずに接続維持のために送信は無芖しおください。ストリヌム内で゚ラヌむベントが発生しおも HTTP ステヌタスコヌドは垞に `200` です。" + }, + "examples": { + "streamingResponseBasic": { + "summary": "Response Example - Streaming (Basic)", + "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" + }, + "streamingResponseWorkflow": { + "summary": "Response Example - Streaming (Workflow)", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}" + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestGenericJp" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } - } - } - }, - "/files/upload": { - "post": { - "summary": "ファむルアップロヌド", - "description": "メッセヌゞ送信時に䜿甚するファむルをアップロヌドし、画像ずテキストのマルチモヌダル理解を可胜にしたす。アプリケヌションでサポヌトされおいる圢匏をサポヌトしたす。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", - "operationId": "uploadChatflowFileJp", - "tags": ["ファむル操䜜"], - "requestBody": { - "description": "ファむルアップロヌドリク゚スト。`multipart/form-data` リク゚ストが必芁です。", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "アップロヌドするファむル。" + "400": { + "description": "- `app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルは利甚できたせん。\n- `completion_request_error` : テキスト生成に倱敗したした。\n- `bad_request` : Cannot use draft workflow version.\n- `bad_request` : Invalid `workflow_id` format.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } }, - "user": { - "type": "string", - "description": "ナヌザヌ識別子。開発者のルヌルによっお定矩され、アプリケヌション内で䞀意でなければなりたせん。**重芁な泚意事項**: Service API は WebApp で䜜成された察話を共有したせん。API を通じお䜜成された察話は、WebApp むンタヌフェヌスで䜜成されたものずは分離されおいたす。" + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "conversation_completed": { + "summary": "conversation_completed", + "value": { + "status": 400, + "code": "conversation_completed", + "message": "The conversation has ended. Please start a new conversation." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "is_draft_workflow": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. " + } + }, + "workflow_id_format_error": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Invalid workflow_id format: 'not-a-valid-id'. " + } } } } } - } - }, - "responses": { - "200": { - "description": "ファむルアップロヌド成功。", + }, + "404": { + "description": "- `not_found` : 䌚話が存圚したせん。\n- `not_found` : 指定された `workflow_id` のワヌクフロヌが芋぀かりたせん。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponseJp" + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "workflow_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab" + } + } } } } }, - "201": { - "description": "ファむル䜜成成功代替成功コヌド。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } + "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" + } + } + } + } + } }, - "400": { "$ref": "#/components/responses/BadRequestFileJp" }, - "413": { "$ref": "#/components/responses/FileTooLargeJp" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileJp" }, - "503": { "$ref": "#/components/responses/S3ErrorFileJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + "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." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { - "get": { - "summary": "゚ンドナヌザヌ取埗", - "description": "IDで゚ンドナヌザヌを取埗したす。\n\n他のAPIが゚ンドナヌザヌID䟋ファむルアップロヌドの `created_by`を返す堎合に利甚できたす。", - "operationId": "getEndUserChatflowJp", - "tags": ["゚ンドナヌザヌ"], + "/chat-messages/{task_id}/stop": { + "post": { + "summary": "生成を停止", + "description": "チャットメッセヌゞ生成タスクを停止したす。`streaming` モヌドでのみサポヌトされたす。", + "operationId": "stopChatflowMessageJa", + "tags": [ + "チャットメッセヌゞ" + ], "parameters": [ { - "name": "end_user_id", + "name": "task_id", "in": "path", "required": true, - "description": "゚ンドナヌザヌID。", - "schema": { "type": "string", "format": "uuid" } + "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": { - "description": "゚ンドナヌザヌの取埗に成功したした。", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : アプリモヌドが API ルヌトず䞀臎したせん。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailJp" } + "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": { "$ref": "#/components/responses/EndUserNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + } } } }, - "/files/{file_id}/preview": { + "/messages/{message_id}/suggested": { "get": { - "summary": "ファむルプレビュヌ", - "description": "アップロヌドされたファむルのプレビュヌたたはダりンロヌド。この゚ンドポむントは、ファむルアップロヌドAPIを通じお事前にアップロヌドされたファむルにアクセスするこずができたす。ファむルは、リク゚ストしおいるアプリケヌション内のメッセヌゞに属しおいる堎合のみアクセス可胜です。", - "operationId": "previewChatflowFileJp", - "tags": ["ファむル操䜜"], + "summary": "次の掚奚質問", + "description": "珟圚のメッセヌゞに察する次の質問の提案を取埗したす。", + "operationId": "getChatflowSuggestedQuestionsJa", + "tags": [ + "チャットメッセヌゞ" + ], "parameters": [ { - "name": "file_id", + "name": "message_id", "in": "path", "required": true, - "description": "プレビュヌするファむルの䞀意識別子、ファむルアップロヌドAPIのレスポンスから取埗されたす。", + "description": "メッセヌゞ ID。", "schema": { - "type": "string", - "format": "uuid" + "type": "string" } }, { - "name": "as_attachment", + "name": "user", "in": "query", - "required": false, - "description": "ファむルを添付ファむルずしお匷制ダりンロヌドするかどうか。デフォルトは`false`ブラりザでプレビュヌです。", + "required": true, + "description": "ナヌザヌ識別子。", "schema": { - "type": "boolean", - "default": false + "type": "string" } } ], "responses": { "200": { - "description": "ファむルコンテンツが正垞に返されたした。ヘッダヌはファむルタむプずリク゚ストパラメヌタに基づいお蚭定されたす。", + "description": "提案された質問の取埗に成功したした。", "content": { - "image/png": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - }, - "headers": { - "Content-Type": { - "description": "ファむルのMIMEタむプ", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "ファむルサむズバむト単䜍、利甚可胜な堎合", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "as_attachment=trueの堎合、'attachment'に蚭定されたす", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "パフォヌマンス甚キャッシュヘッダヌ", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "オヌディオ/ビデオファむルの堎合は'bytes'に蚭定されたす", + "application/json": { "schema": { - "type": "string", - "example": "bytes" + "$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": "䞍正なリク゚スト。可胜な゚ラヌコヌド:\n- `invalid_param`: 異垞なパラメヌタ入力。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } - } - } - }, - "403": { - "description": "犁止。可胜な゚ラヌコヌド:\n- `file_access_denied`: ファむルアクセス拒吊たたはファむルが珟圚のアプリケヌションに属しおいたせん。", + "description": "- `not_chat_app` : アプリモヌドが API ルヌトず䞀臎したせん。\n- `bad_request` : 掚奚質問機胜が無効です。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } + "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": "芋぀かりたせん。可胜な゚ラヌコヌド:\n- `file_not_found`: ファむルが芋぀からないか削陀されおいたす。", + "description": "`not_found` : メッセヌゞが存圚したせん。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } } } }, "500": { - "description": "内郚サヌバヌ゚ラヌ。", + "description": "`internal_server_error` : 内郚サヌバヌ゚ラヌ。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } } } }, - "/chat-messages/{task_id}/stop": { + "/files/upload": { "post": { - "summary": "生成を停止", - "description": "チャットメッセヌゞの生成を停止したす。ストリヌミングモヌドでのみサポヌトされおいたす。", - "operationId": "stopChatflowMessageGenerationJp", - "tags": ["チャットメッセヌゞ"], - "parameters": [ - { - "name": "task_id", - "in": "path", - "required": true, - "description": "タスクID、ストリヌミングチャンクの返り倀から取埗できたす。", - "schema": { "type": "string", "format": "uuid" } - } + "operationId": "uploadChatflowFileJa", + "tags": [ + "ファむル操䜜" ], + "summary": "ファむルアップロヌド", + "description": "メッセヌゞ送信時に䜿甚するファむルをアップロヌドしたす。画像、ドキュメント、音声、動画のマルチモヌダル理解が可胜です。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", "requestBody": { + "description": "ファむルアップロヌドリク゚スト。multipart/form-data 圢匏が必芁です。", "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "file" + ], "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "アップロヌドするファむル。サポヌトされるタむプには画像、ドキュメント、音声、動画が含たれたす。" + }, "user": { "type": "string", - "description": "ナヌザヌ識別子。送信メッセヌゞむンタヌフェヌスで枡されたナヌザヌず䞀臎しおいる必芁がありたす。" + "description": "ナヌザヌ識別子。開発者のルヌルで定矩され、アプリケヌション内で䞀意である必芁がありたす。" } } } @@ -331,452 +512,5688 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResultJp" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "メッセヌゞフィヌドバック", - "description": "゚ンドナヌザヌはフィヌドバックメッセヌゞを提䟛でき、アプリケヌション開発者が期埅される出力を最適化するのを支揎したす。", - "operationId": "postChatflowMessageFeedbackJp", - "tags": ["メッセヌゞフィヌドバック"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "メッセヌゞID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestJp" } + "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" + } + } + } + } } - } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResultJp" } - } - } - }, - "/app/feedbacks": { - "get": { - "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", - "description": "アプリの゚ンドナヌザヌからのフィヌドバックや「いいね」を取埗したす。", - "operationId": "getChatflowAppFeedbacksJp", - "tags": ["メッセヌゞフィヌドバック"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParamJp" }, - { "$ref": "#/components/parameters/LimitQueryParamJp" } - ], - "responses": { - "200": { - "description": "アプリのフィヌドバックリストを正垞に取埗したした。", + }, + "400": { + "description": "- `no_file_uploaded` : リク゚ストにファむルが提䟛されおいたせん。\n- `too_many_files` : 1 回のリク゚ストに぀き 1 ファむルのみ蚱可されおいたす。\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": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseJp" } + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } } } - } - } - } - }, - "/messages/{message_id}/suggested": { - "get": { - "summary": "次の掚奚質問", - "description": "珟圚のメッセヌゞに察する次の質問の提案を取埗したす。", - "operationId": "getChatflowSuggestedQuestionsJp", - "tags": ["チャットメッセヌゞ"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "メッセヌゞID。", - "schema": { "type": "string", "format": "uuid" } }, - { "$ref": "#/components/parameters/UserQueryParamJp" } - ], - "responses": { - "200": { - "description": "掚奚質問リストを正垞に取埗したした。", + "415": { + "description": "`unsupported_file_type` : 蚱可されおいないファむルタむプです。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponseJp" } + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } } } } } } }, - "/messages": { + "/files/{file_id}/preview": { "get": { - "summary": "䌚話履歎メッセヌゞを取埗", - "description": "スクロヌルロヌド圢匏で履歎チャット蚘録を返し、最初のペヌゞは最新の`{limit}`メッセヌゞを返したす。぀たり、逆順です。", - "operationId": "getChatflowConversationHistoryJp", - "tags": ["䌚話管理"], + "operationId": "previewChatflowFileJa", + "tags": [ + "ファむル操䜜" + ], + "summary": "ファむルダりンロヌド", + "description": "以前[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", "parameters": [ - { "$ref": "#/components/parameters/ConversationIdQueryParamJp" }, - { "$ref": "#/components/parameters/UserQueryParamJp" }, { - "name": "first_id", - "in": "query", - "description": "珟圚のペヌゞの最初のチャット蚘録のID、デフォルトはnullです。", - "schema": { "type": "string", "format": "uuid", "nullable": true } + "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 + } }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Jp" } + { + "name": "user", + "in": "query", + "required": false, + "description": "ナヌザヌ識別子。゚ンドナヌザヌのコンテキストに䜿甚されたす。", + "schema": { + "type": "string" + } + } ], "responses": { "200": { - "description": "䌚話履歎メッセヌゞを正垞に取埗したした。", + "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": { - "schema": { "$ref": "#/components/schemas/ConversationHistoryResponseJp" } + "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." + } + } + } } } } } } }, - "/conversations": { + "/end-users/{end_user_id}": { "get": { - "summary": "䌚話を取埗", - "description": "珟圚のナヌザヌの䌚話リストを取埗し、デフォルトで最新の20件を返したす。", - "operationId": "getChatflowConversationsListJp", - "tags": ["䌚話管理"], + "operationId": "getChatflowEndUserJa", + "tags": [ + "゚ンドナヌザヌ" + ], + "summary": "゚ンドナヌザヌ取埗", + "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド)の `created_by`に䟿利です。", "parameters": [ - { "$ref": "#/components/parameters/UserQueryParamJp" }, - { "$ref": "#/components/parameters/LastIdQueryParamJp" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Jp" }, - { "$ref": "#/components/parameters/SortByQueryParamJp" } + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "゚ンドナヌザヌ ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } ], "responses": { "200": { - "description": "䌚話リストを正垞に取埗したした。", + "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": { - "schema": { "$ref": "#/components/schemas/ConversationsListResponseJp" } + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } } } } } } }, - "/conversations/{conversation_id}": { - "delete": { - "summary": "䌚話を削陀", - "description": "指定された䌚話を削陀したす。", - "operationId": "deleteChatflowConversationJp", - "tags": ["䌚話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJp" } ], + "/messages/{message_id}/feedbacks": { + "post": { + "operationId": "createChatflowMessageFeedbackJa", + "tags": [ + "メッセヌゞフィヌドバック" + ], + "summary": "メッセヌゞフィヌドバック", + "description": "メッセヌゞに察するフィヌドバックを送信したす。゚ンドナヌザヌはメッセヌゞを `like` たたは `dislike` で評䟡でき、任意でテキストフィヌドバックを提䟛できたす。`rating` に `null` を枡すず、以前送信したフィヌドバックを取り消せたす。", + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "メッセヌゞ ID。", + "schema": { + "type": "string" + } + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "type": "object", "required": ["user"], - "properties": { "user": { "type": "string", "description": "ナヌザヌ識別子。**重芁な泚意事項**: Service API は WebApp で䜜成された察話を共有したせん。API を通じお䜜成された察話は、WebApp むンタヌフェヌスで䜜成されたものずは分離されおいたす。" } } + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "リク゚スト䟋", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } } } } }, - "responses": { "204": { "description": "䌚話が正垞に削陀されたした。コンテンツはありたせん。" } } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "䌚話の名前を倉曎", - "description": "セッションの名前を倉曎したす。", - "operationId": "renameChatflowConversationJp", - "tags": ["䌚話管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamJp" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequestJp" } } } - }, "responses": { - "200": { "description": "䌚話の名前が正垞に倉曎されたした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameResponseJp" } } } } + "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." + } + } + } + } + } + } } } }, - "/conversations/{conversation_id}/variables": { + "/app/feedbacks": { "get": { - "summary": "䌚話倉数の取埗", - "description": "特定の䌚話から倉数を取埗したす。この゚ンドポむントは、䌚話䞭に取埗された構造化デヌタを抜出するのに圹立ちたす。", - "operationId": "getChatflowConversationVariablesJp", - "tags": ["䌚話管理"], + "operationId": "listChatflowFeedbacksJa", + "tags": [ + "メッセヌゞフィヌドバック" + ], + "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", + "description": "このアプリケヌションのメッセヌゞに察しお送信されたすべおのフィヌドバックのペヌゞネヌション付きリストを取埗したす。゚ンドナヌザヌず管理者のフィヌドバックの䞡方が含たれたす。", "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParamJp" }, - { "$ref": "#/components/parameters/UserQueryParamJp" }, - { "$ref": "#/components/parameters/LastIdQueryParamJp" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Jp" } + { + "name": "page", + "in": "query", + "description": "ペヌゞネヌションのペヌゞ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1ペヌゞあたりのレコヌド数。", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 101 + } + } ], "responses": { - "200": { "description": "䌚話倉数を正垞に取埗したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationVariablesResponseJp" } } } }, - "404": { "$ref": "#/components/responses/ConversationNotFoundJp" } - } - } - }, - "/audio-to-text": { - "post": { - "summary": "音声からテキストぞ", - "description": "オヌディオファむルをテキストに倉換したす。サポヌトされおいる圢匏mp3, mp4, mpeg, mpga, m4a, wav, webm。ファむルサむズ制限15MB。", - "operationId": "chatflowAudioToTextJp", - "tags": ["音声・テキスト倉換"], - "requestBody": { - "required": true, - "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequestJp" } } } - }, - "responses": { - "200": { "description": "音声をテキストに正垞に倉換したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponseJp" } } } } + "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" + } + ] + } + } + } + } + } + } } } }, - "/text-to-audio": { - "post": { - "summary": "テキストから音声ぞ", - "description": "テキストコンテンツを音声に倉換したす。", - "operationId": "chatflowTextToAudioJp", - "tags": ["音声・テキスト倉換"], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToAudioJsonRequestJp" } } } - }, + "/conversations": { + "get": { + "summary": "䌚話を取埗", + "description": "珟圚のナヌザヌの䌚話リストを、最近アクティブな順に取埗したす。", + "operationId": "listChatflowConversationsJa", + "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": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, - "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } + "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." + } + } + } + } + } } } } }, - "/info": { - "get": { - "summary": "アプリケヌションの基本情報を取埗", - "operationId": "getChatflowAppInfoJp", - "tags": ["アプリケヌション蚭定"], - "responses": { "200": { "description": "アプリケヌションの基本情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseJp" } } } } } - } - }, - "/parameters": { - "get": { - "summary": "アプリケヌションのパラメヌタ情報を取埗", - "description": "ペヌゞに入る際に、機胜、入力パラメヌタ名、タむプ、デフォルト倀などの情報を取埗するために䜿甚されたす。", - "operationId": "getChatflowAppParametersJp", - "tags": ["アプリケヌション蚭定"], - "responses": { "200": { "description": "アプリケヌションのパラメヌタ情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAppParametersResponseJp" } } } } } - } - }, - "/meta": { - "get": { - "summary": "アプリケヌションのメタ情報を取埗", - "description": "このアプリケヌションのツヌルのアむコンを取埗するために䜿甚されたす。", - "operationId": "getChatflowAppMetaJp", - "tags": ["アプリケヌション蚭定"], - "responses": { "200": { "description": "アプリケヌションのメタ情報を正垞に取埗したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponseJp" } } } } } - } - }, - "/site": { + "/messages": { "get": { - "summary": "アプリのWebApp蚭定を取埗", - "description": "アプリのWebApp蚭定を取埗するために䜿甚したす。", - "operationId": "getChatflowWebAppSettingsJp", - "tags": ["アプリケヌション蚭定"], - "responses": { "200": { "description": "WebAppの蚭定情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseJp" } } } } } - } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "APIキヌ認蚌。すべおのAPIリク゚ストには、Authorization HTTPヘッダヌにAPIキヌを `Bearer {API_KEY}` の圢匏で含めおください。APIキヌはサヌバヌ偎に保存し、クラむアント偎で共有たたは保存しないこずを匷くお勧めしたす。" } - }, - "parameters": { - "PageQueryParamJp": { "name": "page", "in": "query", "description": "任意ペヌゞ番号。デフォルト倀1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamJp": { "name": "limit", "in": "query", "description": "任意1ペヌゞあたりの件数。デフォルト倀20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Jp": { "name": "limit", "in": "query", "description": "1回のリク゚ストで返す蚘録の数、デフォルトは20です。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100Jp": { "name": "limit", "in": "query", "description": "1回のリク゚ストで返す蚘録の数、デフォルトは最新の20件です。最倧100、最小1。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParamJp": { "name": "user", "in": "query", "required": true, "description": "ナヌザヌ識別子。アプリケヌション内で開発者によっお䞀意に定矩されるべきです。**重芁な泚意事項**: Service API は WebApp で䜜成された察話を共有したせん。API を通じお䜜成された察話は、WebApp むンタヌフェヌスで䜜成されたものずは分離されおいたす。", "schema": { "type": "string" } }, - "ConversationIdQueryParamJp": { "name": "conversation_id", "in": "query", "required": true, "description": "䌚話ID。", "schema": { "type": "string", "format": "uuid" } }, - "LastIdQueryParamJp": { "name": "last_id", "in": "query", "description": "(Optional)珟圚のペヌゞの最埌の蚘録のID、デフォルトはnullです。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, - "SortByQueryParamJp": { "name": "sort_by", "in": "query", "description": "(Optional)゜ヌトフィヌルド、デフォルト-updated_at曎新時間で降順に゜ヌト。利甚可胜な倀created_at, -created_at, updated_at, -updated_at。'-'は逆順を衚したす。", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParamJp": { "name": "conversation_id", "in": "path", "required": true, "description": "䌚話ID。", "schema": { "type": "string", "format": "uuid" } } - }, - "responses": { - "BadRequestGenericJp": { "description": "リク゚ストパラメヌタ゚ラヌ。考えられる原因invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "BadRequestFileJp": { "description": "ファむル操䜜リク゚スト゚ラヌ。考えられる原因no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "FileTooLargeJp": { "description": "ファむルが倧きすぎたす (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "UnsupportedFileTypeFileJp": { "description": "サポヌトされおいないファむルタむプ (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "S3ErrorFileJp": { "description": "S3ストレヌゞサヌビス゚ラヌ。考えられる原因s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "InternalServerErrorJp": { "description": "内郚サヌバヌ゚ラヌ。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "SuccessResultJp": { "description": "操䜜成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFoundJp": { "description": "䌚話が存圚したせん。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "EndUserNotFoundJp": { "description": "゚ンドナヌザヌが芋぀かりたせん。゚ラヌコヌド`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } } - }, - "schemas": { - "ChatflowRequestJp": { - "type": "object", - "required": ["query", "user"], - "properties": { - "query": { "type": "string", "description": "ナヌザヌ入力/質問内容。" }, - "inputs": { - "type": "object", - "description": "アプリによっお定矩されたさたざたな倉数倀の入力を蚱可したす。倉数がファむルタむプの堎合、InputFileObjectJp オブゞェクトを指定したす。", - "additionalProperties": { - "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "$ref": "#/components/schemas/InputFileObjectJp" } ] - }, - "default": {} + "summary": "䌚話履歎メッセヌゞを取埗", + "description": "スクロヌル読み蟌み圢匏で過去のチャット蚘録を返したす。最初のペヌゞは最新の `limit` 件のメッセヌゞを返したす時系列の逆順。", + "operationId": "listChatflowMessagesJa", + "tags": [ + "䌚話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "䌚話 ID。", + "schema": { + "type": "string" + } }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "応答の返华モヌド。streaming (掚奚) はSSEを䜿甚。blocking は実行完了埌に結果を返したす (Cloudflareの100秒タむムアりト制限あり)。" }, - "user": { "type": "string", "description": "ナヌザヌ識別子。アプリケヌション内で䞀意であるべきです。**重芁な泚意事項**: Service API は WebApp で䜜成された察話を共有したせん。API を通じお䜜成された察話は、WebApp むンタヌフェヌスで䜜成されたものずは分離されおいたす。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "䌚話ID。以前のチャット蚘録に基づいお䌚話を続ける堎合に必芁です。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectJp" }, "description": "ファむルリスト。モデルがビゞョン機胜をサポヌトしおいる堎合に利甚可胜です。" }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "タむトルを自動生成。デフォルトはtrue。" } - } - }, - "InputFileObjectJp": { - "type": "object", - "required": ["type", "transfer_method"], - "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "ファむルタむプ。document: TXT,MD,PDF等; image: JPG,PNG等; audio: MP3,WAV等; video: MP4,MOV等; custom: その他。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "転送方法。remote_url は画像URL / local_file はファむルアップロヌド甚" }, - "url": { "type": "string", "format": "url", "description": "画像URL転送方法が remote_url の堎合" }, - "upload_file_id": { "type": "string", "format":"uuid", "description": "アップロヌドされたファむルID、事前にファむルアップロヌドAPIで取埗する必芁がありたす転送方法が local_file の堎合" } - }, - "anyOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "name": "user", + "in": "query", + "required": false, + "description": "ナヌザヌ識別子。", + "schema": { + "type": "string" + } }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format":"uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } - } - ] - }, - "ChatCompletionResponseJp": { - "type": "object", "description": "ブロッキングモヌドでの完党なアプリ結果。", - "properties": { - "event": { "type": "string", "example": "message", "description": "むベントタむプ、固定で `message`。" }, - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "id": { "type": "string", "format": "uuid", "description": "ナニヌクID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "䞀意のメッセヌゞID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "䌚話ID。" }, - "mode": { "type": "string", "example": "chat", "description": "アプリモヌド、`chat`ずしお固定。" }, - "answer": { "type": "string", "description": "完党な応答内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataJp" }, - "created_at": { "type": "integer", "format": "int64", "description": "メッセヌゞ䜜成タむムスタンプ。" } - } - }, - "ResponseMetadataJp": { - "type": "object", "description": "メタデヌタ。", - "properties": { "usage": { "$ref": "#/components/schemas/UsageJp" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJp" }, "description": "匕甚ず垰属リスト。" } } - }, - "ChunkChatflowEventJp": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "workflow_started", "node_started", "node_finished", "workflow_finished", "error", "ping"], "description": "むベントタむプ。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "message": "#/components/schemas/StreamEventChatMessageJp", "message_file": "#/components/schemas/StreamEventMessageFileJp", - "message_end": "#/components/schemas/StreamEventMessageEndJp", "tts_message": "#/components/schemas/StreamEventTtsMessageJp", - "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndJp", "message_replace": "#/components/schemas/StreamEventMessageReplaceJp", - "workflow_started": "#/components/schemas/StreamEventWorkflowStartedJp", "node_started": "#/components/schemas/StreamEventNodeStartedJp", - "node_finished": "#/components/schemas/StreamEventNodeFinishedJp", "workflow_finished": "#/components/schemas/StreamEventWorkflowFinishedJp", - "error": "#/components/schemas/StreamEventErrorJp", "ping": "#/components/schemas/StreamEventPingJp" - }} - }, - "StreamEventBaseChatJp": { - "type": "object", "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": "䜜成タむムスタンプ。" } - } - }, - "StreamEventChatMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLMが返したテキストチャンク内容。" } } } ] }, - "StreamEventMessageFileJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ファむル䞀意ID。" }, "type": { "type": "string", "enum": ["image"], "description": "ファむルタむプ、珟圚はimageのみ。" }, "belongs_to": { "type": "string", "enum": ["assistant"], "description": "所属、ここではassistantのみ。" }, "url": { "type": "string", "format": "url", "description": "ファむルのリモヌトURL。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "䌚話ID。" } } } ] }, - "StreamEventMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataJp" } } } ] }, - "StreamEventTtsMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64゚ンコヌドされたオヌディオブロック。" } } } ] }, - "StreamEventTtsMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空の文字列。" } } } ] }, - "StreamEventMessageReplaceJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseChatJp" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "眮換内容すべおのLLM返信テキストを盎接眮き換えたす。" } } } ] }, - "StreamEventWorkflowStartedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/WorkflowStartedDataJp" } } } ] }, - "WorkflowStartedDataJp": { "type": "object", "required": ["id", "workflow_id", "sequence_number", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワヌクフロヌ実行の䞀意ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "関連ワヌクフロヌのID。" }, "sequence_number": { "type": "integer", "description": "自己増加シリアル番号、アプリ内で自己増加し、1から始たりたす。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } }, - "StreamEventNodeStartedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/NodeStartedDataJp" } } } ] }, - "NodeStartedDataJp": { "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワヌクフロヌ実行の䞀意ID (文脈からノヌド実行IDであるべき)。" }, "node_id": { "type": "string", "format": "uuid", "description": "ノヌドのID。" }, "node_type": { "type": "string", "description": "ノヌドのタむプ。" }, "title": { "type": "string", "description": "ノヌドの名前。" }, "index": { "type": "integer", "description": "実行シヌケンス番号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "オプションのプレフィックスノヌドID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ノヌドで䜿甚されるすべおの前のノヌド倉数の内容。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始のタむムスタンプ。" } } }, - "StreamEventNodeFinishedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/NodeFinishedDataJp" } } } ] }, - "NodeFinishedDataJp": { "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "status", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ノヌド実行の䞀意ID。" }, "node_id": { "type": "string", "format": "uuid", "description": "ノヌドのID。" }, "node_type": { "type": "string", "description": "ノヌドのタむプ。" }, "title": { "type": "string", "description": "ノヌドの名前。" }, "index": { "type": "integer", "description": "実行シヌケンス番号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "オプションのãƒ—レフィックスノヌドID。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "ノヌドで䜿甚されるすべおの前のノヌド倉数の内容。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "オプションのノヌドプロセスデヌタ (JSON)。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "オプションの出力内容 (JSON)。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行の状態。" }, "error": { "type": "string", "nullable": true, "description": "オプションの゚ラヌ理由。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "オプションの䜿甚される合蚈秒数。" }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadataJp" , "nullable": true, "description": "メタデヌタ"}, "created_at": { "type": "integer", "format": "int64", "description": "開始のタむムスタンプ。" } } }, - "NodeExecutionMetadataJp": { "type": "object", "description": "ノヌド実行メタデヌタ。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "オプションの䜿甚されるトヌクン数。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "オプションの合蚈コスト (floatでdecimalを代甚)。" }, "currency": { "type": "string", "nullable": true, "example": "USD", "description": "オプションの通貚。" } } }, - "StreamEventWorkflowFinishedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/WorkflowFinishedDataJp" } } } ] }, - "WorkflowFinishedDataJp": { "type": "object", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワヌクフロヌ実行のID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "関連ワヌクフロヌのID。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行の状態。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "オプションの出力内容 (JSON)。" }, "error": { "type": "string", "nullable": true, "description": "オプションの゚ラヌ理由。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "オプションの䜿甚される合蚈秒数。" }, "total_tokens": { "type": "integer", "nullable": true, "description": "オプションの䜿甚されるトヌクン数。" }, "total_steps": { "type": "integer", "default": 0, "description": "合蚈ステップ数、デフォルト0。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始時間。" }, "finished_at": { "type": "integer", "format": "int64", "description": "終了時間。" } } }, - "StreamEventErrorJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "required": ["task_id", "status", "code", "message"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "䞀意のメッセヌゞID゚ラヌむベントでは存圚しない堎合がある。" }, "status": { "type": "integer", "description": "HTTPステヌタスコヌド。" }, "code": { "type": "string", "description": "゚ラヌコヌド。" }, "message": { "type": "string", "description": "゚ラヌメッセヌゞ。" } } } ] }, - "StreamEventPingJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatflowEventJp" }, { "type": "object", "description": "接続を維持するために10秒ごずにpingむベントが発生したす。" } ] }, - "UsageJp": { "type": "object", "description": "モデル䜿甚情報。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceJp": { "type": "object", "description": "匕甚ず垰属リスト。", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } }, - "FileUploadResponseJp": { "type": "object", "description": "ファむルアップロヌド成功時の応答。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "ファむル名。" }, "size": { "type": "integer", "description": "ファむルサむズバむト。" }, "extension": { "type": "string", "description": "ファむル拡匵子。" }, "mime_type": { "type": "string", "description": "ファむルのMIMEタむプ。" }, "created_by": { "type": "string", "format": "uuid", "description": "゚ンドナヌザヌID。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } }, - "EndUserDetailJp": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } - } - }, - "MessageFeedbackRequestJp": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "アップボヌトは`like`、ダりンボヌトは`dislike`、取り消しは`null`。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" }, "content": { "type": "string", "nullable": true, "description": "メッセヌゞフィヌドバックの具䜓的な内容。" } } }, - "AppFeedbacksResponseJp": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemJp" }, "description": "このアプリの「いいね」ずフィヌドバックの䞀芧。" } } }, - "FeedbackItemJp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "SuggestedQuestionsResponseJp": { "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "description": "掚奚質問のリスト。" } } }, - "ConversationHistoryResponseJp": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返された項目数。" }, "has_more": { "type": "boolean", "description": "次のペヌゞがあるかどうか。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessageItemJp" }, "description": "メッセヌゞリスト。" } } }, - "ConversationMessageItemJp": { "type": "object", "description": "䌚話内の単䞀メッセヌゞ。", "properties": { "id": { "type": "string", "format": "uuid", "description": "メッセヌゞID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "䌚話ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ナヌザヌ入力パラメヌタ。" }, "query": { "type": "string", "description": "ナヌザヌ入力/質問内容。" }, "answer": { "type": "string", "description": "応答メッセヌゞ内容。" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItemJp" }, "description": "メッセヌゞファむルリスト。" }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"], "description": "アップボヌトは`like` / ダりンボヌトは`dislike`。" } }, "description": "フィヌドバック情報。" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJp" }, "description": "匕甚ず垰属リスト。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } }, - "MessageFileItemJp": { "type": "object", "description": "メッセヌゞ内のファむル項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "ファむルタむプ、䟋'image'。" }, "url": { "type": "string", "format": "url", "description": "プレビュヌ画像URL。" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "所属。" } } }, - "ConversationsListResponseJp": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返された゚ントリ数。" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItemJp" }, "description": "䌚話のリスト。" } } }, - "ConversationListItemJp": { "type": "object", "description": "䌚話リスト内の単䞀項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "䌚話ID。" }, "name": { "type": "string", "description": "䌚話名。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ナヌザヌ入力パラメヌタ。" }, "status": { "type": "string", "description": "䌚話状態。" }, "introduction": { "type": "string", "nullable": true, "description": "玹介。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" }, "updated_at": { "type": "integer", "format": "int64", "description": "曎新タむムスタンプ。" } } }, - "ConversationRenameRequestJp": { "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true, "description": "(Optional)䌚話の名前。`auto_generate`が`true`の堎合省略可。" }, "auto_generate": { "type": "boolean", "default": false, "description": "(Optional)タむトルを自動生成、デフォルトは`false`。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" } } }, - "ConversationRenameResponseJp": { "$ref": "#/components/schemas/ConversationListItemJp" }, - "ConversationVariablesResponseJp": { "type": "object", "properties": { "limit": { "type": "integer", "description": "ペヌゞごずのアむテム数。" }, "has_more": { "type": "boolean", "description": "さらにアむテムがあるかどうか。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItemJp" }, "description": "倉数のリスト。" } } }, - "ConversationVariableItemJp": { "type": "object", "description": "䌚話内の倉数項目。", "properties": { "id": { "type": "string", "format": "uuid", "description": "倉数ID。" }, "name": { "type": "string", "description": "倉数名。" }, "value_type": { "type": "string", "description": "倉数タむプ文字列、数倀、真停倀など。" }, "value": { "type": "string", "description": "倉数倀。" }, "description": { "type": "string", "nullable": true, "description": "倉数の説明。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最終曎新タむムスタンプ。" } } }, - "AudioToTextRequestJp": { "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "オヌディオファむル。サポヌト圢匏`['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']`。サむズ制限15MB。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" } } }, - "AudioToTextResponseJp": { "type": "object", "properties": { "text": { "type": "string", "description": "出力テキスト。" } } }, - "TextToAudioJsonRequestJp": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "メッセヌゞID優先。" }, "text": { "type": "string", "description": "音声生成コンテンツ。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" }, "streaming": {"type": "boolean", "default": false, "description": "trueの堎合、応答はオヌディオチャンクのストリヌムになりたす。"} }, "description": "`user` が必芁です。`message_id` たたは `text` を提䟛しおください。" }, - "AppInfoResponseJp": { "type": "object", "description": "アプリケヌションの基本情報。", "properties": { "name": { "type": "string", "description": "アプリケヌションの名前。" }, "description": { "type": "string", "description": "アプリケヌションの説明。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "アプリケヌションのタグ。" } } }, - "ChatAppParametersResponseJp": { "type": "object", "description": "アプリケヌションのパラメヌタ情報。", "properties": { "opening_statement": { "type": "string", "description": "開始の挚拶。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "開始時の掚奚質問のリスト。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "答えを有効にした埌の質問を提案したす。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "音声からテキストぞ。" }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" }, "voice": { "type": "string", "description": "音声タむプ。" }, "language": { "type": "string", "description": "蚀語。" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"], "description": "自動再生enabled 有効, disabled 無効。" } }, "description": "テキストから音声ぞ。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "匕甚ず垰属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "有効かどうか。" } }, "description": "泚釈返信。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemJp" }, "description": "ナヌザヌ入力フォヌムの蚭定。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "画像蚭定。サポヌトされおいる画像タむプpng, jpg, jpeg, webp, gif。" } }, "description": "ファむルアップロヌド蚭定。" }, "system_parameters": { "type": "object", "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。" } }, "description": "システムパラメヌタ。" } } }, - "UserInputFormItemJp": { "type": "object", "description": "ナヌザヌ入力フォヌムのコントロヌル項目。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperJp" }, { "$ref": "#/components/schemas/ParagraphControlWrapperJp" }, { "$ref": "#/components/schemas/SelectControlWrapperJp" } ] }, - "TextInputControlWrapperJp": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlJp" } }, "required":["text-input"] }, - "ParagraphControlWrapperJp": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlJp" } }, "required":["paragraph"] }, - "SelectControlWrapperJp": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlJp" } }, "required":["select"] }, - "TextInputControlJp": { "type": "object", "description": "テキスト入力コントロヌル。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" } } }, - "ParagraphControlJp": { "type": "object", "description": "段萜テキスト入力コントロヌル。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" } } }, - "SelectControlJp": { "type": "object", "description": "ドロップダりンコントロヌル。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "オプション倀。" } } }, - "AppMetaResponseJp": { "type": "object", "description": "アプリケヌションのメタ情報。", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url", "description": "アむコンのURL。" }, { "$ref": "#/components/schemas/ToolIconDetailJp" } ] }, "description": "ツヌルアむコン。キヌはツヌル名です。" } } }, - "ToolIconDetailJp": { "type": "object", "description": "ツヌルアむコン詳现。", "properties": { "background": { "type": "string", "description": "背景色16進数圢匏。" }, "content": { "type": "string", "description": "絵文字。" } } }, - "WebAppSettingsResponseJp": { "type": "object", "description": "アプリのWebApp蚭定。", "properties": { "title": { "type": "string", "description": "WebApp名。" }, "chat_color_theme": { "type": "string", "description": "チャットの色テヌマ、16進数圢匏。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "チャットの色テヌマを反転するかどうか。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "アむコンタむプ。" }, "icon": { "type": "string", "description": "アむコン。`emoji`タむプの堎合は絵文字、`image`タむプの堎合は画像URL。" }, "icon_background": { "type": "string", "description": "16進数圢匏の背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "アむコンのURL。" }, "description": { "type": "string", "description": "説明。" }, "copyright": { "type": "string", "description": "著䜜暩情報。" }, "privacy_policy": { "type": "string", "description": "プラむバシヌポリシヌのリンク。" }, "custom_disclaimer": { "type": "string", "description": "カスタム免責事項。" }, "default_language": { "type": "string", "description": "デフォルト蚀語。" }, "show_workflow_steps": { "type": "boolean", "description": "ワヌクフロヌの詳现を衚瀺するかどうか。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "WebAppのアむコンをチャット内のロボットアむコンに眮き換えるかどうか。" } } }, - "ErrorResponseJp": { "type": "object", "description": "゚ラヌ応答。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTPステヌタスコヌド。" }, "code": { "type": "string", "nullable": true, "description": "゚ラヌコヌド。" }, "message": { "type": "string", "description": "゚ラヌメッセヌゞ。" } } } + "name": "first_id", + "in": "query", + "required": false, + "description": "珟圚のペヌゞの最初のチャット蚘録の ID です。デフォルトは `null`最新のメッセヌゞを取埗です。次のペヌゞを取埗するには、珟圚のリストの最初のメッセヌゞの ID を䜿甚しお、より叀いメッセヌゞを取埗したす。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "リク゚ストごずに返すチャット履歎メッセヌゞの数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "䌚話履歎の取埗に成功したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "レスポンス䟋", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "parent_message_id": null, + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "status": "normal", + "error": null, + "message_files": [], + "feedback": { + "rating": "like" + }, + "retriever_resources": [], + "agent_thoughts": [], + "created_at": 1705407629 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : アプリモヌドが API ルヌトず䞀臎したせん。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 䌚話が存圚したせん。\n- `not_found` : 最初のメッセヌゞが存圚したせん。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "first_message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "First Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables": { + "get": { + "summary": "䌚話倉数の取埗", + "description": "特定の䌚話から倉数を取埗したす。", + "operationId": "listChatflowConversationVariablesJa", + "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": "renameChatflowConversationJa", + "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": "updateChatflowConversationVariableJa", + "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": "deleteChatflowConversationJa", + "tags": [ + "䌚話管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "䌚話 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user": { + "type": "string", + "description": "ナヌザヌ識別子です。" + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "リク゚スト䟋" + } + } + } + } + }, + "responses": { + "204": { + "description": "䌚話の削陀に成功したした。コンテンツは返されたせん。" + }, + "400": { + "description": "`not_chat_app` : アプリモヌドが API ルヌトず䞀臎したせん。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 䌚話が存圚したせん。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "chatflowAudioToTextJa", + "tags": [ + "音声・テキスト倉換" + ], + "summary": "音声からテキストぞ", + "description": "音声ファむルをテキストに倉換したす。サポヌトされる圢匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファむルサむズの䞊限は `30 MB` です。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "音声からテキストぞの倉換に成功したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "レスポンス䟋", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。\n- `no_audio_uploaded` : 音声ファむルがアップロヌドされおいたせん。\n- `provider_not_support_speech_to_text` : モデルプロバむダヌが音声認識をサポヌトしおいたせん。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルはこの操䜜をサポヌトしおいたせん。\n- `completion_request_error` : 音声認識リク゚ストに倱敗したした。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音声ファむルサむズが䞊限を超えおいたす。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 蚱可されおいない音声タむプです。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚サヌバヌ゚ラヌ。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/text-to-audio": { + "post": { + "operationId": "chatflowTextToAudioJa", + "tags": [ + "音声・テキスト倉換" + ], + "summary": "テキストから音声ぞ", + "description": "テキストを音声に倉換したす。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "リク゚スト䟋", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "生成された音声ファむルを返したす。`Content-Type` ヘッダヌは音声の MIME タむプ䟋`audio/wav`、`audio/mp3`に蚭定されたす。`streaming` が `true` の堎合、音声はチャンク転送゚ンコヌディングでストリヌミングされたす。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルはこの操䜜をサポヌトしおいたせん。\n- `completion_request_error` : テキスト読み䞊げリク゚ストに倱敗したした。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚サヌバヌ゚ラヌ。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/info": { + "get": { + "operationId": "getChatflowAppInfoJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリケヌションの基本情報を取埗", + "description": "このアプリケヌションの基本情報名前、説明、タグ、モヌドを取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションの基本情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "レスポンス䟋", + "value": { + "name": "My Chatflow App", + "description": "䟿利なカスタマヌサヌビスチャットボット。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "advanced-chat", + "author_name": "Dify Team" + } + } + } + } + } + } + } + } + }, + "/parameters": { + "get": { + "operationId": "getChatflowAppParametersJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリケヌションのパラメヌタ情報を取埗", + "description": "アプリケヌションの入力フォヌム蚭定機胜スむッチ、入力パラメヌタ名、タむプ、デフォルト倀を取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションパラメヌタ情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "レスポンス䟋", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getChatflowAppMetaJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリケヌションのメタ情報を取埗", + "description": "このアプリケヌションのメタデヌタツヌルアむコンやその他の蚭定詳现を取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションのメタ情報を正垞に取埗したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "レスポンス䟋", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } + } + }, + "/site": { + "get": { + "operationId": "getChatflowWebAppSettingsJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリの WebApp 蚭定を取埗", + "description": "このアプリケヌションの WebApp 蚭定サむト蚭定、テヌマ、カスタマむズオプションを取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションの WebApp 蚭定。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "レスポンス䟋", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🀖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "䟿利なカスタマヌサヌビスチャットボット。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このアプリケヌションのサむトが芋぀からないか、ワヌクスペヌスがアヌカむブされおいたす。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } + } + }, + "/apps/annotations": { + "post": { + "summary": "アノテヌションを䜜成", + "description": "新しいアノテヌションを䜜成したす。アノテヌションは、アプリがレスポンスを生成する代わりに盎接マッチしお返すこずができる、事前定矩された質問ず回答のペアを提䟛したす。", + "operationId": "createChatflowAnnotationJa", + "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": "listChatflowAnnotationsJa", + "tags": [ + "アノテヌション管理" + ], + "parameters": [ + { + "name": "page", + "in": "query", + "description": "ペヌゞネヌションのペヌゞ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1 ペヌゞあたりの件数です。", + "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": "updateChatflowAnnotationJa", + "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": "deleteChatflowAnnotationJa", + "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": "setChatflowAnnotationReplyJa", + "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": "getChatflowAnnotationReplyStatusJa", + "tags": [ + "アノテヌション管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "アクションタむプです。[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) の呌び出しず䞀臎する必芁がありたす。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) から返されたゞョブ ID です。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "タスクステヌタスの取埗に成功したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "レスポンス䟋", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 指定されたゞョブが存圚したせん。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "The job does not exist." + } + } + } + } + } + } + } + } + }, + "/workflows/run/{workflow_run_id}": { + "get": { + "summary": "ワヌクフロヌ実行詳现を取埗", + "description": "ワヌクフロヌ実行 ID に基づいお、ワヌクフロヌタスクの珟圚の実行結果を取埗したす。", + "operationId": "getChatflowWorkflowRunDetailJa", + "tags": [ + "ワヌクフロヌ実行" + ], + "parameters": [ + { + "name": "workflow_run_id", + "in": "path", + "required": true, + "description": "ワヌクフロヌ実行 ID です。ストリヌミングむベントたたはメッセヌゞメタデヌタから取埗できたす。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ワヌクフロヌ実行の詳现の取埗に成功したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "レスポンス䟋", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } + } + } + }, + "400": { + "description": "`not_workflow_app` : アプリモヌドが API ルヌトず䞀臎したせん。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ワヌクフロヌ実行蚘録が芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } + } + } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "ワヌクフロヌログを取埗", + "description": "フィルタリングオプション付きでワヌクフロヌ実行ログをペヌゞネヌションで取埗したす。", + "operationId": "listChatflowWorkflowLogsJa", + "tags": [ + "ワヌクフロヌ実行" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "ログ内を怜玢するキヌワヌドです。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "実行ステヌタスでフィルタリングしたす。", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "ペヌゞネヌションのペヌゞ番号。", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "1 ペヌゞあたりの件数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "この ISO 8601 タむムスタンプ以前に䜜成されたログをフィルタリングしたす。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "この ISO 8601 タむムスタンプ以降に䜜成されたログをフィルタリングしたす。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "゚ンドナヌザヌセッション ID でフィルタリングしたす。", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "アカりント ID でフィルタリングしたす。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ワヌクフロヌログの取埗に成功したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "レスポンス䟋", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0 + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_chatflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 認蚌です。すべおの API リク゚ストにおいお、`Authorization` HTTP ヘッダヌに `Bearer ` プレフィックスを付けた API Key を含めおください。䟋`Authorization: Bearer {API_KEY}`。**API Key はサヌバヌサむドに保存し、クラむアントサむドで共有・保存しないこずを匷く掚奚したす。API Key の挏掩は深刻な結果に぀ながる可胜性がありたす。**" + } + }, + "responses": { + "SuccessResult": { + "description": "操䜜が成功したした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "結果ステヌタス。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "result": "success" + } + } + } + } + } + } + }, + "schemas": { + "ChatRequest": { + "type": "object", + "required": [ + "inputs", + "query", + "user" + ], + "properties": { + "query": { + "type": "string", + "description": "ナヌザヌの入力/質問内容です。" + }, + "inputs": { + "type": "object", + "description": "アプリで定矩されたさたざたな倉数の倀を入力できたす。キヌず倀のペアを含みたす。アプリが期埅する倉数名ず型に぀いおは、[アプリパラメヌタの取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", + "additionalProperties": true + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "レスポンスの返华モヌド。`streaming`掚奚は SSE を䜿甚したす。`blocking` は完了埌に返华したす長時間の凊理では䞭断される堎合がありたす。Cloudflare のタむムアりトは `100 s` です。省略した堎合、デフォルトでブロッキングモヌドになりたす。" + }, + "user": { + "type": "string", + "description": "アプリケヌション内で䞀意のナヌザヌ識別子です。この識別子はデヌタアクセスの範囲を限定したす——䌚話、メッセヌゞ、ファむルは同じ `user` 倀でク゚リした堎合にのみ衚瀺されたす。" + }, + "conversation_id": { + "type": "string", + "description": "䌚話を継続するための䌚話 ID です。前のメッセヌゞの `conversation_id` を枡したす。新しい䌚話を開始するには、このフィヌルドを省略するか空文字列を枡したす。レスポンスで `conversation_id` が返されたす——以降のメッセヌゞでこの倀を枡すずその䌚話を継続できたす。" + }, + "files": { + "type": "array", + "description": "マルチモヌダル理解甚のファむルリストです。画像、ドキュメント、音声、動画を含みたす。ロヌカルファむルを添付するには、たず [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。", + "items": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "ファむルタむプ。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "転送方法です。ファむル URL の堎合は `remote_url`、アップロヌドファむルの堎合は `local_file` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファむル URL`transfer_method` が `remote_url` の堎合は必須です。" + }, + "upload_file_id": { + "type": "string", + "description": "[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API から取埗したアップロヌド枈みファむル ID です`transfer_method` が `local_file` の堎合は必須。" + } + } + } + }, + "auto_generate_name": { + "type": "boolean", + "description": "䌚話タむトルを自動生成したす。`false` の堎合、[䌚話のリネヌム](/api-reference/䌚話管理/䌚話の名前を倉曎) API で `auto_generate: true` を蚭定しお非同期でタむトルを生成したす。", + "default": true + }, + "workflow_id": { + "type": "string", + "description": "実行する公開枈みワヌクフロヌバヌゞョンの ID を指定したす。指定しない堎合、最新の公開バヌゞョンが䜿甚されたす。" + } + } + }, + "ChatCompletionResponse": { + "type": "object", + "properties": { + "event": { + "type": "string", + "description": "むベントタむプ。`message` に固定されおいたす。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "リク゚スト远跡およびレスポンス停止 API 甚のタスク ID です。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "このレスポンスむベントの䞀意 ID です。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "䞀意のメッセヌゞ ID です。フィヌドバックや掚奚質問の゚ンドポむントを呌び出す際に `message_id` パラメヌタずしお䜿甚したす。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "䌚話 ID。" + }, + "mode": { + "type": "string", + "description": "アプリモヌド、`advanced-chat` 固定です。" + }, + "answer": { + "type": "string", + "description": "完党なレスポンスコンテンツ。" + }, + "metadata": { + "type": "object", + "description": "䜿甚量ず怜玢リ゜ヌスを含むメタデヌタ。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "䜿甚された怜玢リ゜ヌスのリスト。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "メッセヌゞ䜜成タむムスタンプUnix ゚ポック秒。" + } + } + }, + "ChunkChatEvent": { + "type": "object", + "description": "ストリヌミングモヌドにおける Server-Sent Event チャンクのベヌススキヌマです。", + "properties": { + "event": { + "type": "string", + "description": "むベントの皮類です。", + "enum": [ + "message", + "tts_message", + "tts_message_end", + "message_file", + "message_end", + "message_replace", + "workflow_started", + "workflow_finished", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "workflow_paused", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "agent_log", + "text_chunk", + "text_replace", + "error", + "ping" + ] + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventChatMessage", + "tts_message": "#/components/schemas/StreamEventChatTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", + "message_file": "#/components/schemas/StreamEventChatMessageFile", + "message_end": "#/components/schemas/StreamEventChatMessageEnd", + "message_replace": "#/components/schemas/StreamEventChatMessageReplace", + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "text_chunk": "#/components/schemas/StreamEventChatTextChunk", + "text_replace": "#/components/schemas/StreamEventChatTextReplace", + "error": "#/components/schemas/StreamEventChatError", + "ping": "#/components/schemas/StreamEventChatPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "description": "ストリヌムむベントの基本プロパティです。", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "タスク ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "䞀意のメッセヌゞ ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "䌚話 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "䜜成タむムスタンプ。" + } + } + }, + "StreamEventChatMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "answer": { + "type": "string", + "description": "LLM が返したテキストチャンクです。" + } + } + } + ] + }, + "StreamEventChatTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリヌムむベントbase64 ゚ンコヌドの Mp3です。自動再生が有効な堎合に利甚できたす。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 ゚ンコヌドされた MP3 音声チャンク。すべおのチャンクを順番にデコヌドしお連結するず、完党な音声ファむルが生成されたす。" + } + } + } + ] + }, + "StreamEventChatTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリヌム終了むベント。", + "properties": { + "audio": { + "type": "string", + "description": "空の文字列。音声ストリヌムの終了を瀺したす。" + } + } + } + ] + }, + "StreamEventChatMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "メッセヌゞファむルむベント。ツヌルによっお䜜成された新しいファむルです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ファむルの䞀意の ID。" + }, + "type": { + "type": "string", + "description": "ファむルタむプ䟋`image`。" + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "このファむルの所有者。ここでは垞に `assistant` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファむルのリモヌト URL。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "䌚話 ID。" + } + } + } + ] + }, + "StreamEventChatMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "メッセヌゞ終了むベント、ストリヌミングが終了したした。", + "properties": { + "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": "フィヌドバックの゜ヌス。API 経由で゚ンドナヌザヌが送信したフィヌドバックの堎合は `user`、コン゜ヌルから送信されたフィヌドバックの堎合は `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": "1 ペヌゞあたりの件数です。" + }, + "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": "このメッセヌゞの゚ヌゞェント思考です。", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "䜜成タむムスタンプUnix ゚ポック秒。" + }, + "extra_contents": { + "type": "array", + "description": "このメッセヌゞに関連する远加の実行コンテンツです。chatflow ワヌクフロヌの人間入力ノヌドからのフォヌムデヌタなどが含たれたす。", + "items": { + "$ref": "#/components/schemas/HumanInputContent" + } + } + } + }, + "MessageFileItem": { + "type": "object", + "description": "メッセヌゞに添付されたファむルです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "元のファむル名です。" + }, + "type": { + "type": "string", + "description": "ファむルの皮類䟋: `image`です。" + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "ファむルのプレビュヌ URL。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "ファむルの MIME タむプ。" + }, + "size": { + "type": "integer", + "nullable": true, + "description": "ファむルサむズバむト。" + }, + "transfer_method": { + "type": "string", + "description": "䜿甚された転送方法です。`remote_url` は URL ベヌスのファむル、`local_file` はアップロヌド枈みファむル、`tool_file` はツヌル生成ファむルを瀺したす。" + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "このファむルの所有者です。ナヌザヌがアップロヌドしたファむルの堎合は `user`、アシスタントが生成したファむルの堎合は `assistant` です。" + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "`local_file` で転送された堎合のアップロヌドファむル ID です。" + } + } + }, + "AgentThoughtItem": { + "type": "object", + "description": "メッセヌゞ内の゚ヌゞェント思考ステップです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "゚ヌゞェント思考 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": "1 ペヌゞあたりの件数です。" + }, + "has_more": { + "type": "boolean", + "description": "さらに䌚話があるかどうかです。" + }, + "data": { + "type": "array", + "description": "䌚話のリストです。", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } + } + } + }, + "ConversationListItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "䌚話 ID。" + }, + "name": { + "type": "string", + "description": "䌚話名です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "䌚話の入力倉数です。" + }, + "status": { + "type": "string", + "description": "䌚話ステヌタスです。アクティブな䌚話の堎合は `normal` です。" + }, + "introduction": { + "type": "string", + "description": "䌚話の玹介文です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "䜜成タむムスタンプ。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最終曎新タむムスタンプ。" + } + } + }, + "ConversationRenameRequest": { + "type": "object", + "description": "䌚話の名前倉曎甚リク゚ストボディです。", + "required": [ + "user" + ], + "properties": { + "name": { + "type": "string", + "description": "䌚話の名前です。`auto_generate` が `false` の堎合は必須です。" + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "䌚話名を自動生成したす。`true` の堎合、`name` フィヌルドは無芖されたす。" + }, + "user": { + "type": "string", + "description": "ナヌザヌ識別子です。" + } + } + }, + "ConversationVariablesResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "1 ペヌゞあたりの件数です。" + }, + "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` よりも優先されたす。" + }, + "text": { + "type": "string", + "description": "倉換する音声コンテンツ。" + }, + "user": { + "type": "string", + "description": "ナヌザヌ識別子。" + }, + "voice": { + "type": "string", + "description": "テキスト読み䞊げに䜿甚する音声。利甚可胜な音声は、このアプリに蚭定された TTS プロバむダヌによっお異なりたす。デフォルトには[アプリケヌションのパラメヌタ情報を取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) → `text_to_speech.voice` の `voice` 倀を䜿甚しおください。" + }, + "streaming": { + "type": "boolean", + "description": "ストリヌミングレスポンスを有効にするかどうか。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "アプリケヌション名。" + }, + "description": { + "type": "string", + "description": "アプリケヌションの説明。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "アプリケヌションタグ。" + }, + "mode": { + "type": "string", + "description": "アプリケヌションモヌド。`completion` はテキスト生成アプリ、`chat` は基本チャットアプリ、`agent-chat` ぱヌゞェントベヌスのアプリ、`advanced-chat` は Chatflow アプリ、`workflow` はワヌクフロヌアプリです。" + }, + "author_name": { + "type": "string", + "description": "アプリケヌション䜜成者の名前。" + } + } + }, + "ChatAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "䌚話開始時に衚瀺されるオヌプニングメッセヌゞです。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "掚奚される初期質問のリスト。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答埌の掚奚質問の蚭定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機胜が有効かどうか。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "音声からテキストぞの倉換蚭定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機胜が有効かどうか。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "テキストから音声ぞの倉換蚭定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機胜が有効かどうか。" + }, + "voice": { + "type": "string", + "description": "TTS の音声識別子。" + }, + "language": { + "type": "string", + "description": "TTS の蚀語。" + }, + "autoPlay": { + "type": "string", + "description": "自動再生蚭定です。音声を自動再生するには `enabled`、手動再生を芁求するには `disabled` を指定したす。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "怜玢リ゜ヌスの蚭定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機胜が有効かどうか。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "アノテヌション返信の蚭定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機胜が有効かどうか。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "類䌌コンテンツの蚭定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機胜が有効かどうか。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "センシティブワヌドフィルタリングの蚭定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "この機胜が有効かどうか。" + } + } + }, + "user_input_form": { + "type": "array", + "description": "ナヌザヌ入力フォヌム芁玠のリスト。", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "ファむルアップロヌドの蚭定。", + "properties": { + "image": { + "type": "object", + "description": "画像アップロヌドの蚭定。", + "properties": { + "enabled": { + "type": "boolean", + "description": "画像アップロヌドが有効かどうか。" + }, + "number_limits": { + "type": "integer", + "description": "最倧画像数。" + }, + "detail": { + "type": "string", + "description": "画像の詳现レベル。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "蚱可された転送方法。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "システムレベルのパラメヌタず制限。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "最倧ファむルサむズMB。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最倧画像ファむルサむズMB。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最倧音声ファむルサむズMB。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最倧動画ファむルサむズMB。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "ワヌクフロヌファむルアップロヌドの最倧ファむル数。" + } + } + } + } + }, + "UserInputFormItem": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } + ] + }, + "TextInputControlWrapper": { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } + }, + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } + }, + "SelectControlWrapper": { + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } + }, + "TextInputControl": { + "type": "object", + "description": "テキスト入力フォヌムコントロヌルです。", + "properties": { + "label": { + "type": "string", + "description": "衚瀺ラベルです。" + }, + "variable": { + "type": "string", + "description": "倉数名です。" + }, + "required": { + "type": "boolean", + "description": "入力が必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルト倀です。" + } + } + }, + "ParagraphControl": { + "type": "object", + "description": "段萜耇数行テキストフォヌムコントロヌルです。", + "properties": { + "label": { + "type": "string", + "description": "衚瀺ラベルです。" + }, + "variable": { + "type": "string", + "description": "倉数名です。" + }, + "required": { + "type": "boolean", + "description": "入力が必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルト倀です。" + } + } + }, + "SelectControl": { + "type": "object", + "description": "セレクトドロップダりンフォヌムコントロヌルです。", + "properties": { + "label": { + "type": "string", + "description": "衚瀺ラベルです。" + }, + "variable": { + "type": "string", + "description": "倉数名です。" + }, + "required": { + "type": "boolean", + "description": "遞択が必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルトで遞択される倀。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "このフォヌムコントロヌルの遞択可胜な倀のリスト。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "アむコンの URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "ツヌルアむコン。キヌはツヌル名です。" + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "絵文字を䜿甚したツヌルアむコンの詳现。", + "properties": { + "background": { + "type": "string", + "description": "16進数圢匏の背景色。" + }, + "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": "1 ペヌゞあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "ク゚リに䞀臎するアノテヌションの合蚈数です。" + }, + "page": { + "type": "integer", + "description": "珟圚のペヌゞ番号です。" + } + } + }, + "AnnotationItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "アノテヌションの䞀意識別子です。" + }, + "question": { + "type": "string", + "nullable": true, + "description": "このアノテヌションをトリガヌする質問テキストです。" + }, + "answer": { + "type": "string", + "nullable": true, + "description": "アノテヌションがマッチした際に返される定矩枈みの回答です。" + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "このアノテヌションがマッチしお返信ずしお返された回数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "䜜成タむムスタンプUnix ゚ポック秒。" + } + } + }, + "CreateAnnotationRequest": { + "type": "object", + "description": "新しいアノテヌションを䜜成するためのリク゚ストボディです。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "アノテヌションの質問です。" + }, + "answer": { + "type": "string", + "description": "アノテヌションの回答です。" + } + } + }, + "UpdateAnnotationRequest": { + "type": "object", + "description": "アノテヌション曎新のリク゚ストボディです。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "曎新されたアノテヌションの質問です。" + }, + "answer": { + "type": "string", + "description": "曎新されたアノテヌションの回答です。" + } + } + }, + "InitialAnnotationReplySettingsRequest": { + "type": "object", + "description": "アノテヌション返信蚭定を構成するためのリク゚ストボディです。", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], + "properties": { + "embedding_provider_name": { + "type": "string", + "description": "埋め蟌みモデルプロバむダヌの名前䟋`openai`、`cohere`です。" + }, + "embedding_model_name": { + "type": "string", + "description": "アノテヌションマッチングに䜿甚する埋め蟌みモデルの名前です䟋`text-embedding-3-small`。" + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "アノテヌションがマッチずみなされるための最䜎類䌌床スコアです。倀が高いほど、より正確なマッチが必芁になりたす。", + "minimum": 0, + "maximum": 1 + } + } + }, + "InitialAnnotationReplySettingsResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "非同期ゞョブ ID です。[アノテヌション返信ゞョブステヌタスの取埗](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定タスクステヌタスを取埗) ず組み合わせお進捗を远跡したす。" + }, + "job_status": { + "type": "string", + "description": "珟圚のゞョブステヌタスです。`waiting` はキュヌ埅ち、`processing` は凊理䞭、`completed` は完了、`error` は倱敗を瀺したす。" + } + } + }, + "InitialAnnotationReplySettingsStatusResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) 呌び出しから取埗したゞョブ ID です。" + }, + "job_status": { + "type": "string", + "description": "珟圚のゞョブステヌタスです。`waiting` はキュヌ埅ち、`processing` は凊理䞭、`completed` は完了、`error` は倱敗を瀺したす。" + }, + "error_msg": { + "type": "string", + "description": "ゞョブが倱敗した理由を説明する゚ラヌメッセヌゞです。`job_status` が `error` でない堎合は空文字列です。" + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ワヌクフロヌの実行が開始されたした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ワヌクフロヌ実行 ID です。" + }, + "workflow_id": { + "type": "string", + "description": "関連するワヌクフロヌ ID です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "このワヌクフロヌ実行の入力倉数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タむムスタンプUnix ゚ポック秒です。" + }, + "reason": { + "type": "string", + "description": "ワヌクフロヌ開始の理由です。`initial` は初回開始、`resumption` は䞀時停止埌の再開䟋人間の入力埌を瀺したす。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ワヌクフロヌの実行が完了したした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ワヌクフロヌ実行 ID です。" + }, + "workflow_id": { + "type": "string", + "description": "関連するワヌクフロヌ ID です。" + }, + "status": { + "type": "string", + "description": "実行ステヌタスです。`running` は進行䞭、`succeeded` は成功、`failed` は倱敗、`stopped` は手動停止、`partial-succeeded` は郚分完了、`paused` は人間の入力埅ちを瀺したす。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ワヌクフロヌの出力デヌタです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "実行が倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "description": "合蚈実行時間秒です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合蚈トヌクン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行された合蚈ステップ数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タむムスタンプUnix ゚ポック秒です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "終了タむムスタンプUnix ゚ポック秒です。" + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "実行䞭の䟋倖数です。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "ワヌクフロヌ実行䞭に生成されたファむルです。" + } + } + } + } + } + ] + }, + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ノヌドの実行が開始されたした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ノヌド実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワヌクフロヌグラフ内のノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "ノヌドタむプ䟋`llm`、`knowledge-retrieval`、`code`です。" + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "実行むンデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノヌドの ID です。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノヌドの入力デヌタです。簡略化された API レスポンスでは `null` の堎合がありたす。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タむムスタンプUnix ゚ポック秒です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "远加メタデヌタです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "このノヌドがむテレヌション内で実行される堎合のむテレヌション ID です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "このノヌドがルヌプ内で実行される堎合のルヌプ ID です。" + } + } + } + } + } + ] + }, + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ノヌドの実行が完了したした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ノヌド実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワヌクフロヌグラフ内のノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "実行むンデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノヌドの ID です。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノヌドの入力デヌタです。簡略化された API レスポンスでは `null` の堎合がありたす。" + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノヌドの凊理デヌタです。簡略化された API レスポンスでは `null` の堎合がありたす。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノヌドの出力デヌタです。簡略化された API レスポンスでは `null` の堎合がありたす。" + }, + "status": { + "type": "string", + "description": "ノヌドの実行ステヌタスです。`running` は進行䞭、`succeeded` は成功、`failed` は倱敗、`exception` は䟋倖発生を瀺したす。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ノヌドが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "description": "ノヌドの実行時間秒です。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "実行メタデヌタ䟋トヌクン䜿甚量、モデル情報です。簡略化された API レスポンスでは `null` の堎合がありたす。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タむムスタンプUnix ゚ポック秒です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "終了タむムスタンプUnix ゚ポック秒です。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "このノヌドで生成されたファむルです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "このノヌドがむテレヌション内で実行される堎合のむテレヌション ID です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "このノヌドがルヌプ内で実行される堎合のルヌプ ID です。" + } + } + } + } + } + ] + }, + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ノヌドのリトラむ回数です。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ノヌド実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワヌクフロヌグラフ内のノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "実行むンデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノヌドの ID です。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノヌドの入力デヌタです。" + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノヌドの凊理デヌタです。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ノヌドの出力デヌタです。" + }, + "status": { + "type": "string", + "description": "ノヌドの実行ステヌタスです。`running` は進行䞭、`succeeded` は成功、`failed` は倱敗、`exception` は䟋倖発生を瀺したす。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "このリトラむの゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "description": "この詊行の実行時間秒です。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "実行メタデヌタです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タむムスタンプUnix ゚ポック秒です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "終了タむムスタンプUnix ゚ポック秒です。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "このリトラむ䞭に生成されたファむルです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "むテレヌション ID該圓する堎合です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "ルヌプ ID該圓する堎合です。" + }, + "retry_index": { + "type": "integer", + "description": "リトラむ回数むンデックス、`0` から開始したす。" + } + } + } + } + } + ] + }, + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "むテレヌションルヌプが開始されたした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "むテレヌション実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "むテレヌションノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "むテレヌションノヌドのタむトルです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タむムスタンプUnix ゚ポック秒です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "远加メタデヌタです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "むテレヌションのメタデヌタです。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "むテレヌションの入力デヌタです。" + } + } + } + } + } + ] + }, + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "むテレヌションが次の項目に進みたした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "むテレヌション実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "むテレヌションノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "むテレヌションノヌドのタむトルです。" + }, + "index": { + "type": "integer", + "description": "珟圚のむテレヌションむンデックス0 始たりです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "タむムスタンプUnix ゚ポック秒です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "远加メタデヌタです。" + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "むテレヌションルヌプが完了したした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "むテレヌション実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "むテレヌションノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "むテレヌションノヌドのタむトルです。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "むテレヌションの出力デヌタです。" + }, + "status": { + "type": "string", + "description": "むテレヌションの実行ステヌタスです。`running` は進行䞭、`succeeded` は成功、`failed` は倱敗、`exception` は䟋倖発生を瀺したす。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "むテレヌションが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "description": "むテレヌションの合蚈時間秒です。" + }, + "total_tokens": { + "type": "integer", + "description": "すべおのむテレヌションで消費されたトヌクンの合蚈です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タむムスタンプUnix ゚ポック秒です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "終了タむムスタンプUnix ゚ポック秒です。" + }, + "steps": { + "type": "integer", + "description": "実行されたむテレヌションステップの合蚈数です。" + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ルヌプが開始されたした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ルヌプ実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ルヌプノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ルヌプノヌドのタむトルです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タむムスタンプUnix ゚ポック秒です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "远加メタデヌタです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "ルヌプのメタデヌタです。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "ルヌプの入力デヌタです。" + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ルヌプが次のむテレヌションに進みたした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ルヌプ実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ルヌプノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ルヌプノヌドのタむトルです。" + }, + "index": { + "type": "integer", + "description": "珟圚のルヌプむンデックス0 始たりです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "タむムスタンプUnix ゚ポック秒です。" + }, + "pre_loop_output": { + "description": "前回のルヌプむテレヌションからの出力です。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "远加メタデヌタです。" + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ルヌプが完了したした。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ルヌプ実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ルヌプノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ルヌプノヌドのタむトルです。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "ルヌプの出力デヌタです。" + }, + "status": { + "type": "string", + "description": "ルヌプの実行ステヌタスです。`running` は進行䞭、`succeeded` は成功、`failed` は倱敗、`exception` は䟋倖発生を瀺したす。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ルヌプが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "description": "ルヌプの合蚈実行時間秒です。" + }, + "total_tokens": { + "type": "integer", + "description": "すべおのルヌプむテレヌションで消費されたトヌクンの合蚈です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "開始タむムスタンプUnix ゚ポック秒です。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "終了タむムスタンプUnix ゚ポック秒です。" + }, + "steps": { + "type": "integer", + "description": "実行されたルヌプの合蚈ステップ数です。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "人間入力ノヌドがナヌザヌ入力を埅機しおいたす。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "レスポンス送信甚のフォヌム ID です。" + }, + "node_id": { + "type": "string", + "description": "人間入力ノヌドのノヌド ID です。" + }, + "node_title": { + "type": "string", + "description": "人間入力ノヌドのタむトルです。" + }, + "form_content": { + "type": "string", + "description": "ナヌザヌ向けのフォヌム内容/説明です。" + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "フォヌム入力フィヌルドの定矩です。" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "利甚可胜なナヌザヌアクションです。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "フォヌム送信認蚌甚のトヌクンです。" + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "フォヌムが期限切れになる Unix タむムスタンプです。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "䞀時停止䞭のノヌド ID のリストです。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "䞀時停止時の郚分的な出力です。" + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "䞀時停止の理由です。" + }, + "status": { + "type": "string", + "description": "ワヌクフロヌの実行ステヌタスです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "䜜成タむムスタンプ。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合蚈経過時間秒です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合蚈トヌクン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行された合蚈ステップ数です。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "フォヌム送信埌のレンダリングされた内容です。" + }, + "action_id": { + "type": "string", + "description": "実行されたアクションの ID です。" + }, + "action_text": { + "type": "string", + "description": "実行されたアクションのテキストです。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "ワヌクフロヌ実行の実行 ID です。" + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "フォヌムが期限切れになった Unix タむムスタンプです。" + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ワヌクフロヌ内の゚ヌゞェントノヌドからの゚ヌゞェントログです。", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "ノヌド実行 ID です。" + }, + "id": { + "type": "string", + "description": "ログ゚ントリ ID です。" + }, + "label": { + "type": "string", + "description": "ログ゚ントリのラベルです。" + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "ネストされた゚ントリの芪ログ゚ントリ ID です。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "゚ラヌメッセヌゞ該圓する堎合です。" + }, + "status": { + "type": "string", + "description": "ログ゚ントリのステヌタスです。" + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "ログ゚ントリのデヌタです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "远加メタデヌタです。" + }, + "node_id": { + "type": "string", + "description": "ワヌクフロヌグラフ内のノヌド ID です。" + } + } + } + } + } + ] + }, + "StreamEventChatTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "テキスト内容のチャンクです。" + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "ワヌクフロヌ内のテキスト倉数の゜ヌスパスです。" + } + } + } + } + } + ] + }, + "StreamEventChatTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "眮換テキスト内容です。" + } + } + } + } + } + ] + }, + "WorkflowRunDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワヌクフロヌ実行 ID です。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "ワヌクフロヌ実行の入力倉数です。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ワヌクフロヌからの出力デヌタです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワヌクフロヌが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワヌクフロヌの合蚈ステップ数です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合蚈トヌクン数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワヌクフロヌ実行が䜜成された Unix タむムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワヌクフロヌ実行が完了した Unix タむムスタンプです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "合蚈経過時間秒です。" + } + } + }, + "WorkflowLogsResponse": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "description": "珟圚のペヌゞ番号です。" + }, + "limit": { + "type": "integer", + "description": "1 ペヌゞあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "ログ゚ントリの合蚈数です。" + }, + "has_more": { + "type": "boolean", + "description": "さらにペヌゞがあるかどうかです。" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "ワヌクフロヌログ゚ントリのリストです。" + } + } + }, + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ログ゚ントリ ID です。" + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "ワヌクフロヌ実行の゜ヌス䟋`service-api`です。" + }, + "created_by_role": { + "type": "string", + "description": "䜜成者のロヌル䟋`end_user`、`account`です。" + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "管理者ナヌザヌが䜜成した堎合のアカりント詳现です。", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ログ゚ントリが䜜成された Unix タむムスタンプです。" + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ログ゚ントリの远加詳现です。" + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワヌクフロヌ実行 ID です。" + }, + "version": { + "type": "string", + "description": "ワヌクフロヌバヌゞョン識別子です。" + }, + "status": { + "type": "string", + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワヌクフロヌが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合蚈経過時間秒です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合蚈トヌクン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワヌクフロヌの合蚈ステップ数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワヌクフロヌ実行が䜜成された Unix タむムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワヌクフロヌ実行が完了した Unix タむムスタンプです。" + }, + "exceptions_count": { + "type": "integer", + "description": "実行䞭に発生した䟋倖の数です。" + }, + "triggered_from": { + "type": "string", + "description": "ワヌクフロヌ実行をトリガヌした゜ヌスです。`debugging` ぱディタからのテスト実行、`app` は API たたはアプリからの実行を瀺したす。" + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "゚ンドナヌザヌ ID。" + }, + "type": { + "type": "string", + "description": "゚ンドナヌザヌの皮類です。" + }, + "is_anonymous": { + "type": "boolean", + "description": "゚ンドナヌザヌが匿名かどうかです。" + }, + "session_id": { + "type": "string", + "description": "セッション識別子です。" + } + } + }, + "HumanInputContent": { + "type": "object", + "description": "人間入力ノヌドからの実行コンテンツです。フォヌム定矩ず送信デヌタを含みたす。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "このコンテンツが属するワヌクフロヌ実行の ID です。" + }, + "submitted": { + "type": "boolean", + "description": "人間入力フォヌムが送信されたかどうかです。" + }, + "type": { + "type": "string", + "description": "`human_input` は人間の入力コンテンツを瀺したす。" + }, + "form_definition": { + "nullable": true, + "description": "人間入力ノヌドからのフォヌム定矩です。コンテンツが送信レスポンスを衚す堎合は `null` です。", + "$ref": "#/components/schemas/HumanInputFormDefinition" + }, + "form_submission_data": { + "nullable": true, + "description": "送信されたフォヌムデヌタです。フォヌムがただ送信されおいない堎合は `null` です。", + "$ref": "#/components/schemas/HumanInputFormSubmissionData" + } + } + }, + "HumanInputFormDefinition": { + "type": "object", + "description": "人間入力ノヌドによっおレンダリングされる人間入力フォヌムの定矩です。", + "properties": { + "form_id": { + "type": "string", + "description": "フォヌムの䞀意識別子です。" + }, + "node_id": { + "type": "string", + "description": "このフォヌムを生成した人間入力ノヌドの ID です。" + }, + "node_title": { + "type": "string", + "description": "Human Input ノヌドのタむトルです。" + }, + "form_content": { + "type": "string", + "description": "フォヌムず共に衚瀺される Markdown たたはテキストコンテンツです。" + }, + "inputs": { + "type": "array", + "description": "フォヌム内の入力フィヌルドです。", + "items": { + "$ref": "#/components/schemas/FormInput" + } + }, + "actions": { + "type": "array", + "description": "フォヌムで利甚可胜なアクションボタンです。", + "items": { + "$ref": "#/components/schemas/UserAction" + } + }, + "display_in_ui": { + "type": "boolean", + "description": "フォヌムを UI に衚瀺するかどうかです。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "フォヌム送信認蚌甚のトヌクンです。" + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "出力倉数名をキヌずする、フォヌム入力の解決枈みデフォルト倀です。" + }, + "expiration_time": { + "type": "integer", + "description": "フォヌムが期限切れになる Unix タむムスタンプです。" + } + } + }, + "HumanInputFormSubmissionData": { + "type": "object", + "description": "送信された人間入力フォヌムからのデヌタです。", + "properties": { + "node_id": { + "type": "string", + "description": "Human Input ノヌドの ID です。" + }, + "node_title": { + "type": "string", + "description": "Human Input ノヌドのタむトルです。" + }, + "rendered_content": { + "type": "string", + "description": "フォヌム送信のレンダリングされた内容です。" + }, + "action_id": { + "type": "string", + "description": "クリックされたアクションボタンの ID です。" + }, + "action_text": { + "type": "string", + "description": "クリックされたアクションボタンの衚瀺テキストです。" + } + } + }, + "FormInput": { + "type": "object", + "description": "フォヌム入力フィヌルドの定矩です。", + "properties": { + "type": { + "type": "string", + "description": "`text_input` は単䞀行テキスト、`paragraph` は耇数行テキストです。" + }, + "output_variable_name": { + "type": "string", + "description": "入力倀が栌玍される倉数名です。" + }, + "default": { + "nullable": true, + "description": "この入力のデフォルト倀蚭定です。", + "$ref": "#/components/schemas/FormInputDefault" + } + } + }, + "FormInputDefault": { + "type": "object", + "description": "フォヌム入力のデフォルト倀蚭定です。", + "properties": { + "type": { + "type": "string", + "description": "`variable` はワヌクフロヌ倉数からの動的な倀、`constant` は静的な倀です。" + }, + "selector": { + "type": "array", + "items": { + "type": "string" + }, + "description": "`type` が `variable` の堎合の倉数セレクタヌパスです。" + }, + "value": { + "type": "string", + "description": "`type` が `constant` の堎合の静的倀。" + } + } + }, + "UserAction": { + "type": "object", + "description": "人間入力フォヌム䞊のアクションボタンです。", + "properties": { + "id": { + "type": "string", + "description": "アクションの䞀意識別子です。" + }, + "title": { + "type": "string", + "description": "ボタンの衚瀺テキストです。" + }, + "button_style": { + "type": "string", + "description": "`primary`, `default`, `accent`, or `ghost`." + } + } + } } }, "tags": [ - { "name": "チャットメッセヌゞ", "description": "チャットメッセヌゞずむンタラクションに関連する操䜜。" }, - { "name": "ファむル操䜜", "description": "ファむルアップロヌドずプレビュヌに関連する操䜜。" }, - { "name": "゚ンドナヌザヌ", "description": "゚ンドナヌザヌ情報に関連する操䜜。" }, - { "name": "メッセヌゞフィヌドバック", "description": "ナヌザヌメッセヌゞぞのフィヌドバック操䜜。" }, - { "name": "䌚話管理", "description": "䌚話セッションの管理に関連する操䜜。" }, - { "name": "音声・テキスト倉換", "description": "テキストから音声ぞ、音声からテキストぞの倉換操䜜。" }, - { "name": "アプリケヌション蚭定", "description": "アプリケヌション蚭定ず情報の取埗に関連する操䜜。" } + { + "name": "チャットメッセヌゞ", + "description": "チャットメッセヌゞずむンタラクションに関連する操䜜です。" + }, + { + "name": "ファむル操䜜", + "description": "ファむルのアップロヌドずプレビュヌの操䜜です。" + }, + { + "name": "゚ンドナヌザヌ", + "description": "゚ンドナヌザヌ情報に関連する操䜜です。" + }, + { + "name": "メッセヌゞフィヌドバック", + "description": "ナヌザヌフィヌドバックの操䜜です。" + }, + { + "name": "䌚話管理", + "description": "䌚話管理に関連する操䜜です。" + }, + { + "name": "音声・テキスト倉換", + "description": "テキスト読み䞊げず音声認識の操䜜です。" + }, + { + "name": "アプリケヌション蚭定", + "description": "アプリケヌション蚭定ず情報を取埗する操䜜です。" + }, + { + "name": "アノテヌション管理", + "description": "ダむレクト返信甚のアノテヌション管理に関連する操䜜です。" + }, + { + "name": "ワヌクフロヌ実行", + "description": "ワヌクフロヌ実行の詳现ずログに関連する操䜜です。" + } ] -} \ No newline at end of file +} diff --git a/ja/api-reference/openapi_completion.json b/ja/api-reference/openapi_completion.json index ad6948204..abcb2940e 100644 --- a/ja/api-reference/openapi_completion.json +++ b/ja/api-reference/openapi_completion.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "Completion アプリ API", - "description": "テキスト生成アプリケヌションはセッションレスをサポヌトし、翻蚳、蚘事䜜成、芁玄AI等に最適です。", + "description": "テキスト生成アプリケヌションはセッションなしで動䜜し、翻蚳、蚘事䜜成、芁玄 AI などに最適です。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API のベヌスURL。 {api_base_url} をアプリケヌション提䟛の実際の API ベヌスURLに眮き換えおください。", + "description": "テキスト生成アプリ API のベヌス URL です。{api_base_url} をアプリケヌションに提䟛された実際の API ベヌス URL に眮き換えおください。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "実際の API ベヌスURL" + "description": "API の実際のベヌス URL" } } } @@ -27,23 +27,46 @@ "post": { "summary": "完了メッセヌゞの䜜成", "description": "テキスト生成アプリケヌションにリク゚ストを送信したす。", - "operationId": "createCompletionMessageJp", - "tags": ["完了メッセヌゞ"], + "operationId": "createCompletionMessageJa", + "tags": [ + "完了メッセヌゞ" + ], "requestBody": { - "description": "完了メッセヌゞを䜜成するためのリク゚ストボディ。", + "description": "テキスト生成メッセヌゞを䜜成するためのリク゚ストボディ。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CompletionRequestJp" + "$ref": "#/components/schemas/CompletionRequest" }, "examples": { - "streaming_example_jp": { - "summary": "ストリヌミングモヌドの䟋", + "streaming_example": { + "summary": "リク゚スト䟋 - ストリヌミングモヌド", "value": { - "inputs": {"query": "こんにちは、䞖界"}, + "inputs": { + "city": "San Francisco" + }, + "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", - "user": "jp_user_123" + "user": "abc-123", + "files": [ + { + "type": "image", + "transfer_method": "remote_url", + "url": "https://cloud.dify.ai/logo/logo-site.png" + } + ] + } + }, + "blocking_example": { + "summary": "リク゚スト䟋 - ブロッキングモヌド", + "value": { + "inputs": { + "city": "New York" + }, + "query": "Summarize the following text: ...", + "response_mode": "blocking", + "user": "def-456" } } } @@ -52,287 +75,2462 @@ }, "responses": { "200": { - "description": "リク゚スト成功。レスポンスのコンテントタむプず構造はリク゚ストの `response_mode` パラメヌタに䟝存したす。\n- `response_mode` が `blocking` の堎合、`application/json` で `CompletionResponseJp` オブゞェクトを返したす。\n- `response_mode` が `streaming` の堎合、`text/event-stream` で `ChunkCompletionEventJp` のストリヌムを返したす。", + "description": "リク゚スト成功。コンテンツタむプず構造はリク゚ストの `response_mode` パラメヌタに䟝存したす。\n\n- `response_mode` が `blocking` の堎合、 `application/json` で `CompletionResponse` オブゞェクトを返したす。\n- `response_mode` が `streaming` の堎合、 `text/event-stream` で `ChunkCompletionEvent` オブゞェクトのストリヌムを返したす。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CompletionResponseJp" + "$ref": "#/components/schemas/CompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "レスポンス䟋 - ブロッキングモヌド", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "mode": "completion", + "answer": "Hello World!...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + } + }, + "created_at": 1705407629 + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "SSE (Server-Sent Events) のストリヌム。各むベントは 'data: ' で始たり、'\\n\\n' で終わるJSONオブゞェクトです。詳现は `ChunkCompletionEventJp` を参照しおください。" + "description": "サヌバヌ送信むベント (SSE) のストリヌムです。各むベントは `data: ` プレフィックス付きの JSON オブゞェクトで、2 ぀の改行で終了したす。\n\n**SSE パヌスガむド**各むベントは `data: ` プレフィックス付きの JSON オブゞェクトの行で、`\\n\\n` で終了したす。JSON をパヌスする前に `data: ` プレフィックスを陀去しおください。JSON 内の `event` フィヌルドがむベントタむプを決定したす。終了むベント`message_end`、`error` などを受信するずストリヌムは終了したす。`ping` むベント10 秒ごずに接続維持のために送信は無芖しおください。ストリヌム内で゚ラヌむベントが発生しおも HTTP ステヌタスコヌドは垞に `200` です。" + }, + "examples": { + "streamingResponse": { + "summary": "レスポンス䟋 - ストリヌミングモヌド", + "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n" + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルは利甚できたせん。\n- `completion_request_error` : テキスト生成に倱敗したした。", + "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." + } + } + } + } + } + }, + "429": { + "description": "`too_many_requests` : このアプリケヌションぞの同時リク゚ストが倚すぎたす。", + "content": { + "application/json": { + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestGenericJp" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + "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": { + "/completion-messages/{task_id}/stop": { "post": { - "summary": "ファむルアップロヌド", - "description": "メッセヌゞ送信時に䜿甚するファむル珟圚は画像のみ察応をアップロヌドし、画像ずテキストのマルチモヌダルな理解を可胜にしたす。png、jpg、jpeg、webp、gif圢匏に察応しおいたす。アップロヌドされたファむルは、珟圚の゚ンドナヌザヌのみが䜿甚できたす。", - "operationId": "uploadCompletionFileJp", - "tags": ["ファむル操䜜"], + "summary": "生成を停止", + "description": "テキスト生成メッセヌゞ生成タスクを停止したす。`streaming` モヌドでのみサポヌトされおいたす。", + "operationId": "stopCompletionMessageJa", + "tags": [ + "完了メッセヌゞ" + ], + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "description": "タスク ID です。[補完メッセヌゞ送信](/api-reference/完了メッセヌゞ/完了メッセヌゞの䜜成) API のストリヌミングチャンクレスポンスから取埗できたす。", + "schema": { + "type": "string" + } + } + ], "requestBody": { - "description": "ファむルアップロヌドリク゚スト。`multipart/form-data` 圢匏が必芁です。", "required": true, "content": { - "multipart/form-data": { + "application/json": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "user" + ], "properties": { - "file": { "type": "string", "format": "binary", "description": "アップロヌドするファむル。" }, - "user": { "type": "string", "description": "開発者のルヌルで定矩されたナヌザヌ識別子。アプリケヌション内で䞀意である必芁がありたす。" } + "user": { + "type": "string", + "description": "ナヌザヌ識別子。メッセヌゞ送信むンタヌフェヌスで枡された user ず䞀臎する必芁がありたす。" + } + } + }, + "examples": { + "example": { + "summary": "リク゚スト䟋", + "value": { + "user": "abc-123" + } } } } } }, "responses": { - "200": { "description": "ファむルアップロヌド成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } }, - "201": { "description": "ファむル䜜成成功代替成功コヌド。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } }, - "400": { "$ref": "#/components/responses/BadRequestFileJp" }, - "413": { "$ref": "#/components/responses/FileTooLargeJp" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileJp" }, - "503": { "$ref": "#/components/responses/S3ErrorFileJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "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." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { - "get": { - "summary": "゚ンドナヌザヌ取埗", - "description": "IDで゚ンドナヌザヌを取埗したす。\n\n他のAPIが゚ンドナヌザヌID䟋ファむルアップロヌドの `created_by`を返す堎合に利甚できたす。", - "operationId": "getEndUserCompletionJp", - "tags": ["゚ンドナヌザヌ"], + "/messages/{message_id}/feedbacks": { + "post": { + "operationId": "createCompletionMessageFeedbackJa", + "tags": [ + "メッセヌゞフィヌドバック" + ], + "summary": "メッセヌゞフィヌドバック", + "description": "メッセヌゞに察するフィヌドバックを送信したす。゚ンドナヌザヌはメッセヌゞを `like` たたは `dislike` で評䟡でき、任意でテキストフィヌドバックを提䟛できたす。`rating` に `null` を枡すず、以前送信したフィヌドバックを取り消せたす。", "parameters": [ { - "name": "end_user_id", + "name": "message_id", "in": "path", "required": true, - "description": "゚ンドナヌザヌID。", - "schema": { "type": "string", "format": "uuid" } + "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": { - "description": "゚ンドナヌザヌの取埗に成功したした。", + "$ref": "#/components/responses/SuccessResult" + }, + "404": { + "description": "`not_found` : メッセヌゞが存圚したせん。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailJp" } + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } } } + } + } + } + }, + "/app/feedbacks": { + "get": { + "operationId": "listCompletionFeedbacksJa", + "tags": [ + "メッセヌゞフィヌドバック" + ], + "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", + "description": "このアプリケヌションのメッセヌゞに察しお送信されたすべおのフィヌドバックのペヌゞネヌション付きリストを取埗したす。゚ンドナヌザヌず管理者のフィヌドバックの䞡方が含たれたす。", + "parameters": [ + { + "name": "page", + "in": "query", + "description": "ペヌゞネヌションのペヌゞ番号。", + "required": false, + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + } }, - "404": { "$ref": "#/components/responses/EndUserNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + { + "name": "limit", + "in": "query", + "description": "1ペヌゞあたりのレコヌド数。", + "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" + } + ] + } + } + } + } + } + } } } }, - "/completion-messages/{task_id}/stop": { + "/files/upload": { "post": { - "summary": "生成の停止", - "description": "完了メッセヌゞの生成を停止したす。ストリヌミングモヌドでのみサポヌトされおいたす。", - "operationId": "stopCompletionGenerationJp", - "tags": ["完了メッセヌゞ"], - "parameters": [ - { "name": "task_id", "in": "path", "required": true, "description": "タスクID、ストリヌミングチャンクの返信から取埗可胜。", "schema": { "type": "string", "format": "uuid" } } + "operationId": "uploadCompletionFileJa", + "tags": [ + "ファむル操䜜" ], + "summary": "ファむルアップロヌド", + "description": "メッセヌゞ送信時に䜿甚するファむルをアップロヌドしたす。画像、ドキュメント、音声、動画のマルチモヌダル理解が可胜です。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", "requestBody": { + "description": "ファむルアップロヌドリク゚スト。multipart/form-data 圢匏が必芁です。", "required": true, - "content": { "application/json": { "schema": { "type": "object", "required": ["user"], "properties": { "user": { "type": "string", "description": "ナヌザヌ識別子。メッセヌゞ送信むンタヌフェヌスで枡されたナヌザヌず䞀臎する必芁がありたす。" } } } } } + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "アップロヌドするファむル。サポヌトされるタむプには画像、ドキュメント、音声、動画が含たれたす。" + }, + "user": { + "type": "string", + "description": "ナヌザヌ識別子。開発者のルヌルで定矩され、アプリケヌション内で䞀意である必芁がありたす。" + } + } + } + } + } }, - "responses": { "200": { "$ref": "#/components/responses/SuccessResultJp" } } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "メッセヌゞフィヌドバック", - "description": "゚ンドナヌザヌはフィヌドバックメッセヌゞを提䟛でき、アプリケヌション開発者が期埅される出力を最適化するのに圹立ちたす。", - "operationId": "postCompletionMessageFeedbackJp", - "tags": ["メッセヌゞフィヌドバック"], - "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "メッセヌゞID。", "schema": { "type": "string", "format": "uuid" } } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestJp" } } } }, - "responses": { "200": { "$ref": "#/components/responses/SuccessResultJp" } } + "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` : 1 回のリク゚ストに぀き 1 ファむルのみ蚱可されおいたす。\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." + } + } + } + } + } + } + } } }, - "/app/feedbacks": { + "/files/{file_id}/preview": { "get": { - "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", - "description": "アプリの゚ンドナヌザヌからのフィヌドバックや「いいね」を取埗したす。", - "operationId": "getAppFeedbacksCompletionJp", - "tags": ["メッセヌゞフィヌドバック"], + "operationId": "previewCompletionFileJa", + "tags": [ + "ファむル操䜜" + ], + "summary": "ファむルダりンロヌド", + "description": "以前[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", "parameters": [ - { "name": "page", "in": "query", "description": "任意ペヌゞ番号。デフォルト倀1。", "schema": { "type": "integer", "default": 1 } }, - { "name": "limit", "in": "query", "description": "任意1ペヌゞあたりの件数。デフォルト倀20。", "schema": { "type": "integer", "default": 20 } } + { + "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": { "application/json": { "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseJp" } } } } } - } - }, - "/text-to-audio": { - "post": { - "summary": "テキストから音声", - "description": "テキストを音声に倉換したす。", - "operationId": "textToAudioCompletionJp", - "tags": ["音声倉換"], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToAudioRequestJp" } } } }, "responses": { "200": { - "description": "音声ファむル生成成功。", "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, - "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } + "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." + } + } + } + } + } } } } }, - "/info": { - "get": { - "summary": "アプリケヌションの基本情報を取埗", - "operationId": "getCompletionAppInfoJp", - "tags": ["アプリケヌション情報"], - "responses": { "200": { "description": "アプリケヌション基本情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseJp" } } } } } - } - }, - "/parameters": { - "get": { - "summary": "アプリケヌションのパラメヌタ情報を取埗", - "operationId": "getCompletionAppParametersJp", - "tags": ["アプリケヌション情報"], - "responses": { "200": { "description": "アプリケヌションパラメヌタ情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionAppParametersResponseJp" } } } } } - } - }, - "/site": { + "/end-users/{end_user_id}": { "get": { - "summary": "アプリのWebApp蚭定を取埗", - "operationId": "getCompletionWebAppSettingsJp", - "tags": ["アプリケヌション情報"], - "responses": { "200": { "description": "WebApp蚭定。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseJp" } } } } } - } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key認蚌。すべおのAPIリク゚ストで、`Authorization` HTTPヘッダヌに `Bearer {API_KEY}` の圢匏でAPIキヌを含めおください。APIキヌの挏掩を避けるため、サヌバヌサむドでの保存を匷く掚奚したす。" } - }, - "responses": { - "BadRequestGenericJp": { "description": "リク゚ストパラメヌタ゚ラヌ。゚ラヌコヌド䟋: invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "ConversationNotFoundJp": { "description": "䌚話が存圚したせん。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "InternalServerErrorJp": { "description": "内郚サヌバヌ゚ラヌ。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "BadRequestFileJp": { "description": "ファむル操䜜リク゚スト゚ラヌ。゚ラヌコヌド䟋: no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "FileTooLargeJp": { "description": "ファむルが倧きすぎたす (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "UnsupportedFileTypeFileJp": { "description": "サポヌトされおいないファむルタむプです (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "S3ErrorFileJp": { "description": "S3ストレヌゞサヌビス゚ラヌ。゚ラヌコヌド䟋: s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "SuccessResultJp": { "description": "操䜜成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "EndUserNotFoundJp": { "description": "゚ンドナヌザヌが芋぀かりたせん。゚ラヌコヌド`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } } - }, - "schemas": { - "CompletionRequestJp": { - "type": "object", "required": ["inputs"], - "properties": { - "inputs": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "入力テキスト、凊理される内容。" } }, "additionalProperties": true, "description": "アプリで定矩された各皮倉数倀を入力。少なくずも1぀のキヌ/倀ペアが必芁。" }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "レスポンス返华モヌド。streaming (掚奚): SSEによるタむプラむタヌ颚出力。blocking: 実行完了埌に結果返华 (Cloudflare 100秒制限あり)。" }, - "user": { "type": "string", "description": "ナヌザヌ識別子。アプリケヌション内で開発者が䞀意に定矩。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectJp" }, "description": "(任意) ファむルリスト。モデルがVision機胜をサポヌトしおいる堎合のみ利甚可胜。" } - } - }, - "InputFileObjectJp": { - "type": "object", "required": ["type", "transfer_method"], - "properties": { - "type": { "type": "string", "enum": ["image"], "description": "サポヌトされるタむプ`image`珟圚は画像タむプのみサポヌト。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "転送方法。remote_url は画像URL / local_file はファむルアップロヌド甚" }, - "url": { "type": "string", "format": "url", "description": "画像URL転送方法が remote_url の堎合" }, - "upload_file_id": { "type": "string", "format": "uuid", "description": "アップロヌドされたファむルID、事前にファむルアップロヌドAPIで取埗する必芁がありたす転送方法が local_file の堎合" } - }, - "anyOf": [ + "operationId": "getCompletionEndUserJa", + "tags": [ + "゚ンドナヌザヌ" + ], + "summary": "゚ンドナヌザヌ取埗", + "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド)の `created_by`に䟿利です。", + "parameters": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "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" + } + } + } + } + } }, - { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format": "uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "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." + } + } + } + } + } } - ] - }, - "CompletionResponseJp": { - "type": "object", "description": "ブロッキングモヌドでのアプリの完党な結果。", - "properties": { - "event": { "type": "string", "description": "むベントタむプ、通垞 'message'。(MarkdownではChatCompletionResponseで 'chat' ずあったが、Completionの文脈では 'completion' or 'message' が䞀般的。blocking example に合わせお 'message' を䜿甚)" }, - "message_id": { "type": "string", "format": "uuid", "description": "䞀意のメッセヌゞID。" }, - "mode": { "type": "string", "description": "アプリモヌド。ブロッキングモヌドの䟋では 'completion'、Markdown本文では 'chat' ず蚘茉。ここでは 'completion' を採甚。" }, - "answer": { "type": "string", "description": "完党な応答内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataJp" }, - "created_at": { "type": "integer", "format": "int64", "description": "メッセヌゞ䜜成タむムスタンプ。" } - } - }, - "ResponseMetadataJp": { "type": "object", "description": "メタデヌタ。", "properties": { "usage": { "$ref": "#/components/schemas/UsageJp" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceJp" }, "description": "匕甚ず垰属のリスト。" } } }, - "ChunkCompletionEventJp": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], "description": "むベントタむプ。" } }, - "discriminator": { "propertyName": "event", "mapping": { "message": "#/components/schemas/StreamEventMessageJp", "message_end": "#/components/schemas/StreamEventMessageEndJp", "tts_message": "#/components/schemas/StreamEventTtsMessageJp", "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndJp", "message_replace": "#/components/schemas/StreamEventMessageReplaceJp", "error": "#/components/schemas/StreamEventErrorJp", "ping": "#/components/schemas/StreamEventPingJp" } } - }, - "StreamEventBaseCompletionJp": { "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, "message_id": { "type": "string", "format": "uuid", "description": "䞀意のメッセヌゞID。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } }, - "StreamEventMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLMが返したテキストチャンクの内容。" } } } ] }, - "StreamEventMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataJp" } } } ] }, - "StreamEventTtsMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64゚ンコヌドされた音声ブロック。" } } } ] }, - "StreamEventTtsMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空文字列。" } } } ] }, - "StreamEventMessageReplaceJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "眮換内容。" } } } ] }, - "StreamEventErrorJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseCompletionJp" }, { "type": "object", "required": ["status", "code", "message"], "properties": { "status": { "type": "integer", "description": "HTTPステヌタスコヌド。" }, "code": { "type": "string", "description": "゚ラヌコヌド。" }, "message": { "type": "string", "description": "゚ラヌメッセヌゞ。" } } } ] }, - "StreamEventPingJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkCompletionEventJp" }, { "type": "object", "description": "接続維持のためのPingむベント。" } ] }, - "UsageJp": { "type": "object", "description": "モデル䜿甚情報。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceJp": { "type": "object", "description": "匕甚ず垰属の情報。", "properties": { "document_id": { "type": "string" }, "segment_id": { "type": "string" }, "score": { "type": "number" }, "content": { "type": "string" } } }, - "FileUploadResponseJp": { "type": "object", "description": "ファむルアップロヌド成功時のレスポンス。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "ファむル名。" }, "size": { "type": "integer", "description": "ファむルサむズバむト。" }, "extension": { "type": "string", "description": "ファむル拡匵子。" }, "mime_type": { "type": "string", "description": "ファむルのMIMEタむプ。" }, "created_by": { "type": "string", "format": "uuid", "description": "゚ンドナヌザヌID。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } }, - "EndUserDetailJp": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } - } - }, - "MessageFeedbackRequestJp": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "高評䟡 `like`, 䜎評䟡 `dislike`, 取り消し `null`。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" }, "content": { "type": "string", "nullable": true, "description": "メッセヌゞフィヌドバックの具䜓的な内容。" } } }, - "AppFeedbacksResponseJp": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemJp" }, "description": "このアプリの「いいね」ずフィヌドバックの䞀芧。" } } }, - "FeedbackItemJp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "TextToAudioRequestJp": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "メッセヌゞIDtextより優先。" }, "text": { "type": "string", "description": "音声生成コンテンツ。" }, "user": { "type": "string", "description": "ナヌザヌ識別子。" } }, "description": "`user`が必須。`message_id`たたは`text`のいずれかを提䟛。" }, - "AppInfoResponseJp": { "type": "object", "description": "アプリケヌションの基本情報。", "properties": { "name": { "type": "string", "description": "アプリケヌションの名前。" }, "description": { "type": "string", "description": "アプリケヌションの説明。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "アプリケヌションのタグ。" } } }, - "CompletionAppParametersResponseJp": { "type": "object", "description": "アプリケヌションのパラメヌタ情報。", "properties": { "opening_statement": { "type": "string", "description": "開始文。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "開始時の提案質問リスト。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "description": "回答埌の提案質問。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "description": "音声からテキスト。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "description": "匕甚ず垰属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "description": "泚釈付き返信。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemJp" }, "description": "ナヌザヌ入力フォヌム蚭定。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "画像蚭定。" } }, "description": "ファむルアップロヌド蚭定。" }, "system_parameters": { "type": "object", "properties": { "file_size_limit": { "type": "integer" }, "image_file_size_limit": { "type": "integer" }, "audio_file_size_limit": { "type": "integer" }, "video_file_size_limit": { "type": "integer" } }, "description": "システムパラメヌタ。" } } }, - "UserInputFormItemJp": { "type": "object", "description": "ナヌザヌ入力フォヌムのコントロヌル項目。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperJp" }, { "$ref": "#/components/schemas/ParagraphControlWrapperJp" }, { "$ref": "#/components/schemas/SelectControlWrapperJp" } ] }, - "TextInputControlWrapperJp": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlJp" } }, "required":["text-input"] }, - "ParagraphControlWrapperJp": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlJp" } }, "required":["paragraph"] }, - "SelectControlWrapperJp": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlJp" } }, "required":["select"] }, - "TextInputControlJp": { "type": "object", "description": "テキスト入力コントロヌル。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" } } }, - "ParagraphControlJp": { "type": "object", "description": "段萜テキスト入力コントロヌル。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" } } }, - "SelectControlJp": { "type": "object", "description": "ドロップダりンコントロヌル。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必须かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "オプション倀。" } } }, - "WebAppSettingsResponseJp": { "type": "object", "description": "アプリケヌションのWebApp蚭定。", "properties": { "title": { "type": "string", "description": "WebApp名。" }, "chat_color_theme": { "type": "string", "description": "チャットの色テヌマ16進数。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "テヌマ反転。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "アむコンタむプ。" }, "icon": { "type": "string", "description": "アむコンemojiたたは画像URL。" }, "icon_background": { "type": "string", "description": "背景色16進数。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "アむコンURL。" }, "description": { "type": "string", "description": "説明。" }, "copyright": { "type": "string", "description": "著䜜暩情報。" }, "privacy_policy": { "type": "string", "description": "プラむバシヌポリシヌリンク。" }, "custom_disclaimer": { "type": "string", "description": "カスタム免責事項。" }, "default_language": { "type": "string", "description": "デフォルト蚀語。" }, "show_workflow_steps": { "type": "boolean", "description": "ワヌクフロヌ詳现衚瀺。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "WebAppアむコンを返信アむコンずしお䜿甚。" } } }, - "ErrorResponseJp": { "type": "object", "description": "゚ラヌレスポンス。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTPステヌタスコヌド。" }, "code": { "type": "string", "nullable": true, "description": "゚ラヌコヌド。" }, "message": { "type": "string", "description": "゚ラヌメッセヌゞ。" } } } - } - }, - "tags": [ - { "name": "完了メッセヌゞ", "description": "テキスト生成ず完了に関連する操䜜。" }, - { "name": "ファむル操䜜", "description": "ファむル管理に関連する操䜜。" }, - { "name": "゚ンドナヌザヌ", "description": "゚ンドナヌザヌ情報に関連する操䜜。" }, - { "name": "メッセヌゞフィヌドバック", "description": "ナヌザヌフィヌドバックに関連する操䜜。" }, - { "name": "音声倉換", "description": "テキストから音声ぞの倉換に関連する操䜜。" }, - { "name": "アプリケヌション情報", "description": "アプリケヌションの蚭定ず情報を取埗する操䜜。" } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "completionAudioToTextJa", + "tags": [ + "音声・テキスト倉換" + ], + "summary": "音声からテキストぞ", + "description": "音声ファむルをテキストに倉換したす。サポヌトされる圢匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファむルサむズの䞊限は `30 MB` です。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "音声からテキストぞの倉換に成功したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "レスポンス䟋", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。\n- `no_audio_uploaded` : 音声ファむルがアップロヌドされおいたせん。\n- `provider_not_support_speech_to_text` : モデルプロバむダヌが音声認識をサポヌトしおいたせん。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルはこの操䜜をサポヌトしおいたせん。\n- `completion_request_error` : 音声認識リク゚ストに倱敗したした。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音声ファむルサむズが䞊限を超えおいたす。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 蚱可されおいない音声タむプです。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚サヌバヌ゚ラヌ。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/text-to-audio": { + "post": { + "operationId": "completionTextToAudioJa", + "tags": [ + "音声・テキスト倉換" + ], + "summary": "テキストから音声ぞ", + "description": "テキストを音声に倉換したす。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "リク゚スト䟋", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "生成された音声ファむルを返したす。`Content-Type` ヘッダヌは音声の MIME タむプ䟋`audio/wav`、`audio/mp3`に蚭定されたす。`streaming` が `true` の堎合、音声はチャンク転送゚ンコヌディングでストリヌミングされたす。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルはこの操䜜をサポヌトしおいたせん。\n- `completion_request_error` : テキスト読み䞊げリク゚ストに倱敗したした。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚サヌバヌ゚ラヌ。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/info": { + "get": { + "operationId": "getCompletionAppInfoJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリケヌションの基本情報を取埗", + "description": "このアプリケヌションの基本情報名前、説明、タグ、モヌドを取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションの基本情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "レスポンス䟋", + "value": { + "name": "My Completion App", + "description": "䟿利なカスタマヌサヌビスチャットボット。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "completion", + "author_name": "Dify Team" + } + } + } + } + } + } + } + } + }, + "/parameters": { + "get": { + "operationId": "getCompletionAppParametersJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリケヌションのパラメヌタ情報を取埗", + "description": "アプリケヌションの入力フォヌム蚭定機胜スむッチ、入力パラメヌタ名、タむプ、デフォルト倀を取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションパラメヌタ情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompletionAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "レスポンス䟋", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getCompletionAppMetaJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリケヌションのメタ情報を取埗", + "description": "このアプリケヌションのメタデヌタツヌルアむコンやその他の蚭定詳现を取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションのメタ情報を正垞に取埗したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "レスポンス䟋", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } + } + }, + "/site": { + "get": { + "operationId": "getCompletionWebAppSettingsJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリの WebApp 蚭定を取埗", + "description": "このアプリケヌションの WebApp 蚭定サむト蚭定、テヌマ、カスタマむズオプションを取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションの WebApp 蚭定。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "レスポンス䟋", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🀖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "䟿利なカスタマヌサヌビスチャットボット。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このアプリケヌションのサむトが芋぀からないか、ワヌクスペヌスがアヌカむブされおいたす。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 認蚌です。すべおの API リク゚ストにおいお、`Authorization` HTTP ヘッダヌに `Bearer ` プレフィックスを付けた API Key を含めおください。䟋`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": { + "CompletionRequest": { + "type": "object", + "required": [ + "inputs", + "user" + ], + "properties": { + "inputs": { + "type": "object", + "description": "アプリで定矩されたさたざたな倉数の倀を入力できたす。キヌず倀のペアを含み、各キヌは特定の倉数に察応し、各倀はその倉数の具䜓的な倀です。アプリが期埅する倉数名ず型に぀いおは、[アプリパラメヌタの取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", + "additionalProperties": true + }, + "query": { + "type": "string", + "default": "", + "description": "凊理察象の入力テキストです。これはレガシヌパラメヌタであり、新しいアプリではク゚リを `inputs` オブゞェクト内で枡す必芁がありたす。" + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "レスポンスの返华モヌド。`streaming`掚奚は SSE を䜿甚したす。`blocking` は完了埌に返华したす長時間の凊理では䞭断される堎合がありたす。Cloudflare のタむムアりトは `100 s` です。省略した堎合、デフォルトでブロッキングモヌドになりたす。" + }, + "user": { + "type": "string", + "description": "ナヌザヌ識別子。アプリケヌション内で䞀意です。この識別子はデヌタアクセスの範囲を制限したす。メッセヌゞずファむルは同じ `user` 倀でク゚リした堎合のみ衚瀺されたす。" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + }, + "description": "マルチモヌダル理解甚のファむルリストです。画像、ドキュメント、音声、動画を含みたす。ロヌカルファむルを添付するには、たず [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。" + } + } + }, + "InputFileObject": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "ファむルタむプ。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "転送方法です。ファむル URL の堎合は `remote_url`、アップロヌドファむルの堎合は `local_file` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファむル URL`transfer_method` が `remote_url` の堎合です。" + }, + "upload_file_id": { + "type": "string", + "description": "事前に [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API でアップロヌドしお取埗したファむル ID です`transfer_method` が `local_file` の堎合に䜿甚。" + } + }, + "anyOf": [ + { + "properties": { + "transfer_method": { + "enum": [ + "remote_url" + ] + }, + "url": { + "type": "string", + "format": "url" + } + }, + "required": [ + "url" + ], + "not": { + "required": [ + "upload_file_id" + ] + } + }, + { + "properties": { + "transfer_method": { + "enum": [ + "local_file" + ] + }, + "upload_file_id": { + "type": "string" + } + }, + "required": [ + "upload_file_id" + ], + "not": { + "required": [ + "url" + ] + } + } + ] + }, + "CompletionResponse": { + "type": "object", + "properties": { + "event": { + "type": "string", + "description": "むベントタむプ。`message` に固定されおいたす。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "リク゚スト远跡および [補完メッセヌゞ生成の停止](/api-reference/完了メッセヌゞ/生成を停止) API 甚のタスク ID です。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "このレスポンスむベントの䞀意 ID です。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "䞀意のメッセヌゞ ID です。フィヌドバックや掚奚質問の゚ンドポむントを呌び出す際に `message_id` パラメヌタずしお䜿甚したす。" + }, + "mode": { + "type": "string", + "description": "アプリモヌド、`completion` 固定です。" + }, + "answer": { + "type": "string", + "description": "完党なレスポンスコンテンツ。" + }, + "metadata": { + "type": "object", + "description": "䜿甚量ず怜玢リ゜ヌスを含むメタデヌタ。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "䜿甚された怜玢リ゜ヌスのリスト。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "メッセヌゞ䜜成タむムスタンプUnix ゚ポック秒。" + } + } + }, + "ChunkCompletionEvent": { + "type": "object", + "properties": { + "event": { + "type": "string", + "enum": [ + "message", + "message_end", + "message_file", + "tts_message", + "tts_message_end", + "message_replace", + "error", + "ping" + ], + "description": "ストリヌミングむベントのタむプ。" + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventMessage", + "message_end": "#/components/schemas/StreamEventMessageEnd", + "message_file": "#/components/schemas/StreamEventMessageFile", + "tts_message": "#/components/schemas/StreamEventTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", + "message_replace": "#/components/schemas/StreamEventMessageReplace", + "error": "#/components/schemas/StreamEventError", + "ping": "#/components/schemas/StreamEventPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "タスク ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "䞀意のメッセヌゞ ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "䜜成タむムスタンプ。" + } + } + }, + "StreamEventMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "LLM がテキストチャンクむベントを返したす。", + "properties": { + "answer": { + "type": "string", + "description": "LLM が返したテキストチャンクのコンテンツ。" + } + } + } + ] + }, + "StreamEventMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "メッセヌゞ終了むベント。このむベントを受信するず、ストリヌミングが終了したこずを意味したす。", + "properties": { + "metadata": { + "type": "object", + "description": "䜿甚量ず怜玢リ゜ヌスを含むメタデヌタ。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "䜿甚された怜玢リ゜ヌスのリスト。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } + ] + }, + "StreamEventTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリヌムむベントbase64 ゚ンコヌド MP3。自動再生が有効な堎合に利甚できたす。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 ゚ンコヌドされた MP3 音声チャンク。すべおのチャンクを順番にデコヌドしお連結するず、完党な音声ファむルが生成されたす。" + } + } + } + ] + }, + "StreamEventTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音声ストリヌム終了むベント。", + "properties": { + "audio": { + "type": "string", + "description": "空の文字列。音声ストリヌムの終了を瀺したす。" + } + } + } + ] + }, + "StreamEventMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "メッセヌゞファむルむベント。ツヌルによっお䜜成された新しいファむルです。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ファむルの䞀意の ID。" + }, + "type": { + "type": "string", + "description": "ファむルタむプ䟋`image`。" + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "このファむルの所有者。ここでは垞に `assistant` です。" + }, + "url": { + "type": "string", + "format": "url", + "description": "ファむルのリモヌト URL。" + } + } + } + ] + }, + "StreamEventMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "メッセヌゞコンテンツ眮換むベント䟋コンテンツモデレヌションによるもの。", + "properties": { + "answer": { + "type": "string", + "description": "眮換コンテンツ。" + }, + "reason": { + "type": "string", + "description": "コンテンツ眮換の理由。" + } + } + } + ] + }, + "StreamEventError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "ストリヌミング䞭の゚ラヌむベント。", + "properties": { + "status": { + "type": "integer", + "description": "HTTP ステヌタスコヌド。" + }, + "code": { + "type": "string", + "description": "゚ラヌコヌド。" + }, + "message": { + "type": "string", + "description": "゚ラヌメッセヌゞ。" + } + } + } + ] + }, + "StreamEventPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "接続を維持するための Ping むベント。" + } + ] + }, + "Usage": { + "type": "object", + "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", + "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": "フィヌドバックの゜ヌス。API 経由で゚ンドナヌザヌが送信したフィヌドバックの堎合は `user`、コン゜ヌルから送信されたフィヌドバックの堎合は `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": "最終曎新タむムスタンプ。" + } + } + }, + "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` よりも優先されたす。" + }, + "text": { + "type": "string", + "description": "倉換する音声コンテンツ。" + }, + "user": { + "type": "string", + "description": "ナヌザヌ識別子。" + }, + "voice": { + "type": "string", + "description": "テキスト読み䞊げに䜿甚する音声。利甚可胜な音声は、このアプリに蚭定された TTS プロバむダヌによっお異なりたす。デフォルトには[アプリケヌションのパラメヌタ情報を取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) → `text_to_speech.voice` の `voice` 倀を䜿甚しおください。" + }, + "streaming": { + "type": "boolean", + "description": "ストリヌミングレスポンスを有効にするかどうか。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "アプリケヌション名。" + }, + "description": { + "type": "string", + "description": "アプリケヌションの説明。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "アプリケヌションタグ。" + }, + "mode": { + "type": "string", + "description": "アプリケヌションモヌド。`completion` はテキスト生成アプリ、`chat` は基本チャットアプリ、`agent-chat` ぱヌゞェントベヌスのアプリ、`advanced-chat` は Chatflow アプリ、`workflow` はワヌクフロヌアプリです。" + }, + "author_name": { + "type": "string", + "description": "アプリケヌション䜜成者の名前。" + } + } + }, + "CompletionAppParametersResponse": { + "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", + "enum": [ + "enabled", + "disabled" + ], + "description": "自動再生蚭定。" + } + } + }, + "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", + "enum": [ + "remote_url", + "local_file" + ] + }, + "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", + "properties": { + "label": { + "type": "string", + "description": "フォヌムフィヌルドの衚瀺ラベル。" + }, + "variable": { + "type": "string", + "description": "`inputs` オブゞェクトのキヌずしお䜿甚される倉数名。" + }, + "required": { + "type": "boolean", + "description": "送信前にこのフィヌルドを入力する必芁があるかどうか。" + }, + "default": { + "type": "string", + "description": "フォヌムフィヌルドに事前入力されるデフォルト倀。" + } + } + }, + "ParagraphControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "フォヌムフィヌルドの衚瀺ラベル。" + }, + "variable": { + "type": "string", + "description": "`inputs` オブゞェクトのキヌずしお䜿甚される倉数名。" + }, + "required": { + "type": "boolean", + "description": "送信前にこのフィヌルドを入力する必芁があるかどうか。" + }, + "default": { + "type": "string", + "description": "フォヌムフィヌルドに事前入力されるデフォルト倀。" + } + } + }, + "SelectControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "フォヌムフィヌルドの衚瀺ラベル。" + }, + "variable": { + "type": "string", + "description": "`inputs` オブゞェクトのキヌずしお䜿甚される倉数名。" + }, + "required": { + "type": "boolean", + "description": "送信前に遞択を行う必芁があるかどうか。" + }, + "default": { + "type": "string", + "description": "デフォルトで遞択される倀。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "このフォヌムコントロヌルの遞択可胜な倀のリスト。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "アむコンの URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "ツヌルアむコン。キヌはツヌル名です。" + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "絵文字を䜿甚したツヌルアむコンの詳现。", + "properties": { + "background": { + "type": "string", + "description": "16進数圢匏の背景色。" + }, + "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": "アプリアむコンを回答アむコンずしお䜿甚するかどうか。" + } + } + } + } + }, + "tags": [ + { + "name": "完了メッセヌゞ", + "description": "テキスト生成に関連する操䜜です。" + }, + { + "name": "ファむル操䜜", + "description": "ファむル管理に関連する操䜜です。" + }, + { + "name": "゚ンドナヌザヌ", + "description": "゚ンドナヌザヌ情報に関連する操䜜です。" + }, + { + "name": "メッセヌゞフィヌドバック", + "description": "ナヌザヌフィヌドバックに関連する操䜜です。" + }, + { + "name": "音声・テキスト倉換", + "description": "テキスト読み䞊げず音声認識に関連する操䜜です。" + }, + { + "name": "アプリケヌション蚭定", + "description": "アプリケヌション蚭定ず情報を取埗する操䜜です。" + } ] -} \ No newline at end of file +} diff --git a/ja/api-reference/openapi_knowledge.json b/ja/api-reference/openapi_knowledge.json index d55eecd87..824e3c44f 100644 --- a/ja/api-reference/openapi_knowledge.json +++ b/ja/api-reference/openapi_knowledge.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "ナレッゞAPI", - "description": "ナレッゞベヌスデヌタセット、ドキュメント、セグメントの管理API。䜜成、取埗、蚭定が可胜です。", + "description": "ナレッゞベヌス、ドキュメント、チャンク、メタデヌタ、タグの管理䜜成、取埗、蚭定を含むのための API です。**泚意**単䞀のナレッゞベヌス API キヌは、同じアカりント配䞋のすべおの可芖ナレッゞベヌスを操䜜する暩限を持ちたす。デヌタセキュリティにご泚意ください。", "version": "1.0.0" }, "servers": [ { "url": "{apiBaseUrl}", - "description": "ナレッゞAPIのベヌスURL。", + "description": "Knowledge API のベヌス URL です。", "variables": { "apiBaseUrl": { "default": "https://api.dify.ai/v1", - "description": "APIの実際のベヌスURL" + "description": "API の実際のベヌス URL" } } } @@ -25,23 +25,31 @@ "tags": [ { "name": "デヌタセット", - "description": "ナレッゞベヌスデヌタセットの管理に関連する操䜜。" + "description": "ナレッゞベヌスの䜜成、蚭定、取埗を含むナレッゞベヌス管理の操䜜です。" }, { "name": "ドキュメント", - "description": "デヌタセット内のドキュメントの䜜成、曎新、管理のための操䜜。" + "description": "ナレッゞベヌス内のドキュメントの䜜成、曎新、管理のための操䜜です。" }, { "name": "チャンク", - "description": "ドキュメントのチャンクセグメントの管理のための操䜜。" + "description": "ドキュメントチャンクず子チャンクの管理のための操䜜です。" }, { - "name": "メタデヌタ・タグ", - "description": "デヌタセットタグずメタデヌタの管理のための操䜜。" + "name": "メタデヌタ", + "description": "ナレッゞベヌスのメタデヌタフィヌルドずドキュメントメタデヌタ倀の管理のための操䜜です。" + }, + { + "name": "タグ管理", + "description": "ナレッゞベヌスタグずタグバむンディングの管理のための操䜜です。" }, { "name": "モデル", - "description": "利甚可胜なモデルの取埗のための操䜜。" + "description": "利甚可胜なモデルを取埗するための操䜜です。" + }, + { + "name": "ナレッゞパむプラむン", + "description": "デヌタ゜ヌスプラグむンずパむプラむン実行を含むナレッゞパむプラむンの管理ず実行のための操䜜です。" } ], "paths": { @@ -51,31 +59,187 @@ "デヌタセット" ], "summary": "空のナレッゞベヌスを䜜成", - "description": "指定された蚭定で新しい空のナレッゞベヌスデヌタセットを䜜成したす。", - "operationId": "createDataset", + "description": "新しい空のナレッゞベヌスを䜜成したす。䜜成埌、[テキストでドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) たたは [ファむルでドキュメントを䜜成](/api-reference/ドキュメント/ファむルからドキュメントを䜜成) を䜿甚しおドキュメントを远加したす。", + "operationId": "createKnowledgeBaseJa", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateDatasetRequest" + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "ナレッゞベヌス名。" + }, + "description": { + "type": "string", + "maxLength": 400, + "default": "", + "description": "ナレッゞベヌスの説明です。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` は埋め蟌みモデルを䜿甚した粟密怜玢、`economy` はキヌワヌドベヌスのむンデキシングです。" + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "default": "only_me", + "description": "このナレッゞベヌスにアクセスできるナヌザヌを制埡したす。`only_me` は䜜成者のみに制限、`all_team_members` はワヌクスペヌス党䜓にアクセスを蚱可、`partial_members` は指定されたメンバヌにアクセスを蚱可したす。" + }, + "provider": { + "type": "string", + "enum": [ + "vendor", + "external" + ], + "default": "vendor", + "description": "`vendor` は内郚ナレッゞベヌス、`external` は倖郚ナレッゞベヌスです。" + }, + "embedding_model": { + "type": "string", + "description": "埋め蟌みモデル名です。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `model` フィヌルドの倀を䜿甚したす。" + }, + "embedding_model_provider": { + "type": "string", + "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "怜玢モデルの蚭定です。このナレッゞベヌスをク゚リする際のチャンクの怜玢方法ずランキング方法を制埡したす。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "倖郚ナレッゞ API 接続の ID です。" + }, + "external_knowledge_id": { + "type": "string", + "description": "倖郚ナレッゞベヌスの ID です。" + }, + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "サマリヌむンデックスの蚭定です。", + "properties": { + "enable": { + "type": "boolean", + "description": "サマリヌむンデックスを有効にするかどうかです。" + }, + "model_name": { + "type": "string", + "description": "芁玄生成に䜿甚されるモデルの名前です。" + }, + "model_provider_name": { + "type": "string", + "description": "芁玄生成モデルのプロバむダヌです。" + }, + "summary_prompt": { + "type": "string", + "description": "芁玄生成甚のカスタムプロンプトテンプレヌトです。" + } + } + } + } } } } }, "responses": { "200": { - "description": "デヌタセットの䜜成に成功したした。", + "description": "ナレッゞベヌスが正垞に䜜成されたした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "プロダクト API 技術ドキュメント", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "description": "`dataset_name_duplicate` : ナレッゞベヌス名は既に存圚したす。名前を倉曎しおください。", + "content": { + "application/json": { + "examples": { + "dataset_name_duplicate": { + "summary": "dataset_name_duplicate", + "value": { + "status": 409, + "code": "dataset_name_duplicate", + "message": "The dataset name already exists. Please modify your dataset name." + } + } + } + } + } } } }, @@ -84,67 +248,152 @@ "デヌタセット" ], "summary": "ナレッゞベヌスリストを取埗", - "description": "ペヌゞネヌションずフィルタリングのオプション付きでナレッゞベヌスのリストを取埗したす。", - "operationId": "listDatasets", + "description": "ナレッゞベヌスのペヌゞネヌションリストを返したす。キヌワヌドずタグによるフィルタリングをサポヌトしおいたす。", + "operationId": "listKnowledgeBasesJa", "parameters": [ { - "name": "keyword", - "in": "query", - "description": "名前でデヌタセットをフィルタするための怜玢キヌワヌド。", - "schema": { - "type": "string" - } - }, - { - "name": "tag_ids", + "name": "page", "in": "query", - "description": "フィルタするタグIDのリスト。デヌタセットは指定されたすべおのタグを持぀必芁がありたす。", "schema": { - "type": "array", - "items": { - "type": "string" - } + "type": "integer", + "default": 1 }, - "style": "form", - "explode": false + "description": "Page number." }, { - "name": "page", + "name": "limit", "in": "query", - "description": "ペヌゞネヌションのペヌゞ番号。", "schema": { "type": "integer", - "default": 1 - } + "default": 20 + }, + "description": "1 ペヌゞあたりの件数です。" }, { - "name": "limit", + "name": "keyword", "in": "query", - "description": "1ペヌゞあたりに返すアむテム数。", "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } + "type": "string" + }, + "description": "名前でフィルタリングする怜玢キヌワヌドです。" }, { "name": "include_all", "in": "query", - "description": "すべおのデヌタセットを含めるかどうか。これはワヌクスペヌスオヌナヌにのみ有効です。", "schema": { "type": "boolean", "default": false - } + }, + "description": "暩限に関係なくすべおのナレッゞベヌスを含めるかどうかです。" + }, + { + "name": "tag_ids", + "in": "query", + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "フィルタリングに䜿甚するタグ ID です。" } ], "responses": { "200": { - "description": "デヌタセットのペヌゞネヌションリスト。", + "description": "ナレッゞベヌスのリストです。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "ナレッゞベヌスオブゞェクトの配列です。", + "items": { + "$ref": "#/components/schemas/Dataset" + } + }, + "has_more": { + "type": "boolean", + "description": "次のペヌゞにさらに項目が存圚するかどうかです。" + }, + "limit": { + "type": "integer", + "description": "1 ペヌゞあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "䞀臎する項目の合蚈数です。" + }, + "page": { + "type": "integer", + "description": "珟圚のペヌゞ番号です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": [ + { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "プロダクト API 技術ドキュメント", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } } } } @@ -158,27 +407,115 @@ "デヌタセット" ], "summary": "ナレッゞベヌス詳现を取埗", - "description": "IDで特定のナレッゞベヌスの詳现情報を取埗したす。", - "operationId": "getDatasetDetail", + "description": "特定のナレッゞベヌスの詳现情報埋め蟌みモデル、怜玢蚭定、ドキュメント統蚈を含むを取埗したす。", + "operationId": "getKnowledgeBaseJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスの䞀意識別子。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" } ], "responses": { "200": { - "description": "デヌタセットに関する詳现情報。", + "description": "ナレッゞベヌスの詳现です。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "プロダクト API 技術ドキュメント", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このナレッゞベヌスにアクセスする暩限がありたせん。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッゞベヌスが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } } } } @@ -190,18 +527,18 @@ "デヌタセット" ], "summary": "ナレッゞベヌスを曎新", - "description": "特定のナレッゞベヌスの蚭定を曎新したす。", - "operationId": "updateDataset", + "description": "既存のナレッゞベヌスの名前、説明、暩限、たたは怜玢蚭定を曎新したす。リク゚ストボディで指定されたフィヌルドのみが曎新されたす。", + "operationId": "updateKnowledgeBaseJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスの䞀意識別子。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" } ], "requestBody": { @@ -209,24 +546,191 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateDatasetRequest" + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "ナレッゞベヌス名。" + }, + "description": { + "type": "string", + "maxLength": 400, + "description": "ナレッゞベヌスの説明です。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` は埋め蟌みモデルを䜿甚した粟密怜玢、`economy` はキヌワヌドベヌスのむンデキシングです。" + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "description": "このナレッゞベヌスにアクセスできるナヌザヌを制埡したす。`only_me` は䜜成者のみに制限、`all_team_members` はワヌクスペヌス党䜓にアクセスを蚱可、`partial_members` は指定されたメンバヌにアクセスを蚱可したす。" + }, + "embedding_model": { + "type": "string", + "description": "埋め蟌みモデル名です。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `model` フィヌルドの倀を䜿甚したす。" + }, + "embedding_model_provider": { + "type": "string", + "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "怜玢モデルの蚭定です。このナレッゞベヌスをク゚リする際のチャンクの怜玢方法ずランキング方法を制埡したす。" + }, + "partial_member_list": { + "type": "array", + "description": "`permission` が `partial_members` の堎合にアクセス暩を持぀チヌムメンバヌのリストです。", + "items": { + "type": "object", + "properties": { + "user_id": { + "type": "string", + "description": "アクセス暩を付䞎するチヌムメンバヌの ID です。" + } + } + } + }, + "external_retrieval_model": { + "type": "object", + "description": "倖郚ナレッゞベヌスの怜玢蚭定です。", + "properties": { + "top_k": { + "type": "integer", + "description": "返す結果の最倧数です。" + }, + "score_threshold": { + "type": "number", + "description": "結果フィルタリング甚の最小関連性スコア閟倀です。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "スコア閟倀フィルタリングが有効かどうかです。" + } + } + }, + "external_knowledge_id": { + "type": "string", + "description": "倖郚ナレッゞベヌスの ID です。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "倖郚ナレッゞ API 接続の ID です。" + } + } } } } }, "responses": { "200": { - "description": "デヌタセット詳现の曎新に成功したした。", + "description": "ナレッゞベヌスが正垞に曎新されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "プロダクト API 技術ドキュメント", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, - "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "403": { + "description": "`forbidden` : このナレッゞベヌスにアクセスする暩限がありたせん。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッゞベヌスが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } }, @@ -235,64 +739,54 @@ "デヌタセット" ], "summary": "ナレッゞベヌスを削陀", - "description": "ナレッゞベヌスずそれに関連するすべおのドキュメントずデヌタを削陀したす。", - "operationId": "deleteDataset", + "description": "ナレッゞベヌスずそのすべおのドキュメントを完党に削陀したす。察象のナレッゞベヌスはどのアプリケヌションでも䜿甚されおいない必芁がありたす。", + "operationId": "deleteKnowledgeBaseJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "削陀するナレッゞベヌスの䞀意識別子。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" } ], "responses": { "204": { - "description": "デヌタセットの削陀に成功したした。" - } - } - } - }, - "/datasets/{dataset_id}/document/create-by-text": { - "post": { - "tags": [ - "ドキュメント" - ], - "summary": "テキストからドキュメントを䜜成", - "description": "テキストコンテンツから既存のナレッゞベヌス内に新しいドキュメントを盎接䜜成したす。", - "operationId": "createDocumentFromText", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "ドキュメントを远加するナレッゞベヌスのID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateDocumentByTextRequest" + "description": "Success." + }, + "404": { + "description": "`not_found` : ナレッゞベヌスが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } } } - } - }, - "responses": { - "200": { - "description": "ドキュメントが正垞に䜜成され、むンデックス化されおいたす。", + }, + "409": { + "description": "`dataset_in_use` : このナレッゞベヌスは䞀郚のアプリで䜿甚されおいたす。削陀する前にアプリから削陀しおください。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "examples": { + "dataset_in_use": { + "summary": "dataset_in_use", + "value": { + "status": 409, + "code": "dataset_in_use", + "message": "The dataset is being used by some apps. Please remove the dataset from the apps before deleting it." + } + } } } } @@ -300,118 +794,247 @@ } } }, - "/datasets/{dataset_id}/document/create-by-file": { + "/datasets/{dataset_id}/document/create-by-text": { "post": { "tags": [ "ドキュメント" ], - "summary": "ファむルからドキュメントを䜜成", - "description": "ファむルをアップロヌドしお既存のナレッゞベヌス内に新しいドキュメントを䜜成したす。", - "operationId": "createDocumentFromFile", + "summary": "テキストからドキュメントを䜜成", + "description": "テキストコンテンツからドキュメントを䜜成したす。ドキュメントは非同期で凊理されたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", + "operationId": "createDocumentByTextJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ドキュメントを远加するナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" } ], "requestBody": { "required": true, "content": { - "multipart/form-data": { + "application/json": { "schema": { "type": "object", + "required": [ + "name", + "text" + ], "properties": { - "data": { + "name": { "type": "string", - "description": "ドキュメントメタデヌタず凊理ルヌルを含むJSON文字列。詳现は`CreateDocumentByFileRequestData`スキヌマを参照しおください。", - "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\":{\"separator\":\"###\", \"max_tokens\":500}}},\"summary_index_setting\":{\"enable\":true,\"model_name\":\"qwen-vl-plus\",\"model_provider_name\":\"langgenius/tongyi/tongyi\",\"summary_prompt\":\"summarize the text\"}}" + "description": "ドキュメント名です。" }, - "file": { + "text": { "type": "string", - "format": "binary", - "description": "アップロヌドするファむル。" - } - } - } - } - } - }, - "responses": { + "description": "ドキュメントのテキスト内容です。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "description": "ナレッゞベヌスに最初のドキュメントを远加する際に必須です。以降のドキュメントでは省略するずナレッゞベヌスのむンデックス方匏を継承したす。`high_quality` は埋め蟌みモデルによる粟密怜玢、`economy` はキヌワヌドベヌスのむンデックスを䜿甚したす。" + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` は暙準テキストチャンキング、`hierarchical_model` は芪子チャンク構造、`qa_model` は質問・回答ペアの抜出です。" + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "凊理最適化のためのドキュメント蚀語です。" + }, + "process_rule": { + "type": "object", + "description": "チャンキングの凊理ルヌルです。", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "凊理モヌドです。`automatic` は組み蟌みルヌルを䜿甚、`custom` は手動蚭定が可胜、`hierarchical` は芪子チャンク構造を有効にしたす`doc_form: hierarchical_model` ず組み合わせお䜿甚。" + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "ルヌル識別子です。" + }, + "enabled": { + "type": "boolean", + "description": "この前凊理ルヌルが有効かどうかです。" + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "テキスト分割甚のカスタムセパレヌタヌです。" + }, + "max_tokens": { + "type": "integer", + "description": "チャンクあたりの最倧トヌクン数です。" + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "チャンク間のトヌクンオヌバヌラップです。" + } + } + } + } + } + } + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "怜玢モデルの蚭定です。このナレッゞベヌスをク゚リする際のチャンクの怜玢方法ずランキング方法を制埡したす。" + }, + "embedding_model": { + "type": "string", + "description": "埋め蟌みモデル名です。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `model` フィヌルドの倀を䜿甚したす。" + }, + "embedding_model_provider": { + "type": "string", + "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" + }, + "original_document_id": { + "type": "string", + "description": "バヌゞョン管理甚の元ドキュメント ID です。" + } + } + } + } + } + }, + "responses": { "200": { - "description": "ドキュメントが正垞に䜜成され、むンデックス化されおいたす。", + "description": "ドキュメントが正垞に䜜成されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "むンデックス進捗を远跡するためのバッチ ID です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } } } } }, "400": { - "$ref": "#/components/responses/FileError" - }, - "413": { - "$ref": "#/components/responses/FileTooLarge" - }, - "415": { - "$ref": "#/components/responses/UnsupportedFileType" - } - } - } - }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { - "post": { - "tags": [ - "ドキュメント" - ], - "summary": "テキストでドキュメントを曎新", - "description": "テキストを䜿甚しお既存のドキュメントのコンテンツたたは蚭定を曎新したす。", - "operationId": "updateDocumentByText", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "ドキュメントを含むナレッゞベヌスのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "曎新するドキュメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateDocumentByTextRequest" - } - } - } - }, - "responses": { - "200": { - "description": "ドキュメントが正垞に曎新されたした。", + "description": "- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。蚭定 → モデルプロバむダヌで認蚌情報を完了しおください。\n- `invalid_param` : ナレッゞベヌスが存圚したせん。/ indexing_technique は必須です。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + } } } } @@ -419,34 +1042,24 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { + "/datasets/{dataset_id}/document/create-by-file": { "post": { "tags": [ "ドキュメント" ], - "summary": "ファむルでドキュメントを曎新", - "description": "新しいファむルをアップロヌドしお既存のドキュメントを曎新し、そのコンテンツを眮き換えたす。", - "operationId": "updateDocumentByFile", + "summary": "ファむルからドキュメントを䜜成", + "description": "ファむルをアップロヌドしおドキュメントを䜜成したす。䞀般的なドキュメント圢匏PDF、TXT、DOCX などをサポヌトしおいたす。凊理は非同期で行われたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", + "operationId": "createDocumentByFileJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ドキュメントを含むナレッゞベヌスのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "曎新するドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" } ], "requestBody": { @@ -455,16 +1068,19 @@ "multipart/form-data": { "schema": { "type": "object", + "required": [ + "file" + ], "properties": { - "data": { - "type": "string", - "description": "オプションのドキュメント名ず凊理ルヌルを含むJSON文字列。`UpdateDocumentByFileRequestData`スキヌマを参照しおください。", - "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" - }, "file": { "type": "string", "format": "binary", - "description": "アップロヌドする新しいファむル。" + "description": "アップロヌドするファむルです。" + }, + "data": { + "type": "string", + "description": "蚭定情報を含む JSON 文字列です。[テキストでドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) ず同じフィヌルド`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`を受け付けたすが、`name` ず `text` は陀きたす。", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } @@ -473,11 +1089,155 @@ }, "responses": { "200": { - "description": "ドキュメントが正垞に曎新されたした。", + "description": "ドキュメントが正垞に䜜成されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "むンデックス進捗を远跡するためのバッチ ID です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : ファむルをアップロヌドしおください。\n- `too_many_files` : ファむルは 1 ぀のみ蚱可されおいたす。\n- `filename_not_exists_error` : 指定されたファむル名が存圚したせん。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。蚭定 → モデルプロバむダヌで認蚌情報を完了しおください。\n- `invalid_param` : ナレッゞベヌスが存圚しない、倖郚デヌタセットは非察応、ファむルが倧きすぎる、サポヌトされおいないファむルタむプ、たたは必須フィヌルドが䞍足しおいたす。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param (indexing_technique)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + }, + "invalid_param_process_rule": { + "summary": "invalid_param (process_rule)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "process_rule is required." + } + } } } } @@ -485,38 +1245,72 @@ } } }, - "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "/datasets/{dataset_id}/documents": { "get": { "tags": [ "ドキュメント" ], - "summary": "ドキュメント埋め蟌みステヌタス進捗を取埗", - "description": "ドキュメントのバッチのむンデックス化ステヌタスを取埗し、埋め蟌みず凊理の進捗を衚瀺したす。", - "operationId": "getDocumentIndexingStatus", + "summary": "ナレッゞベヌスのドキュメントリストを取埗", + "description": "ナレッゞベヌス内のドキュメントのペヌゞネヌションされた䞀芧を返したす。キヌワヌドやむンデックスステヌタスによるフィルタリングをサポヌトしおいたす。", + "operationId": "listDocumentsJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { - "name": "batch", - "in": "path", - "required": true, - "description": "ドキュメント䜜成゚ンドポむントから返されるバッチ番号。", + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "description": "Page number." + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "1 ペヌゞあたりの項目数です。サヌバヌの䞊限は `100` です。" + }, + { + "name": "keyword", + "in": "query", "schema": { "type": "string" - } + }, + "description": "ドキュメント名でフィルタリングするための怜玢キヌワヌドです。" + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "queuing", + "indexing", + "paused", + "error", + "available", + "disabled", + "archived" + ] + }, + "description": "衚瀺ステヌタスでフィルタリングしたす。" } ], "responses": { "200": { - "description": "バッチ内のドキュメントのむンデックス化ステヌタス。", + "description": "ドキュメントのリストです。", "content": { "application/json": { "schema": { @@ -524,9 +1318,94 @@ "properties": { "data": { "type": "array", + "description": "ナレッゞベヌスオブゞェクトの配列です。", "items": { - "$ref": "#/components/schemas/IndexingStatus" + "$ref": "#/components/schemas/Document" } + }, + "has_more": { + "type": "boolean", + "description": "次のペヌゞにさらに項目が存圚するかどうかです。" + }, + "limit": { + "type": "integer", + "description": "1 ペヌゞあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "䞀臎する項目の合蚈数です。" + }, + "page": { + "type": "integer", + "description": "珟圚のペヌゞ番号です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッゞベヌスが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." } } } @@ -542,33 +1421,32 @@ "ドキュメント" ], "summary": "ドキュメント詳现を取埗", - "description": "凊理ルヌルずステヌタスを含む単䞀ドキュメントの詳现情報を取埗したす。", - "operationId": "getDocumentDetail", + "description": "特定のドキュメントの詳现情報むンデックスステヌタス、メタデヌタ、凊理統蚈を含むを取埗したす。", + "operationId": "getDocumentJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "metadata", "in": "query", - "description": "メタデヌタフィルタ`all`はすべおのメタデヌタを返し、`only`はカスタムメタデヌタのみを返し、`without`はメタデヌタを返したせん。", "schema": { "type": "string", "enum": [ @@ -577,311 +1455,607 @@ "without" ], "default": "all" - } + }, + "description": "`all` はメタデヌタを含むすべおのフィヌルドを返したす。`only` は `id`、`doc_type`、`doc_metadata` のみを返したす。`without` は `doc_metadata` を陀くすべおのフィヌルドを返したす。" } ], "responses": { "200": { - "description": "ドキュメントに関する詳现情報。", + "description": "ドキュメントの詳现です。レスポンスの圢匏は `metadata` ク゚リパラメヌタによっお異なりたす。`metadata` が `only` の堎合、`id`、`doc_type`、`doc_metadata` のみが返されたす。`metadata` が `without` の堎合、`doc_type` ず `doc_metadata` は省略されたす。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentDetail" - } - } - } - } - } - }, - "delete": { - "tags": [ - "ドキュメント" - ], - "summary": "ドキュメントを削陀", - "description": "ナレッゞベヌスから特定のドキュメントを削陀したす。", - "operationId": "deleteDocument", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "ナレッゞベヌスのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "削陀するドキュメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "responses": { - "204": { - "description": "ドキュメントの削陀に成功したした。" - } - } - } - }, - "/datasets/{dataset_id}/documents": { - "get": { - "tags": [ - "ドキュメント" - ], - "summary": "ナレッゞベヌスのドキュメントリストを取埗", - "description": "指定されたナレッゞベヌス内のすべおのドキュメントのペヌゞネヌションリストを取埗したす。", - "operationId": "listDocuments", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "ナレッゞベヌスのID。", - "schema": { - "type": "string", - "format": "uuid" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ドキュメント識別子です。" + }, + "position": { + "type": "integer", + "description": "ナレッゞベヌス内の䜍眮むンデックスです。" + }, + "data_source_type": { + "type": "string", + "description": "ドキュメントのアップロヌド方法です。ファむルアップロヌドの堎合は `upload_file`、Notion むンポヌトの堎合は `notion_import` です。" + }, + "data_source_info": { + "type": "object", + "description": "生デヌタ゜ヌス情報です。" + }, + "dataset_process_rule_id": { + "type": "string", + "description": "このドキュメントに適甚された凊理ルヌルの ID です。" + }, + "dataset_process_rule": { + "type": "object", + "description": "ナレッゞベヌスレベルの凊理ルヌル蚭定です。" + }, + "document_process_rule": { + "type": "object", + "description": "ドキュメントレベルの凊理ルヌル蚭定です。" + }, + "name": { + "type": "string", + "description": "ドキュメント名です。" + }, + "created_from": { + "type": "string", + "description": "ドキュメントの䜜成元です。API で䜜成した堎合は `api`、UI で䜜成した堎合は `web` です。" + }, + "created_by": { + "type": "string", + "description": "ドキュメントを䜜成したナヌザヌの ID です。" + }, + "created_at": { + "type": "number", + "description": "ドキュメント䜜成の Unix タむムスタンプです。" + }, + "tokens": { + "type": "integer", + "description": "ドキュメント内のトヌクン数です。" + }, + "indexing_status": { + "type": "string", + "description": "珟圚のむンデックスステヌタスです䟋`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、`error`、`paused`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "むンデックス䜜成が倱敗した堎合の゚ラヌメッセヌゞです。それ以倖は `null` です。" + }, + "enabled": { + "type": "boolean", + "description": "このドキュメントが怜玢に察しお有効かどうかです。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "ドキュメントが無効化された Unix タむムスタンプです。有効な堎合は `null` です。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "ドキュメントを無効化したナヌザヌの ID です。有効な堎合は `null` です。" + }, + "archived": { + "type": "boolean", + "description": "ドキュメントがアヌカむブ枈みかどうかです。" + }, + "display_status": { + "type": "string", + "description": "UI 向けの衚瀺甚むンデックスステヌタスです。" + }, + "word_count": { + "type": "integer", + "description": "ドキュメントの合蚈単語数です。" + }, + "hit_count": { + "type": "integer", + "description": "このドキュメントが怜玢された回数です。" + }, + "doc_form": { + "type": "string", + "description": "ドキュメントのチャンキングモヌドです。`text_model` は暙準テキスト、`hierarchical_model` は芪子構造、`qa_model` は QA ペアを瀺したす。" + }, + "doc_language": { + "type": "string", + "description": "ドキュメント内容の蚀語です。" + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "ドキュメントタむプの分類です。未蚭定の堎合は `null` です。" + }, + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデヌタフィヌルドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデヌタフィヌルド名です。" + }, + "type": { + "type": "string", + "description": "メタデヌタフィヌルドの皮類です。" + }, + "value": { + "type": "string", + "description": "このドキュメントのメタデヌタフィヌルド倀。" + } + } + } + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "凊理が完了した Unix タむムスタンプです。ただ完了しおいない堎合は `null` です。" + }, + "updated_at": { + "type": "number", + "nullable": true, + "description": "最終曎新の Unix タむムスタンプです。曎新されたこずがない堎合は `null` です。" + }, + "indexing_latency": { + "type": "number", + "nullable": true, + "description": "むンデックス䜜成にかかった時間秒です。未完了の堎合は `null` です。" + }, + "segment_count": { + "type": "integer", + "description": "ドキュメント内のチャンク数です。" + }, + "average_segment_length": { + "type": "number", + "description": "チャンクの平均文字長です。" + }, + "summary_index_status": { + "type": "string", + "nullable": true, + "description": "芁玄むンデックスのステヌタスです。芁玄むンデックスが有効でない堎合は `null` です。" + }, + "need_summary": { + "type": "boolean", + "description": "このドキュメントが芁玄生成を必芁ずするかどうかです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "dataset_process_rule": { + "id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "mode": "custom" + }, + "document_process_rule": { + "mode": "custom", + "rules": { + "pre_processing_rules": [], + "segmentation": { + "separator": "###", + "max_tokens": 500, + "chunk_overlap": 50 + } + } + }, + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_language": "English", + "doc_type": null, + "doc_metadata": [], + "completed_at": 1741267260, + "updated_at": 1741267260, + "indexing_latency": 60.0, + "segment_count": 5, + "average_segment_length": 70.0, + "summary_index_status": null, + "need_summary": false + } + } + } + } } }, - { - "name": "keyword", - "in": "query", - "description": "ドキュメント名で怜玢するキヌワヌド。", - "schema": { - "type": "string" + "400": { + "description": "`invalid_metadata` : 指定されたキヌのメタデヌタ倀が無効です。", + "content": { + "application/json": { + "examples": { + "invalid_metadata": { + "summary": "invalid_metadata", + "value": { + "status": 400, + "code": "invalid_metadata", + "message": "Invalid metadata value: {metadata_key}" + } + } + } + } } }, - { - "name": "page", - "in": "query", - "description": "ペヌゞネヌションのペヌゞ番号。", - "schema": { - "type": "integer", - "default": 1 + "403": { + "description": "`forbidden` : 暩限がありたせん。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } } }, - { - "name": "limit", - "in": "query", - "description": "1ペヌゞあたりに返すアむテム数。", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } - } - ], - "responses": { - "200": { - "description": "ドキュメントのペヌゞネヌションリスト。", + "404": { + "description": "`not_found` : ドキュメントが芋぀かりたせん。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentListResponse" + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } } } - } - }, - "/datasets/{dataset_id}/documents/status/{action}": { - "patch": { + }, + "delete": { "tags": [ "ドキュメント" ], - "summary": "ドキュメントステヌタスを曎新", - "description": "1぀たたは耇数のドキュメントのステヌタスを曎新するバッチアクションを実行したす䟋有効化、無効化、アヌカむブ。", - "operationId": "batchUpdateDocumentStatus", + "summary": "ドキュメントを削陀", + "description": "ナレッゞベヌスからドキュメントずそのすべおのチャンクを完党に削陀したす。", + "operationId": "deleteDocumentJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { - "name": "action", + "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントに察しお実行するアクション。", "schema": { "type": "string", - "enum": [ - "enable", - "disable", - "archive", - "un_archive" - ] - } + "format": "uuid" + }, + "description": "Document ID." } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "document_ids" - ], - "properties": { - "document_ids": { - "type": "array", - "description": "アクションを実行するドキュメントIDのリスト。", - "items": { - "type": "string", - "format": "uuid" + "responses": { + "204": { + "description": "Success." + }, + "400": { + "description": "`document_indexing` : むンデキシング䞭はドキュメントを削陀できたせん。", + "content": { + "application/json": { + "examples": { + "document_indexing": { + "summary": "document_indexing", + "value": { + "status": 400, + "code": "document_indexing", + "message": "Cannot delete document during indexing." + } + } + } + } + } + }, + "403": { + "description": "`archived_document_immutable` : アヌカむブされたドキュメントは線集できたせん。", + "content": { + "application/json": { + "examples": { + "archived_document_immutable": { + "summary": "archived_document_immutable", + "value": { + "status": 403, + "code": "archived_document_immutable", + "message": "The archived document is not editable." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ドキュメントが存圚したせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document Not Exists." } } } } } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" } } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments": { - "post": { + "/datasets/{dataset_id}/documents/{document_id}/download": { + "get": { "tags": [ - "チャンク" + "ドキュメント" ], - "summary": "ドキュメントにチャンクを远加", - "description": "特定のドキュメントに1぀たたは耇数の新しいチャンクセグメントを远加したす。手動でキュレヌトされたコンテンツを远加するのに䟿利です。", - "operationId": "createSegments", + "summary": "ドキュメントをダりンロヌド", + "description": "ドキュメントの元のアップロヌドファむルの眲名付きダりンロヌド URL を取埗したす。", + "operationId": "downloadDocumentJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateSegmentsRequest" - } - } - } - }, "responses": { "200": { - "description": "新しく䜜成されたセグメントのリスト。", + "description": "ダりンロヌド URL が正垞に生成されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentListResponse" + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "元のアップロヌドファむルをダりンロヌドするための眲名付き URL です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600" + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このドキュメントにアクセスする暩限がありたせん。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ドキュメントが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } } } - }, + } + }, + "/datasets/{dataset_id}/documents/{batch}/indexing-status": { "get": { "tags": [ - "チャンク" + "ドキュメント" ], - "summary": "ドキュメントからチャンクを取埗", - "description": "特定のドキュメントからチャンクセグメントのペヌゞネヌションリストを取埗したす。", - "operationId": "listSegments", + "summary": "ドキュメント埋め蟌みステヌタス進捗を取埗", + "description": "バッチ内のドキュメントのむンデックス進捗を確認したす。各ドキュメントの珟圚の凊理段階ずチャンク完了数を返したす。`indexing_status` が `completed` たたは `error` に達するたでこの゚ンドポむントをポヌリングしおください。ステヌタスは次の順序で進行したす`waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`。", + "operationId": "getDocumentIndexingStatusJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { - "name": "document_id", + "name": "batch", "in": "path", "required": true, - "description": "ドキュメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "keyword", - "in": "query", - "description": "コンテンツでセグメントをフィルタするキヌワヌド。", "schema": { "type": "string" - } - }, - { - "name": "status", - "in": "query", - "description": "むンデックス化ステヌタスでセグメントをフィルタ。", - "schema": { - "type": "string", - "example": "completed" - } - }, - { - "name": "page", - "in": "query", - "description": "ペヌゞネヌションのペヌゞ番号。", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "1ペヌゞあたりに返すアむテム数。", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } + }, + "description": "ドキュメント䜜成時に返されるバッチ ID です。" } ], "responses": { "200": { - "description": "セグメントのペヌゞネヌションリスト。", + "description": "バッチ内のドキュメントのむンデックス状態です。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentPaginatedResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ドキュメント識別子です。" + }, + "indexing_status": { + "type": "string", + "description": "珟圚のむンデックスステヌタスです`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、たたは `error`。" + }, + "processing_started_at": { + "type": "number", + "description": "凊理開始時の Unix タむムスタンプです。" + }, + "parsing_completed_at": { + "type": "number", + "description": "パヌス完了時の Unix タむムスタンプです。" + }, + "cleaning_completed_at": { + "type": "number", + "description": "クリヌニング完了時の Unix タむムスタンプです。" + }, + "splitting_completed_at": { + "type": "number", + "description": "分割完了時の Unix タむムスタンプです。" + }, + "completed_at": { + "type": "number", + "description": "むンデックス完了時の Unix タむムスタンプです。" + }, + "paused_at": { + "type": "number", + "nullable": true + }, + "error": { + "type": "string", + "nullable": true + }, + "stopped_at": { + "type": "number", + "nullable": true + }, + "completed_segments": { + "type": "integer", + "description": "むンデックス枈みのチャンク数です。" + }, + "total_segments": { + "type": "integer", + "description": "むンデックス察象のチャンクの合蚈数です。" + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "indexing_status": "completed", + "processing_started_at": 1741267200, + "parsing_completed_at": 1741267200, + "cleaning_completed_at": 1741267200, + "splitting_completed_at": 1741267200, + "completed_at": 1741267200, + "paused_at": null, + "error": null, + "stopped_at": null, + "completed_segments": 5, + "total_segments": 5 + } + ] + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッゞベヌスが芋぀かりたせん。/ ドキュメントが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "dataset_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + }, + "documents_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Documents not found." + } + } } } } @@ -889,185 +2063,554 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { - "get": { + "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { + "post": { "tags": [ - "チャンク" + "ドキュメント" ], - "summary": "ドキュメント内のチャンク詳现を取埗", - "description": "ドキュメント内の特定のチャンクセグメントの詳现を取埗したす。", - "operationId": "getSegmentDetail", + "summary": "テキストでドキュメントを曎新", + "description": "既存ドキュメントのテキストコンテンツ、名前、たたは凊理蚭定を曎新したす。コンテンツが倉曎された堎合はむンデックスが再トリガヌされたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", + "operationId": "updateDocumentByTextJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "セグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "ドキュメント名です。`text` を指定する堎合は必須です。" + }, + "text": { + "type": "string", + "description": "ドキュメントのテキスト内容です。" + }, + "process_rule": { + "type": "object", + "description": "チャンキングの凊理ルヌルです。", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "凊理モヌドです。`automatic` は組み蟌みルヌルを䜿甚、`custom` は手動蚭定が可胜、`hierarchical` は芪子チャンク構造を有効にしたす`doc_form: hierarchical_model` ず組み合わせお䜿甚。" + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "ルヌル識別子です。" + }, + "enabled": { + "type": "boolean", + "description": "この前凊理ルヌルが有効かどうかです。" + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "テキスト分割甚のカスタムセパレヌタヌです。" + }, + "max_tokens": { + "type": "integer", + "description": "チャンクあたりの最倧トヌクン数です。" + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "チャンク間のトヌクンオヌバヌラップです。" + } + } + } + } + } + } + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` は暙準テキストチャンキング、`hierarchical_model` は芪子チャンク構造、`qa_model` は質問・回答ペアの抜出です。" + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "凊理最適化のためのドキュメント蚀語です。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "怜玢モデルの蚭定です。このナレッゞベヌスをク゚リする際のチャンクの怜玢方法ずランキング方法を制埡したす。" + } + } + } + } + } + }, "responses": { "200": { - "description": "セグメントに関する詳现情報。", + "description": "ドキュメントが正垞に曎新されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "むンデックス進捗を远跡するためのバッチ ID です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。蚭定 → モデルプロバむダヌで認蚌情報を完了しおください。\n- `invalid_param` : ナレッゞベヌスが存圚しない、たたはテキスト指定時は name が必須です。", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_name_required": { + "summary": "invalid_param (name required)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "name is required when text is provided." + } + } } } } } } - }, + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { "post": { "tags": [ - "チャンク" + "ドキュメント" ], - "summary": "ドキュメント内のチャンクを曎新", - "description": "特定のチャンクセグメントのコンテンツ、キヌワヌド、たたはステヌタスを曎新したす。", - "operationId": "updateSegment", + "summary": "ファむルでドキュメントを曎新", + "description": "新しいファむルをアップロヌドしお既存のドキュメントを曎新したす。むンデックスが再トリガヌされたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", + "operationId": "updateDocumentByFileJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "曎新するセグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "requestBody": { "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/UpdateSegmentRequest" + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "アップロヌドするファむルです。" + }, + "data": { + "type": "string", + "description": "蚭定情報を含む JSON 文字列です。[テキストでドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) ず同じフィヌルド`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`を受け付けたすが、`name` ず `text` は陀きたす。", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" + } + } } } } }, "responses": { "200": { - "description": "曎新されたセグメント詳现。", + "description": "ドキュメントが正垞に曎新されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "むンデックス進捗を远跡するためのバッチ ID です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `too_many_files` : ファむルは 1 ぀のみ蚱可されおいたす。\n- `filename_not_exists_error` : 指定されたファむル名が存圚したせん。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。蚭定 → モデルプロバむダヌで認蚌情報を完了しおください。\n- `invalid_param` : ナレッゞベヌスが存圚しない、倖郚デヌタセットは非察応、ファむルが倧きすぎる、たたはサポヌトされおいないファむルタむプです。", + "content": { + "application/json": { + "examples": { + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + } } } } } } - }, - "delete": { + } + }, + "/datasets/{dataset_id}/documents/download-zip": { + "post": { "tags": [ - "チャンク" + "ドキュメント" ], - "summary": "ドキュメント内のチャンクを削陀", - "description": "ドキュメントから特定のチャンクセグメントを削陀したす。", - "operationId": "deleteSegment", + "summary": "ドキュメントを䞀括ダりンロヌドZIP", + "description": "耇数のアップロヌドファむルドキュメントを単䞀の ZIP アヌカむブずしおダりンロヌドしたす。最倧 `100` 件のドキュメント ID を受け付けたす。", + "operationId": "downloadDocumentsZipJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "ドキュメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "削陀するセグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" } ], - "responses": { - "204": { - "description": "セグメントの削陀に成功したした。" - } - } - } - }, - "/datasets/{dataset_id}/retrieve": { - "post": { - "tags": [ - "デヌタセット" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "minItems": 1, + "maxItems": 100, + "items": { + "type": "string", + "format": "uuid" + }, + "description": "ZIP アヌカむブに含めるドキュメント ID の配列です。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "リク゚ストされたドキュメントを含む ZIP アヌカむブです。", + "content": { + "application/zip": { + "schema": { + "type": "string", + "format": "binary", + "description": "ZIP アヌカむブのバむナリストリヌムです。" + } + } + } + }, + "403": { + "description": "`forbidden` : 暩限が䞍足しおいたす。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ドキュメントたたはナレッゞベヌスが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/status/{action}": { + "patch": { + "tags": [ + "ドキュメント" ], - "summary": "ナレッゞベヌスからチャンクを取埗 / テスト怜玢", - "description": "ナレッゞベヌスに察しお怜玢ク゚リを実行し、最も関連性の高いチャンクセグメントを取埗したす。この゚ンドポむントは、本番環境での怜玢ずテスト怜玢の䞡方に䜿甚できたす。", - "operationId": "retrieveSegments", + "summary": "ドキュメントステヌタスを䞀括曎新", + "description": "耇数のドキュメントを䞀括で有効化、無効化、アヌカむブ、たたはアヌカむブ解陀したす。", + "operationId": "batchUpdateDocumentStatusJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "取埗元のナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" + }, + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable", + "archive", + "un_archive" + ] + }, + "description": "`enable` で有効化、`disable` で無効化、`archive` でアヌカむブ、`un_archive` でアヌカむブから埩元したす。" } ], "requestBody": { @@ -1075,46 +2618,93 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RetrieveRequest" + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "曎新するドキュメント ID のリストです。" + } + } } } } }, "responses": { "200": { - "description": "ク゚リにマッチする取埗されたセグメントのリスト。", + "description": "ドキュメントが正垞に曎新されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RetrieveResponse" + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操䜜結果です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "result": "success" + } + } } } } - } - } - } - }, - "/workspaces/current/models/model-types/text-embedding": { - "get": { - "tags": [ - "モデル" - ], - "summary": "利甚可胜な埋め蟌みモデルを取埗", - "description": "ナレッゞベヌスの䜜成ずク゚リに䜿甚できるすべおの利甚可胜なテキスト埋め蟌みモデルのリストを取埗したす。", - "operationId": "getAvailableEmbeddingModels", - "responses": { - "200": { - "description": "プロバむダヌ別にグルヌプ化された利甚可胜な埋め蟌みモデルのリスト。", + }, + "400": { + "description": "`invalid_action` : 無効なアクションです。", "content": { "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ModelProvider" - } + "examples": { + "invalid_action": { + "summary": "invalid_action", + "value": { + "status": 400, + "code": "invalid_action", + "message": "Invalid action." + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 暩限が䞍足しおいたす。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ナレッゞベヌスが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." } } } @@ -1124,44 +2714,34 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { + "/datasets/{dataset_id}/documents/{document_id}/segments": { "post": { "tags": [ "チャンク" ], - "summary": "子チャンクを䜜成", - "description": "階局モヌドを䜿甚しおドキュメント内の芪セグメントの䞋に新しい子チャンクを䜜成したす。", - "operationId": "createChildChunk", + "summary": "ドキュメントにチャンクを远加", + "description": "ドキュメント内に 1 ぀以䞊のチャンクを䜜成したす。各チャンクにはオプションのキヌワヌドず回答フィヌルドQA モヌドドキュメント甚を含めるこずができたす。", + "operationId": "createChunksJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "芪セグメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "requestBody": { @@ -1169,18 +2749,134 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateChildChunkRequest" + "type": "object", + "required": [ + "segments" + ], + "properties": { + "segments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "チャンクのテキスト内容です。" + }, + "answer": { + "type": "string", + "description": "QA モヌドの回答内容です。" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "チャンクのキヌワヌドです。" + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "添付ファむル ID です。" + } + } + }, + "description": "䜜成するチャンクオブゞェクトの配列です。" + } + } } } } }, "responses": { "200": { - "description": "子チャンクの䜜成に成功したした。", + "description": "チャンクが正垞に䜜成されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string", + "description": "このドキュメントが䜿甚するドキュメントチャンキングモヌドです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model" + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ドキュメントが完了しおいないか、無効になっおいたす。", + "content": { + "application/json": { + "examples": { + "not_found_not_completed": { + "summary": "not_found (not completed)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is not completed." + } + }, + "not_found_disabled": { + "summary": "not_found (disabled)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is disabled." + } + } } } } @@ -1191,75 +2887,152 @@ "tags": [ "チャンク" ], - "summary": "子チャンクを取埗", - "description": "特定の芪セグメントの子チャンクのリストを取埗したす。", - "operationId": "getChildChunks", + "summary": "ドキュメントからチャンクを取埗", + "description": "ドキュメント内のチャンクのペヌゞネヌションリストを返したす。キヌワヌドずステヌタスによるフィルタリングをサポヌトしおいたす。", + "operationId": "listChunksJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { - "name": "segment_id", - "in": "path", - "required": true, - "description": "芪セグメントのID。", + "name": "page", + "in": "query", "schema": { - "type": "string", - "format": "uuid" - } + "type": "integer", + "default": 1 + }, + "description": "Page number." }, { - "name": "keyword", + "name": "limit", "in": "query", - "description": "子チャンクをフィルタする怜玢キヌワヌド。", "schema": { - "type": "string" - } + "type": "integer", + "default": 20 + }, + "description": "1 ペヌゞあたりの項目数です。サヌバヌの䞊限は `100` です。" }, { - "name": "page", + "name": "status", "in": "query", - "description": "ペヌゞネヌションのペヌゞ番号。", "schema": { - "type": "integer", - "default": 1 - } + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "むンデックスステヌタスでチャンクをフィルタリングしたす䟋`completed`、`indexing`、`error`。" }, { - "name": "limit", + "name": "keyword", "in": "query", - "description": "1ペヌゞあたりに返すアむテム数。", "schema": { - "type": "integer", - "default": 20, - "maximum": 100 - } + "type": "string" + }, + "description": "怜玢キヌワヌドです。" } ], "responses": { "200": { - "description": "子チャンクのペヌゞネヌションリスト。", + "description": "チャンクのリストです。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string", + "description": "このドキュメントが䜿甚するドキュメントチャンキングモヌドです。" + }, + "total": { + "type": "integer", + "description": "䞀臎するチャンクの合蚈数です。" + }, + "has_more": { + "type": "boolean", + "description": "次のペヌゞにさらに項目が存圚するかどうかです。" + }, + "limit": { + "type": "integer", + "description": "1 ペヌゞあたりの件数です。" + }, + "page": { + "type": "integer", + "description": "珟圚のペヌゞ番号です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model", + "total": 1, + "has_more": false, + "limit": 20, + "page": 1 + } + } } } } @@ -1267,54 +3040,146 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { - "patch": { + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { + "get": { "tags": [ "チャンク" ], - "summary": "子チャンクを曎新", - "description": "特定の子チャンクのコンテンツを曎新したす。", - "operationId": "updateChildChunk", + "summary": "ドキュメント内のチャンク詳现を取埗", + "description": "特定のチャンクの詳现情報内容、キヌワヌド、むンデックスステヌタスを含むを取埗したす。", + "operationId": "getChunkJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "芪セグメントのID。", "schema": { "type": "string", "format": "uuid" - } - }, - { - "name": "child_chunk_id", + }, + "description": "Chunk ID." + } + ], + "responses": { + "200": { + "description": "チャンクの詳现です。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "このドキュメントが䜿甚するドキュメントチャンキングモヌドです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } + } + } + } + } + } + }, + "post": { + "tags": [ + "チャンク" + ], + "summary": "ドキュメント内のチャンクを曎新", + "description": "チャンクのコンテンツ、キヌワヌド、たたは回答を曎新したす。倉曎されたチャンクのむンデックス䜜成が再トリガヌされたす。", + "operationId": "updateChunkJa", + "parameters": [ + { + "name": "dataset_id", "in": "path", "required": true, - "description": "曎新する子チャンクのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." } ], "requestBody": { @@ -1322,18 +3187,115 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateChildChunkRequest" + "type": "object", + "required": [ + "segment" + ], + "properties": { + "segment": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "チャンクのテキスト内容です。" + }, + "answer": { + "type": "string", + "description": "QA モヌドの回答内容です。" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "チャンクのキヌワヌドです。" + }, + "enabled": { + "type": "boolean", + "description": "チャンクが有効かどうかです。" + }, + "regenerate_child_chunks": { + "type": "boolean", + "default": false, + "description": "子チャンクを再生成するかどうかです。" + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "添付ファむル ID です。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "サマリヌむンデックスのサマリヌ内容です。" + } + }, + "description": "曎新するチャンクデヌタです。" + } + } } } } }, "responses": { "200": { - "description": "子チャンクの曎新に成功したした。", + "description": "チャンクが正垞に曎新されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "このドキュメントが䜿甚するドキュメントチャンキングモヌドです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } @@ -1344,66 +3306,88 @@ "tags": [ "チャンク" ], - "summary": "子チャンクを削陀", - "description": "特定の子チャンクを削陀したす。", - "operationId": "deleteChildChunk", + "summary": "ドキュメント内のチャンクを削陀", + "description": "ドキュメントからチャンクを完党に削陀したす。", + "operationId": "deleteChunkJa", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "ナレッゞベヌスのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "ナレッゞベヌス ID です。" }, { "name": "document_id", "in": "path", "required": true, - "description": "ドキュメントのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "芪セグメントのID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "child_chunk_id", - "in": "path", - "required": true, - "description": "削陀する子チャンクのID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Chunk ID." } ], "responses": { "204": { - "description": "子チャンクの削陀に成功したした。" + "description": "Success." } } } }, - "/datasets/tags": { + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { "post": { "tags": [ - "メタデヌタ・タグ" + "チャンク" + ], + "summary": "子チャンクを䜜成", + "description": "芪チャンクの䞋に子チャンクを䜜成したす。`hierarchical_model` チャンキングモヌドを䜿甚しおいるドキュメントでのみ利甚可胜です。", + "operationId": "createChildChunkJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + } ], - "summary": "新しいナレッゞベヌスタむプタグを䜜成", - "description": "ナレッゞベヌスを分類するために䜿甚できる新しいタグを䜜成したす。", - "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { @@ -1411,13 +3395,12 @@ "schema": { "type": "object", "required": [ - "name" + "content" ], "properties": { - "name": { + "content": { "type": "string", - "description": "新しいタグの名前。", - "maxLength": 50 + "description": "子チャンクのテキスト内容です。" } } } @@ -1426,33 +3409,49 @@ }, "responses": { "200": { - "description": "タグの䜜成に成功したした。", + "description": "子チャンクが正垞に䜜成されたした。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } } } } - } - } - }, - "get": { - "tags": [ - "メタデヌタ・タグ" - ], - "summary": "ナレッゞベヌスタむプタグを取埗", - "description": "利甚可胜なすべおのナレッゞベヌスタグのリストを取埗したす。", - "operationId": "getKnowledgeTags", - "responses": { - "200": { - "description": "タグのリスト。", + }, + "400": { + "description": "`invalid_param` : 子チャンクむンデックスの䜜成に倱敗したした。", "content": { "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Tag" + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } } } } @@ -1460,59 +3459,184 @@ } } }, - "patch": { + "get": { "tags": [ - "メタデヌタ・タグ" + "チャンク" ], - "summary": "ナレッゞベヌスタむプタグ名を倉曎", - "description": "既存のタグの名前を曎新したす。", - "operationId": "updateKnowledgeTag", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "tag_id", - "name" - ], - "properties": { - "tag_id": { - "type": "string", - "description": "倉曎するタグのID。", - "format": "uuid" - }, - "name": { - "type": "string", - "description": "タグの新しい名前。", - "maxLength": 50 - } - } - } - } + "summary": "子チャンクを取埗", + "description": "特定の芪チャンク配䞋の子チャンクのペヌゞネヌションリストを返したす。", + "operationId": "listChildChunksJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "Page number." + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1 + }, + "description": "1 ペヌゞあたりの項目数です。サヌバヌの䞊限は `100` です。" + }, + { + "name": "keyword", + "in": "query", + "schema": { + "type": "string" + }, + "description": "怜玢キヌワヌドです。" } - }, + ], "responses": { "200": { - "description": "タグの曎新に成功したした。", + "description": "子チャンクのリストです。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChildChunk" + } + }, + "total": { + "type": "integer", + "description": "子チャンクの合蚈数です。" + }, + "total_pages": { + "type": "integer", + "description": "合蚈ペヌゞ数です。" + }, + "page": { + "type": "integer", + "description": "珟圚のペヌゞ番号です。" + }, + "limit": { + "type": "integer", + "description": "1 ペヌゞあたりの件数です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": [ + { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + ], + "total": 1, + "total_pages": 1, + "page": 1, + "limit": 20 + } + } } } } } } - }, - "delete": { + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { + "patch": { "tags": [ - "メタデヌタ・タグ" + "チャンク" + ], + "summary": "子チャンクを曎新", + "description": "既存の子チャンクのコンテンツを曎新したす。", + "operationId": "updateChildChunkJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + }, + { + "name": "child_chunk_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "子チャンク ID です。" + } ], - "summary": "ナレッゞベヌスタむプタグを削陀", - "description": "タグを削陀したす。タグはどのナレッゞベヌスにもバむンドされおいない必芁がありたす。", - "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, "content": { @@ -1520,13 +3644,12 @@ "schema": { "type": "object", "required": [ - "tag_id" + "content" ], "properties": { - "tag_id": { + "content": { "type": "string", - "description": "削陀するタグのID。", - "format": "uuid" + "description": "子チャンクのテキスト内容です。" } } } @@ -1535,63 +3658,149 @@ }, "responses": { "200": { - "$ref": "#/components/responses/Success" + "description": "子チャンクが正垞に曎新されたした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 子チャンクむンデックスの曎新に倱敗したした。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } + } + } + } + } } } - } - }, - "/datasets/tags/binding": { - "post": { + }, + "delete": { "tags": [ - "メタデヌタ・タグ" + "チャンク" ], - "summary": "デヌタセットをナレッゞベヌスタむプタグにバむンド", - "description": "1぀たたは耇数のタグを特定のナレッゞベヌスにバむンドしたす。", - "operationId": "bindTagsToDataset", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "target_id", - "tag_ids" - ], - "properties": { - "target_id": { - "type": "string", - "description": "タグをバむンドするデヌタセットのID。", - "format": "uuid" - }, - "tag_ids": { - "type": "array", - "description": "バむンドするタグIDのリスト。", - "items": { - "type": "string", - "format": "uuid" + "summary": "子チャンクを削陀", + "description": "芪チャンクから子チャンクを完党に削陀したす。", + "operationId": "deleteChildChunkJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + }, + { + "name": "child_chunk_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "子チャンク ID です。" + } + ], + "responses": { + "204": { + "description": "Success." + }, + "400": { + "description": "`invalid_param` : 子チャンクむンデックスの削陀に倱敗したした。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Delete child chunk index failed: {error details}" } } } } } } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" - } } } }, - "/datasets/tags/unbinding": { + "/datasets/{dataset_id}/retrieve": { "post": { "tags": [ - "メタデヌタ・タグ" + "デヌタセット" + ], + "summary": "ナレッゞベヌスからチャンクを取埗 / テスト怜玢", + "description": "ナレッゞベヌスに察しお怜玢ク゚リを実行し、最も関連性の高いチャンクを取埗したす。この゚ンドポむントは本番環境の怜玢ずテスト怜玢の䞡方に䜿甚できたす。", + "operationId": "searchKnowledgeBaseJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + } ], - "summary": "デヌタセットずナレッゞベヌスタむプタグのバむンドを解陀", - "description": "ナレッゞベヌスから特定のタグのバむンドを解陀したす。", - "operationId": "unbindTagFromDataset", "requestBody": { "required": true, "content": { @@ -1599,19 +3808,43 @@ "schema": { "type": "object", "required": [ - "target_id", - "tag_id" + "query" ], "properties": { - "target_id": { + "query": { "type": "string", - "description": "デヌタセットのID。", - "format": "uuid" + "maxLength": 250, + "description": "怜玢ク゚リテキストです。" }, - "tag_id": { - "type": "string", - "description": "バむンドを解陀するタグのID。", - "format": "uuid" + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "怜玢モデルの蚭定です。このナレッゞベヌスをク゚リする際のチャンクの怜玢方法ずランキング方法を制埡したす。" + }, + "external_retrieval_model": { + "type": "object", + "description": "倖郚ナレッゞベヌスの怜玢蚭定です。", + "properties": { + "top_k": { + "type": "integer", + "description": "返す結果の最倧数です。" + }, + "score_threshold": { + "type": "number", + "description": "結果フィルタリング甚の最小関連性スコア閟倀です。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "スコア閟倀フィルタリングが有効かどうかです。" + } + } + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "怜玢コンテキストに含める添付ファむル ID のリストです。" } } } @@ -1620,1490 +3853,2787 @@ }, "responses": { "200": { - "$ref": "#/components/responses/Success" - } - } - } - }, - "/datasets/{dataset_id}/tags": { - "get": { - "tags": [ - "メタデヌタ・タグ" - ], - "summary": "デヌタセットにバむンドされたタグをク゚リ", - "description": "特定のデヌタセットに珟圚バむンドされおいるすべおのタグを取埗したす。", - "operationId": "queryDatasetTags", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "デヌタセットのID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "responses": { - "200": { - "description": "デヌタセットにバむンドされたタグのリスト。", + "description": "怜玢結果です。", "content": { "application/json": { "schema": { "type": "object", "properties": { - "data": { + "query": { + "type": "object", + "description": "元のク゚リオブゞェクトです。", + "properties": { + "content": { + "type": "string", + "description": "ク゚リテキストです。" + } + } + }, + "records": { "type": "array", "items": { "type": "object", "properties": { - "id": { - "type": "string", - "format": "uuid" + "segment": { + "type": "object", + "description": "ナレッゞベヌスから䞀臎したチャンクです。", + "properties": { + "id": { + "type": "string", + "description": "チャンクの䞀意識別子です。" + }, + "position": { + "type": "integer", + "description": "ドキュメント内のチャンクの䜍眮。" + }, + "document_id": { + "type": "string", + "description": "このチャンクが属するドキュメントの ID です。" + }, + "content": { + "type": "string", + "description": "チャンクのテキスト内容です。" + }, + "sign_content": { + "type": "string", + "description": "敎合性怜蚌甚の眲名付きコンテンツハッシュです。" + }, + "answer": { + "type": "string", + "description": "回答コンテンツです。Q&A モヌドのドキュメントで䜿甚されたす。" + }, + "word_count": { + "type": "integer", + "description": "チャンク内容の単語数です。" + }, + "tokens": { + "type": "integer", + "description": "チャンク内容のトヌクン数です。" + }, + "keywords": { + "type": "array", + "description": "キヌワヌドベヌスの怜玢のためにこのチャンクに関連付けられたキヌワヌドです。", + "items": { + "type": "string" + } + }, + "index_node_id": { + "type": "string", + "description": "ベクトルストア内のむンデックスノヌドの ID です。" + }, + "index_node_hash": { + "type": "string", + "description": "むンデックスされたコンテンツのハッシュです。倉曎の怜出に䜿甚されたす。" + }, + "hit_count": { + "type": "integer", + "description": "このチャンクが怜玢ク゚リでマッチした回数です。" + }, + "enabled": { + "type": "boolean", + "description": "このチャンクが怜玢に察しお有効かどうかです。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "チャンクが無効化されたタむムスタンプです。有効な堎合は `null` です。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "チャンクを無効化したナヌザヌの ID です。有効な堎合は `null` です。" + }, + "status": { + "type": "string", + "description": "チャンクのむンデックスステヌタスです。" + }, + "created_by": { + "type": "string", + "description": "チャンクを䜜成したナヌザヌの ID です。" + }, + "created_at": { + "type": "number", + "description": "䜜成タむムスタンプUnix ゚ポック、秒単䜍です。" + }, + "indexing_at": { + "type": "number", + "nullable": true, + "description": "むンデックス䜜成が開始されたタむムスタンプです。ただ開始されおいない堎合は `null` です。" + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "むンデックス䜜成が完了したタむムスタンプです。ただ完了しおいない堎合は `null` です。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "むンデックス䜜成が倱敗した堎合の゚ラヌメッセヌゞです。゚ラヌなしの堎合は `null` です。" + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "むンデックス䜜成が停止されたタむムスタンプです。停止されおいない堎合は `null` です。" + }, + "document": { + "type": "object", + "description": "マッチしたチャンクの芪ドキュメント情報です。", + "properties": { + "id": { + "type": "string", + "description": "ドキュメントの䞀意識別子です。" + }, + "data_source_type": { + "type": "string", + "description": "ドキュメントの䜜成方法です。" + }, + "name": { + "type": "string", + "description": "ドキュメント名です。" + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "ドキュメントタむプの分類です。未蚭定の堎合は `null` です。" + }, + "doc_metadata": { + "type": "object", + "nullable": true, + "description": "ドキュメントのメタデヌタ倀です。メタデヌタが蚭定されおいない堎合は `null` です。" + } + } + } + } }, - "name": { - "type": "string" + "child_chunks": { + "type": "array", + "description": "階局むンデックスを䜿甚しおいる堎合、チャンク内でマッチした子チャンクです。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "子チャンクの䞀意識別子です。" + }, + "content": { + "type": "string", + "description": "子チャンクのテキスト内容です。" + }, + "position": { + "type": "integer", + "description": "芪チャンク内の子チャンクの䜍眮です。" + }, + "score": { + "type": "number", + "description": "子チャンクの関連性スコアです。" + } + } + } + }, + "score": { + "type": "number", + "description": "関連性スコアです。" + }, + "tsne_position": { + "type": "object", + "nullable": true, + "description": "t-SNE 可芖化の䜍眮です。" + }, + "files": { + "type": "array", + "description": "このチャンクに添付されたファむルです。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "添付ファむルの識別子です。" + }, + "name": { + "type": "string", + "description": "元のファむル名です。" + }, + "size": { + "type": "integer", + "description": "ファむルサむズバむト。" + }, + "extension": { + "type": "string", + "description": "ファむル拡匵子。" + }, + "mime_type": { + "type": "string", + "description": "ファむルの MIME タむプ。" + }, + "source_url": { + "type": "string", + "description": "添付ファむルにアクセスする URL です。" + } + } + } + }, + "summary": { + "type": "string", + "nullable": true, + "description": "芁玄むンデックス経由で取埗された堎合の芁玄コンテンツです。" } } } - }, - "total": { - "type": "integer" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "query": { + "content": "What is Dify?" + }, + "records": [ + { + "segment": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 1, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "data_source_type": "upload_file", + "name": "guide.txt", + "doc_type": null, + "doc_metadata": null + } + }, + "child_chunks": [], + "score": 0.92, + "tsne_position": null, + "files": [], + "summary": null + } + ] } } } } } - } - } - } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "API_KEY", - "description": "APIキヌ認蚌。すべおのAPIリク゚ストにおいお、Authorization HTTPヘッダヌにAPIキヌを含めおください。圢匏Bearer {API_KEY}。**APIキヌの挏掩を防ぐため、APIキヌはクラむアント偎で共有たたは保存せず、サヌバヌ偎で保存するこずを匷くお勧めしたす。**" - } - }, - "responses": { - "Success": { - "description": "操䜜に成功したした。", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" - } - } - } - } - } - }, - "FileError": { - "description": "ファむルアップロヌドに関連する䞍正なリク゚スト。`no_file_uploaded` たたは `too_many_files` の可胜性がありたす。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" + }, + "400": { + "description": "- `dataset_not_initialized` : ナレッゞベヌスはただ初期化䞭たたはむンデキシング䞭です。しばらくお埅ちください。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。蚭定 → モデルプロバむダヌで認蚌情報を完了しおください。\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "dataset_not_initialized": { + "summary": "dataset_not_initialized", + "value": { + "status": 400, + "code": "dataset_not_initialized", + "message": "The dataset is still being initialized or indexing. Please wait a moment." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Invalid parameter value." + } + } + } + } } - } - } - }, - "FileTooLarge": { - "description": "ファむルサむズが䞊限を超えたした。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" + }, + "403": { + "description": "`forbidden` : 暩限が䞍足しおいたす。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } } - } - } - }, - "UnsupportedFileType": { - "description": "ファむルタむプが蚱可されおいたせん。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" + }, + "404": { + "description": "`not_found` : ナレッゞベヌスが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } } - } - } - }, - "DatasetNameDuplicate": { - "description": "デヌタセット名が既に存圚したす。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" + }, + "500": { + "description": "`internal_server_error` : 怜玢䞭に内郚゚ラヌが発生したした。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "An internal error occurred." + } + } + } + } } } } } }, - "schemas": { - "ErrorResponse": { - "type": "object", - "properties": { - "code": { - "type": "string", - "description": "機械読み取り可胜な゚ラヌコヌド。" - }, - "message": { - "type": "string", - "description": "人間が読める゚ラヌメッセヌゞ。" - }, - "status": { - "type": "integer", - "description": "HTTPステヌタスコヌド。" + "/datasets/tags": { + "post": { + "tags": [ + "タグ管理" + ], + "summary": "ナレッゞベヌスタグを䜜成", + "description": "ナレッゞベヌスを敎理するための新しいタグを䜜成したす。", + "operationId": "createKnowledgeTagJa", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "Tag name." + } + } + } + } } }, - "example": { - "code": "no_file_uploaded", - "message": "ファむルをアップロヌドしおください。", - "status": 400 + "responses": { + "200": { + "description": "タグが正垞に䜜成されたした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "タグ識別子です。" + }, + "name": { + "type": "string", + "description": "タグの衚瀺名です。" + }, + "type": { + "type": "string", + "description": "タグタむプです。ナレッゞベヌスタグの堎合は垞に `knowledge` です。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "このタグにバむンドされたナレッゞベヌスの数です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } + } + } + } + } } }, - "RetrievalModel": { - "type": "object", - "properties": { - "search_method": { - "type": "string", - "description": "取埗に䜿甚する怜玢方法。", - "enum": [ - "hybrid_search", - "semantic_search", - "full_text_search", - "keyword_search" - ] - }, - "reranking_enable": { - "type": "boolean", - "description": "怜玢結果を改善するためのリランキングモデルを有効にするかどうか。" - }, - "reranking_mode": { - "type": "string", - "description": "リランキングモヌド。", - "default": "reranking_model", - "enum": [ - "reranking_model", - "weighted_score" - ] - }, - "reranking_model": { - "type": "object", - "description": "リランキングモデルの蚭定。", - "properties": { - "reranking_provider_name": { - "type": "string", - "description": "リランクモデルのプロバむダヌ。" - }, - "reranking_model_name": { - "type": "string", - "description": "リランクモデルの名前。" + "get": { + "tags": [ + "タグ管理" + ], + "summary": "ナレッゞベヌスタグリストを取埗", + "description": "ワヌクスペヌス内のすべおのナレッゞベヌスタグのリストを返したす。", + "operationId": "listKnowledgeTagsJa", + "responses": { + "200": { + "description": "タグのリストです。", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "タグ識別子です。" + }, + "name": { + "type": "string", + "description": "タグの衚瀺名です。" + }, + "type": { + "type": "string", + "description": "タグタむプです。ナレッゞベヌスタグの堎合は垞に `knowledge` です。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "このタグにバむンドされたナレッゞベヌスの数です。" + } + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + ] + } + } } - }, - "nullable": true - }, - "top_k": { - "type": "integer", - "description": "返すトップマッチング結果の数。" - }, - "score_threshold_enabled": { - "type": "boolean", - "description": "結果をフィルタするためのスコア閟倀を適甚するかどうか。" - }, - "score_threshold": { - "type": "number", - "format": "float", - "description": "結果に含たれる最小スコア。", - "nullable": true - }, - "weights": { - "type": "number", - "format": "float", - "description": "ハむブリッド怜玢モヌドでのセマンティック怜玢の重み。", - "nullable": true + } } } }, - "SummaryIndexSetting": { - "type": "object", - "description": "芁玄自動生成の蚭定。", - "properties": { - "enable": { - "type": "boolean", - "description": "芁玄自動生成を有効にするかどうか。" - }, - "model_name": { - "type": "string", - "description": "芁玄生成に䜿甚するモデル名。" - }, - "model_provider_name": { - "type": "string", - "description": "芁玄モデルのプロバむダヌ。" - }, - "summary_prompt": { - "type": "string", - "description": "芁玄生成に䜿甚するプロンプトテンプレヌト。" + "patch": { + "tags": [ + "タグ管理" + ], + "summary": "ナレッゞベヌスタグを倉曎", + "description": "既存のナレッゞベヌスタグの名前を倉曎したす。", + "operationId": "updateKnowledgeTagJa", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_id", + "name" + ], + "properties": { + "tag_id": { + "type": "string", + "description": "曎新するタグ ID です。" + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "新しいタグ名です。" + } + } + } + } } }, - "required": [ - "enable" - ] - }, - "PreprocessingRule": { - "type": "object", - "description": "ドキュメントコンテンツの前凊理ルヌル。", - "properties": { - "id": { - "type": "string", - "description": "前凊理ルヌルの䞀意識別子。", - "enum": [ - "remove_extra_spaces", - "remove_urls_emails" - ] - }, - "enabled": { - "type": "boolean", - "description": "このルヌルが有効かどうか。" - } - } - }, - "SegmentationRule": { - "type": "object", - "description": "ドキュメントコンテンツをチャンクにセグメント化するためのルヌル。", - "properties": { - "separator": { - "type": "string", - "description": "セグメントを分離するために䜿甚するカスタム区切り文字。" - }, - "max_tokens": { - "type": "integer", - "description": "単䞀セグメントで蚱可される最倧トヌクン数。" + "responses": { + "200": { + "description": "タグが正垞に曎新されたした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "タグ識別子です。" + }, + "name": { + "type": "string", + "description": "タグの衚瀺名です。" + }, + "type": { + "type": "string", + "description": "タグタむプです。ナレッゞベヌスタグの堎合は垞に `knowledge` です。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "このタグにバむンドされたナレッゞベヌスの数です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } + } + } + } } } }, - "SubChunkSegmentationRule": { - "type": "object", - "description": "芪チャンクを小さな子チャンクにセグメント化するためのルヌル階局モヌド甚。", - "properties": { - "separator": { - "type": "string", - "description": "サブチャンク化の区切り文字。" - }, - "max_tokens": { - "type": "integer", - "description": "サブチャンクの最倧トヌクン長。" - }, - "chunk_overlap": { - "type": "integer", - "description": "隣接するサブチャンク間の重耇トヌクン数。" - } - } - }, - "ProcessRule": { - "type": "object", - "description": "クリヌニングずセグメント化を含む、ドキュメントを凊理するためのルヌルセット。", - "properties": { - "mode": { - "type": "string", - "description": "凊理モヌドautomatic、custom、たたはhierarchical。", - "enum": [ - "automatic", - "custom", - "hierarchical" - ] - }, - "rules": { - "type": "object", - "description": "適甚する特定のルヌル、モヌドが'custom'たたは'hierarchical'の堎合に䜿甚。", - "properties": { - "pre_processing_rules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PreprocessingRule" + "delete": { + "tags": [ + "タグ管理" + ], + "summary": "ナレッゞベヌスタグを削陀", + "description": "ナレッゞベヌスタグを完党に削陀したす。タグ付けされたナレッゞベヌス自䜓は削陀されたせん。", + "operationId": "deleteKnowledgeTagJa", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_id" + ], + "properties": { + "tag_id": { + "type": "string", + "description": "削陀するタグ ID です。" + } } - }, - "segmentation": { - "$ref": "#/components/schemas/SegmentationRule" - }, - "parent_mode": { - "type": "string", - "description": "階局モヌドでの芪チャンクの取埗モヌド。", - "enum": [ - "full-doc", - "paragraph" - ] - }, - "subchunk_segmentation": { - "$ref": "#/components/schemas/SubChunkSegmentationRule" } - }, - "nullable": true + } } - } - }, - "CreateDocumentByTextRequest": { - "type": "object", - "required": [ - "name", - "text" - ], - "properties": { - "name": { - "type": "string", - "description": "ドキュメントの名前。" - }, - "text": { - "type": "string", - "description": "ドキュメントの完党なテキストコンテンツ。" - }, - "indexing_technique": { - "type": "string", - "description": "ドキュメントのむンデックス化技術。", - "enum": [ - "high_quality", - "economy" - ] - }, - "doc_form": { - "type": "string", - "description": "むンデックス化されたコンテンツの圢匏。", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] - }, - "doc_language": { - "type": "string", - "description": "ドキュメントの蚀語、Q&Aモヌドで重芁。", - "example": "Japanese" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { - "type": "string", - "description": "䜿甚する埋め蟌みモデルの名前。" - }, - "embedding_model_provider": { - "type": "string", - "description": "埋め蟌みモデルのプロバむダヌ。" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "芁玄自動生成の蚭定。" + }, + "responses": { + "204": { + "description": "Success." } } - }, - "CreateDocumentByFileRequestData": { - "type": "object", - "description": "ファむルからドキュメントを䜜成するためのメタデヌタずルヌル。", - "properties": { - "original_document_id": { - "type": "string", - "description": "再アップロヌドたたは修正する既存のドキュメントのID。", - "format": "uuid" - }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] - }, - "doc_form": { - "type": "string", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] - }, - "doc_language": { - "type": "string", - "example": "Japanese" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { - "type": "string" - }, - "embedding_model_provider": { - "type": "string" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "芁玄自動生成の蚭定。" + } + }, + "/datasets/tags/binding": { + "post": { + "tags": [ + "タグ管理" + ], + "summary": "タグをデヌタセットにバむンド", + "description": "ナレッゞベヌスに 1 ぀以䞊のタグをバむンドしたす。ナレッゞベヌスには耇数のタグを蚭定できたす。", + "operationId": "bindKnowledgeTagsJa", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_ids", + "target_id" + ], + "properties": { + "tag_ids": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "description": "バむンドするタグ ID です。" + }, + "target_id": { + "type": "string", + "description": "ナレッゞベヌス ID です。" + } + } + } + } } - } - }, - "UpdateDocumentByTextRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "ドキュメントの新しい名前オプション。" - }, - "text": { - "type": "string", - "description": "ドキュメントの新しいテキストコンテンツオプション。" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + }, + "responses": { + "204": { + "description": "Success." } } - }, - "UpdateDocumentByFileRequestData": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "ドキュメントの新しい名前オプション。" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + } + }, + "/datasets/tags/unbinding": { + "post": { + "tags": [ + "タグ管理" + ], + "summary": "タグずデヌタセットのバむンドを解陀", + "description": "ナレッゞベヌスからタグバむンディングを削陀したす。", + "operationId": "unbindKnowledgeTagJa", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_id", + "target_id" + ], + "properties": { + "tag_id": { + "type": "string", + "description": "バむンド解陀するタグ ID です。" + }, + "target_id": { + "type": "string", + "description": "ナレッゞベヌス ID です。" + } + } + } + } } - } - }, - "Document": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "position": { - "type": "integer" - }, - "data_source_type": { - "type": "string" - }, - "data_source_info": { - "type": "object", - "nullable": true - }, - "dataset_process_rule_id": { - "type": "string", - "format": "uuid", - "nullable": true - }, - "name": { - "type": "string" - }, - "created_from": { - "type": "string" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - }, - "tokens": { - "type": "integer" - }, - "indexing_status": { - "type": "string" - }, - "error": { - "type": "string", - "nullable": true - }, - "enabled": { - "type": "boolean" - }, - "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true - }, - "disabled_by": { - "type": "string", - "format": "uuid", - "nullable": true - }, - "archived": { - "type": "boolean" - }, - "display_status": { - "type": "string" - }, - "word_count": { - "type": "integer" - }, - "hit_count": { - "type": "integer" - }, - "doc_form": { - "type": "string" + }, + "responses": { + "204": { + "description": "Success." } } - }, - "DocumentCreationResponse": { - "type": "object", - "properties": { - "document": { - "$ref": "#/components/schemas/Document" - }, - "batch": { - "type": "string", - "description": "むンデックス化の進捗を远跡するためのバッチ識別子。" + } + }, + "/datasets/{dataset_id}/tags": { + "get": { + "tags": [ + "タグ管理" + ], + "summary": "ナレッゞベヌスにバむンドされたタグを取埗", + "description": "特定のナレッゞベヌスにバむンドされたタグのリストを返したす。", + "operationId": "getKnowledgeBaseTagsJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" } - } - }, - "CreateDatasetRequest": { - "type": "object", - "required": [ - "name" ], - "properties": { - "name": { - "type": "string", - "description": "ナレッゞベヌスの名前。" - }, - "description": { - "type": "string", - "description": "ナレッゞベヌスの説明オプション。" - }, - "indexing_technique": { - "type": "string", - "description": "䜿甚するむンデックス化技術。", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "description": "ナレッゞベヌスのアクセス暩限。", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "provider": { - "type": "string", - "description": "ナレッゞベヌスのプロバむダヌ。", - "enum": [ - "vendor", - "external" - ] - }, - "external_knowledge_api_id": { - "type": "string", - "description": "倖郚ナレッゞAPIのIDプロバむダヌが'external'の堎合。" - }, - "external_knowledge_id": { - "type": "string", - "description": "倖郚ナレッゞのIDプロバむダヌが'external'の堎合。" - }, - "embedding_model": { - "type": "string", - "description": "埋め蟌みモデルの名前。" + "responses": { + "200": { + "description": "ナレッゞベヌスにバむンドされたタグです。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "タグ識別子です。" + }, + "name": { + "type": "string", + "description": "タグの衚瀺名です。" + } + } + } + }, + "total": { + "type": "integer", + "description": "このナレッゞベヌスにバむンドされたタグの合蚈数です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs" + } + ], + "total": 1 + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata": { + "post": { + "tags": [ + "メタデヌタ" + ], + "summary": "メタデヌタフィヌルドを䜜成", + "description": "ナレッゞベヌスのカスタムメタデヌタフィヌルドを䜜成したす。メタデヌタフィヌルドを䜿甚しお、構造化された情報でドキュメントにアノテヌションを付けるこずができたす。", + "operationId": "createMetadataFieldJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "string", + "number", + "time" + ], + "description": "`string` はテキスト倀、`number` は数倀、`time` は日付/時刻倀です。" + }, + "name": { + "type": "string", + "description": "メタデヌタフィヌルド名です。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "メタデヌタフィヌルドが正垞に䜜成されたした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデヌタフィヌルドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデヌタフィヌルド名です。" + }, + "type": { + "type": "string", + "description": "メタデヌタフィヌルドの皮類です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "get": { + "tags": [ + "メタデヌタ" + ], + "summary": "メタデヌタフィヌルドリストを取埗", + "description": "ナレッゞベヌスのすべおのメタデヌタフィヌルドカスタムおよび組み蟌みの䞡方の䞀芧ず、各フィヌルドを䜿甚しおいるドキュメント数を返したす。", + "operationId": "listMetadataFieldsJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + } + ], + "responses": { + "200": { + "description": "ナレッゞベヌスのメタデヌタフィヌルドです。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデヌタフィヌルドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデヌタフィヌルド名です。" + }, + "type": { + "type": "string", + "description": "メタデヌタフィヌルドの皮類です。" + }, + "count": { + "type": "integer", + "description": "このメタデヌタフィヌルドを䜿甚しおいるドキュメント数です。" + } + } + } + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "このナレッゞベヌスで組み蟌みメタデヌタフィヌルドが有効かどうかです。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "doc_metadata": [ + { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string", + "count": 3 + } + ], + "built_in_field_enabled": true + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/{metadata_id}": { + "patch": { + "tags": [ + "メタデヌタ" + ], + "summary": "メタデヌタフィヌルドを曎新", + "description": "カスタムメタデヌタフィヌルドの名前を倉曎したす。", + "operationId": "updateMetadataFieldJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" }, - "embedding_model_provider": { - "type": "string", - "description": "埋め蟌みモデルのプロバむダヌ。" + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "メタデヌタフィヌルド ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "新しいメタデヌタフィヌルド名です。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "メタデヌタフィヌルドが正垞に曎新されたした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデヌタフィヌルドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデヌタフィヌルド名です。" + }, + "type": { + "type": "string", + "description": "メタデヌタフィヌルドの皮類です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "delete": { + "tags": [ + "メタデヌタ" + ], + "summary": "メタデヌタフィヌルドを削陀", + "description": "カスタムメタデヌタフィヌルドを完党に削陀したす。このフィヌルドを䜿甚しおいるドキュメントは、該圓するメタデヌタ倀を倱いたす。", + "operationId": "deleteMetadataFieldJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "メタデヌタフィヌルド ID です。" + } + ], + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in": { + "get": { + "tags": [ + "メタデヌタ" + ], + "summary": "組み蟌みメタデヌタフィヌルドを取埗", + "description": "システムが提䟛する組み蟌みメタデヌタフィヌルドの䞀芧を返したす䟋ドキュメントタむプ、゜ヌス URL。", + "operationId": "getBuiltInMetadataFieldsJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + } + ], + "responses": { + "200": { + "description": "組み蟌みメタデヌタフィヌルドです。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "fields": { + "type": "array", + "description": "システム提䟛のメタデヌタフィヌルドのリストです。", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "組み蟌みフィヌルド識別子です。`document_name` はドキュメントタむトル、`uploader` は䜜成者、`upload_date` は䜜成日時、`last_update_date` は最終曎新日時、`source` はドキュメントの出兞を瀺したす。" + }, + "type": { + "type": "string", + "description": "フィヌルドのデヌタ型です。テキスト倀の堎合は `string`、日時倀の堎合は `time` です。" + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "fields": [ + { + "name": "document_name", + "type": "string" + }, + { + "name": "uploader", + "type": "string" + }, + { + "name": "upload_date", + "type": "time" + }, + { + "name": "last_update_date", + "type": "time" + }, + { + "name": "source", + "type": "string" + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in/{action}": { + "post": { + "tags": [ + "メタデヌタ" + ], + "summary": "組み蟌みメタデヌタフィヌルドを曎新", + "description": "ナレッゞベヌスの組み蟌みメタデヌタフィヌルドを有効たたは無効にしたす。", + "operationId": "toggleBuiltInMetadataFieldJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "芁玄自動生成の蚭定。" + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + }, + "description": "`enable` で内蔵メタデヌタフィヌルドを有効化、`disable` で無効化したす。" + } + ], + "responses": { + "200": { + "description": "組み蟌みメタデヌタフィヌルドの切り替えに成功したした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操䜜結果です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/metadata": { + "post": { + "tags": [ + "メタデヌタ" + ], + "summary": "ドキュメントメタデヌタを䞀括曎新", + "description": "耇数のドキュメントのメタデヌタ倀を䞀括曎新したす。リク゚スト内の各ドキュメントに指定されたメタデヌタのキヌず倀のペアが適甚されたす。", + "operationId": "batchUpdateDocumentMetadataJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "operation_data" + ], + "properties": { + "operation_data": { + "type": "array", + "items": { + "type": "object", + "required": [ + "document_id", + "metadata_list" + ], + "properties": { + "document_id": { + "type": "string", + "description": "メタデヌタを曎新するドキュメントの ID です。" + }, + "metadata_list": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { + "type": "string", + "description": "メタデヌタフィヌルド ID です。" + }, + "name": { + "type": "string", + "description": "メタデヌタフィヌルド名です。" + }, + "value": { + "description": "メタデヌタ倀。文字列、数倀、たたは `null` を指定できたす。" + } + } + } + }, + "partial_update": { + "type": "boolean", + "default": false, + "description": "メタデヌタを郚分的に曎新し、未指定フィヌルドの既存の倀を保持するかどうかです。" + } + } + }, + "description": "ドキュメントメタデヌタの曎新操䜜の配列です。各゚ントリはドキュメント ID をメタデヌタのキヌず倀のペアにマッピングしたす。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "ドキュメントメタデヌタが正垞に曎新されたした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操䜜結果です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "result": "success" + } + } + } + } + } } } - }, - "Dataset": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string", - "nullable": true - }, - "provider": { - "type": "string" - }, - "permission": { - "type": "string" - }, - "data_source_type": { - "type": "string", - "nullable": true - }, - "indexing_technique": { - "type": "string", - "nullable": true - }, - "app_count": { - "type": "integer" - }, - "document_count": { - "type": "integer" - }, - "word_count": { - "type": "integer" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - }, - "updated_by": { - "type": "string", - "format": "uuid" - }, - "updated_at": { - "type": "integer", - "format": "int64" - }, - "embedding_model": { - "type": "string", - "nullable": true + } + }, + "/workspaces/current/models/model-types/{model_type}": { + "get": { + "tags": [ + "モデル" + ], + "summary": "利甚可胜なモデルを取埗", + "description": "タむプ別に利甚可胜なモデルの䞀芧を取埗したす。䞻にナレッゞベヌス蚭定甚の `text-embedding` モデルず `rerank` モデルのク゚リに䜿甚したす。", + "operationId": "getAvailableModelsJa", + "parameters": [ + { + "name": "model_type", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "text-embedding", + "rerank", + "llm", + "tts", + "speech2text", + "moderation" + ] + }, + "description": "取埗するモデルのタむプです。ナレッゞベヌスの蚭定には、埋め蟌みモデルの堎合は `text-embedding`、リランキングモデルの堎合は `rerank` を䜿甚したす。" + } + ], + "responses": { + "200": { + "description": "指定された皮類で利甚可胜なモデルです。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "利甚可胜なモデルを持぀モデルプロバむダヌのリストです。", + "items": { + "type": "object", + "properties": { + "provider": { + "type": "string", + "description": "モデルプロバむダヌの識別子です䟋`openai`、`cohere`。" + }, + "label": { + "type": "object", + "description": "プロバむダヌのロヌカラむズ衚瀺名です。", + "properties": { + "en_US": { + "type": "string" + }, + "zh_Hans": { + "type": "string" + } + } + }, + "icon_small": { + "type": "object", + "description": "プロバむダヌの小アむコンの URL です。", + "properties": { + "en_US": { + "type": "string" + } + } + }, + "icon_large": { + "type": "object", + "description": "プロバむダヌの倧アむコンの URL です。", + "properties": { + "en_US": { + "type": "string" + } + } + }, + "status": { + "type": "string", + "description": "プロバむダヌのステヌタスです。認蚌情報が蚭定枈みで有効な堎合は `active` です。" + }, + "models": { + "type": "array", + "description": "このプロバむダヌから利甚可胜なモデルのリストです。", + "items": { + "type": "object", + "properties": { + "model": { + "type": "string", + "description": "モデル識別子です。ナレッゞベヌスの䜜成たたは曎新時に `embedding_model` の倀ずしお䜿甚したす。" + }, + "label": { + "type": "object", + "description": "モデルのロヌカラむズ衚瀺名です。", + "properties": { + "en_US": { + "type": "string" + }, + "zh_Hans": { + "type": "string" + } + } + }, + "model_type": { + "type": "string", + "description": "モデルのタむプです。`model_type` パスパラメヌタず䞀臎したす。" + }, + "features": { + "type": "array", + "nullable": true, + "description": "モデルがサポヌトする機胜です。なしの堎合は `null` です。", + "items": { + "type": "string" + } + }, + "fetch_from": { + "type": "string", + "description": "モデル定矩の取埗元です。`predefined-model` は組み蟌みモデル、`customizable-model` はナヌザヌ蚭定モデルを瀺したす。" + }, + "model_properties": { + "type": "object", + "description": "`context_size` などのモデル固有のプロパティです。" + }, + "status": { + "type": "string", + "description": "モデルの利甚可胜ステヌタスです。䜿甚可胜な堎合は `active` です。" + } + } + } + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "data": [ + { + "provider": "openai", + "label": { + "en_US": "OpenAI", + "zh_Hans": "OpenAI" + }, + "icon_small": { + "en_US": "https://example.com/openai-small.svg" + }, + "icon_large": { + "en_US": "https://example.com/openai-large.svg" + }, + "status": "active", + "models": [ + { + "model": "text-embedding-3-small", + "label": { + "en_US": "text-embedding-3-small", + "zh_Hans": "text-embedding-3-small" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8191 + }, + "status": "active" + } + ] + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/pipeline/file-upload": { + "post": { + "tags": [ + "ナレッゞパむプラむン" + ], + "summary": "パむプラむンファむルをアップロヌド", + "description": "ナレッゞパむプラむンで䜿甚するファむルをアップロヌドしたす。`multipart/form-data` で単䞀ファむルを受け付けたす。", + "operationId": "uploadPipelineFileJa", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "アップロヌドするファむルです。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "ファむルが正垞にアップロヌドされたした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "アップロヌドされたファむルの䞀意識別子です。" + }, + "name": { + "type": "string", + "description": "元のファむル名です。" + }, + "size": { + "type": "integer", + "description": "ファむルサむズバむト。" + }, + "extension": { + "type": "string", + "description": "ファむル拡匵子。" + }, + "mime_type": { + "type": "string", + "description": "ファむルの MIME タむプ。" + }, + "created_by": { + "type": "string", + "description": "ファむルをアップロヌドしたナヌザヌの ID。" + }, + "created_at": { + "type": "string", + "description": "アップロヌドタむムスタンプISO 8601 圢匏です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "report.pdf", + "size": 524288, + "extension": "pdf", + "mime_type": "application/pdf", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": "2025-03-06T12:00:00" + } + } + } + } + } }, - "embedding_model_provider": { - "type": "string", - "nullable": true + "400": { + "description": "- `no_file_uploaded` : ファむルをアップロヌドしおください。\n- `filename_not_exists_error` : 指定されたファむル名が存圚したせん。\n- `too_many_files` : ファむルは 1 ぀のみ蚱可されおいたす。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + } + } + } + } }, - "embedding_available": { - "type": "boolean", - "nullable": true + "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." + } + } + } + } + } }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "このデヌタセットの芁玄自動生成蚭定。", - "nullable": true + "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." + } + } + } + } + } } } - }, - "DatasetListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Dataset" + } + }, + "/datasets/{dataset_id}/pipeline/datasource-plugins": { + "get": { + "tags": [ + "ナレッゞパむプラむン" + ], + "summary": "デヌタ゜ヌスプラグむンリストを取埗", + "description": "ナレッゞパむプラむンで利甚可胜なすべおのデヌタ゜ヌスプラグむンを䞀芧衚瀺したす。`is_published` ク゚リパラメヌタに応じお公開枈みたたはドラフトのプラグむンを返したす。", + "operationId": "listDatasourcePluginsJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" + }, + { + "name": "is_published", + "in": "query", + "schema": { + "type": "boolean", + "default": true + }, + "description": "公開枈みたたはドラフトのデヌタ゜ヌスプラグむンのどちらを取埗するかを指定したす。`true` は公開枈みプラグむン、`false` はドラフトプラグむンを返したす。" + } + ], + "responses": { + "200": { + "description": "デヌタ゜ヌスプラグむンのリストです。", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "デヌタ゜ヌスプラグむンの䞀意の識別子です。" + }, + "name": { + "type": "string", + "description": "デヌタ゜ヌスプラグむンの衚瀺名です。" + }, + "type": { + "type": "string", + "description": "デヌタ゜ヌスプラグむンの皮類です。" + } + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": [ + { + "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", + "name": "Web Scraper", + "type": "online_document" + } + ] + } + } + } } }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" + "404": { + "description": "`not_found` : ナレッゞベヌスが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } - }, - "DatasetDetail": { - "allOf": [ + } + }, + "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": { + "post": { + "tags": [ + "ナレッゞパむプラむン" + ], + "summary": "デヌタ゜ヌスノヌドを実行", + "description": "ナレッゞパむプラむン内の単䞀のデヌタ゜ヌスノヌドを実行したす。ノヌドの実行結果を含むストリヌミングレスポンスを返したす。", + "operationId": "runDatasourceNodeJa", + "parameters": [ { - "$ref": "#/components/schemas/Dataset" + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" }, { - "type": "object", - "properties": { - "retrieval_model_dict": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "tags": { - "type": "array", - "items": { - "type": "object" + "name": "node_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "実行するデヌタ゜ヌスノヌドの ID です。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "is_published" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "デヌタ゜ヌスノヌドの入力倉数です。" + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "デヌタ゜ヌスの皮類です。" + }, + "credential_id": { + "type": "string", + "nullable": true, + "description": "デヌタ゜ヌスずの認蚌に䜿甚する認蚌情報の ID です。" + }, + "is_published": { + "type": "boolean", + "description": "ノヌドの公開バヌゞョンずドラフトバヌゞョンのどちらを実行するかを指定したす。`true` は公開バヌゞョン、`false` はドラフトを実行したす。" + } } - }, - "doc_form": { - "type": "string", - "nullable": true } } } - ] - }, - "UpdateDatasetRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "ナレッゞベヌスの新しい名前。" - }, - "description": { - "type": "string", - "description": "ナレッゞベヌスの新しい説明。" - }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "embedding_model_provider": { - "type": "string" - }, - "embedding_model": { - "type": "string" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "partial_member_list": { - "type": "array", - "description": "'partial_members'暩限でアクセスできるメンバヌのリスト。", - "items": { - "type": "object", - "required": [ - "user_id" - ], - "properties": { - "user_id": { + }, + "responses": { + "200": { + "description": "ノヌド実行むベントを含むストリヌミングレスポンスです。", + "content": { + "text/event-stream": { + "schema": { "type": "string", - "description": "メンバヌのナヌザヌID。" + "description": "ノヌド実行の進捗ず結果を含む Server-Sent Events ストリヌムです。" } } } }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "芁玄自動生成の蚭定。" + "404": { + "description": "`not_found` : ナレッゞベヌスが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } - }, - "IndexingStatus": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "indexing_status": { - "type": "string" - }, - "processing_started_at": { - "type": "number", - "format": "float" - }, - "parsing_completed_at": { - "type": "number", - "format": "float" - }, - "cleaning_completed_at": { - "type": "number", - "format": "float" - }, - "splitting_completed_at": { - "type": "number", - "format": "float" - }, - "completed_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "paused_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "error": { - "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "completed_segments": { - "type": "integer" - }, - "total_segments": { - "type": "integer" + } + }, + "/datasets/{dataset_id}/pipeline/run": { + "post": { + "tags": [ + "ナレッゞパむプラむン" + ], + "summary": "パむプラむンを実行", + "description": "ナレッゞベヌスの完党なナレッゞパむプラむンを実行したす。ストリヌミングずブロッキングの䞡方のレスポンスモヌドをサポヌトしおいたす。", + "operationId": "runPipelineJa", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "ナレッゞベヌス ID です。" } - } - }, - "DocumentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "datasource_info_list", + "start_node_id", + "is_published", + "response_mode" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "パむプラむンの入力倉数です。" + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "デヌタ゜ヌスの皮類です。" + }, + "datasource_info_list": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "パむプラむンが凊理するデヌタ゜ヌス情報オブゞェクトのリストです。" + }, + "start_node_id": { + "type": "string", + "description": "パむプラむン実行を開始するノヌドの ID です。" + }, + "is_published": { + "type": "boolean", + "description": "パむプラむンの公開バヌゞョンずドラフトバヌゞョンのどちらを実行するかを指定したす。`true` は公開バヌゞョン、`false` はドラフトを実行したす。" + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "パむプラむン実行のレスポンスモヌドです。`streaming` はサヌバヌ送信むベントストリヌムを返し、`blocking` は完了を埅っお完党な結果を返したす。" + } + } + } } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" } - } - }, - "DocumentDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Document" - }, - { - "type": "object", - "properties": { - "dataset_process_rule": { - "$ref": "#/components/schemas/ProcessRule" + }, + "responses": { + "200": { + "description": "パむプラむン実行結果。フォヌマットは `response_mode` に䟝存したすストリヌミングは `text/event-stream` を返し、ブロッキングは完党な JSON 結果を返したす。", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "パむプラむン実行の進捗ず結果を含むサヌバヌ送信むベントストリヌムです。`response_mode` が `streaming` の堎合に返されたす。" + } }, - "document_process_rule": { - "allOf": [ - { - "$ref": "#/components/schemas/ProcessRule" - }, - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "dataset_id": { - "type": "string" + "application/json": { + "schema": { + "type": "object", + "description": "パむプラむン実行の完党な結果です。`response_mode` が `blocking` の堎合に返されたす。", + "additionalProperties": true + }, + "examples": { + "success": { + "summary": "Blocking Response Example", + "value": { + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "data": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "status": "succeeded", + "outputs": {}, + "created_at": 1741267200, + "finished_at": 1741267210 } } } - ] - }, - "indexing_latency": { - "type": "number", - "format": "float", - "nullable": true - }, - "segment_count": { - "type": "integer" - }, - "average_segment_length": { - "type": "integer" - }, - "doc_language": { - "type": "string", - "nullable": true + } + } + } + }, + "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": "Dataset not found." + } + } + } + } + } + }, + "500": { + "description": "`pipeline_run_error` : パむプラむン実行に倱敗したした。", + "content": { + "application/json": { + "examples": { + "pipeline_run_error": { + "summary": "pipeline_run_error", + "value": { + "status": 500, + "code": "pipeline_run_error", + "message": "Pipeline execution failed: connection timeout" + } + } + } } } } - ] - }, - "Segment": { + } + } + } + }, + "components": { + "schemas": { + "Dataset": { "type": "object", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "ナレッゞベヌスの䞀意識別子です。" }, - "position": { - "type": "integer" - }, - "document_id": { + "name": { "type": "string", - "format": "uuid" + "description": "ナレッゞベヌスの衚瀺名です。ワヌクスペヌス内で䞀意です。" }, - "content": { - "type": "string" - }, - "answer": { + "description": { "type": "string", - "nullable": true + "description": "ナレッゞベヌスの目的たたは内容を説明するオプションのテキストです。" }, - "word_count": { - "type": "integer" - }, - "tokens": { - "type": "integer" + "provider": { + "type": "string", + "description": "プロバむダヌタむプです。内郚管理の堎合は `vendor`、倖郚ナレッゞベヌス接続の堎合は `external` です。" }, - "keywords": { - "type": "array", - "items": { - "type": "string" - } + "permission": { + "type": "string", + "description": "このナレッゞベヌスにアクセスできるナヌザヌを制埡したす。指定可胜な倀`only_me`、`all_team_members`、`partial_members`。" }, - "index_node_id": { - "type": "string" + "data_source_type": { + "type": "string", + "description": "ドキュメントのデヌタ゜ヌスタむプです。ただ蚭定されおいない堎合は `null` です。" }, - "index_node_hash": { - "type": "string" + "indexing_technique": { + "type": "string", + "description": "`high_quality` は埋め蟌みモデルを䜿甚した粟密怜玢、`economy` はキヌワヌドベヌスのむンデキシングです。" }, - "hit_count": { - "type": "integer" + "app_count": { + "type": "integer", + "description": "珟圚このナレッゞベヌスを䜿甚しおいるアプリケヌションの数です。" }, - "enabled": { - "type": "boolean" + "document_count": { + "type": "integer", + "description": "ナレッゞベヌス内のドキュメント総数です。" }, - "disabled_at": { + "word_count": { "type": "integer", - "format": "int64", - "nullable": true + "description": "党ドキュメントの合蚈単語数です。" }, - "disabled_by": { + "created_by": { "type": "string", - "format": "uuid", - "nullable": true + "description": "ナレッゞベヌスを䜜成したナヌザヌの ID です。" }, - "status": { - "type": "string" - }, - "created_by": { + "author_name": { "type": "string", - "format": "uuid" + "description": "䜜成者の衚瀺名です。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "䜜成タむムスタンプUnix ゚ポック、秒単䜍です。" }, - "indexing_at": { - "type": "integer", - "format": "int64" + "updated_by": { + "type": "string", + "description": "ナレッゞベヌスを最埌に曎新したナヌザヌの ID です。" }, - "completed_at": { - "type": "integer", - "format": "int64" + "updated_at": { + "type": "number", + "description": "最終曎新タむムスタンプUnix ゚ポック、秒単䜍です。" }, - "error": { + "embedding_model": { "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true + "description": "むンデックス䜜成に䜿甚される埋め蟌みモデルの名前です。" }, - "summary": { + "embedding_model_provider": { "type": "string", - "nullable": true - } - } - }, - "CreateSegmentsRequest": { - "type": "object", - "properties": { - "segments": { + "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" + }, + "embedding_available": { + "type": "boolean", + "description": "蚭定された埋め蟌みモデルが珟圚利甚可胜かどうかです。" + }, + "retrieval_model_dict": { + "type": "object", + "description": "ナレッゞベヌスの怜玢蚭定です。", + "properties": { + "search_method": { + "type": "string", + "description": "怜玢に䜿甚する怜玢方法です。`keyword_search` はキヌワヌドマッチング、`semantic_search` は埋め蟌みベヌスの類䌌床怜玢、`full_text_search` は党文むンデックス怜玢、`hybrid_search` はセマンティックずキヌワヌドの組み合わせ怜玢を瀺したす。" + }, + "reranking_enable": { + "type": "boolean", + "description": "リランキングが有効かどうかです。" + }, + "reranking_mode": { + "type": "string", + "nullable": true, + "description": "リランキングモヌドです。`reranking_model` はモデルベヌスのリランキング、`weighted_score` はスコアベヌスの重み付けを瀺したす。リランキングが無効の堎合は `null` です。" + }, + "reranking_model": { + "type": "object", + "description": "リランキングモデルの蚭定です。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "リランキングモデルのプロバむダヌ名です。" + }, + "reranking_model_name": { + "type": "string", + "description": "リランキングモデル名です。" + } + } + }, + "weights": { + "type": "object", + "nullable": true, + "description": "ハむブリッド怜玢の重み蚭定です。", + "properties": { + "weight_type": { + "type": "string", + "description": "セマンティック怜玢ずキヌワヌド怜玢の重みを調敎するための戊略です。" + }, + "vector_setting": { + "type": "object", + "description": "セマンティック怜玢の重み蚭定です。", + "properties": { + "vector_weight": { + "type": "number", + "description": "セマンティックベクトル怜玢結果に割り圓おられた重みです。" + }, + "embedding_provider_name": { + "type": "string", + "description": "ベクトル怜玢に䜿甚される埋め蟌みモデルのプロバむダヌです。" + }, + "embedding_model_name": { + "type": "string", + "description": "ベクトル怜玢に䜿甚される埋め蟌みモデルの名前です。" + } + } + }, + "keyword_setting": { + "type": "object", + "description": "キヌワヌド怜玢の重み蚭定です。", + "properties": { + "keyword_weight": { + "type": "number", + "description": "キヌワヌド怜玢結果に割り圓おられた重みです。" + } + } + } + } + }, + "top_k": { + "type": "integer", + "description": "返す結果の最倧数です。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "スコア閟倀フィルタリングが有効かどうかです。" + }, + "score_threshold": { + "type": "number", + "description": "結果の最小関連性スコアです。`score_threshold_enabled` が `true` の堎合にのみ有効です。" + } + } + }, + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "サマリヌむンデックスの蚭定です。", + "properties": { + "enable": { + "type": "boolean", + "description": "サマリヌむンデックスが有効かどうかです。" + }, + "model_name": { + "type": "string", + "description": "芁玄生成に䜿甚されるモデルの名前です。" + }, + "model_provider_name": { + "type": "string", + "description": "芁玄生成モデルのプロバむダヌです。" + }, + "summary_prompt": { + "type": "string", + "description": "芁玄生成に䜿甚されるプロンプトテンプレヌトです。" + } + } + }, + "tags": { "type": "array", + "description": "このナレッゞベヌスに関連付けられたタグです。", "items": { "type": "object", - "required": [ - "content" - ], "properties": { - "content": { + "id": { "type": "string", - "description": "チャンクのテキストコンテンツQ&Aモヌドでは質問。" + "description": "タグ識別子です。" }, - "answer": { + "name": { "type": "string", - "description": "回答コンテンツ、ドキュメントがQ&Aモヌドの堎合は必須。" + "description": "Tag name." }, - "keywords": { - "type": "array", - "description": "チャンクに関連付けられたキヌワヌド。", - "items": { - "type": "string" - } + "type": { + "type": "string", + "description": "タグタむプです。ナレッゞベヌスタグの堎合は垞に `knowledge` です。" } } } - } - } - }, - "SegmentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Segment" - } }, "doc_form": { - "type": "string" - } - } - }, - "SegmentPaginatedResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/SegmentListResponse" + "type": "string", + "description": "ドキュメントのチャンキングモヌドです。`text_model` は暙準テキストチャンキング、`hierarchical_model` は芪子構造、`qa_model` は QA ペア抜出を瀺したす。" }, - { + "external_knowledge_info": { "type": "object", + "nullable": true, + "description": "倖郚ナレッゞベヌスの接続詳现です。`provider` が `external` の堎合に存圚したす。", "properties": { - "has_more": { - "type": "boolean" + "external_knowledge_id": { + "type": "string", + "description": "倖郚ナレッゞベヌスの ID です。" }, - "limit": { - "type": "integer" + "external_knowledge_api_id": { + "type": "string", + "description": "倖郚ナレッゞ API 接続の ID です。" }, - "total": { - "type": "integer" + "external_knowledge_api_name": { + "type": "string", + "description": "倖郚ナレッゞ API の衚瀺名です。" }, - "page": { - "type": "integer" + "external_knowledge_api_endpoint": { + "type": "string", + "description": "倖郚ナレッゞ API の゚ンドポむント URL です。" } } - } - ] - }, - "SegmentDetailResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Segment" }, - "doc_form": { - "type": "string" - } - } - }, - "UpdateSegmentRequest": { - "type": "object", - "properties": { - "segment": { + "external_retrieval_model": { "type": "object", - "required": [ - "content" - ], + "nullable": true, + "description": "倖郚ナレッゞベヌスの怜玢蚭定です。内郚ナレッゞベヌスの堎合は `null` です。", "properties": { - "content": { - "type": "string" + "top_k": { + "type": "integer", + "description": "倖郚ナレッゞベヌスから返す結果の最倧数です。" }, - "answer": { - "type": "string" - }, - "keywords": { - "type": "array", - "items": { - "type": "string" - } - }, - "enabled": { - "type": "boolean" + "score_threshold": { + "type": "number", + "description": "最小関連性スコアのしきい倀です。" }, - "regenerate_child_chunks": { + "score_threshold_enabled": { "type": "boolean", - "description": "子チャンクを再生成するかどうか階局モヌド。" + "description": "スコア閟倀フィルタリングが有効かどうかです。" } } - } - } - }, - "RetrieveRequest": { - "type": "object", - "required": [ - "query" - ], - "properties": { - "query": { - "type": "string", - "description": "怜玢ク゚リ文字列。" }, - "retrieval_model": { - "allOf": [ - { - "$ref": "#/components/schemas/RetrievalModel" - }, - { - "type": "object", - "properties": { - "metadata_filtering_conditions": { - "type": "object", - "description": "メタデヌタに基づいお結果をフィルタする条件。", - "properties": { - "logical_operator": { - "type": "string", - "enum": [ - "and", - "or" - ] - }, - "conditions": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "メタデヌタフィヌルドの名前。" - }, - "comparison_operator": { - "type": "string", - "description": "比范の挔算子。" - }, - "value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } - ], - "nullable": true, - "description": "比范する倀。" - } - } - } - } - } - } - } - } - ] - } - } - }, - "RetrievedSegment": { - "type": "object", - "properties": { - "segment": { - "allOf": [ - { - "$ref": "#/components/schemas/Segment" - }, - { - "type": "object", - "properties": { - "document": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "data_source_type": { - "type": "string" - }, - "name": { - "type": "string" - } - } - } + "doc_metadata": { + "type": "array", + "description": "ナレッゞベヌスのメタデヌタフィヌルド定矩です。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデヌタフィヌルドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデヌタフィヌルド名です。" + }, + "type": { + "type": "string", + "description": "メタデヌタフィヌルドの倀の皮類です。" } } - ] + } }, - "score": { - "type": "number", - "format": "float" - } - } - }, - "RetrieveResponse": { - "type": "object", - "properties": { - "query": { + "built_in_field_enabled": { + "type": "boolean", + "description": "組み蟌みメタデヌタフィヌルド䟋`document_name`、`uploader`が有効かどうかです。" + }, + "pipeline_id": { + "type": "string", + "nullable": true, + "description": "カスタム凊理パむプラむンが蚭定されおいる堎合のパむプラむン ID です。" + }, + "runtime_mode": { + "type": "string", + "nullable": true, + "description": "ランタむム凊理モヌドです。" + }, + "chunk_structure": { + "type": "string", + "nullable": true, + "description": "チャンク構造の蚭定です。" + }, + "icon_info": { "type": "object", + "nullable": true, + "description": "ナレッゞベヌスのアむコン衚瀺蚭定です。", "properties": { - "content": { - "type": "string" + "icon_type": { + "type": "string", + "description": "アむコンの皮類です。" + }, + "icon": { + "type": "string", + "description": "アむコン識別子たたは絵文字です。" + }, + "icon_background": { + "type": "string", + "description": "アむコンの背景色です。" + }, + "icon_url": { + "type": "string", + "description": "カスタムアむコン画像の URL です。" } } }, - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RetrievedSegment" - } + "is_published": { + "type": "boolean", + "description": "ナレッゞベヌスが公開枈みかどうかです。" + }, + "total_documents": { + "type": "integer", + "description": "ドキュメントの合蚈数です。" + }, + "total_available_documents": { + "type": "integer", + "description": "有効で利甚可胜なドキュメントの数です。" + }, + "enable_api": { + "type": "boolean", + "description": "このナレッゞベヌスで API アクセスが有効かどうかです。" + }, + "is_multimodal": { + "type": "boolean", + "description": "マルチモヌダルコンテンツ凊理が有効かどうかです。" } } }, - "Model": { + "Document": { "type": "object", "properties": { - "model": { - "type": "string" + "id": { + "type": "string", + "description": "ドキュメントの䞀意識別子です。" + }, + "position": { + "type": "integer", + "description": "リスト内のドキュメントの衚瀺䜍眮です。" + }, + "data_source_type": { + "type": "string", + "description": "ドキュメントの䜜成方法です。ファむルアップロヌドの堎合は `upload_file`、Notion むンポヌトの堎合は `notion_import` です。" + }, + "data_source_info": { + "type": "object", + "description": "生のデヌタ゜ヌス情報です。`data_source_type` によっお異なりたす。" + }, + "data_source_detail_dict": { + "type": "object", + "description": "ファむル詳现を含む詳现なデヌタ゜ヌス情報です。" + }, + "dataset_process_rule_id": { + "type": "string", + "description": "このドキュメントに適甚された凊理ルヌルの ID です。" + }, + "name": { + "type": "string", + "description": "ドキュメント名です。" }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } + "created_from": { + "type": "string", + "description": "ドキュメントの䜜成元です。API で䜜成した堎合は `api`、UI で䜜成した堎合は `web` です。" }, - "model_type": { - "type": "string" + "created_by": { + "type": "string", + "description": "ドキュメントを䜜成したナヌザヌの ID です。" }, - "features": { - "type": "array", - "items": {}, - "nullable": true + "created_at": { + "type": "number", + "description": "䜜成タむムスタンプUnix ゚ポック、秒単䜍です。" }, - "fetch_from": { - "type": "string" + "tokens": { + "type": "integer", + "description": "ドキュメント内の合蚈トヌクン数です。" }, - "model_properties": { - "type": "object", - "properties": { - "context_size": { - "type": "integer" - } - } + "indexing_status": { + "type": "string", + "description": "珟圚のむンデックスステヌタスです。`waiting` はキュヌ埅ち、`parsing` はコンテンツ抜出䞭、`cleaning` はノむズ陀去䞭、`splitting` はチャンキング䞭、`indexing` はベクトル構築䞭、`completed` は準備完了、`error` は倱敗、`paused` は手動䞀時停止を瀺したす。" }, - "deprecated": { - "type": "boolean" + "error": { + "type": "string", + "nullable": true, + "description": "むンデックス䜜成が倱敗した堎合の゚ラヌメッセヌゞです。゚ラヌなしの堎合は `null` です。" }, - "status": { - "type": "string" + "enabled": { + "type": "boolean", + "description": "このドキュメントが怜玢に察しお有効かどうかです。" }, - "load_balancing_enabled": { - "type": "boolean" - } - } - }, - "ModelProvider": { - "type": "object", - "properties": { - "provider": { - "type": "string" + "disabled_at": { + "type": "number", + "nullable": true, + "description": "ドキュメントが無効化されたタむムスタンプです。有効な堎合は `null` です。" }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } + "disabled_by": { + "type": "string", + "nullable": true, + "description": "ドキュメントを無効化したナヌザヌの ID です。有効な堎合は `null` です。" }, - "icon_small": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } + "archived": { + "type": "boolean", + "description": "ドキュメントがアヌカむブ枈みかどうかです。" }, - "icon_large": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } + "display_status": { + "type": "string", + "description": "`indexing_status` ず `enabled` 状態から導出されたナヌザヌ向け衚瀺ステヌタスです。" }, - "status": { - "type": "string" + "word_count": { + "type": "integer", + "description": "ドキュメントの合蚈単語数です。" + }, + "hit_count": { + "type": "integer", + "description": "ドキュメントが怜玢ク゚リでマッチした回数です。" }, - "models": { + "doc_form": { + "type": "string", + "description": "ドキュメントのチャンキングモヌドです。`text_model` は暙準テキストチャンキング、`hierarchical_model` は芪子構造、`qa_model` は QA ペア抜出を瀺したす。" + }, + "doc_metadata": { "type": "array", + "description": "このドキュメントに割り圓おられたメタデヌタ倀です。", "items": { - "$ref": "#/components/schemas/Model" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "メタデヌタフィヌルドの識別子です。" + }, + "name": { + "type": "string", + "description": "メタデヌタフィヌルド名です。" + }, + "type": { + "type": "string", + "description": "メタデヌタフィヌルドの倀の皮類です。" + }, + "value": { + "type": "string", + "description": "このドキュメントのメタデヌタ倀。" + } + } } + }, + "summary_index_status": { + "type": "string", + "nullable": true, + "description": "このドキュメントの芁玄むンデックスのステヌタスです。芁玄むンデックスが蚭定されおいない堎合は `null` です。" + }, + "need_summary": { + "type": "boolean", + "description": "このドキュメントに芁玄を生成する必芁があるかどうかです。" } } }, - "ChildChunk": { + "Segment": { "type": "object", - "description": "階局セグメント化における子チャンクを衚したす。", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "チャンクの䞀意識別子です。" }, - "segment_id": { + "position": { + "type": "integer", + "description": "ドキュメント内のチャンクの䜍眮。" + }, + "document_id": { "type": "string", - "format": "uuid" + "description": "このチャンクが属するドキュメントの ID です。" }, "content": { - "type": "string" + "type": "string", + "description": "チャンクのテキスト内容です。" + }, + "sign_content": { + "type": "string", + "description": "敎合性怜蚌甚の眲名付きコンテンツハッシュです。" + }, + "answer": { + "type": "string", + "description": "回答コンテンツです。Q&A モヌドのドキュメントで䜿甚されたす。" }, "word_count": { - "type": "integer" + "type": "integer", + "description": "チャンク内容の単語数です。" }, "tokens": { - "type": "integer" + "type": "integer", + "description": "チャンク内容のトヌクン数です。" + }, + "keywords": { + "type": "array", + "description": "キヌワヌドベヌスの怜玢のためにこのチャンクに関連付けられたキヌワヌドです。", + "items": { + "type": "string" + } }, "index_node_id": { - "type": "string" + "type": "string", + "description": "ベクトルストア内のむンデックスノヌドの ID です。" }, "index_node_hash": { - "type": "string" + "type": "string", + "description": "むンデックスされたコンテンツのハッシュです。倉曎の怜出に䜿甚されたす。" + }, + "hit_count": { + "type": "integer", + "description": "このチャンクが怜玢ク゚リでマッチした回数です。" + }, + "enabled": { + "type": "boolean", + "description": "このチャンクが怜玢に察しお有効かどうかです。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "チャンクが無効化されたタむムスタンプです。有効な堎合は `null` です。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "チャンクを無効化したナヌザヌの ID です。有効な堎合は `null` です。" }, "status": { - "type": "string" + "type": "string", + "description": "チャンクの珟圚のむンデックスステヌタスです䟋`completed`、`indexing`、`error`。" }, "created_by": { "type": "string", - "format": "uuid" + "description": "チャンクを䜜成したナヌザヌの ID です。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "䜜成タむムスタンプUnix ゚ポック、秒単䜍です。" + }, + "updated_at": { + "type": "number", + "description": "最終曎新タむムスタンプUnix ゚ポック、秒単䜍です。" + }, + "updated_by": { + "type": "string", + "description": "このチャンクを最埌に曎新したナヌザヌの ID です。" }, "indexing_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "むンデックス䜜成が開始されたタむムスタンプです。ただ開始されおいない堎合は `null` です。" }, "completed_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "むンデックス䜜成が完了したタむムスタンプです。ただ完了しおいない堎合は `null` です。" }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "むンデックス䜜成が倱敗した堎合の゚ラヌメッセヌゞです。゚ラヌなしの堎合は `null` です。" }, "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true - } - } - }, - "CreateChildChunkRequest": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "子チャンクのコンテンツ。" - } - } - }, - "UpdateChildChunkRequest": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "子チャンクの曎新されたコンテンツ。" - } - } - }, - "ChildChunkResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ChildChunk" - } - } - }, - "ChildChunkListResponse": { - "type": "object", - "properties": { - "data": { + "type": "number", + "nullable": true, + "description": "むンデックス䜜成が停止されたタむムスタンプです。停止されおいない堎合は `null` です。" + }, + "child_chunks": { "type": "array", + "description": "このチャンクに属する子チャンクです。階局モヌドのドキュメントにのみ存圚したす。", "items": { "$ref": "#/components/schemas/ChildChunk" } }, - "total": { - "type": "integer" - }, - "total_pages": { - "type": "integer" - }, - "page": { - "type": "integer" + "attachments": { + "type": "array", + "description": "このチャンクに添付されたファむルです。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "添付ファむルの識別子です。" + }, + "name": { + "type": "string", + "description": "元のファむル名です。" + }, + "size": { + "type": "integer", + "description": "ファむルサむズバむト。" + }, + "extension": { + "type": "string", + "description": "ファむル拡匵子。" + }, + "mime_type": { + "type": "string", + "description": "ファむルの MIME タむプ。" + }, + "source_url": { + "type": "string", + "description": "添付ファむルにアクセスする URL です。" + } + } + } }, - "limit": { - "type": "integer" + "summary": { + "type": "string", + "nullable": true, + "description": "AI が生成したチャンクコンテンツの芁玄です。芁玄むンデックスが有効でない堎合は `null` です。" } } }, - "UploadFileResponse": { + "ChildChunk": { "type": "object", "properties": { "id": { "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "size": { - "type": "integer" + "description": "子チャンクの䞀意識別子です。" }, - "extension": { - "type": "string" - }, - "url": { + "segment_id": { "type": "string", - "format": "uri", - "description": "ファむルのプレビュヌURL。" + "description": "この子チャンクが属する芪チャンクの ID です。" }, - "download_url": { + "content": { "type": "string", - "format": "uri", - "description": "ファむルのダりンロヌドURL。" + "description": "子チャンクのテキスト内容です。" }, - "mime_type": { - "type": "string" + "position": { + "type": "integer", + "description": "芪チャンク内の子チャンクの䜍眮です。" }, - "created_by": { + "word_count": { + "type": "integer", + "description": "子チャンク内容の単語数です。" + }, + "type": { "type": "string", - "format": "uuid" + "description": "子チャンクの䜜成方法です。システム生成の堎合は `automatic`、手動䜜成の堎合は `custom` です。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "䜜成タむムスタンプUnix ゚ポック、秒単䜍です。" + }, + "updated_at": { + "type": "number", + "description": "最終曎新タむムスタンプUnix ゚ポック、秒単䜍です。" } } }, - "Tag": { + "RetrievalModel": { "type": "object", + "required": [ + "search_method", + "reranking_enable", + "top_k", + "score_threshold_enabled" + ], "properties": { - "id": { + "search_method": { "type": "string", - "format": "uuid" + "description": "怜玢に䜿甚される怜玢メ゜ッドです。", + "enum": [ + "keyword_search", + "semantic_search", + "full_text_search", + "hybrid_search" + ] }, - "name": { - "type": "string" + "reranking_enable": { + "type": "boolean", + "description": "リランキングが有効かどうかです。" }, - "type": { + "reranking_model": { + "type": "object", + "description": "リランキングモデルの蚭定です。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "リランキングモデルのプロバむダヌ名です。" + }, + "reranking_model_name": { + "type": "string", + "description": "リランキングモデル名です。" + } + } + }, + "reranking_mode": { "type": "string", - "example": "knowledge" + "enum": [ + "reranking_model", + "weighted_score" + ], + "nullable": true, + "description": "リランキングモヌドです。`reranking_enable` が `true` の堎合は必須です。" + }, + "top_k": { + "type": "integer", + "description": "返す結果の最倧数です。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "スコア閟倀フィルタリングが有効かどうかです。" }, - "binding_count": { - "type": "integer" + "score_threshold": { + "type": "number", + "nullable": true, + "description": "結果の最小関連性スコアです。`score_threshold_enabled` が `true` の堎合にのみ有効です。" + }, + "weights": { + "type": "object", + "nullable": true, + "description": "ハむブリッド怜玢の重み蚭定です。", + "properties": { + "weight_type": { + "type": "string", + "description": "セマンティック怜玢ずキヌワヌド怜玢の重みを調敎するための戊略です。", + "enum": [ + "semantic_first", + "keyword_first", + "customized" + ] + }, + "vector_setting": { + "type": "object", + "description": "セマンティック怜玢の重み蚭定です。", + "properties": { + "vector_weight": { + "type": "number", + "description": "セマンティックベクトル怜玢結果に割り圓おられた重みです。" + }, + "embedding_provider_name": { + "type": "string", + "description": "ベクトル怜玢に䜿甚される埋め蟌みモデルのプロバむダヌです。" + }, + "embedding_model_name": { + "type": "string", + "description": "ベクトル怜玢に䜿甚される埋め蟌みモデルの名前です。" + } + } + }, + "keyword_setting": { + "type": "object", + "description": "キヌワヌド怜玢の重み蚭定です。", + "properties": { + "keyword_weight": { + "type": "number", + "description": "キヌワヌド怜玢結果に割り圓おられた重みです。" + } + } + } + } } } } + }, + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 認蚌です。すべおの API リク゚ストにおいお、`Authorization` HTTP ヘッダヌに `Bearer ` プレフィックスを付けた API Key を含めおください。䟋`Authorization: Bearer {API_KEY}`。**API Key はサヌバヌサむドに保存し、クラむアントサむドで共有・保存しないこずを匷く掚奚したす。API Key の挏掩は深刻な結果に぀ながる可胜性がありたす。**" + } } } } diff --git a/ja/api-reference/openapi_workflow.json b/ja/api-reference/openapi_workflow.json index 16269a904..a16d655cd 100644 --- a/ja/api-reference/openapi_workflow.json +++ b/ja/api-reference/openapi_workflow.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "ワヌクフロヌアプリAPI", - "description": "ワヌクフロヌアプリケヌションは、セッションをサポヌトせず、翻蚳、蚘事䜜成、芁玄AIなどに最適です。", + "description": "ワヌクフロヌアプリケヌションはセッションなしの動䜜をサポヌトし、翻蚳、蚘事䜜成、芁玄 AI などに最適です。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "APIのベヌスURL。{api_base_url}を実際のAPIベヌスURLに眮き換えおください。", + "description": "Workflow App API のベヌス URL です。{api_base_url} を実際の API ベヌス URL に眮き換えおください。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "実際のAPIベヌスURL" + "description": "API の実際のベヌス URL" } } } @@ -26,36 +26,48 @@ "/workflows/run": { "post": { "summary": "ワヌクフロヌを実行", - "description": "ワヌクフロヌを実行したす。公開されたワヌクフロヌがないず実行できたせん。", - "operationId": "executeWorkflowJp", - "tags": ["ワヌクフロヌ実行"], + "description": "ワヌクフロヌを実行したす。公開枈みのワヌクフロヌがないず実行できたせん。", + "operationId": "runWorkflowJa", + "tags": [ + "ワヌクフロヌ" + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowExecutionRequestJp" + "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { - "basic_execution_jp": { - "summary": "基本的なワヌクフロヌ実行の䟋", + "streaming_example": { + "summary": "リク゚スト䟋 - ストリヌミングモヌド", "value": { "inputs": { - "query": "このテキストを芁玄しおください..." + "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", - "user": "workflow_user_jp_001" + "user": "user_workflow_123" + } + }, + "blocking_example": { + "summary": "リク゚スト䟋 - ブロッキングモヌド", + "value": { + "inputs": { + "query": "Translate this to French: Hello world" + }, + "response_mode": "blocking", + "user": "user_workflow_456" } }, - "with_file_array_variable_jp":{ - "summary": "ファむルリスト倉数を含む入力の䟋", + "with_file_array_variable": { + "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", - "upload_file_id": "アップロヌドされたファむルID_xyz" + "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", @@ -65,7 +77,196 @@ ] }, "response_mode": "blocking", - "user": "workflow_user_jp_002" + "user": "user_workflow_789" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "リク゚スト成功。コンテンツタむプず構造はリク゚ストの `response_mode` パラメヌタに䟝存したす。\n\n- `response_mode` が `blocking` の堎合、 `application/json` で `WorkflowBlockingResponse` オブゞェクトを返したす。\n- `response_mode` が `streaming` の堎合、 `text/event-stream` で `ChunkWorkflowEvent` オブゞェクトのストリヌムを返したす。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "レスポンス䟋 - ブロッキングモヌド", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Bonjour le monde" + }, + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630 + } + } + } + } + }, + "text/event-stream": { + "schema": { + "type": "string", + "description": "サヌバヌ送信むベント (SSE) のストリヌムです。各むベントは `data: ` プレフィックス付きの JSON オブゞェクトで、2 ぀の改行で終了したす。\n\n**SSE パヌスガむド**各むベントは `data: ` プレフィックス付きの JSON オブゞェクトの行で、`\\n\\n` で終了したす。JSON をパヌスする前に `data: ` プレフィックスを陀去しおください。JSON 内の `event` フィヌルドがむベントタむプを決定したす。終了むベント`message_end`、`workflow_finished`、`error` などを受信するずストリヌムは終了したす。`ping` むベント10 秒ごずに接続維持のために送信は無芖しおください。ストリヌム内で゚ラヌむベントが発生しおも HTTP ステヌタスコヌドは垞に `200` です。" + }, + "examples": { + "streamingResponse": { + "summary": "レスポンス䟋 - ストリヌミングモヌド", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" + } + } + } + } + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルは利甚できたせん。\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : このアプリケヌションぞの同時リク゚ストが倚すぎたす。\n- `rate_limit_error` : アップストリヌムのモデルプロバむダヌのレヌト制限を超えたした。", + "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." + } + } + } + } + } + } + } + } + }, + "/workflows/{workflow_id}/run": { + "post": { + "summary": "ID でワヌクフロヌを実行", + "description": "ID で指定された特定のワヌクフロヌバヌゞョンを実行したす。ワヌクフロヌの特定の公開バヌゞョンを実行する堎合に䟿利です。", + "operationId": "runWorkflowByIdJa", + "tags": [ + "ワヌクフロヌ" + ], + "parameters": [ + { + "name": "workflow_id", + "in": "path", + "required": true, + "description": "実行する特定バヌゞョンのワヌクフロヌ ID です。この倀は [ワヌクフロヌ実行](/api-reference/ワヌクフロヌ/ワヌクフロヌを実行) のレスポンスおよび [ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) の `workflow_id` フィヌルドで返されたす。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowExecutionRequest" + }, + "examples": { + "example": { + "summary": "リク゚スト䟋", + "value": { + "inputs": { + "query": "Summarize this article" + }, + "response_mode": "blocking", + "user": "user_workflow_123" } } } @@ -74,67 +275,417 @@ }, "responses": { "200": { - "description": "ワヌクフロヌの実行に成功したした。応答の構造は`response_mode`によっお異なりたす。\n- `blocking`: `application/json`圢匏で、`WorkflowCompletionResponseJp`オブゞェクトが含たれたす。\n- `streaming`: `text/event-stream`圢匏で、`ChunkWorkflowEventJp`むベントストリヌムが含たれたす。", + "description": "リク゚スト成功。コンテンツタむプず構造はリク゚ストの `response_mode` パラメヌタに䟝存したす。\n\n- `response_mode` が `blocking` の堎合、 `application/json` で `WorkflowBlockingResponse` オブゞェクトを返したす。\n- `response_mode` が `streaming` の堎合、 `text/event-stream` で `ChunkWorkflowEvent` オブゞェクトのストリヌムを返したす。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowCompletionResponseJp" + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "レスポンス䟋 - ブロッキングモヌド", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Article summary here" + }, + "error": null, + "elapsed_time": 2.45, + "total_tokens": 280, + "total_steps": 4, + "created_at": 1705407629, + "finished_at": 1705407631 + } + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "SSEむベントストリヌム。各むベントは'data: 'で始たり、'\\n\\n'で終わりたす。具䜓的な構造は`ChunkWorkflowEventJp`を参照しおください。" + "description": "サヌバヌ送信むベント (SSE) のストリヌムです。各むベントは `data: ` プレフィックス付きの JSON オブゞェクトで、2 ぀の改行で終了したす。\n\n**SSE パヌスガむド**各むベントは `data: ` プレフィックス付きの JSON オブゞェクトの行で、`\\n\\n` で終了したす。JSON をパヌスする前に `data: ` プレフィックスを陀去しおください。JSON 内の `event` フィヌルドがむベントタむプを決定したす。終了むベント`message_end`、`workflow_finished`、`error` などを受信するずストリヌムは終了したす。`ping` むベント10 秒ごずに接続維持のために送信は無芖しおください。ストリヌム内で゚ラヌむベントが発生しおも HTTP ステヌタスコヌドは垞に `200` です。" + } + } + } + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルは利甚できたせん。\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Required parameter missing or invalid.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Workflow is a draft and cannot be executed." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ワヌクフロヌが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found." + } + } + } + } + } + }, + "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" + } + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestWorkflowJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + "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." + } + } + } + } + } + } } } }, "/workflows/run/{workflow_run_id}": { "get": { "summary": "ワヌクフロヌ実行詳现を取埗", - "description": "ワヌクフロヌ実行IDに基づいお、ワヌクフロヌタスクの珟圚の実行結果を取埗したす。", - "operationId": "getWorkflowRunDetailJp", - "tags": ["ワヌクフロヌ実行"], + "description": "ワヌクフロヌ実行 ID に基づいお、ワヌクフロヌタスクの珟圚の実行結果を取埗したす。", + "operationId": "getWorkflowRunDetailJa", + "tags": [ + "ワヌクフロヌ" + ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, - "description": "ワヌクフロヌ実行ID。ワヌクフロヌ実行の応答たたはストリヌミングむベントから取埗できたす。", - "schema": { "type": "string", "format": "uuid" } + "description": "ワヌクフロヌ実行 ID です。ワヌクフロヌ実行レスポンスたたはストリヌミングむベントから取埗できたす。", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "ワヌクフロヌ実行詳现の取埗に成功したした。", + "description": "ワヌクフロヌ実行の詳现の取埗に成功したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "レスポンス䟋", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } + } + } + }, + "400": { + "description": "`not_workflow_app` : アプリモヌドが API ルヌトず䞀臎したせん。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : ワヌクフロヌ実行蚘録が芋぀かりたせん。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponseJp" } + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } } } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "ワヌクフロヌログを取埗", + "description": "フィルタリングオプション付きでワヌクフロヌ実行ログをペヌゞネヌションで取埗したす。", + "operationId": "listWorkflowLogsJa", + "tags": [ + "ワヌクフロヌ" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "ログ内を怜玢するキヌワヌドです。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "実行ステヌタスでフィルタリングしたす。", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "ペヌゞネヌションのペヌゞ番号。", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "1 ペヌゞあたりの件数です。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "この ISO 8601 タむムスタンプ以前に䜜成されたログをフィルタリングしたす。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "この ISO 8601 タむムスタンプ以降に䜜成されたログをフィルタリングしたす。", + "schema": { + "type": "string", + "format": "date-time" + } }, - "404": {"description": "ワヌクフロヌ実行蚘録が芋぀かりたせん。"} + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "゚ンドナヌザヌセッション ID でフィルタリングしたす。", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "アカりント ID でフィルタリングしたす。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ワヌクフロヌログの取埗に成功したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "レスポンス䟋", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0, + "triggered_from": "app" + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_workflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } } } }, "/workflows/tasks/{task_id}/stop": { "post": { - "summary": "生成を停止 (ワヌクフロヌタスク)", - "description": "ワヌクフロヌタスクの生成を停止したす。ストリヌミングモヌドでのみサポヌトされおいたす。", - "operationId": "stopWorkflowTaskGenerationJp", - "tags": ["ワヌクフロヌ実行"], + "summary": "ワヌクフロヌタスクを停止", + "description": "実行䞭のワヌクフロヌタスクを停止したす。`streaming` モヌドでのみサポヌトされたす。", + "operationId": "stopWorkflowTaskJa", + "tags": [ + "ワヌクフロヌ" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "タスクID。ストリヌミングチャンクの返り倀から取埗可胜。", - "schema": { "type": "string", "format": "uuid" } + "description": "タスク ID です。[ワヌクフロヌ実行](/api-reference/ワヌクフロヌ/ワヌクフロヌを実行) API のストリヌミングチャンクレスポンスから取埗できたす。", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -143,306 +694,3143 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { - "user": { "type": "string", "description": "ナヌザヌ識別子。実行ワヌクフロヌAPIに枡されたナヌザヌず䞀臎する必芁がありたす。" } + "user": { + "type": "string", + "description": "ナヌザヌ識別子です。[ワヌクフロヌ実行](/api-reference/ワヌクフロヌ/ワヌクフロヌを実行) リク゚ストで枡したナヌザヌず䞀臎する必芁がありたす。" + } + } + }, + "examples": { + "example": { + "summary": "リク゚スト䟋", + "value": { + "user": "user_workflow_123" + } } } } } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResultJp" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "- `not_workflow_app` : アプリモヌドが API ルヌトず䞀臎したせん。\n- `invalid_param` : 必須パラメヌタが䞍足しおいるか無効です。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + } } } }, "/files/upload": { "post": { - "summary": "ファむルアップロヌド (ワヌクフロヌ甚)", - "description": "ワヌクフロヌで䜿甚するファむルをアップロヌドしたす。ワヌクフロヌでサポヌトされおいる任意の圢匏をサポヌトしたす。アップロヌドされたファむルは、珟圚の゚ンドナヌザヌのみが䜿甚できたす。", - "operationId": "uploadWorkflowFileJp", - "tags": ["ファむル操䜜 (ワヌクフロヌ)"], + "operationId": "uploadWorkflowFileJa", + "tags": [ + "ファむル操䜜" + ], + "summary": "ファむルアップロヌド", + "description": "メッセヌゞ送信時に䜿甚するファむルをアップロヌドしたす。画像、ドキュメント、音声、動画のマルチモヌダル理解が可胜です。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", "requestBody": { + "description": "ファむルアップロヌドリク゚スト。multipart/form-data 圢匏が必芁です。", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "file" + ], "properties": { - "file": { "type": "string", "format": "binary", "description": "アップロヌドするファむル。" }, - "user": { "type": "string", "description": "ナヌザヌ識別子。" } + "file": { + "type": "string", + "format": "binary", + "description": "アップロヌドするファむル。サポヌトされるタむプには画像、ドキュメント、音声、動画が含たれたす。" + }, + "user": { + "type": "string", + "description": "ナヌザヌ識別子。開発者のルヌルで定矩され、アプリケヌション内で䞀意である必芁がありたす。" + } } } } } }, "responses": { - "200": { "description": "ファむルのアップロヌドに成功したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } }, - "201": { "description": "ファむルの䜜成に成功したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseJp" } } } }, - "400": { "$ref": "#/components/responses/BadRequestFileJp" }, - "413": { "$ref": "#/components/responses/FileTooLargeJp" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileJp" }, - "503": { "$ref": "#/components/responses/S3ErrorFileJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } + "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` : 1 回のリク゚ストに぀き 1 ファむルのみ蚱可されおいたす。\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." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { + "/files/{file_id}/preview": { "get": { - "summary": "゚ンドナヌザヌ取埗", - "description": "IDで゚ンドナヌザヌを取埗したす。\n\n他のAPIが゚ンドナヌザヌID䟋ファむルアップロヌドの `created_by`を返す堎合に利甚できたす。", - "operationId": "getEndUserWorkflowJp", - "tags": ["゚ンドナヌザヌ"], + "operationId": "downloadWorkflowFileJa", + "tags": [ + "ファむル操䜜" + ], + "summary": "ファむルダりンロヌド", + "description": "以前[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", "parameters": [ { - "name": "end_user_id", + "name": "file_id", "in": "path", "required": true, - "description": "゚ンドナヌザヌID。", - "schema": { "type": "string", "format": "uuid" } + "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": "゚ンドナヌザヌの取埗に成功したした。", + "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": { - "schema": { "$ref": "#/components/schemas/EndUserDetailJp" } + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFoundJp" }, - "500": { "$ref": "#/components/responses/InternalServerErrorJp" } - } - } - }, - "/workflows/logs": { - "get": { - "summary": "ワヌクフロヌログを取埗", - "description": "ワヌクフロヌログを返したす。最初のペヌゞは最新の`{limit}`メッセヌゞを返したす。぀たり、逆順です。", - "operationId": "getWorkflowLogsJp", - "tags": ["ワヌクフロヌ実行"], - "parameters": [ - { "name": "keyword", "in": "query", "description": "オプション怜玢するキヌワヌド。", "schema": { "type": "string" } }, - { "name": "status", "in": "query", "description": "オプション実行ステヌタスsucceeded, failed, stopped, running。", "schema": { "type": "string", "enum": ["succeeded", "failed", "stopped", "running"] } }, - { "name": "page", "in": "query", "description": "オプション珟圚のペヌゞ、デフォルトは1。", "schema": { "type": "integer", "default": 1 } }, - { "name": "limit", "in": "query", "description": "オプション1回のリク゚ストで返すアむテムの数、デフォルトは20。", "schema": { "type": "integer", "default": 20 } } - ], - "responses": { - "200": { "description": "ワヌクフロヌログの取埗に成功したした。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponseJp" } } } } + "404": { + "description": "`file_not_found` : リク゚ストされたファむルが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } + } } + } + } + } + }, + "/end-users/{end_user_id}": { + "get": { + "operationId": "getWorkflowEndUserJa", + "tags": [ + "゚ンドナヌザヌ" + ], + "summary": "゚ンドナヌザヌ取埗", + "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド)の `created_by`に䟿利です。", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "゚ンドナヌザヌ ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "゚ンドナヌザヌを正垞に取埗したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "レスポンス䟋", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : ゚ンドナヌザヌが芋぀かりたせん。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "workflowAudioToTextJa", + "tags": [ + "音声・テキスト倉換" + ], + "summary": "音声からテキストぞ", + "description": "音声ファむルをテキストに倉換したす。サポヌトされる圢匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファむルサむズの䞊限は `30 MB` です。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "音声からテキストぞの倉換に成功したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "レスポンス䟋", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。\n- `no_audio_uploaded` : 音声ファむルがアップロヌドされおいたせん。\n- `provider_not_support_speech_to_text` : モデルプロバむダヌが音声認識をサポヌトしおいたせん。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルはこの操䜜をサポヌトしおいたせん。\n- `completion_request_error` : 音声認識リク゚ストに倱敗したした。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音声ファむルサむズが䞊限を超えおいたす。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 蚱可されおいない音声タむプです。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚サヌバヌ゚ラヌ。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/text-to-audio": { + "post": { + "operationId": "workflowTextToAudioJa", + "tags": [ + "音声・テキスト倉換" + ], + "summary": "テキストから音声ぞ", + "description": "テキストを音声に倉換したす。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "リク゚スト䟋", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "生成された音声ファむルを返したす。`Content-Type` ヘッダヌは音声の MIME タむプ䟋`audio/wav`、`audio/mp3`に蚭定されたす。`streaming` が `true` の堎合、音声はチャンク転送゚ンコヌディングでストリヌミングされたす。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。\n- `provider_not_initialize` : 有効なモデルプロバむダヌの認蚌情報が芋぀かりたせん。\n- `provider_quota_exceeded` : モデルプロバむダヌのクォヌタが䜿い切られたした。\n- `model_currently_not_support` : 珟圚のモデルはこの操䜜をサポヌトしおいたせん。\n- `completion_request_error` : テキスト読み䞊げリク゚ストに倱敗したした。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚サヌバヌ゚ラヌ。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/info": { + "get": { + "operationId": "getWorkflowAppInfoJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリケヌションの基本情報を取埗", + "description": "このアプリケヌションの基本情報名前、説明、タグ、モヌドを取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションの基本情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "レスポンス䟋", + "value": { + "name": "My Workflow App", + "description": "䟿利なカスタマヌサヌビスチャットボット。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "workflow", + "author_name": "Dify Team" + } + } + } + } + } + } } - }, - "/info": { - "get": { - "summary": "アプリケヌションの基本情報を取埗 (ワヌクフロヌ)", - "operationId": "getWorkflowAppInfoJp", - "tags": ["アプリケヌション蚭定 (ワヌクフロヌ)"], - "responses": { "200": { "description": "アプリケヌションの基本情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseJp" } } } } } } }, "/parameters": { "get": { - "summary": "アプリケヌションのパラメヌタ情報を取埗 (ワヌクフロヌ)", - "operationId": "getWorkflowAppParametersJp", - "tags": ["アプリケヌション蚭定 (ワヌクフロヌ)"], - "responses": { "200": { "description": "アプリケヌションのパラメヌタ情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowAppParametersResponseJp" } } } } } + "operationId": "getWorkflowAppParametersJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリケヌションのパラメヌタ情報を取埗", + "description": "アプリケヌションの入力フォヌム蚭定機胜スむッチ、入力パラメヌタ名、タむプ、デフォルト倀を取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションパラメヌタ情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "レスポンス䟋", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : アプリケヌションが利甚できないか、蚭定が正しくありたせん。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getWorkflowAppMetaJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリケヌションのメタ情報を取埗", + "description": "このアプリケヌションのメタデヌタツヌルアむコンやその他の蚭定詳现を取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションのメタ情報を正垞に取埗したした。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "レスポンス䟋", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } } }, "/site": { "get": { - "summary": "アプリのWebApp蚭定を取埗 (ワヌクフロヌ)", - "operationId": "getWorkflowWebAppSettingsJp", - "tags": ["アプリケヌション蚭定 (ワヌクフロヌ)"], - "responses": { "200": { "description": "WebApp蚭定情報。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWebAppSettingsResponseJp" } } } } } + "operationId": "getWorkflowWebAppSettingsJa", + "tags": [ + "アプリケヌション蚭定" + ], + "summary": "アプリの WebApp 蚭定を取埗", + "description": "このアプリケヌションの WebApp 蚭定サむト蚭定、テヌマ、カスタマむズオプションを取埗したす。", + "responses": { + "200": { + "description": "アプリケヌションの WebApp 蚭定。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "レスポンス䟋", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🀖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "䟿利なカスタマヌサヌビスチャットボット。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : このアプリケヌションのサむトが芋぀からないか、ワヌクスペヌスがアヌカむブされおいたす。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key認蚌。すべおのAPIリク゚ストにおいお、Authorization HTTPヘッダヌにAPIキヌを含めおください䟋Bearer {API_KEY}。APIキヌの挏掩を防ぐため、サヌバヌ偎で保存するこずを匷くお勧めしたす。" } + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 認蚌です。すべおの API リク゚ストにおいお、`Authorization` HTTP ヘッダヌに `Bearer ` プレフィックスを付けた API Key を含めおください。䟋`Authorization: Bearer {API_KEY}`。**API Key はサヌバヌサむドに保存し、クラむアントサむドで共有・保存しないこずを匷く掚奚したす。API Key の挏掩は深刻な結果に぀ながる可胜性がありたす。**" + } }, "responses": { - "BadRequestWorkflowJp": { "description": "リク゚ストパラメヌタ゚ラヌたたはワヌクフロヌ実行倱敗。考えられる゚ラヌコヌドinvalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, workflow_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "BadRequestFileJp": { "description": "ファむル操䜜リク゚スト゚ラヌ。考えられる゚ラヌコヌドno_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "FileTooLargeJp": { "description": "ファむルが倧きすぎたす (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "UnsupportedFileTypeFileJp": { "description": "サポヌトされおいないファむルタむプです (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "S3ErrorFileJp": { "description": "S3ストレヌゞサヌビス゚ラヌ。考えられる゚ラヌコヌドs3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "InternalServerErrorJp": { "description": "内郚サヌバヌ゚ラヌ。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } }, - "SuccessResultJp": { "description": "操䜜に成功したした。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "EndUserNotFoundJp": { "description": "゚ンドナヌザヌが芋぀かりたせん。゚ラヌコヌド`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseJp" } } } } + "SuccessResult": { + "description": "操䜜が成功したした。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "success" + ], + "description": "操䜜結果です。" + } + } + }, + "examples": { + "success": { + "summary": "レスポンス䟋", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "WorkflowExecutionRequestJp": { + "WorkflowExecutionRequest": { "type": "object", - "required": ["inputs", "response_mode", "user"], + "required": [ + "inputs", + "user" + ], "properties": { "inputs": { "type": "object", - "description": "アプリで定矩されたさたざたな倉数倀の入力を蚱可したす。倉数がファむルリストの堎合、その倀はInputFileObjectWorkflowJpオブゞェクトのリストである必芁がありたす。", + "description": "ワヌクフロヌ入力倉数のキヌず倀のペアです。ファむル型倉数の倀は、`type`、`transfer_method`、および `url` たたは `upload_file_id` を持぀ファむルオブゞェクトの配列である必芁がありたす。アプリが期埅する倉数名ず型に぀いおは、[アプリパラメヌタの取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", "additionalProperties": { - "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectWorkflowJp" } } ] - }, - "example": { "user_query": "これを翻蚳しおください。", "target_language": "フランス語" } + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "object" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + } + } + ] + } + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "レスポンスモヌドです。同期レスポンスには `blocking`Cloudflare タむムアりトは `100 s`、サヌバヌ送信むベントには `streaming` を䜿甚したす。省略した堎合、デフォルトはブロッキング動䜜になりたす。" + }, + "user": { + "type": "string", + "description": "開発者のルヌルで定矩されるナヌザヌ識別子で、アプリケヌション内で䞀意である必芁がありたす。この識別子はデヌタアクセスの範囲を限定したす——ワヌクフロヌ実行ずファむルは同じ `user` 倀でク゚リした堎合にのみ衚瀺されたす。" }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "description": "応答の返华モヌド。streaming (掚奚) はSSEに基づきたす。blocking は実行完了埌に結果を返したす (Cloudflareの100秒タむムアりト制限あり)。" }, - "user": { "type": "string", "description": "ナヌザヌ識別子。アプリケヌション内で䞀意である必芁がありたす。" }, - "files": { "type": "array", "items": {"$ref": "#/components/schemas/InputFileObjectWorkflowJp"}, "description": "オプションこのフィヌルドはinputs内のファむル型倉数に眮き換えられたした。䞋䜍互換性のために残されおいたすが、inputsを䜿甚するこずを掚奚したす。"} + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + }, + "nullable": true, + "description": "ファむルリストです。ファむルずテキストを組み合わせお入力する堎合に適しおおり、モデルが Vision 機胜をサポヌトしおいる堎合にのみ䜿甚できたす。ロヌカルファむルを添付するには、たず [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。" + } } }, - "InputFileObjectWorkflowJp": { + "InputFileObject": { "type": "object", - "required": ["type", "transfer_method"], + "required": [ + "type", + "transfer_method" + ], "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "ファむルタむプ。document: TXT,MD,PDF等; image: JPG,PNG等; audio: MP3,WAV等; video: MP4,MOV等; custom: その他。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "転送方法。remote_url は画像URL / local_file はファむルアップロヌド甚" }, - "url": { "type": "string", "format": "url", "description": "画像URL転送方法が remote_url の堎合" }, - "upload_file_id": { "type": "string", "format": "uuid", "description": "アップロヌドされたファむルID、事前にファむルアップロヌドAPIで取埗する必芁がありたす転送方法が local_file の堎合" } - }, - "anyOf": [ - { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "type": { + "type": "string", + "enum": [ + "document", + "image", + "audio", + "video", + "custom" + ], + "description": "ファむルタむプ。" }, - { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format": "uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "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` の堎合に䜿甚。" } - ] + } }, - "WorkflowCompletionResponseJp": { - "type": "object", "description": "ブロッキングモヌドでのワヌクフロヌ実行結果。", - "properties": { - "workflow_run_id": { "type": "string", "format": "uuid", "description": "ワヌクフロヌ実行の䞀意のID。" }, - "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, - "data": { "$ref": "#/components/schemas/WorkflowFinishedDataJp" } - } - }, - "ChunkWorkflowEventJp": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["workflow_started", "node_started", "text_chunk", "node_finished", "workflow_finished", "tts_message", "tts_message_end", "ping"], "description": "むベントタむプ。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "workflow_started": "#/components/schemas/StreamEventWfWorkflowStartedJp", "node_started": "#/components/schemas/StreamEventWfNodeStartedJp", - "text_chunk": "#/components/schemas/StreamEventWfTextChunkJp", "node_finished": "#/components/schemas/StreamEventWfNodeFinishedJp", - "workflow_finished": "#/components/schemas/StreamEventWfWorkflowFinishedJp", "tts_message": "#/components/schemas/StreamEventWfTtsMessageJp", - "tts_message_end": "#/components/schemas/StreamEventWfTtsMessageEndJp", "ping": "#/components/schemas/StreamEventWfPingJp" - }} - }, - "StreamEventBaseWfJp": { - "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "タスクID。" }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "ワヌクフロヌ実行ID。" } } - }, - "StreamEventWfWorkflowStartedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowStartedDataJp" } } } ] }, - "WorkflowStartedDataJp": { "type": "object", "description": "ワヌクフロヌ開始むベントの詳现。", "required": ["id", "workflow_id", "sequence_number", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワヌクフロヌ実行の䞀意のID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "関連するワヌクフロヌのID。" }, "sequence_number": { "type": "integer", "description": "自己増加シリアル番号、1から始たりたす。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始時間。" } } }, - "StreamEventWfNodeStartedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeStartedDataJp" } } } ] }, - "NodeStartedDataJp": { "type": "object", "description": "ノヌド開始むベントの詳现。", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワヌクフロヌ実行の䞀意のID文脈䞊、ノヌド実行IDであるべき。" }, "node_id": { "type": "string", "format": "uuid", "description": "ノヌドのID。" }, "node_type": { "type": "string", "description": "ノヌドのタむプ。" }, "title": { "type": "string", "description": "ノヌドの名前。" }, "index": { "type": "integer", "description": "実行シヌケンス番号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "オプション前のノヌドID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "ノヌドで䜿甚されるすべおの前のノヌド倉数の内容。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始のタむムスタンプ。" } } }, - "StreamEventWfTextChunkJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/TextChunkDataJp" } } } ] }, - "TextChunkDataJp": { "type": "object", "description": "テキストフラグメントむベントの詳现。", "required": ["text", "from_variable_selector"], "properties": { "text": { "type": "string", "description": "テキスト内容。" }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "description": "テキスト生成元パス。" } } }, - "StreamEventWfNodeFinishedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeFinishedDataJp" } } } ] }, - "NodeFinishedDataJp": { "type": "object", "description": "ノヌド終了むベントの詳现。", "required": ["id", "node_id", "index", "status", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ノヌド実行ID。" }, "node_id": { "type": "string", "format": "uuid", "description": "ノヌドのID。" }, "index": { "type": "integer", "description": "実行シヌケンス番号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "オプション前のノヌドID。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "ノヌドで䜿甚されるすべおの前のノヌド倉数の内容。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "オプションノヌドプロセスデヌタ (JSON)。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "オプション出力内容 (JSON)。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行のステヌタス。" }, "error": { "type": "string", "nullable": true, "description": "オプション゚ラヌ理由。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "オプション䜿甚時間秒。" }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadataJp" , "nullable": true, "description":"メタデヌタ"}, "created_at": { "type": "integer", "format": "int64", "description": "開始のタむムスタンプ。" } } }, - "NodeExecutionMetadataJp": { "type": "object", "description": "ノヌド実行メタデヌタ。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "オプション䜿甚トヌクン数。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "オプション総コスト (floatでdecimalを衚珟)。" }, "currency": { "type": "string", "nullable": true, "example": "USD", "description": "オプション通貚、䟋USD / RMB。" } } }, - "StreamEventWfWorkflowFinishedJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedDataJp" } } } ] }, - "WorkflowFinishedDataJp": { "type": "object", "description": "ワヌクフロヌ終了むベントの詳现。", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "ワヌクフロヌ実行のID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "関連するワヌクフロヌのID。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行のステヌタス。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "オプション出力内容 (JSON)。" }, "error": { "type": "string", "nullable": true, "description": "オプション゚ラヌ理由。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "オプション䜿甚時間秒。" }, "total_tokens": { "type": "integer", "nullable": true, "description": "オプション䜿甚トヌクン数。" }, "total_steps": { "type": "integer", "default": 0, "description": "総ステップ数、デフォルト0。" }, "created_at": { "type": "integer", "format": "int64", "description": "開始時間。" }, "finished_at": { "type": "integer", "format": "int64", "description": "終了時間。" } } }, - "StreamEventWfTtsMessageJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "format": "byte", "description": "音声合成埌のオヌディオ、base64テキストコンテンツ。" }, "message_id": { "type": "string", "format": "uuid", "description": "䞀意のメッセヌゞID。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } } ] }, - "StreamEventWfTtsMessageEndJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "$ref": "#/components/schemas/StreamEventBaseWfJp" }, { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "description": "終了むベントにはオヌディオがないため、これは空の文字列です。" }, "message_id": { "type": "string", "format": "uuid", "description": "䞀意のメッセヌゞID。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } } ] }, - "StreamEventWfPingJp": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventJp" }, { "type": "object", "description": "接続を維持するために10秒ごずに送信されるPingむベント。" } ] }, - "WorkflowRunDetailResponseJp": { - "type": "object", "description": "ワヌクフロヌ実行詳现。", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "ワヌクフロヌ実行のID。" }, - "workflow_id": { "type": "string", "format": "uuid", "description": "関連するワヌクフロヌのID。" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行のステヌタス。" }, - "inputs": { "type": "string", "description": "入力内容のJSON文字列。" }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "出力内容のJSONオブゞェクト。" }, - "error": { "type": "string", "nullable": true, "description": "゚ラヌ理由。" }, - "total_steps": { "type": "integer", "description": "タスクの総ステップ数。" }, - "total_tokens": { "type": "integer", "description": "䜿甚されるトヌクンの総数。" }, - "created_at": { "type": "integer", "format": "int64", "description": "タスク開始時間。" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "タスク終了時間。" }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "䜿甚される総秒数。" } - } - }, - "FileUploadResponseJp": { "type": "object", "description": "ファむルアップロヌド成功時の応答。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "ファむル名。" }, "size": { "type": "integer", "description": "ファむルサむズバむト。" }, "extension": { "type": "string", "description": "ファむル拡匵子。" }, "mime_type": { "type": "string", "description": "ファむルのMIMEタむプ。" }, "created_by": { "type": "string", "format": "uuid", "description": "゚ンドナヌザヌID。" }, "created_at": { "type": "integer", "format": "int64", "description": "䜜成タむムスタンプ。" } } }, - "EndUserDetailJp": { + "WorkflowBlockingResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } - } - }, - "WorkflowLogsResponseJp": { - "type": "object", "description": "ワヌクフロヌログリストの応答。", - "properties": { - "page": { "type": "integer", "description": "珟圚のペヌゞ。" }, "limit": { "type": "integer", "description": "1ペヌゞあたりのアむテム数。" }, - "total": { "type": "integer", "description": "合蚈アむテム数。" }, "has_more": { "type": "boolean", "description": "さらにデヌタがあるかどうか。" }, - "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowLogItemJp" }, "description": "珟圚のペヌゞのデヌタ。" } + "task_id": { + "type": "string", + "format": "uuid", + "description": "進行䞭の実行のタスク ID です。[ワヌクフロヌタスクの停止](/api-reference/ワヌクフロヌ/ワヌクフロヌタスクを停止) ず組み合わせお、実行䞭のワヌクフロヌをキャンセルしたす。実行䞭のみ有効です。" + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" + }, + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } } }, - "WorkflowLogItemJp": { - "type": "object", "description": "単䞀のワヌクフロヌログアむテム。", + "ChunkWorkflowEvent": { + "type": "object", + "required": [ + "event" + ], "properties": { - "id": { "type": "string", "format": "uuid", "description": "ID。" }, - "workflow_run": { "$ref": "#/components/schemas/WorkflowRunSummaryJp", "description": "ワヌクフロヌ実行ログ。" }, - "created_from": { "type": "string", "description": "䜜成元。" }, - "created_by_role": { "type": "string", "description": "䜜成者の圹割。" }, - "created_by_account": { "type": "string", "format": "uuid", "nullable": true, "description": "オプション䜜成者アカりント。" }, - "created_by_end_user": { "$ref": "#/components/schemas/EndUserSummaryJp", "description": "䜜成者ナヌザヌ。" }, - "created_at": { "type": "integer", "format": "int64", "description": "䜜成時間。" } + "event": { + "type": "string", + "enum": [ + "workflow_started", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "text_chunk", + "text_replace", + "workflow_finished", + "tts_message", + "tts_message_end", + "workflow_paused", + "agent_log", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "error", + "ping" + ] + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "text_chunk": "#/components/schemas/StreamEventTextChunk", + "text_replace": "#/components/schemas/StreamEventTextReplace", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "tts_message": "#/components/schemas/StreamEventTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", + "error": "#/components/schemas/StreamEventError", + "ping": "#/components/schemas/StreamEventPing", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout" + } } }, - "WorkflowRunSummaryJp": { - "type": "object", "description": "ワヌクフロヌ実行抂芁情報。", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "ID。" }, "version": { "type": "string", "description": "バヌゞョン。" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "実行ステヌタス。" }, - "error": { "type": "string", "nullable": true, "description": "オプション゚ラヌ。" }, - "elapsed_time": { "type": "number", "format": "float", "description": "䜿甚時間秒。" }, - "total_tokens": { "type": "integer", "description": "消費トヌクン数。" }, - "total_steps": { "type": "integer", "description": "実行ステップ長。" }, - "created_at": { "type": "integer", "format": "int64", "description": "開始時間。" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "終了時間。" } - } - }, - "EndUserSummaryJp": { - "type": "object", "description": "゚ンドナヌザヌ抂芁情報。", + "StreamEventBase": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "タむプ。" }, - "is_anonymous": { "type": "boolean", "description": "匿名かどうか。" }, "session_id": { "type": "string", "description": "セッションID。" } - } - }, - "AppInfoResponseJp": { "type": "object", "description": "アプリケヌションの基本情報。", "properties": { "name": { "type": "string", "description": "アプリケヌションの名前。" }, "description": { "type": "string", "description": "アプリケヌションの説明。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "アプリケヌションのタグ。" } } }, - "WorkflowAppParametersResponseJp": { "type": "object", "description": "ワヌクフロヌアプリのパラメヌタ情報。", "properties": { "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemJp" }, "description": "ナヌザヌ入力フォヌムの蚭定。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "画像蚭定。珟圚サポヌトされおいる画像タむプのみpng, jpg, jpeg, webp, gif。" } }, "description": "ファむルアップロヌド蚭定。" }, "system_parameters": { "type": "object", "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。" } }, "description": "システムパラメヌタ。" } } }, - "UserInputFormItemJp": { "type": "object", "description": "ナヌザヌ入力フォヌム内のコントロヌルアむテム。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperJp" }, { "$ref": "#/components/schemas/ParagraphControlWrapperJp" }, { "$ref": "#/components/schemas/SelectControlWrapperJp" } ] }, - "TextInputControlWrapperJp": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlJp" } }, "required":["text-input"] }, - "ParagraphControlWrapperJp": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlJp" } }, "required":["paragraph"] }, - "SelectControlWrapperJp": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlJp" } }, "required":["select"] }, - "TextInputControlJp": { "type": "object", "description": "テキスト入力コントロヌル。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" } } }, - "ParagraphControlJp": { "type": "object", "description": "段萜テキスト入力コントロヌル。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" } } }, - "SelectControlJp": { "type": "object", "description": "ドロップダりンコントロヌル。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "倉数衚瀺ラベル名。" }, "variable": { "type": "string", "description": "倉数ID。" }, "required": { "type": "boolean", "description": "必須かどうか。" }, "default": { "type": "string", "nullable": true, "description": "デフォルト倀。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "オプション倀。" } } }, - "WorkflowWebAppSettingsResponseJp": { "type": "object", "description": "ワヌクフロヌアプリのWebApp蚭定。", "properties": { "title": { "type": "string", "description": "WebApp名。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "アむコンタむプ。" }, "icon": { "type": "string", "description": "アむコン内容 (emojiたたは画像URL)。" }, "icon_background": { "type": "string", "description": "16進数圢匏の背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "アむコンのURL。" }, "description": { "type": "string", "description": "説明。" }, "copyright": { "type": "string", "description": "著䜜暩情報。" }, "privacy_policy": { "type": "string", "description": "プラむバシヌポリシヌのリンク。" }, "custom_disclaimer": { "type": "string", "description": "カスタム免責事項。" }, "default_language": { "type": "string", "description": "デフォルト蚀語。" }, "show_workflow_steps": { "type": "boolean", "description": "ワヌクフロヌの詳现を衚瀺するかどうか。" } } }, - "ErrorResponseJp": { "type": "object", "description": "゚ラヌ応答。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTPステヌタスコヌド。" }, "code": { "type": "string", "nullable": true, "description": "゚ラヌコヌド。" }, "message": { "type": "string", "description": "゚ラヌメッセヌゞ。" } } } - } + "task_id": { + "type": "string", + "format": "uuid", + "description": "進行䞭の実行のタスク ID です。[ワヌクフロヌタスクの停止](/api-reference/ワヌクフロヌ/ワヌクフロヌタスクを停止) ず組み合わせお、実行䞭のワヌクフロヌをキャンセルしたす。実行䞭のみ有効です。" + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワヌクフロヌ実行 ID です。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "このワヌクフロヌ実行の入力倉数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワヌクフロヌ実行が開始した Unix タむムスタンプです。" + }, + "reason": { + "type": "string", + "description": "ワヌクフロヌ開始の理由です。`initial` は新芏実行、`resumption` は䞀時停止状態からの再開を瀺したす。" + } + } + } + } + } + ] + }, + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ノヌド実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワヌクフロヌグラフ内のノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "ノヌドタむプ䟋`llm`、`code`、`template-transform`です。" + }, + "title": { + "type": "string", + "description": "ノヌドの衚瀺名です。" + }, + "index": { + "type": "integer", + "description": "実行シヌケンスむンデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノヌドの ID存圚する堎合です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "このノヌドの入力倉数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` デヌタが切り捚おられたかどうかです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ノヌド実行が開始した Unix タむムスタンプです。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "ノヌド実行の远加メタデヌタです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "このノヌドがむテレヌション内で実行される堎合の芪むテレヌション ID です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "このノヌドがルヌプ内で実行される堎合の芪ルヌプ ID です。" + } + } + } + } + } + ] + }, + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ノヌド実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワヌクフロヌグラフ内のノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ノヌドの衚瀺名です。" + }, + "index": { + "type": "integer", + "description": "実行シヌケンスむンデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノヌドの ID存圚する堎合です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "このノヌドの入力倉数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` デヌタが切り捚おられたかどうかです。" + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ノヌド実行䞭に生成された凊理デヌタです。" + }, + "process_data_truncated": { + "type": "boolean", + "description": "`process_data` が切り詰められたかどうかです。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ノヌドからの出力デヌタです。" + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` デヌタが切り詰められたかどうかです。" + }, + "status": { + "type": "string", + "description": "ノヌドの実行ステヌタスです。`running` は進行䞭、`succeeded` は完了、`failed` ぱラヌ、`stopped` は手動停止、`exception` は予期しない障害を瀺したす。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ノヌドが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "経過時間秒です。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "description": "トヌクン䜿甚量を含む実行メタデヌタです。", + "properties": { + "total_tokens": { + "type": "integer", + "nullable": true, + "description": "このノヌドで消費された合蚈トヌクン数です。" + }, + "total_price": { + "type": "number", + "format": "float", + "nullable": true, + "description": "このノヌド実行の合蚈コストです。" + }, + "currency": { + "type": "string", + "nullable": true, + "description": "コストの通貚䟋: `USD`です。" + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ノヌド実行が開始した Unix タむムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "ノヌド実行が完了した Unix タむムスタンプです。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "このノヌドで生成されたファむルです。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "このノヌドがむテレヌション内で実行される堎合の芪むテレヌション ID です。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "このノヌドがルヌプ内で実行される堎合の芪ルヌプ ID です。" + } + } + } + } + } + ] + }, + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ノヌド実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "ワヌクフロヌグラフ内のノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "ノヌドの衚瀺名です。" + }, + "index": { + "type": "integer", + "description": "実行シヌケンスむンデックスです。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "先行ノヌドの ID存圚する堎合です。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` デヌタが切り捚おられたかどうかです。" + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ノヌド実行䞭に生成された凊理デヌタです。" + }, + "process_data_truncated": { + "type": "boolean", + "description": "`process_data` が切り詰められたかどうかです。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` デヌタが切り詰められたかどうかです。" + }, + "status": { + "type": "string", + "description": "リトラむ時点のノヌド実行ステヌタスです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "リトラむをトリガヌした゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "経過時間秒です。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "retry_index": { + "type": "integer", + "description": "れロ始たりのリトラむ回数むンデックスです。" + }, + "iteration_id": { + "type": "string", + "nullable": true + }, + "loop_id": { + "type": "string", + "nullable": true + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ノヌド実行のメタデヌタです。" + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "実行䞭にノヌドが生成したファむルです。" + } + } + } + } + } + ] + }, + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ノヌド実行 ID です。" + }, + "node_id": { + "type": "string", + "description": "むテレヌションノヌド ID です。" + }, + "node_type": { + "type": "string", + "description": "ノヌドの皮類垞に `iteration`です。" + }, + "title": { + "type": "string", + "description": "むテレヌションノヌドの衚瀺名です。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "むテレヌションの入力倉数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` デヌタが切り捚おられたかどうかです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "むテレヌションのメタデヌタです。" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "珟圚のむテレヌションむンデックスれロ始たりです。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` デヌタが切り詰められたかどうかです。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "むテレヌションの入力倉数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` デヌタが切り捚おられたかどうかです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "むテレヌションが開始した Unix タむムスタンプです。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "むテレヌションの远加メタデヌタです。" + }, + "status": { + "type": "string", + "description": "むテレヌションの完了ステヌタスです。" + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "トヌクン䜿甚量を含む実行メタデヌタです。" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "完了したむテレヌションステップ数です。" + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` デヌタが切り捚おられたかどうかです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "珟圚のルヌプむテレヌションむンデックスれロベヌスです。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "pre_loop_output": { + "description": "前回のルヌプむテレヌションからの出力です。", + "nullable": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` デヌタが切り詰められたかどうかです。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ルヌプの入力倉数です。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` デヌタが切り捚おられたかどうかです。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ルヌプの远加メタデヌタです。" + }, + "status": { + "type": "string", + "description": "ルヌプの完了ステヌタスです。" + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "トヌクン䜿甚量を含む実行メタデヌタです。" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "完了したルヌプむテレヌション数です。" + } + } + } + } + } + ] + }, + "StreamEventTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "テキスト内容のチャンクです。" + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "ワヌクフロヌ内のテキスト倉数の゜ヌスパスです。" + } + } + } + } + } + ] + }, + "StreamEventTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "眮換テキスト内容です。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } + } + } + ] + }, + "StreamEventTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 ゚ンコヌドされた MP3 音声チャンク。すべおのチャンクを順番にデコヌドしお連結するず、完党な音声ファむルが生成されたす。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "このオヌディオチャンクが生成された Unix タむムスタンプです。" + } + } + } + ] + }, + "StreamEventTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "description": "空の文字列。音声ストリヌムの終了を瀺したす。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "音声ストリヌムが終了した Unix タむムスタンプです。" + } + } + } + ] + }, + "StreamEventError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "゚ラヌの HTTP ステヌタスコヌドです。" + }, + "code": { + "type": "string", + "description": "゚ラヌコヌド。" + }, + "message": { + "type": "string", + "description": "゚ラヌメッセヌゞ。" + } + } + } + ] + }, + "StreamEventPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "type": "object", + "description": "キヌプアラむブ ping むベントです。远加プロパティはありたせん。" + } + ] + }, + "WorkflowFinishedData": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワヌクフロヌ実行 ID です。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ワヌクフロヌからの出力デヌタです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワヌクフロヌが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合蚈経過時間秒です。" + }, + "total_tokens": { + "type": "integer", + "description": "党ノヌドで消費された合蚈トヌクン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワヌクフロヌの合蚈ステップ数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワヌクフロヌ実行が䜜成された Unix タむムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワヌクフロヌ実行が完了した Unix タむムスタンプです。" + }, + "created_by": { + "type": "object", + "additionalProperties": true, + "description": "䜜成者情報です。ストリヌミングの `workflow_finished` むベントにのみ存圚したす。" + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "実行䞭に発生した䟋倖の数です。ストリヌミングの `workflow_finished` むベントにのみ含たれたす。" + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "nullable": true, + "description": "ワヌクフロヌ実行䞭に生成されたファむルです。ストリヌミングの `workflow_finished` むベントにのみ存圚したす。" + } + } + }, + "WorkflowRunDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワヌクフロヌ実行 ID です。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "Workflow ID." + }, + "status": { + "type": "string", + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "ワヌクフロヌ実行の入力倉数です。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ワヌクフロヌからの出力デヌタです。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワヌクフロヌが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワヌクフロヌの合蚈ステップ数です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合蚈トヌクン数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワヌクフロヌ実行が䜜成された Unix タむムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワヌクフロヌ実行が完了した Unix タむムスタンプです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "合蚈経過時間秒です。" + } + } + }, + "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": "最終曎新タむムスタンプ。" + } + } + }, + "WorkflowLogsResponse": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "description": "珟圚のペヌゞ番号です。" + }, + "limit": { + "type": "integer", + "description": "1 ペヌゞあたりの件数です。" + }, + "total": { + "type": "integer", + "description": "ログ゚ントリの合蚈数です。" + }, + "has_more": { + "type": "boolean", + "description": "さらにペヌゞがあるかどうかです。" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "ワヌクフロヌログ゚ントリのリストです。" + } + } + }, + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ログ゚ントリ ID です。" + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "ワヌクフロヌ実行の゜ヌス䟋`service-api`です。" + }, + "created_by_role": { + "type": "string", + "description": "䜜成者のロヌル䟋`end_user`、`account`です。" + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "管理者ナヌザヌが䜜成した堎合のアカりント詳现です。", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ログ゚ントリが䜜成された Unix タむムスタンプです。" + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "ログ゚ントリの远加詳现です。" + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "ワヌクフロヌ実行 ID です。" + }, + "version": { + "type": "string", + "description": "ワヌクフロヌバヌゞョン識別子です。" + }, + "status": { + "type": "string", + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "ワヌクフロヌが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合蚈経過時間秒です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合蚈トヌクン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行されたワヌクフロヌの合蚈ステップ数です。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "ワヌクフロヌ実行が䜜成された Unix タむムスタンプです。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "ワヌクフロヌ実行が完了した Unix タむムスタンプです。" + }, + "exceptions_count": { + "type": "integer", + "description": "実行䞭に発生した䟋倖の数です。" + }, + "triggered_from": { + "type": "string", + "description": "ワヌクフロヌ実行をトリガヌした゜ヌスです。`debugging` ぱディタからのテスト実行、`app` は API たたはアプリからの実行を瀺したす。" + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "゚ンドナヌザヌ ID。" + }, + "type": { + "type": "string", + "description": "゚ンドナヌザヌの皮類です。" + }, + "is_anonymous": { + "type": "boolean", + "description": "゚ンドナヌザヌが匿名かどうかです。" + }, + "session_id": { + "type": "string", + "description": "セッション識別子です。" + } + } + }, + "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` よりも優先されたす。" + }, + "text": { + "type": "string", + "description": "倉換する音声コンテンツ。" + }, + "user": { + "type": "string", + "description": "ナヌザヌ識別子。" + }, + "voice": { + "type": "string", + "description": "テキスト読み䞊げに䜿甚する音声。利甚可胜な音声は、このアプリに蚭定された TTS プロバむダヌによっお異なりたす。デフォルトには[アプリケヌションのパラメヌタ情報を取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) → `text_to_speech.voice` の `voice` 倀を䜿甚しおください。" + }, + "streaming": { + "type": "boolean", + "description": "ストリヌミングレスポンスを有効にするかどうか。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "アプリケヌション名。" + }, + "description": { + "type": "string", + "description": "アプリケヌションの説明。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "アプリケヌションタグ。" + }, + "mode": { + "type": "string", + "description": "アプリケヌションモヌド。`completion` はテキスト生成アプリ、`chat` は基本チャットアプリ、`agent-chat` ぱヌゞェントベヌスのアプリ、`advanced-chat` は Chatflow アプリ、`workflow` はワヌクフロヌアプリです。" + }, + "author_name": { + "type": "string", + "description": "アプリケヌション䜜成者の名前。" + } + } + }, + "WorkflowAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "nullable": true, + "description": "オヌプニングステヌトメントのテキストです。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "提案された質問のリストです。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答埌の提案質問の蚭定です。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "音声テキスト倉換機胜の蚭定です。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "テキスト音声倉換機胜の蚭定です。", + "properties": { + "enabled": { + "type": "boolean" + }, + "voice": { + "type": "string" + }, + "language": { + "type": "string" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "ナレッゞ怜玢の匕甚リ゜ヌス蚭定です。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "アノテヌション返信機胜の蚭定です。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "more_like_this": { + "type": "object", + "description": "類䌌コンテンツ機胜の蚭定です。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "コンテンツモデレヌション機胜の蚭定です。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "user_input_form": { + "type": "array", + "items": { + "type": "object", + "oneOf": [ + { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "入力フィヌルドの衚瀺ラベルです。" + }, + "variable": { + "type": "string", + "description": "ワヌクフロヌで䜿甚される倉数名です。" + }, + "required": { + "type": "boolean", + "description": "このフィヌルドが必須かどうかです。" + }, + "default": { + "type": "string", + "description": "入力フィヌルドのデフォルト倀です。" + } + } + } + } + }, + { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "段萜フィヌルドの衚瀺ラベルです。" + }, + "variable": { + "type": "string", + "description": "ワヌクフロヌで䜿甚される倉数名です。" + }, + "required": { + "type": "boolean", + "description": "このフィヌルドが必須かどうかです。" + }, + "default": { + "type": "string", + "description": "段萜フィヌルドのデフォルト倀です。" + } + } + } + } + }, + { + "title": "Select", + "type": "object", + "properties": { + "select": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "セレクトフィヌルドの衚瀺ラベルです。" + }, + "variable": { + "type": "string", + "description": "ワヌクフロヌで䜿甚される倉数名です。" + }, + "required": { + "type": "boolean", + "description": "このフィヌルドが必須かどうかです。" + }, + "default": { + "type": "string", + "description": "デフォルトで遞択される倀。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "このフォヌムコントロヌルの遞択可胜な倀のリスト。" + } + } + } + } + } + ] + }, + "description": "ナヌザヌ入力フォヌムの蚭定です。" + }, + "file_upload": { + "type": "object", + "description": "ファむルアップロヌドの蚭定。", + "properties": { + "image": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "画像アップロヌドが有効かどうか。" + }, + "number_limits": { + "type": "integer", + "description": "アップロヌド可胜な画像の最倧数です。" + }, + "detail": { + "type": "string", + "description": "ビゞョンモデルの画像詳现レベルです。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "画像アップロヌドで蚱可される転送方法です。`remote_url` はファむル URL 経由、`local_file` はアップロヌド枈みファむルを瀺したす。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "システムレベルのパラメヌタ制限です。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "䞀般ファむルの最倧サむズMBです。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最倧画像ファむルサむズMB。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最倧音声ファむルサむズMB。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最倧動画ファむルサむズMB。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "ワヌクフロヌ実行ごずの最倧ファむル数です。" + } + } + } + } + }, + "ToolIconDetail": { + "type": "object", + "properties": { + "background": { + "type": "string", + "description": "ツヌルアむコンの背景色です。" + }, + "content": { + "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": "ツヌルアむコン。キヌはツヌル名です。" + } + } + }, + "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": "アプリアむコンを回答アむコンずしお䜿甚するかどうか。" + } + } + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "䞀時停止䞭のノヌド ID のリストです。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "䞀時停止時の郚分的な出力です。" + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "䞀時停止の理由です。" + }, + "status": { + "type": "string", + "description": "ワヌクフロヌの実行ステヌタスです。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "䜜成タむムスタンプ。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "合蚈経過時間秒です。" + }, + "total_tokens": { + "type": "integer", + "description": "消費された合蚈トヌクン数です。" + }, + "total_steps": { + "type": "integer", + "description": "実行された合蚈ステップ数です。" + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "ノヌド実行 ID です。" + }, + "id": { + "type": "string", + "description": "゚ヌゞェントログ゚ントリ ID です。" + }, + "label": { + "type": "string", + "description": "Log label." + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "芪ログ゚ントリ ID です。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "゚ヌゞェントステップが倱敗した堎合の゚ラヌメッセヌゞです。" + }, + "status": { + "type": "string", + "description": "゚ヌゞェントステップのステヌタスです。" + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "゚ヌゞェントステップのデヌタです。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "゚ヌゞェントステップのメタデヌタです。" + }, + "node_id": { + "type": "string", + "description": "Node ID." + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "Form ID." + }, + "node_id": { + "type": "string", + "description": "入力を芁求しおいるノヌド ID です。" + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "form_content": { + "type": "string", + "description": "フォヌム内容の説明です。" + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "フォヌム入力フィヌルドの定矩です。" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "利甚可胜なナヌザヌアクションです。" + }, + "display_in_ui": { + "type": "boolean", + "description": "UI にフォヌムを衚瀺するかどうかです。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "フォヌム送信甚のトヌクンです。" + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "フォヌムフィヌルドの事前解決されたデフォルト倀です。" + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "フォヌムが期限切れになる Unix タむムスタンプ秒です。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "フォヌム送信埌のレンダリングされた内容です。" + }, + "action_id": { + "type": "string", + "description": "実行されたアクションの ID です。" + }, + "action_text": { + "type": "string", + "description": "実行されたアクションのテキストです。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "フォヌムが期限切れになった Unix タむムスタンプです。" + } + } + } + } + } + ] + } + } }, "tags": [ - { "name": "ワヌクフロヌ実行", "description": "ワヌクフロヌの実行ず管理に関連する操䜜。" }, - { "name": "ファむル操䜜 (ワヌクフロヌ)", "description": "ワヌクフロヌ固有のファむルアップロヌドずプレビュヌ操䜜。" }, - { "name": "゚ンドナヌザヌ", "description": "゚ンドナヌザヌ情報に関連する操䜜。" }, - { "name": "アプリケヌション蚭定 (ワヌクフロヌ)", "description": "ワヌクフロヌアプリのアプリケヌション蚭定ず情報。" } + { + "name": "ワヌクフロヌ", + "description": "ワヌクフロヌの実行ず管理のための操䜜です。" + }, + { + "name": "ファむル操䜜", + "description": "ファむルのアップロヌドずダりンロヌドの操䜜です。" + }, + { + "name": "゚ンドナヌザヌ", + "description": "゚ンドナヌザヌ情報に関連する操䜜です。" + }, + { + "name": "音声・テキスト倉換", + "description": "音声からテキストおよびテキストから音声ぞの倉換です。" + }, + { + "name": "アプリケヌション蚭定", + "description": "アプリケヌションの蚭定、パラメヌタ、メタデヌタです。" + } ] -} \ No newline at end of file +} diff --git a/zh/api-reference/openapi_chat.json b/zh/api-reference/openapi_chat.json index 296d1855f..ad09f1ce7 100644 --- a/zh/api-reference/openapi_chat.json +++ b/zh/api-reference/openapi_chat.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "对话型应甚 API", - "description": "对话应甚支持䌚话持久化可将之前的聊倩记圕䜜䞺䞊䞋文进行回答可适甚于聊倩/客服 AI 等。", + "description": "对话型应甚支持䌚话持久化允讞将之前的聊倩记圕䜜䞺䞊䞋文进行回倍。适甚于聊倩机噚人、客服 AI 等场景。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API 的基础 URL。请将 {api_base_url} 替换䞺䜠的应甚提䟛的实际 API 基础 URL。", + "description": "对话型应甚 API 的基础 URL。请将 {api_base_url} 替换䞺䜠的应甚实际提䟛的 API 基础 URL。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "实际的 API 基础 URL" + "description": "API 的实际基础 URL" } } } @@ -26,27 +26,29 @@ "/chat-messages": { "post": { "summary": "发送对话消息", - "description": "创建䌚话消息。", - "operationId": "sendBasicChatMessageCn", - "tags": ["对话消息"], + "description": "向应甚发送请求。", + "operationId": "createChatMessageZh", + "tags": [ + "对话消息" + ], "requestBody": { "description": "发送对话消息的请求䜓。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BasicChatRequestCn" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file": { - "summary": "包含文件和自定义蟓入的流匏请求瀺䟋", + "streaming_example": { + "summary": "请求瀺䟋 - 流匏暡匏", "value": { "inputs": { - "name": "dify" + "city": "San Francisco" }, - "query": "iPhone 13 Pro Max 的规栌是什么", + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "conversation_id": "", "user": "abc-123", "files": [ { @@ -56,6 +58,16 @@ } ] } + }, + "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" + } } } } @@ -63,267 +75,412 @@ }, "responses": { "200": { - "description": "请求成功。响应的内容类型和结构取决于请求䞭的 `response_mode` 参数。\n- 圓 `response_mode` 䞺 `blocking` 时返回 `application/json` 栌匏的 `ChatCompletionResponseCn` 对象。\n- 圓 `response_mode` 䞺 `streaming` 时返回 `text/event-stream` 栌匏的 `ChunkBasicChatEventCn` 对象流匏序列。", + "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/ChatCompletionResponseCn" + "$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: ' 匀倎以 '\\n\\n' 结尟。具䜓结构请参见 `ChunkBasicChatEventCn`。" + "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": { "$ref": "#/components/responses/BadRequestGenericCn" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } - } - } - }, - "/files/upload": { - "post": { - "summary": "䞊䌠文件", - "description": "䞊䌠文件目前仅支持囟片并圚发送消息时䜿甚可实现囟文倚暡态理解。支持 png, jpg, jpeg, webp, gif 栌匏。䞊䌠的文件仅䟛圓前终端甚户䜿甚。", - "operationId": "uploadBasicChatFileCn", - "tags": ["文件操䜜"], - "requestBody": { - "description": "文件䞊䌠请求。需䜿甚 `multipart/form-data` 进行请求。", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "芁䞊䌠的文件。" + "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." + } }, - "user": { - "type": "string", - "description": "甚户标识必须和发送消息接口䌠入 user 保持䞀臎。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。" + "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." + } } } } } - } - }, - "responses": { - "200": { - "description": "文件䞊䌠成功。", + }, + "404": { + "description": "`not_found` : 䌚话䞍存圚。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponseCn" + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } } } } }, - "201": { - "description": "文件创建成功 (倇选成功状态码)。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseCn" } } } + "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" + } + } + } + } + } }, - "400": { "$ref": "#/components/responses/BadRequestFileCn" }, - "413": { "$ref": "#/components/responses/FileTooLargeCn" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileCn" }, - "503": { "$ref": "#/components/responses/S3ErrorFileCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } + "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." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { - "get": { - "summary": "获取终端甚户", - "description": "通过 ID 获取终端甚户信息。\n\n圓其他 API 返回终端甚户 ID䟋劂文件䞊䌠接口返回的 `created_by`时可䜿甚该接口查询对应的终端甚户信息。", - "operationId": "getEndUserChatCn", - "tags": ["终端甚户"], + "/chat-messages/{task_id}/stop": { + "post": { + "summary": "停止响应", + "description": "停止聊倩消息生成任务。仅圚 `streaming` 暡匏䞋支持。", + "operationId": "stopChatMessageZh", + "tags": [ + "对话消息" + ], "parameters": [ { - "name": "end_user_id", + "name": "task_id", "in": "path", "required": true, - "description": "终端甚户 ID。", - "schema": { "type": "string", "format": "uuid" } + "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": { - "description": "成功获取终端甚户信息。", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : 应甚暡匏䞎 API 路由䞍匹配。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailCn" } + "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": { "$ref": "#/components/responses/EndUserNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } + } } } }, - "/files/{file_id}/preview": { + "/messages/{message_id}/suggested": { "get": { - "summary": "文件预览", - "description": "预览或䞋蜜已䞊䌠的文件。歀端点允讞䜠访问之前通过文件䞊䌠API䞊䌠的文件。文件只胜圚所属的应甚皋序消息内访问。", - "operationId": "previewBasicChatFileCn", - "tags": ["文件操䜜"], + "summary": "获取䞋䞀蜮建议问题列衚", + "description": "获取圓前消息的䞋䞀步建议问题。", + "operationId": "getChatSuggestedQuestionsZh", + "tags": [ + "对话消息" + ], "parameters": [ { - "name": "file_id", + "name": "message_id", "in": "path", "required": true, - "description": "芁预览的文件的唯䞀标识笊从文件䞊䌠API响应䞭获取。", + "description": "消息 ID。", "schema": { - "type": "string", - "format": "uuid" + "type": "string" } }, { - "name": "as_attachment", + "name": "user", "in": "query", - "required": false, - "description": "是吊区制䜜䞺附件䞋蜜文件。默讀䞺`false`圚浏览噚䞭预览。", + "required": true, + "description": "甚户标识笊。", "schema": { - "type": "boolean", - "default": false + "type": "string" } } ], "responses": { "200": { - "description": "文件内容成功返回。根据文件类型和请求参数讟眮响应倎。", + "description": "成功获取建议问题。", "content": { - "image/png": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - }, - "headers": { - "Content-Type": { - "description": "文件的MIME类型", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "文件倧小字节劂果可甚", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "劂果as_attachment=true则讟眮䞺'attachment'", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "甚于性胜的猓存倎", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "对于音频/视频文件讟眮䞺'bytes'", + "application/json": { "schema": { - "type": "string", - "example": "bytes" + "$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": "错误请求。可胜的错误代码:\n- `invalid_param`: 匂垞参数蟓入。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } - } - } - }, - "403": { - "description": "犁止访问。可胜的错误代码:\n- `file_access_denied`: 文件访问被拒绝或文件䞍属于圓前应甚皋序。", + "description": "- `not_chat_app` : 应甚暡匏䞎 API 路由䞍匹配。\n- `bad_request` : 建议问题功胜已犁甚。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "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": "未扟到。可胜的错误代码:\n- `file_not_found`: 文件未扟到或已被删陀。", + "description": "`not_found` : 消息䞍存圚。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } } } }, "500": { - "description": "内郚服务噚错误。", + "description": "`internal_server_error` : 内郚服务噚错误。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } } } }, - "/chat-messages/{task_id}/stop": { + "/files/upload": { "post": { - "summary": "停止响应", - "description": "停止生成对话消息。仅支持流匏暡匏。", - "operationId": "stopBasicChatMessageGenerationCn", - "tags": ["对话消息"], - "parameters": [ - { - "name": "task_id", - "in": "path", - "required": true, - "description": "任务 ID可圚流匏返回 Chunk 䞭获取。", - "schema": { "type": "string", "format": "uuid" } - } + "summary": "䞊䌠文件", + "description": "䞊䌠文件甚于发送消息时䜿甚支持囟片、文档、音频和视频的倚暡态理解。䞊䌠的文件仅䟛圓前终端甚户䜿甚。", + "operationId": "uploadChatFileZh", + "tags": [ + "文件操䜜" ], "requestBody": { + "description": "文件䞊䌠请求。需芁 multipart/form-data 栌匏。", "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "file" + ], "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "芁䞊䌠的文件。支持的类型包括囟片、文档、音频和视频。" + }, "user": { "type": "string", - "description": "甚户标识必须和发送消息接口䌠入 user 保持䞀臎。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。" + "description": "甚户标识笊由匀发者定义的规则生成必须圚应甚内唯䞀。" } } } @@ -331,480 +488,3934 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "消息反銈点赞", - "description": "消息终端甚户反銈、点赞方䟿应甚匀发者䌘化蟓出预期。", - "operationId": "postBasicChatMessageFeedbackCn", - "tags": ["消息反銈"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestCn" } + "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" + } + } + } + } } - } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } - } - } - }, - "/app/feedbacks": { - "get": { - "summary": "获取APP的消息点赞和反銈", - "description": "获取应甚的终端甚户反銈、点赞。", - "operationId": "getBasicChatAppFeedbacksCn", - "tags": ["消息反銈"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamCn" } - ], - "responses": { - "200": { - "description": "成功获取应甚的反銈列衚。", + }, + "400": { + "description": "- `no_file_uploaded` : 请求䞭未提䟛文件。\n- `too_many_files` : 每次请求仅允讞䞊䌠䞀䞪文件。\n- `filename_not_exists_error` : 䞊䌠的文件没有文件名。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseCn" } + "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." + } + } + } } } - } - } - } - }, - "/messages/{message_id}/suggested": { - "get": { - "summary": "获取䞋䞀蜮建议问题列衚", - "description": "获取圓前消息的䞋䞀蜮建议问题列衚。", - "operationId": "getBasicChatSuggestedQuestionsCn", - "tags": ["对话消息"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } }, - { "$ref": "#/components/parameters/UserQueryParamCn" } - ], - "responses": { - "200": { - "description": "成功获取建议问题列衚。", + "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": { - "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponseCn" } + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } } } } } } }, - "/messages": { + "/files/{file_id}/preview": { "get": { - "summary": "获取䌚话历史消息", - "description": "滚劚加蜜圢匏返回历史聊倩记圕第䞀页返回最新 `limit` 条即倒序返回。", - "operationId": "getBasicChatConversationHistoryCn", - "tags": ["䌚话管理"], + "summary": "文件䞋蜜", + "description": "预览或䞋蜜之前通过[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 䞊䌠的文件。仅可访问属于请求应甚内消息的文件。", + "operationId": "previewChatFileZh", + "tags": [ + "文件操䜜" + ], "parameters": [ - { "$ref": "#/components/parameters/ConversationIdQueryParamCn" }, - { "$ref": "#/components/parameters/UserQueryParamCn" }, { - "name": "first_id", - "in": "query", - "description": "圓前页第䞀条聊倩记圕的 ID默讀 null。", - "schema": { "type": "string", "format": "uuid", "nullable": true } - }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Cn" } - ], + "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": "成功获取䌚话历史消息。", + "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": { - "schema": { "$ref": "#/components/schemas/BasicConversationHistoryResponseCn" } + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } } } } } } }, - "/conversations": { + "/end-users/{end_user_id}": { "get": { - "summary": "获取䌚话列衚", - "description": "获取圓前甚户的䌚话列衚默讀返回最近的 20 条。", - "operationId": "getBasicChatConversationsListCn", - "tags": ["䌚话管理"], + "summary": "获取终端甚户", + "description": "根据 ID 获取终端甚户信息。圓其他 API 返回终端甚户 ID䟋劂[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件)返回的 `created_by`时埈有甚。", + "operationId": "getChatEndUserZh", + "tags": [ + "终端甚户" + ], "parameters": [ - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { "$ref": "#/components/parameters/LastIdQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" }, - { "$ref": "#/components/parameters/SortByQueryParamCn" } + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "终端甚户 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } ], "responses": { "200": { - "description": "成功获取䌚话列衚。", + "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": { - "schema": { "$ref": "#/components/schemas/ConversationsListResponseCn" } + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } } } } } } }, - "/conversations/{conversation_id}": { - "delete": { - "summary": "删陀䌚话", - "description": "删陀䞀䞪指定的䌚话。", - "operationId": "deleteBasicChatConversationCn", - "tags": ["䌚话管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamCn" } ], + "/messages/{message_id}/feedbacks": { + "post": { + "summary": "消息反銈点赞", + "description": "提亀消息反銈。终端甚户可以对消息评价 `like` 或 `dislike`并可选择提䟛文字反銈。将 `rating` 讟䞺 `null` 可撀销之前提亀的反銈。", + "operationId": "createChatMessageFeedbackZh", + "tags": [ + "消息反銈" + ], + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "消息 ID。", + "schema": { + "type": "string" + } + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "type": "object", "required": ["user"], - "properties": { "user": { "type": "string", "description": "甚户标识。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。" } } + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "请求瀺䟋", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } } } } }, - "responses": { "204": { "description": "䌚话删陀成功无内容返回。" } } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "䌚话重呜名", - "description": "对䌚话进行重呜名。", - "operationId": "renameBasicChatConversationCn", - "tags": ["䌚话管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamCn" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequestCn" } } } - }, "responses": { - "200": { "description": "䌚话重呜名成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameResponseCn" } } } } + "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." + } + } + } + } + } + } } } }, - "/conversations/{conversation_id}/variables": { + "/app/feedbacks": { "get": { - "summary": "获取对话变量", - "description": "从特定对话䞭检玢变量。歀端点对于提取对话过皋䞭捕获的结构化数据非垞有甚。", - "operationId": "getBasicChatConversationVariablesCn", - "tags": ["䌚话管理"], + "summary": "获取应甚的消息点赞和反銈", + "description": "获取歀应甚䞭所有消息反銈的分页列衚包括终端甚户和管理员反銈。", + "operationId": "listChatFeedbacksZh", + "tags": [ + "消息反銈" + ], "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParamCn" }, - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { "$ref": "#/components/parameters/LastIdQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" }, - { "$ref": "#/components/parameters/VariableNameQueryParamCn" } + { + "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/ConversationVariablesResponseCn" } } } }, - "404": { "$ref": "#/components/responses/ConversationNotFoundCn" } - } - } - }, - "/audio-to-text": { - "post": { - "summary": "语音蜬文字", - "description": "将语音文件蜬换䞺文字。支持栌匏mp3, mp4, mpeg, mpga, m4a, wav, webm。文件倧小限制15MB。", - "operationId": "basicChatAudioToTextCn", - "tags": ["语音䞎文字蜬换"], - "requestBody": { - "required": true, - "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequestCn" } } } - }, - "responses": { - "200": { "description": "成功将语音蜬换䞺文字。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponseCn" } } } } + "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" + } + ] + } + } + } + } + } + } } } }, - "/text-to-audio": { - "post": { - "summary": "文字蜬语音", - "description": "将文字内容蜬换䞺语音。", - "operationId": "basicChatTextToAudioCn", - "tags": ["语音䞎文字蜬换"], - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TextToAudioFormRequestCn" } } + "/conversations": { + "get": { + "summary": "获取䌚话列衚", + "description": "获取圓前甚户的䌚话列衚按最近掻跃时闎排序。", + "operationId": "listChatConversationsZh", + "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": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, - "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } + "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." + } + } + } + } + } } } } }, - "/info": { - "get": { - "summary": "获取应甚基本信息", - "operationId": "getBasicChatAppInfoCn", - "tags": ["应甚配眮"], - "responses": { "200": { "description": "应甚基本信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseCn" } } } } } - } - }, - "/parameters": { - "get": { - "summary": "获取应甚参数", - "description": "甚于进入页面䞀匀始获取功胜匀关、蟓入参数名称、类型及默讀倌等䜿甚。", - "operationId": "getBasicChatAppParametersCn", - "tags": ["应甚配眮"], - "responses": { "200": { "description": "应甚参数信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAppParametersResponseCn" } } } } } - } - }, - "/meta": { - "get": { - "summary": "获取应甚Meta信息", - "description": "甚于获取工具 icon。", - "operationId": "getBasicChatAppMetaCn", - "tags": ["应甚配眮"], - "responses": { "200": { "description": "成功获取应甚 Meta 信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponseCn" } } } } } - } - }, - "/site": { + "/messages": { "get": { - "summary": "获取应甚 WebApp 讟眮", - "description": "甚于获取应甚的 WebApp 讟眮。", - "operationId": "getBasicChatWebAppSettingsCn", - "tags": ["应甚配眮"], - "responses": { "200": { "description": "WebApp 讟眮信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseCn" } } } } } - } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key 鉎权。所有 API 请求郜应圚 Authorization HTTP Header 䞭包含䜠的 API-Key栌匏䞺Bearer {API_KEY}。区烈建议匀发者把 API-Key 攟圚后端存傚而非客户端以免泄露。" } - }, - "parameters": { - "PageQueryParamCn": { "name": "page", "in": "query", "description": "页码选填默讀倌1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamCn": { "name": "limit", "in": "query", "description": "每页数量选填默讀倌20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Cn": { "name": "limit", "in": "query", "description": "䞀次请求返回倚少条记圕默讀 20 条。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100Cn": { "name": "limit", "in": "query", "description": "䞀次请求返回倚少条记圕默讀 20 条最倧 100 条最小 1 条。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParamCn": { "name": "user", "in": "query", "required": true, "description": "甚户标识由匀发者定义规则需保证甚户标识圚应甚内唯䞀。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。", "schema": { "type": "string" } }, - "ConversationIdQueryParamCn": { "name": "conversation_id", "in": "query", "required": true, "description": "䌚话 ID。", "schema": { "type": "string", "format": "uuid" } }, - "LastIdQueryParamCn": { "name": "last_id", "in": "query", "description": "选填圓前页最后面䞀条记圕的 ID默讀 null。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, - "SortByQueryParamCn": { "name": "sort_by", "in": "query", "description": "选填排序字段默讀 -updated_at (按曎新时闎倒序排列)。可选倌created_at, -created_at, updated_at, -updated_at。'-' 代衚倒序。", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParamCn": { "name": "conversation_id", "in": "path", "required": true, "description": "䌚话 ID。", "schema": { "type": "string", "format": "uuid" } }, - "VariableNameQueryParamCn": { "name": "variable_name", "in": "query", "description": "选填按变量名称筛选。", "schema": { "type": "string" } } - }, - "responses": { - "BadRequestGenericCn": { "description": "请求参数错误。可胜原因invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "BadRequestFileCn": { "description": "文件操䜜请求错误。可胜原因no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "FileTooLargeCn": { "description": "文件倪倧 (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "UnsupportedFileTypeFileCn": { "description": "䞍支持的文件类型 (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "S3ErrorFileCn": { "description": "S3 存傚服务错误。可胜原因s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "InternalServerErrorCn": { "description": "服务内郚匂垞。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "SuccessResultCn": { "description": "操䜜成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFoundCn": { "description": "对话䞍存圚。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "EndUserNotFoundCn": { "description": "终端甚户䞍存圚。错误码`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } } - }, - "schemas": { - "BasicChatRequestCn": { - "type": "object", - "required": ["query", "user"], - "properties": { - "query": { "type": "string", "description": "甚户蟓入/提问内容。" }, - "inputs": { - "type": "object", - "description": "允讞䌠入 App 定义的各变量倌。", - "additionalProperties": true, - "default": {} + "summary": "获取䌚话历史消息", + "description": "以滚劚加蜜的栌匏返回历史聊倩记圕銖页返回最新的 `limit` 条消息即按时闎倒序排列。", + "operationId": "listChatMessagesZh", + "tags": [ + "䌚话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "䌚话 ID。", + "schema": { + "type": "string" + } }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "响应暡匏。streaming (掚荐) 基于 SSEblocking 等埅执行完毕后返回 (Cloudflare 100秒超时限制Agent暡匏䞋䞍允讞)。" }, - "user": { "type": "string", "description": "甚户标识应甚内唯䞀。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "选填䌚话 ID甚于继续之前的对话。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/BasicInputFileObjectCn" }, "description": "选填䞊䌠的文件列衚 (目前仅支持囟片)。" }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "选填自劚生成䌚话标题默讀 true。" } - } - }, - "BasicInputFileObjectCn": { - "type": "object", - "required": ["type", "transfer_method"], - "properties": { - "type": { "type": "string", "enum": ["image"], "description": "文件类型目前仅支持 'image'。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "䌠递方匏remote_url 甚于囟片 URL / local_file 甚于文件䞊䌠" }, - "url": { "type": "string", "format": "url", "description": "囟片地址圓䌠递方匏䞺 remote_url 时" }, - "upload_file_id": { "type": "string", "format":"uuid", "description": "䞊䌠文件 ID必须通过事先䞊䌠文件接口获埗圓䌠递方匏䞺 local_file 时" } - }, - "anyOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "name": "user", + "in": "query", + "required": false, + "description": "甚户标识笊。", + "schema": { + "type": "string" + } }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format":"uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "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": "listChatConversationVariablesZh", + "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": "renameChatConversationZh", + "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": "deleteChatConversationZh", + "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": "chatAudioToTextZh", + "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": "chatTextToAudioZh", + "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": "getChatAppInfoZh", + "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": "getChatAppParametersZh", + "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": "getChatAppMetaZh", + "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": "getChatWebAppSettingsZh", + "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": { + "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": "应甚䜜者名称。" + } + } }, - "ChatCompletionResponseCn": { - "type": "object", "description": "阻塞暡匏䞋的完敎 App 结果。", - "properties": { - "event": { "type": "string", "example": "message", "description": "事件类型固定䞺 `message`。" }, - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, - "id": { "type": "string", "format": "uuid", "description": "唯䞀ID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯䞀 ID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "䌚话 ID。" }, - "mode": { "type": "string", "example": "chat", "description": "App 暡匏固定䞺 `chat`。" }, - "answer": { "type": "string", "description": "完敎回倍内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataCn" }, - "created_at": { "type": "integer", "format": "int64", "description": "消息创建时闎戳。" } - } - }, - "ResponseMetadataCn": { - "type": "object", "description": "元数据。", - "properties": { "usage": { "$ref": "#/components/schemas/UsageCn" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceCn" }, "description": "匕甚和園属分段列衚。" } } - }, - "ChunkBasicChatEventCn": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "agent_message", "agent_thought", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], "description": "事件类型。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "message": "#/components/schemas/StreamEventChatMessageCn", - "agent_message": "#/components/schemas/StreamEventAgentMessageCn", - "agent_thought": "#/components/schemas/StreamEventAgentThoughtCn", - "message_file": "#/components/schemas/StreamEventMessageFileCn", - "message_end": "#/components/schemas/StreamEventMessageEndCn", - "tts_message": "#/components/schemas/StreamEventTtsMessageCn", - "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndCn", - "message_replace": "#/components/schemas/StreamEventMessageReplaceCn", - "error": "#/components/schemas/StreamEventErrorCn", - "ping": "#/components/schemas/StreamEventPingCn" - }} - }, - "StreamEventBaseChatCn": { - "type": "object", "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": "创建时闎戳。" } - } - }, - "StreamEventChatMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLM 返回文本块内容。" } } } ] }, - "StreamEventAgentMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "Agent暡匏䞋 LLM 返回文本块内容。" } } } ] }, - "StreamEventAgentThoughtCn": { - "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, - { "type": "object", "required": ["id", "position"], + "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": { - "id": { "type": "string", "format": "uuid", "description": "agent_thought ID。" }, - "position": { "type": "integer", "description": "agent_thought 圚消息䞭的䜍眮。" }, - "thought": { "type": "string", "description": "agent 的思考内容。" }, - "observation": { "type": "string", "description": "工具调甚的返回结果。" }, - "tool": { "type": "string", "description": "䜿甚的工具列衚以 ';' 分割。" }, - "tool_input": { "type": "string", "description": "工具的蟓入JSON 栌匏的字笊䞲。" }, - "message_files": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "圓前 agent_thought 关联的文件ID列衚 (原描述䞺 file_id 字笊䞲修正䞺数组以匹配 agent_thoughts 历史消息䞭的 files)。" } + "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" + } ] }, - "StreamEventMessageFileCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { "id": { "type": "string", "format": "uuid", "description": "文件唯䞀ID。" }, "type": { "type": "string", "enum": ["image"], "description": "文件类型目前仅䞺 image。" }, "belongs_to": { "type": "string", "enum": ["assistant"], "description": "文件園属仅䞺 assistant。" }, "url": { "type": "string", "format": "url", "description": "文件访问地址。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "䌚话ID。" } } } ] }, - "StreamEventMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataCn" } } } ] }, - "StreamEventTtsMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 猖码的音频块。" } } } ] }, - "StreamEventTtsMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空字笊䞲。" } } } ] }, - "StreamEventMessageReplaceCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "替换内容盎接替换 LLM 所有回倍文本。" } } } ] }, - "StreamEventErrorCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "type": "object", "required": ["task_id", "status", "code", "message"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "消息唯䞀 ID错误事件䞭可胜䞍存圚。" }, "status": { "type": "integer", "description": "HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } ] }, - "StreamEventPingCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkBasicChatEventCn" }, { "type": "object", "description": "每 10s 䞀次的 ping 事件保持连接存掻。" } ] }, - "UsageCn": { "type": "object", "description": "暡型甚量信息。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceCn": { "type": "object", "description": "匕甚和園属分段信息。", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } }, - "FileUploadResponseCn": { "type": "object", "description": "文件䞊䌠成功后的响应。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件倧小 (byte)。" }, "extension": { "type": "string", "description": "文件后猀。" }, "mime_type": { "type": "string", "description": "文件 mime-type。" }, "created_by": { "type": "string", "format": "uuid", "description": "䞊䌠人 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "䞊䌠时闎。" } } }, - "EndUserDetailCn": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } - } - }, - "MessageFeedbackRequestCn": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "点赞 'like', 点螩 'dislike', 撀销点赞 null。" }, "user": { "type": "string", "description": "甚户标识。" }, "content": { "type": "string", "nullable": true, "description": "消息反銈的具䜓信息。" } } }, - "AppFeedbacksResponseCn": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemCn" }, "description": "返回该APP的点赞、反銈列衚。" } } }, - "FeedbackItemCn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "SuggestedQuestionsResponseCn": { "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "description": "建议问题列衚。" } } }, - "BasicConversationHistoryResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返回条数。" }, "has_more": { "type": "boolean", "description": "是吊存圚䞋䞀页。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BasicConversationMessageItemCn" }, "description": "消息列衚。" } } }, - "BasicConversationMessageItemCn": { "type": "object", "description": "䌚话䞭的单条消息。", "properties": { "id": { "type": "string", "format": "uuid", "description": "消息 ID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "䌚话 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "甚户蟓入参数。" }, "query": { "type": "string", "description": "甚户蟓入/提问内容。" }, "answer": { "type": "string", "description": "回答消息内容。" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItemCn" }, "description": "消息文件列衚。" }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"], "description": "点赞 'like' / 点螩 'dislike'。" } }, "description": "反銈信息。" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceCn" }, "description": "匕甚和園属分段列衚。" }, "agent_thoughts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentThoughtItemCn" }, "description": "Agent思考内容仅Agent暡匏䞋䞍䞺空。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎。" } } }, - "MessageFileItemCn": { "type": "object", "description": "消息䞭的文件项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "文件类型䟋劂 'image'。" }, "url": { "type": "string", "format": "url", "description": "预览囟片地址。" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "文件園属方。" } } }, - "AgentThoughtItemCn": { - "type": "object", "description": "Agent思考内容。", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "agent_thought ID。" }, - "chain_id": { "type": "string", "format": "uuid", "nullable": true, "description": "瀺䟋䞭存圚描述䞭未明确暂定䞺可选"}, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯䞀ID。" }, - "position": { "type": "integer", "description": "agent_thought圚消息䞭的䜍眮。" }, - "thought": { "type": "string", "description": "agent的思考内容。" }, - "tool": { "type": "string", "description": "䜿甚的工具列衚以 ';' 分割。" }, - "tool_input": { "type": "string", "description": "工具的蟓入JSON栌匏的字笊䞲。" }, - "observation": { "type": "string", "description": "工具调甚的返回结果。" }, - "files": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "圓前agent_thought关联的文件ID (瀺䟋䞭䞺filesmarkdown䞭䞺message_files.file_id)。" }, - "created_at": { "type": "integer", "format": "int64", "description": "创建时闎戳。" } - } - }, - "ConversationsListResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返回条数。" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItemCn" }, "description": "䌚话列衚。" } } }, - "ConversationListItemCn": { "type": "object", "description": "䌚话列衚䞭的单项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "䌚话 ID。" }, "name": { "type": "string", "description": "䌚话名称。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "甚户蟓入参数。" }, "status": { "type": "string", "description": "䌚话状态。" }, "introduction": { "type": "string", "nullable": true, "description": "匀场癜。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎。" }, "updated_at": { "type": "integer", "format": "int64", "description": "曎新时闎。" } } }, - "ConversationRenameRequestCn": { "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true, "description": "选填名称若 auto_generate 䞺 true 时可䞍䌠。" }, "auto_generate": { "type": "boolean", "default": false, "description": "选填自劚生成标题默讀 false。" }, "user": { "type": "string", "description": "甚户标识。" } } }, - "ConversationRenameResponseCn": { "$ref": "#/components/schemas/ConversationListItemCn" }, - "ConversationVariablesResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "每页项目数。" }, "has_more": { "type": "boolean", "description": "是吊有曎倚项目。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItemCn" }, "description": "变量列衚。" } } }, - "ConversationVariableItemCn": { "type": "object", "description": "对话䞭的变量项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "变量ID。" }, "name": { "type": "string", "description": "变量名称。" }, "value_type": { "type": "string", "description": "变量类型 (string, number, boolean 等)。" }, "value": { "type": "string", "description": "变量倌。" }, "description": { "type": "string", "nullable": true, "description": "变量描述。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎戳。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最后曎新时闎戳。" } } }, - "AudioToTextRequestCn": { "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "语音文件。支持栌匏['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']。倧小限制15MB。" }, "user": { "type": "string", "description": "甚户标识。" } } }, - "AudioToTextResponseCn": { "type": "object", "properties": { "text": { "type": "string", "description": "蟓出文字。" } } }, - "TextToAudioFormRequestCn": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "消息ID (䌘先)。" }, "text": { "type": "string", "description": "语音生成内容。" }, "user": { "type": "string", "description": "甚户标识。" } }, "description": "需芁 `user`。提䟛 `message_id` 或 `text`。" }, - "AppInfoResponseCn": { "type": "object", "description": "应甚基本信息。", "properties": { "name": { "type": "string", "description": "应甚名称。" }, "description": { "type": "string", "description": "应甚描述。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "应甚标筟。" } } }, - "ChatAppParametersResponseCn": { "type": "object", "description": "应甚参数信息。", "properties": { "opening_statement": { "type": "string", "description": "匀场癜。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "匀场掚荐问题列衚。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" } }, "description": "启甚回答后给出掚荐问题。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" } }, "description": "语音蜬文本。" }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" }, "voice": { "type": "string", "description": "语音类型。" }, "language": { "type": "string", "description": "语蚀。" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"], "description": "自劚播攟enabled 匀启, disabled 关闭。" } }, "description": "文本蜬语音。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" } }, "description": "匕甚和園属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" } }, "description": "标记回倍。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemCn" }, "description": "甚户蟓入衚单配眮。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "囟片讟眮。支持 png, jpg, jpeg, webp, gif。" } }, "description": "文件䞊䌠配眮。" }, "system_parameters": { "type": "object", "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)。" } }, "description": "系统参数。" } } }, - "UserInputFormItemCn": { "type": "object", "description": "甚户蟓入衚单䞭的控件项。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperCn" }, { "$ref": "#/components/schemas/ParagraphControlWrapperCn" }, { "$ref": "#/components/schemas/SelectControlWrapperCn" } ] }, - "TextInputControlWrapperCn": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlCn" } }, "required":["text-input"] }, - "ParagraphControlWrapperCn": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlCn" } }, "required":["paragraph"] }, - "SelectControlWrapperCn": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlCn" } }, "required":["select"] }, - "TextInputControlCn": { "type": "object", "description": "文本蟓入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "nullable": true, "description": "默讀倌。" } } }, - "ParagraphControlCn": { "type": "object", "description": "段萜文本蟓入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "nullable": true, "description": "默讀倌。" } } }, - "SelectControlCn": { "type": "object", "description": "䞋拉控件。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "nullable": true, "description": "默讀倌。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "选项倌。" } } }, - "AppMetaResponseCn": { "type": "object", "description": "应甚 Meta 信息。", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url", "description": "囟标 URL。" }, { "$ref": "#/components/schemas/ToolIconDetailCn" } ] }, "description": "工具囟标键䞺工具名称。" } } }, - "ToolIconDetailCn": { "type": "object", "description": "工具囟标诊情。", "properties": { "background": { "type": "string", "description": "hex 栌匏的背景色。" }, "content": { "type": "string", "description": "emoji。" } } }, - "WebAppSettingsResponseCn": { "type": "object", "description": "应甚 WebApp 讟眮。", "properties": { "title": { "type": "string", "description": "WebApp 名称。" }, "chat_color_theme": { "type": "string", "description": "聊倩颜色䞻题, hex 栌匏。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "聊倩颜色䞻题是吊反蜬。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "囟标类型。" }, "icon": { "type": "string", "description": "囟标内容 (emoji 或囟片 URL)。" }, "icon_background": { "type": "string", "description": "hex 栌匏的背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "囟标 URL。" }, "description": { "type": "string", "description": "描述。" }, "copyright": { "type": "string", "description": "版权信息。" }, "privacy_policy": { "type": "string", "description": "隐私政策铟接。" }, "custom_disclaimer": { "type": "string", "description": "自定义免莣声明。" }, "default_language": { "type": "string", "description": "默讀语蚀。" }, "show_workflow_steps": { "type": "boolean", "description": "是吊星瀺工䜜流诊情。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "是吊䜿甚 WebApp 囟标替换聊倩䞭的机噚人囟标。" } } }, - "ErrorResponseCn": { "type": "object", "description": "错误响应。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTP 状态码。" }, "code": { "type": "string", "nullable": true, "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } + "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": "䞎聊倩消息和亀互盞关的操䜜。" + }, + { + "name": "文件操䜜", + "description": "文件䞊䌠和预览操䜜。" + }, + { + "name": "终端甚户", + "description": "终端甚户信息盞关操䜜。" + }, + { + "name": "消息反銈", + "description": "甚户反銈操䜜。" + }, + { + "name": "䌚话管理", + "description": "䞎管理䌚话盞关的操䜜。" + }, + { + "name": "语音䞎文字蜬换", + "description": "文字蜬语音和语音蜬文字操䜜。" + }, + { + "name": "应甚配眮", + "description": "获取应甚讟眮和信息的操䜜。" + }, + { + "name": "标泚管理", + "description": "䞎管理标泚盎接回倍盞关的操䜜。" + } ] -} \ No newline at end of file +} diff --git a/zh/api-reference/openapi_chatflow.json b/zh/api-reference/openapi_chatflow.json index 341280133..c80828f74 100644 --- a/zh/api-reference/openapi_chatflow.json +++ b/zh/api-reference/openapi_chatflow.json @@ -1,18 +1,18 @@ { "openapi": "3.0.1", "info": { - "title": "工䜜流猖排对话型应甚 API (Chatflow API)", - "description": "对话应甚支持䌚话持久化可将之前的聊倩记圕䜜䞺䞊䞋文进行回答可适甚于聊倩/客服 AI 等。", + "title": "工䜜流猖排对话型应甚 API (对话流 API)", + "description": "对话流应甚支持䌚话持久化允讞将之前的聊倩记圕䜜䞺响应的䞊䞋文。对话流应甚䜿甚 `advanced-chat` 暡匏提䟛工䜜流级别的流匏事件甚于诊细的执行远螪包括节点匀始、完成、迭代和工䜜流生呜呚期。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API 的基础 URL。请将 {api_base_url} 替换䞺䜠的应甚提䟛的实际 API 基础 URL。", + "description": "工䜜流猖排对话型应甚 API 的基础 URL。请将 {api_base_url} 替换䞺䜠的应甚实际提䟛的 API 基础 URL。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "实际的 API 基础 URL" + "description": "API 的实际基础 URL" } } } @@ -26,27 +26,29 @@ "/chat-messages": { "post": { "summary": "发送对话消息", - "description": "创建䌚话消息。", - "operationId": "sendChatMessageCn", - "tags": ["对话消息"], + "description": "向对话型应甚发送请求。", + "operationId": "createChatflowMessageZh", + "tags": [ + "对话消息" + ], "requestBody": { "description": "发送对话消息的请求䜓。", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatRequestCn" + "$ref": "#/components/schemas/ChatRequest" }, "examples": { - "streaming_with_file": { - "summary": "包含文件和自定义蟓入的流匏请求瀺䟋", + "streaming_example": { + "summary": "请求瀺䟋 - 流匏暡匏", "value": { "inputs": { - "name": "dify" + "city": "San Francisco" }, - "query": "iPhone 13 Pro Max 的规栌是什么", + "query": "What are the specs of the iPhone 13 Pro Max?", "response_mode": "streaming", - "conversation_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "conversation_id": "", "user": "abc-123", "files": [ { @@ -56,6 +58,16 @@ } ] } + }, + "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" + } } } } @@ -63,267 +75,436 @@ }, "responses": { "200": { - "description": "请求成功。响应的内容类型和结构取决于请求䞭的 `response_mode` 参数。\n- 圓 `response_mode` 䞺 `blocking` 时返回 `application/json` 栌匏的 `ChatCompletionResponseCn` 对象。\n- 圓 `response_mode` 䞺 `streaming` 时返回 `text/event-stream` 栌匏的 `ChunkChatEventCn` 对象流匏序列。", + "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/ChatCompletionResponseCn" + "$ref": "#/components/schemas/ChatCompletionResponse" + }, + "examples": { + "blockingResponse": { + "summary": "响应瀺䟋 - 阻塞暡匏", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "advanced-chat", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\" \"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "SSE 事件流。每䞪事件以 'data: ' 匀倎以 '\\n\\n' 结尟。具䜓结构请参见 `ChunkChatEventCn`。" + "description": "服务噚发送事件 (SSE) 流。每䞪事件是䞀䞪以 `data: ` 䞺前猀的 JSON 对象以䞀䞪换行笊终止。\n\n**SSE 解析指南**每䞪事件是䞀行以 `data: ` 䞺前猀的 JSON 对象以 `\\n\\n` 终止。解析 JSON 前先去陀 `data: ` 前猀。JSON 内的 `event` 字段决定事件类型。圓收到终止事件劂 `message_end`、`workflow_finished` 或 `error`时流结束。応略 `ping` 事件每 10 秒发送䞀次以保持连接掻跃。泚意即䜿流䞭出现错误事件HTTP 状态码仍䞺 `200`。" + }, + "examples": { + "streamingResponseBasic": { + "summary": "Response Example - Streaming (Basic)", + "value": "data: {\"event\": \"message\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"answer\": \" I\", \"created_at\": 1679586595} data: {\"event\": \"message_end\", \"task_id\":\"mock_task_id\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"conversation_id\": \"45701982-8118-4bc5-8e9b-64562b4555f2\", \"metadata\": {\"usage\": {\"total_tokens\": 10, \"latency\": 1.0}}}" + }, + "streamingResponseWorkflow": { + "summary": "Response Example - Streaming (工䜜流)", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"inputs\": {\"city\": \"San Francisco\"}, \"created_at\": 1705395332}} data: {\"event\": \"node_started\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"created_at\": 1705395332}} data: {\"event\": \"message\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"answer\": \" I\", \"created_at\": 1705395333} data: {\"event\": \"node_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"ne_001\", \"node_id\": \"node_llm_1\", \"node_type\": \"llm\", \"title\": \"LLM\", \"index\": 1, \"status\": \"succeeded\", \"elapsed_time\": 1.5, \"created_at\": 1705395332, \"finished_at\": 1705395334}} data: {\"event\": \"message_end\", \"task_id\": \"task123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"metadata\": {\"usage\": {\"total_tokens\": 50, \"latency\": 2.5}}} data: {\"event\": \"workflow_finished\", \"task_id\": \"task123\", \"workflow_run_id\": \"wfr_abc123\", \"message_id\": \"msg123\", \"conversation_id\": \"conv123\", \"data\": {\"id\": \"wfr_abc123\", \"workflow_id\": \"wf_def456\", \"status\": \"succeeded\", \"elapsed_time\": 2.5, \"total_tokens\": 50, \"total_steps\": 2, \"created_at\": 1705395332, \"finished_at\": 1705395335}}" + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestGenericCn" }, - "404": { "$ref": "#/components/responses/ConversationNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } - } - } - }, - "/files/upload": { - "post": { - "summary": "䞊䌠文件", - "description": "䞊䌠文件并圚发送消息时䜿甚可实现囟文倚暡态理解。支持䜠的应甚皋序所支持的所有栌匏。䞊䌠的文件仅䟛圓前终端甚户䜿甚。", - "operationId": "uploadFileCn", - "tags": ["文件操䜜"], - "requestBody": { - "description": "文件䞊䌠请求。需䜿甚 `multipart/form-data` 进行请求。", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "芁䞊䌠的文件。" + "400": { + "description": "- `app_unavailable` : 应甚䞍可甚或配眮错误。\n- `not_chat_app` : App mode does not match the API route.\n- `conversation_completed` : The conversation has ended.\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。\n- `provider_quota_exceeded` : 暡型提䟛商配额已甚尜。\n- `model_currently_not_support` : 圓前暡型䞍可甚。\n- `completion_request_error` : 文本生成倱莥。\n- `bad_request` : Cannot use draft 工䜜流 version.\n- `bad_request` : Invalid `workflow_id` format.", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } }, - "user": { - "type": "string", - "description": "甚户标识必须和发送消息接口䌠入 user 保持䞀臎。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。" + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "conversation_completed": { + "summary": "conversation_completed", + "value": { + "status": 400, + "code": "conversation_completed", + "message": "The conversation has ended. Please start a new conversation." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "is_draft_workflow": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. " + } + }, + "workflow_id_format_error": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Invalid workflow_id format: 'not-a-valid-id'. " + } } } } } - } - }, - "responses": { - "200": { - "description": "文件䞊䌠成功。", + }, + "404": { + "description": "- `not_found` : Conversation does not exist.\n- `not_found` : 工䜜流 not found with the specified `workflow_id`.", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponseCn" + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "workflow_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab" + } + } } } } }, - "201": { - "description": "文件创建成功 (倇选成功状态码)。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseCn" } } } + "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" + } + } + } + } + } }, - "400": { "$ref": "#/components/responses/BadRequestFileCn" }, - "413": { "$ref": "#/components/responses/FileTooLargeCn" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileCn" }, - "503": { "$ref": "#/components/responses/S3ErrorFileCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } + "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." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { - "get": { - "summary": "获取终端甚户", - "description": "通过 ID 获取终端甚户信息。\n\n圓其他 API 返回终端甚户 ID䟋劂文件䞊䌠接口返回的 `created_by`时可䜿甚该接口查询对应的终端甚户信息。", - "operationId": "getEndUserChatflowCn", - "tags": ["终端甚户"], + "/chat-messages/{task_id}/stop": { + "post": { + "summary": "停止响应", + "description": "停止聊倩消息生成任务。仅圚 `streaming` 暡匏䞋支持。", + "operationId": "stopChatflowMessageZh", + "tags": [ + "对话消息" + ], "parameters": [ { - "name": "end_user_id", + "name": "task_id", "in": "path", "required": true, - "description": "终端甚户 ID。", - "schema": { "type": "string", "format": "uuid" } + "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": { - "description": "成功获取终端甚户信息。", + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "`not_chat_app` : 应甚暡匏䞎 API 路由䞍匹配。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/EndUserDetailCn" } + "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": { "$ref": "#/components/responses/EndUserNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } + } } } }, - "/files/{file_id}/preview": { + "/messages/{message_id}/suggested": { "get": { - "summary": "文件预览", - "description": "预览或䞋蜜已䞊䌠的文件。歀端点允讞䜠访问之前通过文件䞊䌠API䞊䌠的文件。文件只胜圚所属的应甚皋序消息内访问。", - "operationId": "previewChatFlowFileCn", - "tags": ["文件操䜜"], + "summary": "获取䞋䞀蜮建议问题列衚", + "description": "获取圓前消息的䞋䞀步建议问题。", + "operationId": "getChatflowSuggestedQuestionsZh", + "tags": [ + "对话消息" + ], "parameters": [ { - "name": "file_id", + "name": "message_id", "in": "path", "required": true, - "description": "芁预览的文件的唯䞀标识笊从文件䞊䌠API响应䞭获取。", + "description": "消息 ID。", "schema": { - "type": "string", - "format": "uuid" + "type": "string" } }, { - "name": "as_attachment", + "name": "user", "in": "query", - "required": false, - "description": "是吊区制䜜䞺附件䞋蜜文件。默讀䞺`false`圚浏览噚䞭预览。", + "required": true, + "description": "甚户标识笊。", "schema": { - "type": "boolean", - "default": false + "type": "string" } } ], "responses": { "200": { - "description": "文件内容成功返回。根据文件类型和请求参数讟眮响应倎。", + "description": "成功获取建议问题。", "content": { - "image/png": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/jpeg": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/webp": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "image/gif": { - "schema": { - "type": "string", - "format": "binary" - } - }, - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - }, - "headers": { - "Content-Type": { - "description": "文件的MIME类型", - "schema": { - "type": "string" - } - }, - "Content-Length": { - "description": "文件倧小字节劂果可甚", - "schema": { - "type": "integer" - } - }, - "Content-Disposition": { - "description": "劂果as_attachment=true则讟眮䞺'attachment'", - "schema": { - "type": "string" - } - }, - "Cache-Control": { - "description": "甚于性胜的猓存倎", - "schema": { - "type": "string", - "example": "public, max-age=3600" - } - }, - "Accept-Ranges": { - "description": "对于音频/视频文件讟眮䞺'bytes'", + "application/json": { "schema": { - "type": "string", - "example": "bytes" + "$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": "错误请求。可胜的错误代码:\n- `invalid_param`: 匂垞参数蟓入。", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } - } - } - }, - "403": { - "description": "犁止访问。可胜的错误代码:\n- `file_access_denied`: 文件访问被拒绝或文件䞍属于圓前应甚皋序。", + "description": "- `not_chat_app` : 应甚暡匏䞎 API 路由䞍匹配。\n- `bad_request` : 建议问题功胜已犁甚。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "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": "未扟到。可胜的错误代码:\n- `file_not_found`: 文件未扟到或已被删陀。", + "description": "`not_found` : 消息䞍存圚。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Message Not Exists." + } + } + } } } }, "500": { - "description": "内郚服务噚错误。", + "description": "`internal_server_error` : 内郚服务噚错误。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } } } }, - "/chat-messages/{task_id}/stop": { + "/files/upload": { "post": { - "summary": "停止响应", - "description": "停止生成对话消息。仅支持流匏暡匏。", - "operationId": "stopChatMessageGenerationCn", - "tags": ["对话消息"], - "parameters": [ - { - "name": "task_id", - "in": "path", - "required": true, - "description": "任务 ID可圚流匏返回 Chunk 䞭获取。", - "schema": { "type": "string", "format": "uuid" } - } + "operationId": "uploadChatflowFileZh", + "tags": [ + "文件操䜜" ], + "summary": "䞊䌠文件", + "description": "䞊䌠文件甚于发送消息时䜿甚支持囟片、文档、音频和视频的倚暡态理解。䞊䌠的文件仅䟛圓前终端甚户䜿甚。", "requestBody": { + "description": "文件䞊䌠请求。需芁 multipart/form-data 栌匏。", "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "file" + ], "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "芁䞊䌠的文件。支持的类型包括囟片、文档、音频和视频。" + }, "user": { "type": "string", - "description": "甚户标识必须和发送消息接口䌠入 user 保持䞀臎。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。" + "description": "甚户标识笊由匀发者定义的规则生成必须圚应甚内唯䞀。" } } } @@ -331,522 +512,5688 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } - } - } - }, - "/messages/{message_id}/feedbacks": { - "post": { - "summary": "消息反銈点赞", - "description": "消息终端甚户反銈、点赞方䟿应甚匀发者䌘化蟓出预期。", - "operationId": "postMessageFeedbackCn", - "tags": ["消息反銈"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequestCn" } + "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" + } + } + } + } } - } - }, - "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } - } - } - }, - "/app/feedbacks": { - "get": { - "summary": "获取APP的消息点赞和反銈", - "description": "获取应甚的终端甚户反銈、点赞。", - "operationId": "getAppFeedbacksCn", - "tags": ["消息反銈"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamCn" } - ], - "responses": { - "200": { - "description": "成功获取应甚的反銈列衚。", + }, + "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": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponseCn" } + "examples": { + "file_too_large": { + "summary": "file_too_large", + "value": { + "status": 413, + "code": "file_too_large", + "message": "File size exceeded." + } + } + } } } - } - } - } - }, - "/messages/{message_id}/suggested": { - "get": { - "summary": "获取䞋䞀蜮建议问题列衚", - "description": "获取圓前消息的䞋䞀蜮建议问题列衚。", - "operationId": "getSuggestedQuestionsCn", - "tags": ["对话消息"], - "parameters": [ - { - "name": "message_id", - "in": "path", - "required": true, - "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } }, - { "$ref": "#/components/parameters/UserQueryParamCn" } - ], - "responses": { - "200": { - "description": "成功获取建议问题列衚。", + "415": { + "description": "`unsupported_file_type` : 䞍允讞的文件类型。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/SuggestedQuestionsResponseCn" } + "examples": { + "unsupported_file_type": { + "summary": "unsupported_file_type", + "value": { + "status": 415, + "code": "unsupported_file_type", + "message": "File type not allowed." + } + } + } } } } } } }, - "/messages": { + "/files/{file_id}/preview": { "get": { - "summary": "获取䌚话历史消息", - "description": "滚劚加蜜圢匏返回历史聊倩记圕第䞀页返回最新 `limit` 条即倒序返回。", - "operationId": "getConversationHistoryCn", - "tags": ["䌚话管理"], + "operationId": "previewChatflowFileZh", + "tags": [ + "文件操䜜" + ], + "summary": "文件䞋蜜", + "description": "预览或䞋蜜之前通过[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 䞊䌠的文件。仅可访问属于请求应甚内消息的文件。", "parameters": [ - { "$ref": "#/components/parameters/ConversationIdQueryParamCn" }, - { "$ref": "#/components/parameters/UserQueryParamCn" }, { - "name": "first_id", + "name": "file_id", + "in": "path", + "required": true, + "description": "芁预览的文件唯䞀标识笊从 [文件䞊䌠](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", "in": "query", - "description": "圓前页第䞀条聊倩记圕的 ID默讀 null。", - "schema": { "type": "string", "format": "uuid", "nullable": true } + "required": false, + "description": "劂果䞺 `true`则区制文件以附件圢匏䞋蜜而䞍是圚浏览噚䞭预览。", + "schema": { + "type": "boolean", + "default": false + } }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Cn" } + { + "name": "user", + "in": "query", + "required": false, + "description": "甚户标识笊甚于终端甚户䞊䞋文。", + "schema": { + "type": "string" + } + } ], "responses": { "200": { - "description": "成功获取䌚话历史消息。", + "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": { - "schema": { "$ref": "#/components/schemas/ConversationHistoryResponseCn" } + "examples": { + "file_not_found": { + "summary": "file_not_found", + "value": { + "status": 404, + "code": "file_not_found", + "message": "The requested file was not found." + } + } + } } } } } } }, - "/conversations": { + "/end-users/{end_user_id}": { "get": { - "summary": "获取䌚话列衚", - "description": "获取圓前甚户的䌚话列衚默讀返回最近的 20 条。", - "operationId": "getConversationsListCn", - "tags": ["䌚话管理"], + "operationId": "getChatflowEndUserZh", + "tags": [ + "终端甚户" + ], + "summary": "获取终端甚户", + "description": "根据 ID 获取终端甚户信息。圓其他 API 返回终端甚户 ID䟋劂[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件)返回的 `created_by`时埈有甚。", "parameters": [ - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { "$ref": "#/components/parameters/LastIdQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" }, - { "$ref": "#/components/parameters/SortByQueryParamCn" } + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "终端甚户 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } ], "responses": { "200": { - "description": "成功获取䌚话列衚。", + "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": { - "schema": { "$ref": "#/components/schemas/ConversationsListResponseCn" } + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } } } } } } }, - "/conversations/{conversation_id}": { - "delete": { - "summary": "删陀䌚话", - "description": "删陀䞀䞪指定的䌚话。", - "operationId": "deleteConversationCn", - "tags": ["䌚话管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamCn" } ], + "/messages/{message_id}/feedbacks": { + "post": { + "operationId": "createChatflowMessageFeedbackZh", + "tags": [ + "消息反銈" + ], + "summary": "消息反銈点赞", + "description": "提亀消息反銈。终端甚户可以对消息评价 `like` 或 `dislike`并可选择提䟛文字反銈。将 `rating` 讟䞺 `null` 可撀销之前提亀的反銈。", + "parameters": [ + { + "name": "message_id", + "in": "path", + "required": true, + "description": "消息 ID。", + "schema": { + "type": "string" + } + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "type": "object", "required": ["user"], - "properties": { "user": { "type": "string", "description": "甚户标识。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。" } } + "$ref": "#/components/schemas/MessageFeedbackRequest" + }, + "examples": { + "likeFeedback": { + "summary": "请求瀺䟋", + "value": { + "rating": "like", + "user": "abc-123", + "content": "This answer was very helpful!" + } + } } } } }, - "responses": { "204": { "description": "䌚话删陀成功无内容返回。" } } - } - }, - "/conversations/{conversation_id}/name": { - "post": { - "summary": "䌚话重呜名", - "description": "对䌚话进行重呜名。", - "operationId": "renameConversationCn", - "tags": ["䌚话管理"], - "parameters": [ { "$ref": "#/components/parameters/ConversationIdPathParamCn" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameRequestCn" } } } - }, "responses": { - "200": { "description": "䌚话重呜名成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationRenameResponseCn" } } } } + "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." + } + } + } + } + } + } } } }, - "/conversations/{conversation_id}/variables": { + "/app/feedbacks": { "get": { - "summary": "获取对话变量", - "description": "从特定对话䞭检玢变量。歀端点对于提取对话过皋䞭捕获的结构化数据非垞有甚。", - "operationId": "getConversationVariablesCn", - "tags": ["䌚话管理"], + "operationId": "listChatflowFeedbacksZh", + "tags": [ + "消息反銈" + ], + "summary": "获取应甚的消息点赞和反銈", + "description": "获取歀应甚䞭所有消息反銈的分页列衚包括终端甚户和管理员反銈。", "parameters": [ - { "$ref": "#/components/parameters/ConversationIdPathParamCn" }, - { "$ref": "#/components/parameters/UserQueryParamCn" }, - { "$ref": "#/components/parameters/LastIdQueryParamCn" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" } + { + "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/ConversationVariablesResponseCn" } } } }, - "404": { "$ref": "#/components/responses/ConversationNotFoundCn" } - } - } - }, - "/audio-to-text": { - "post": { - "summary": "语音蜬文字", - "description": "将语音文件蜬换䞺文字。支持栌匏mp3, mp4, mpeg, mpga, m4a, wav, webm。文件倧小限制15MB。", - "operationId": "audioToTextCn", - "tags": ["语音䞎文字蜬换"], - "requestBody": { - "required": true, - "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AudioToTextRequestCn" } } } - }, - "responses": { - "200": { "description": "成功将语音蜬换䞺文字。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioToTextResponseCn" } } } } - } - } - }, - "/text-to-audio": { - "post": { - "summary": "文字蜬语音", - "description": "将文字内容蜬换䞺语音。", - "operationId": "textToAudioCn", - "tags": ["语音䞎文字蜬换"], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextToAudioJsonRequestCn" } } } - }, "responses": { "200": { - "description": "成功生成语音文件。", - "content": { "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/mp3": { "schema": { "type": "string", "format": "binary" } } }, - "headers": { "Content-Type": { "schema": { "type": "string", "example": "audio/wav" } } } + "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" + } + ] + } + } + } + } + } } } } }, - "/info": { - "get": { - "summary": "获取应甚基本信息", - "operationId": "getAppInfoCn", - "tags": ["应甚配眮"], - "responses": { "200": { "description": "应甚基本信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseCn" } } } } } - } - }, - "/parameters": { - "get": { - "summary": "获取应甚参数", - "description": "甚于进入页面䞀匀始获取功胜匀关、蟓入参数名称、类型及默讀倌等䜿甚。", - "operationId": "getAppParametersCn", - "tags": ["应甚配眮"], - "responses": { "200": { "description": "应甚参数信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAppParametersResponseCn" } } } } } - } - }, - "/meta": { - "get": { - "summary": "获取应甚Meta信息", - "description": "甚于获取工具 icon。", - "operationId": "getAppMetaCn", - "tags": ["应甚配眮"], - "responses": { "200": { "description": "成功获取应甚 Meta 信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetaResponseCn" } } } } } - } - }, - "/site": { - "get": { - "summary": "获取应甚 WebApp 讟眮", - "description": "甚于获取应甚的 WebApp 讟眮。", - "operationId": "getWebAppSettingsCn", - "tags": ["应甚配眮"], - "responses": { "200": { "description": "WebApp 讟眮信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponseCn" } } } } } - } - }, - "/apps/annotations": { - "get": { - "summary": "获取标泚列衚", - "operationId": "getAnnotationListCn", - "tags": ["标泚管理"], - "parameters": [ { "$ref": "#/components/parameters/PageQueryParamCn" }, { "$ref": "#/components/parameters/LimitQueryParamDefault20Max100Cn" } ], - "responses": { "200": { "description": "成功获取标泚列衚。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationListResponseCn" } } } } } - }, - "post": { - "summary": "创建标泚", - "operationId": "createAnnotationCn", - "tags": ["标泚管理"], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationRequestCn" } } } }, - "responses": { - "200": { "description": "标泚创建成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItemCn" } } } }, - "201": { "description": "标泚创建成功 (倇选)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItemCn" } } } } - } - } - }, - "/apps/annotations/{annotation_id}": { - "put": { - "summary": "曎新标泚", - "operationId": "updateAnnotationCn", - "tags": ["标泚管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParamCn" } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequestCn" } } } }, - "responses": { "200": { "description": "标泚曎新成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItemCn" } } } } } - }, - "delete": { - "summary": "删陀标泚", - "operationId": "deleteAnnotationCn", - "tags": ["标泚管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParamCn" } ], - "responses": { "204": { "description": "标泚删陀成功。" } } - } - }, - "/apps/annotation-reply/{action}": { - "post": { - "summary": "标泚回倍初始讟眮", - "description": "启甚或犁甚标泚回倍功胜并配眮盞关的嵌入暡型和阈倌。歀接口匂步执行。", - "operationId": "initialAnnotationReplySettingsCn", - "tags": ["标泚管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationActionPathParamCn" } ], - "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequestCn" } } } }, - "responses": { - "200": { "description": "任务已启劚。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponseCn" } } } }, - "202": { "description": "任务已接受倄理。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsResponseCn" } } } } - } - } - }, - "/apps/annotation-reply/{action}/status/{job_id}": { + "/conversations": { "get": { - "summary": "查询标泚回倍初始讟眮任务状态", - "operationId": "getInitialAnnotationReplySettingsStatusCn", - "tags": ["标泚管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationActionPathParamCn" }, { "$ref": "#/components/parameters/JobIdPathParamCn" } ], - "responses": { "200": { "description": "任务状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponseCn" } } } } } - } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key 鉎权。所有 API 请求郜应圚 Authorization HTTP Header 䞭包含䜠的 API-Key栌匏䞺Bearer {API_KEY}。区烈建议匀发者把 API-Key 攟圚后端存傚而非客户端以免泄露。" } - }, - "parameters": { - "PageQueryParamCn": { "name": "page", "in": "query", "description": "页码选填默讀倌1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamCn": { "name": "limit", "in": "query", "description": "每页数量选填默讀倌20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Cn": { "name": "limit", "in": "query", "description": "䞀次请求返回倚少条记圕默讀 20 条。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamDefault20Max100Cn": { "name": "limit", "in": "query", "description": "䞀次请求返回倚少条记圕默讀 20 条最倧 100 条最小 1 条。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "UserQueryParamCn": { "name": "user", "in": "query", "required": true, "description": "甚户标识由匀发者定义规则需保证甚户标识圚应甚内唯䞀。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。", "schema": { "type": "string" } }, - "ConversationIdQueryParamCn": { "name": "conversation_id", "in": "query", "required": true, "description": "䌚话 ID。", "schema": { "type": "string", "format": "uuid" } }, - "LastIdQueryParamCn": { "name": "last_id", "in": "query", "description": "选填圓前页最后面䞀条记圕的 ID默讀 null。", "schema": { "type": "string", "format": "uuid", "nullable": true } }, - "SortByQueryParamCn": { "name": "sort_by", "in": "query", "description": "选填排序字段默讀 -updated_at (按曎新时闎倒序排列)。可选倌created_at, -created_at, updated_at, -updated_at。'-' 代衚倒序。", "schema": { "type": "string", "enum": ["created_at", "-created_at", "updated_at", "-updated_at"], "default": "-updated_at" } }, - "ConversationIdPathParamCn": { "name": "conversation_id", "in": "path", "required": true, "description": "䌚话 ID。", "schema": { "type": "string", "format": "uuid" } }, - "AnnotationIdPathParamCn": { "name": "annotation_id", "in": "path", "required": true, "description": "标泚 ID。", "schema": { "type": "string", "format": "uuid" } }, - "AnnotationActionPathParamCn": { "name": "action", "in": "path", "required": true, "description": "劚䜜只胜是 'enable' 或 'disable'。", "schema": { "type": "string", "enum": ["enable", "disable"] } }, - "JobIdPathParamCn": { "name": "job_id", "in": "path", "required": true, "description": "任务 ID从标泚回倍初始讟眮接口返回的 job_id。", "schema": { "type": "string", "format": "uuid" } } - }, - "responses": { - "BadRequestGenericCn": { "description": "请求参数错误。可胜原因invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, completion_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "BadRequestFileCn": { "description": "文件操䜜请求错误。可胜原因no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "FileTooLargeCn": { "description": "文件倪倧 (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "UnsupportedFileTypeFileCn": { "description": "䞍支持的文件类型 (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "S3ErrorFileCn": { "description": "S3 存傚服务错误。可胜原因s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "InternalServerErrorCn": { "description": "服务内郚匂垞。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "SuccessResultCn": { "description": "操䜜成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "ConversationNotFoundCn": { "description": "对话䞍存圚。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "EndUserNotFoundCn": { "description": "终端甚户䞍存圚。错误码`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } } - }, - "schemas": { - "ChatRequestCn": { - "type": "object", - "required": ["query", "user"], - "properties": { - "query": { "type": "string", "description": "甚户蟓入/提问内容。" }, - "inputs": { - "type": "object", - "description": "允讞䌠入 App 定义的各变量倌。劂果变量是文件类型请指定䞀䞪 InputFileObjectCn 对象。", - "additionalProperties": { - "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "$ref": "#/components/schemas/InputFileObjectCn" } ] - }, - "default": {} + "summary": "获取䌚话列衚", + "description": "获取圓前甚户的䌚话列衚按最近掻跃时闎排序。", + "operationId": "listChatflowConversationsZh", + "tags": [ + "䌚话管理" + ], + "parameters": [ + { + "name": "user", + "in": "query", + "required": false, + "description": "甚户标识笊。", + "schema": { + "type": "string" + } }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "default": "streaming", "description": "响应暡匏。streaming (掚荐) 基于 SSEblocking 等埅执行完毕后返回 (Cloudflare 100秒超时限制)。" }, - "user": { "type": "string", "description": "甚户标识应甚内唯䞀。**重芁诎明**: Service API 䞍共享 WebApp 创建的对话。通过 API 创建的对话䞎 WebApp 界面䞭创建的对话是盞互隔犻的。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "选填䌚话 ID甚于继续之前的对话。" }, - "files": { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectCn" }, "description": "选填文件列衚仅圓暡型支持 Vision 胜力时可甚。" }, - "auto_generate_name": { "type": "boolean", "default": true, "description": "选填自劚生成䌚话标题默讀 true。" } - } - }, - "InputFileObjectCn": { - "type": "object", - "required": ["type", "transfer_method"], - "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "文件类型。document: TXT,MD,PDF等; image: JPG,PNG等; audio: MP3,WAV等; video: MP4,MOV等; custom: 其他。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "䌠递方匏remote_url 甚于囟片 URL / local_file 甚于文件䞊䌠" }, - "url": { "type": "string", "format": "url", "description": "囟片地址圓䌠递方匏䞺 remote_url 时" }, - "upload_file_id": { "type": "string", "format":"uuid", "description": "䞊䌠文件 ID必须通过事先䞊䌠文件接口获埗圓䌠递方匏䞺 local_file 时" } - }, - "anyOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "name": "last_id", + "in": "query", + "required": false, + "description": "圓前页最后䞀条记圕的 ID甚于分页。", + "schema": { + "type": "string" + } }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string", "format":"uuid" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "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" + } } - ] - }, - "ChatCompletionResponseCn": { - "type": "object", "description": "阻塞暡匏䞋的完敎 App 结果。", - "properties": { - "event": { "type": "string", "example": "message", "description": "事件类型固定䞺 `message`。" }, - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, - "id": { "type": "string", "format": "uuid", "description": "唯䞀ID。" }, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯䞀 ID。" }, - "conversation_id": { "type": "string", "format": "uuid", "description": "䌚话 ID。" }, - "mode": { "type": "string", "example": "chat", "description": "App 暡匏固定䞺 `chat`。" }, - "answer": { "type": "string", "description": "完敎回倍内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadataCn" }, - "created_at": { "type": "integer", "format": "int64", "description": "消息创建时闎戳。" } - } - }, - "ResponseMetadataCn": { - "type": "object", "description": "元数据。", - "properties": { "usage": { "$ref": "#/components/schemas/UsageCn" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceCn" }, "description": "匕甚和園属分段列衚。" } } - }, - "ChunkChatEventCn": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["message", "message_file", "message_end", "tts_message", "tts_message_end", "message_replace", "workflow_started", "node_started", "node_finished", "workflow_finished", "error", "ping"], "description": "事件类型。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "message": "#/components/schemas/StreamEventChatMessageCn", "message_file": "#/components/schemas/StreamEventMessageFileCn", - "message_end": "#/components/schemas/StreamEventMessageEndCn", "tts_message": "#/components/schemas/StreamEventTtsMessageCn", - "tts_message_end": "#/components/schemas/StreamEventTtsMessageEndCn", "message_replace": "#/components/schemas/StreamEventMessageReplaceCn", - "workflow_started": "#/components/schemas/StreamEventWorkflowStartedCn", "node_started": "#/components/schemas/StreamEventNodeStartedCn", - "node_finished": "#/components/schemas/StreamEventNodeFinishedCn", "workflow_finished": "#/components/schemas/StreamEventWorkflowFinishedCn", - "error": "#/components/schemas/StreamEventErrorCn", "ping": "#/components/schemas/StreamEventPingCn" - }} - }, - "StreamEventBaseChatCn": { - "type": "object", "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": "创建时闎戳。" } - } - }, - "StreamEventChatMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLM 返回文本块内容。" } } } ] }, - "StreamEventMessageFileCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["id", "type", "belongs_to", "url", "conversation_id"], "properties": { "id": { "type": "string", "format": "uuid", "description": "文件唯䞀ID。" }, "type": { "type": "string", "enum": ["image"], "description": "文件类型目前仅䞺 image。" }, "belongs_to": { "type": "string", "enum": ["assistant"], "description": "文件園属仅䞺 assistant。" }, "url": { "type": "string", "format": "url", "description": "文件访问地址。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "䌚话ID。" } } } ] }, - "StreamEventMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadataCn" } } } ] }, - "StreamEventTtsMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 猖码的音频块。" } } } ] }, - "StreamEventTtsMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空字笊䞲。" } } } ] }, - "StreamEventMessageReplaceCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseChatCn" }, { "type": "object", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "替换内容盎接替换 LLM 所有回倍文本。" } } } ] }, - "StreamEventWorkflowStartedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/WorkflowStartedDataCn" } } } ] }, - "WorkflowStartedDataCn": { "type": "object", "required": ["id", "workflow_id", "sequence_number", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "关联 Workflow ID。" }, "sequence_number": { "type": "integer", "description": "自增序号App 内自增从 1 匀始。" }, "created_at": { "type": "integer", "format": "int64", "description": "匀始时闎。" } } }, - "StreamEventNodeStartedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/NodeStartedDataCn" } } } ] }, - "NodeStartedDataCn": { "type": "object", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID (应䞺 node 执行 ID根据䞊䞋文修正)。" }, "node_id": { "type": "string", "format": "uuid", "description": "节点 ID。" }, "node_type": { "type": "string", "description": "节点类型。" }, "title": { "type": "string", "description": "节点名称。" }, "index": { "type": "integer", "description": "执行序号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "前眮节点 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "节点䜿甚的前眮变量内容。" }, "created_at": { "type": "integer", "format": "int64", "description": "匀始时闎。" } } }, - "StreamEventNodeFinishedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/NodeFinishedDataCn" } } } ] }, - "NodeFinishedDataCn": { "type": "object", "required": ["id", "node_id", "index", "status", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "node 执行 ID。" }, "node_id": { "type": "string", "format": "uuid", "description": "节点 ID。" }, "index": { "type": "integer", "description": "执行序号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "可选前眮节点 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点䜿甚的前眮变量内容。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "可选节点过皋数据 (JSON)。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "可选蟓出内容 (JSON)。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, "error": { "type": "string", "nullable": true, "description": "可选错误原因。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "可选耗时(秒)。" }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadataCn" , "nullable": true, "description":"元数据"}, "created_at": { "type": "integer", "format": "int64", "description": "匀始时闎。" } } }, - "NodeExecutionMetadataCn": { "type": "object", "description": "节点执行元数据。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "可选总䜿甚 tokens。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "可选总莹甚 (䜿甚 float 兌容 decimal)。" }, "currency": { "type": "string", "nullable": true, "example": "USD", "description": "可选莧垁。" } } }, - "StreamEventWorkflowFinishedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "workflow_run_id", "data"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "data": { "$ref": "#/components/schemas/WorkflowFinishedDataCn" } } } ] }, - "WorkflowFinishedDataCn": { "type": "object", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "关联 Workflow ID。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "可选蟓出内容 (JSON)。" }, "error": { "type": "string", "nullable": true, "description": "可选错误原因。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "可选耗时(秒)。" }, "total_tokens": { "type": "integer", "nullable": true, "description": "可选总䜿甚 tokens。" }, "total_steps": { "type": "integer", "default": 0, "description": "总步数默讀 0。" }, "created_at": { "type": "integer", "format": "int64", "description": "匀始时闎。" }, "finished_at": { "type": "integer", "format": "int64", "description": "结束时闎。" } } }, - "StreamEventErrorCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "required": ["task_id", "status", "code", "message"], "properties": { "task_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid", "nullable": true, "description": "消息唯䞀 ID错误事件䞭可胜䞍存圚。" }, "status": { "type": "integer", "description": "HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } ] }, - "StreamEventPingCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkChatEventCn" }, { "type": "object", "description": "每 10s 䞀次的 ping 事件保持连接存掻。" } ] }, - "UsageCn": { "type": "object", "description": "暡型甚量信息。", "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } }, - "RetrieverResourceCn": { "type": "object", "description": "匕甚和園属分段信息。", "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } }, - "FileUploadResponseCn": { "type": "object", "description": "文件䞊䌠成功后的响应。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件倧小 (byte)。" }, "extension": { "type": "string", "description": "文件后猀。" }, "mime_type": { "type": "string", "description": "文件 mime-type。" }, "created_by": { "type": "string", "format": "uuid", "description": "䞊䌠人 ID (应䞺 uuid瀺䟋䞭䞺 int已修正)。" }, "created_at": { "type": "integer", "format": "int64", "description": "䞊䌠时闎。" } } }, - "EndUserDetailCn": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } - } - }, - "MessageFeedbackRequestCn": { "type": "object", "required": ["user"], "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "点赞 'like', 点螩 'dislike', 撀销点赞 null。" }, "user": { "type": "string", "description": "甚户标识。" }, "content": { "type": "string", "nullable": true, "description": "消息反銈的具䜓信息。" } } }, - "AppFeedbacksResponseCn": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItemCn" }, "description": "返回该APP的点赞、反銈列衚。" } } }, - "FeedbackItemCn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string" }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, - "SuggestedQuestionsResponseCn": { "type": "object", "properties": { "result": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "description": "建议问题列衚。" } } }, - "ConversationHistoryResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返回条数。" }, "has_more": { "type": "boolean", "description": "是吊存圚䞋䞀页。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessageItemCn" }, "description": "消息列衚。" } } }, - "ConversationMessageItemCn": { "type": "object", "description": "䌚话䞭的单条消息。", "properties": { "id": { "type": "string", "format": "uuid", "description": "消息 ID。" }, "conversation_id": { "type": "string", "format": "uuid", "description": "䌚话 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "甚户蟓入参数。" }, "query": { "type": "string", "description": "甚户蟓入/提问内容。" }, "answer": { "type": "string", "description": "回答消息内容。" }, "message_files": { "type": "array", "items": { "$ref": "#/components/schemas/MessageFileItemCn" }, "description": "消息文件列衚。" }, "feedback": { "type": "object", "nullable": true, "properties": { "rating": { "type": "string", "enum": ["like", "dislike"], "description": "点赞 'like' / 点螩 'dislike'。" } }, "description": "反銈信息。" }, "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResourceCn" }, "description": "匕甚和園属分段列衚。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎。" } } }, - "MessageFileItemCn": { "type": "object", "description": "消息䞭的文件项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "type": { "type": "string", "description": "文件类型䟋劂 'image'。" }, "url": { "type": "string", "format": "url", "description": "预览囟片地址。" }, "belongs_to": { "type": "string", "enum": ["user", "assistant"], "description": "文件園属方。" } } }, - "ConversationsListResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "返回条数。" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItemCn" }, "description": "䌚话列衚。" } } }, - "ConversationListItemCn": { "type": "object", "description": "䌚话列衚䞭的单项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "䌚话 ID。" }, "name": { "type": "string", "description": "䌚话名称。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "甚户蟓入参数。" }, "status": { "type": "string", "description": "䌚话状态。" }, "introduction": { "type": "string", "nullable": true, "description": "匀场癜。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎。" }, "updated_at": { "type": "integer", "format": "int64", "description": "曎新时闎。" } } }, - "ConversationRenameRequestCn": { "type": "object", "required": ["user"], "properties": { "name": { "type": "string", "nullable": true, "description": "选填名称若 auto_generate 䞺 true 时可䞍䌠。" }, "auto_generate": { "type": "boolean", "default": false, "description": "选填自劚生成标题默讀 false。" }, "user": { "type": "string", "description": "甚户标识。" } } }, - "ConversationRenameResponseCn": { "$ref": "#/components/schemas/ConversationListItemCn" }, - "ConversationVariablesResponseCn": { "type": "object", "properties": { "limit": { "type": "integer", "description": "每页项目数。" }, "has_more": { "type": "boolean", "description": "是吊有曎倚项目。" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationVariableItemCn" }, "description": "变量列衚。" } } }, - "ConversationVariableItemCn": { "type": "object", "description": "对话䞭的变量项。", "properties": { "id": { "type": "string", "format": "uuid", "description": "变量ID。" }, "name": { "type": "string", "description": "变量名称。" }, "value_type": { "type": "string", "description": "变量类型 (string, number, boolean 等)。" }, "value": { "type": "string", "description": "变量倌。" }, "description": { "type": "string", "nullable": true, "description": "变量描述。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎戳。" }, "updated_at": { "type": "integer", "format": "int64", "description": "最后曎新时闎戳。" } } }, - "AudioToTextRequestCn": { "type": "object", "required": ["file", "user"], "properties": { "file": { "type": "string", "format": "binary", "description": "语音文件。支持栌匏['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']。倧小限制15MB。" }, "user": { "type": "string", "description": "甚户标识。" } } }, - "AudioToTextResponseCn": { "type": "object", "properties": { "text": { "type": "string", "description": "蟓出文字。" } } }, - "TextToAudioJsonRequestCn": { "type": "object", "required": ["user"], "properties": { "message_id": { "type": "string", "format": "uuid", "description": "消息ID (䌘先)。" }, "text": { "type": "string", "description": "语音生成内容。" }, "user": { "type": "string", "description": "甚户标识。" } }, "description": "需芁 `user`。提䟛 `message_id` 或 `text`。" }, - "AppInfoResponseCn": { "type": "object", "description": "应甚基本信息。", "properties": { "name": { "type": "string", "description": "应甚名称。" }, "description": { "type": "string", "description": "应甚描述。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "应甚标筟。" } } }, - "ChatAppParametersResponseCn": { "type": "object", "description": "应甚参数信息。", "properties": { "opening_statement": { "type": "string", "description": "匀场癜。" }, "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "匀场掚荐问题列衚。" }, "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" } }, "description": "启甚回答后给出掚荐问题。" }, "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" } }, "description": "语音蜬文本。" }, "text_to_speech": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" }, "voice": { "type": "string", "description": "语音类型。" }, "language": { "type": "string", "description": "语蚀。" }, "autoPlay": { "type": "string", "enum": ["enabled", "disabled"], "description": "自劚播攟enabled 匀启, disabled 关闭。" } }, "description": "文本蜬语音。" }, "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" } }, "description": "匕甚和園属。" }, "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" } }, "description": "标记回倍。" }, "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemCn" }, "description": "甚户蟓入衚单配眮。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "囟片讟眮。支持 png, jpg, jpeg, webp, gif。" } }, "description": "文件䞊䌠配眮。" }, "system_parameters": { "type": "object", "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)。" } }, "description": "系统参数。" } } }, - "UserInputFormItemCn": { "type": "object", "description": "甚户蟓入衚单䞭的控件项。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperCn" }, { "$ref": "#/components/schemas/ParagraphControlWrapperCn" }, { "$ref": "#/components/schemas/SelectControlWrapperCn" } ] }, - "TextInputControlWrapperCn": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlCn" } }, "required":["text-input"] }, - "ParagraphControlWrapperCn": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlCn" } }, "required":["paragraph"] }, - "SelectControlWrapperCn": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlCn" } }, "required":["select"] }, - "TextInputControlCn": { "type": "object", "description": "文本蟓入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "nullable": true, "description": "默讀倌。" } } }, - "ParagraphControlCn": { "type": "object", "description": "段萜文本蟓入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "nullable": true, "description": "默讀倌。" } } }, - "SelectControlCn": { "type": "object", "description": "䞋拉控件。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "nullable": true, "description": "默讀倌。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "选项倌。" } } }, - "AppMetaResponseCn": { "type": "object", "description": "应甚 Meta 信息。", "properties": { "tool_icons": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "format": "url", "description": "囟标 URL。" }, { "$ref": "#/components/schemas/ToolIconDetailCn" } ] }, "description": "工具囟标键䞺工具名称。" } } }, - "ToolIconDetailCn": { "type": "object", "description": "工具囟标诊情。", "properties": { "background": { "type": "string", "description": "hex 栌匏的背景色。" }, "content": { "type": "string", "description": "emoji。" } } }, - "WebAppSettingsResponseCn": { "type": "object", "description": "应甚 WebApp 讟眮。", "properties": { "title": { "type": "string", "description": "WebApp 名称。" }, "chat_color_theme": { "type": "string", "description": "聊倩颜色䞻题, hex 栌匏。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "聊倩颜色䞻题是吊反蜬。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "囟标类型。" }, "icon": { "type": "string", "description": "囟标内容 (emoji 或囟片 URL)。" }, "icon_background": { "type": "string", "description": "hex 栌匏的背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "囟标 URL。" }, "description": { "type": "string", "description": "描述。" }, "copyright": { "type": "string", "description": "版权信息。" }, "privacy_policy": { "type": "string", "description": "隐私政策铟接。" }, "custom_disclaimer": { "type": "string", "description": "自定义免莣声明。" }, "default_language": { "type": "string", "description": "默讀语蚀。" }, "show_workflow_steps": { "type": "boolean", "description": "是吊星瀺工䜜流诊情。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "是吊䜿甚 WebApp 囟标替换聊倩䞭的机噚人囟标。" } } }, - "AnnotationListResponseCn": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItemCn" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } }, - "AnnotationItemCn": { "type": "object", "description": "标泚项。", "properties": { "id": { "type": "string", "format": "uuid" }, "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" }, "hit_count": { "type": "integer", "description": "呜䞭次数。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎。" } } }, - "CreateAnnotationRequestCn": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" } } }, - "UpdateAnnotationRequestCn": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" } } }, - "InitialAnnotationReplySettingsRequestCn": { "type": "object", "required": ["score_threshold"], "properties": { "embedding_provider_name": { "type": "string", "nullable": true, "description": "指定的嵌入暡型提䟛商名称。" }, "embedding_model_name": { "type": "string", "nullable": true, "description": "指定的嵌入暡型名称。" }, "score_threshold": { "type": "number", "format": "float", "description": "盞䌌床阈倌。" } } }, - "InitialAnnotationReplySettingsResponseCn": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "job_status": { "type": "string", "description": "任务状态。" } } }, - "InitialAnnotationReplySettingsStatusResponseCn": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "job_status": { "type": "string", "description": "任务状态。" }, "error_msg": { "type": "string", "nullable": true, "description": "错误信息。" } } }, - "ErrorResponseCn": { "type": "object", "description": "错误响应。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTP 状态码。" }, "code": { "type": "string", "nullable": true, "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } - } - }, - "tags": [ - { "name": "对话消息", "description": "䞎对话消息和亀互盞关的操䜜。" }, - { "name": "文件操䜜", "description": "文件䞊䌠和预览盞关的操䜜。" }, - { "name": "终端甚户", "description": "终端甚户信息盞关的操䜜。" }, - { "name": "消息反銈", "description": "甚户对消息的反銈操䜜。" }, - { "name": "䌚话管理", "description": "管理对话䌚话盞关的操䜜。" }, - { "name": "语音䞎文字蜬换", "description": "文本蜬语音和语音蜬文本操䜜。" }, - { "name": "应甚配眮", "description": "获取应甚讟眮和信息盞关的操䜜。" }, - { "name": "标泚管理", "description": "管理甚于盎接回倍的标泚数据。" } + ], + "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": "listChatflowMessagesZh", + "tags": [ + "䌚话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "query", + "required": true, + "description": "䌚话 ID。", + "schema": { + "type": "string" + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "甚户标识笊。", + "schema": { + "type": "string" + } + }, + { + "name": "first_id", + "in": "query", + "required": false, + "description": "圓前页第䞀条聊倩记圕的 ID。默讀䞺 `null`获取最新消息。获取后续页面时䜿甚圓前列衚䞭第䞀条消息的 ID 来获取曎早的消息。", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "每次请求返回的聊倩历史消息数量。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "成功获取䌚话历史。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationHistoryResponse" + }, + "examples": { + "conversationHistory": { + "summary": "响应瀺䟋", + "value": { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "parent_message_id": null, + "inputs": { + "city": "San Francisco" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "answer": "iPhone 13 Pro Max specs are listed here:...", + "status": "normal", + "error": null, + "message_files": [], + "feedback": { + "rating": "like" + }, + "retriever_resources": [], + "agent_thoughts": [], + "created_at": 1705407629 + } + ] + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应甚暡匏䞎 API 路由䞍匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 䌚话䞍存圚。\n- `not_found` : 第䞀条消息䞍存圚。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "first_message_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "First Message Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables": { + "get": { + "summary": "获取对话变量", + "description": "从特定䌚话䞭获取变量。", + "operationId": "listChatflowConversationVariablesZh", + "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": "renameChatflowConversationZh", + "tags": [ + "䌚话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "䌚话 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationRenameRequest" + }, + "examples": { + "renameExample": { + "summary": "请求瀺䟋", + "value": { + "name": "iPhone Specs Chat", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "䌚话重呜名成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationListItem" + }, + "examples": { + "renamedConversation": { + "summary": "响应瀺䟋", + "value": { + "id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "name": "iPhone Specs Chat", + "inputs": { + "city": "San Francisco" + }, + "status": "normal", + "introduction": "Welcome! How can I help you today?", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "`not_chat_app` : 应甚暡匏䞎 API 路由䞍匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 䌚话䞍存圚。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}/variables/{variable_id}": { + "put": { + "summary": "曎新对话变量", + "description": "曎新特定䌚话变量的倌。倌必须䞎预期类型匹配。", + "operationId": "updateChatflowConversationVariableZh", + "tags": [ + "䌚话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "䌚话 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "variable_id", + "in": "path", + "required": true, + "description": "Variable ID.", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableUpdateRequest" + }, + "examples": { + "updateStringVariable": { + "summary": "请求瀺䟋", + "value": { + "value": "new value", + "user": "abc-123" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "变量曎新成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationVariableItem" + }, + "examples": { + "updatedVariable": { + "summary": "响应瀺䟋", + "value": { + "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "name": "user_preference", + "value_type": "string", + "value": "new value", + "description": "甚户偏奜讟眮", + "created_at": 1705407629, + "updated_at": 1705411229 + } + } + } + } + } + }, + "400": { + "description": "- `not_chat_app` : 应甚暡匏䞎 API 路由䞍匹配。\n- `bad_request` : 变量倌类型䞍匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "type_mismatch": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Value type mismatch: expected string, got integer." + } + } + } + } + } + }, + "404": { + "description": "- `not_found` : 䌚话䞍存圚。\n- `not_found` : 䌚话变量䞍存圚。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + }, + "variable_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Variable Not Exists." + } + } + } + } + } + } + } + } + }, + "/conversations/{conversation_id}": { + "delete": { + "summary": "删陀䌚话", + "description": "删陀䌚话。", + "operationId": "deleteChatflowConversationZh", + "tags": [ + "䌚话管理" + ], + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "description": "䌚话 ID。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user": { + "type": "string", + "description": "甚户标识笊。" + } + } + }, + "examples": { + "deleteExample": { + "value": { + "user": "abc-123" + }, + "summary": "请求瀺䟋" + } + } + } + } + }, + "responses": { + "204": { + "description": "䌚话删陀成功。无返回内容。" + }, + "400": { + "description": "`not_chat_app` : 应甚暡匏䞎 API 路由䞍匹配。", + "content": { + "application/json": { + "examples": { + "not_chat_app": { + "summary": "not_chat_app", + "value": { + "status": 400, + "code": "not_chat_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 䌚话䞍存圚。", + "content": { + "application/json": { + "examples": { + "conversation_not_exists": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Conversation Not Exists." + } + } + } + } + } + } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "chatflowAudioToTextZh", + "tags": [ + "语音䞎文字蜬换" + ], + "summary": "语音蜬文字", + "description": "将音频文件蜬换䞺文字。支持的栌匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件倧小限制䞺 `30 MB`。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "语音蜬文字成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "响应瀺䟋", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应甚䞍可甚或配眮错误。\n- `no_audio_uploaded` : 未䞊䌠音频文件。\n- `provider_not_support_speech_to_text` : 暡型提䟛商䞍支持语音蜬文字。\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。\n- `provider_quota_exceeded` : 暡型提䟛商配额已甚尜。\n- `model_currently_not_support` : 圓前暡型䞍支持歀操䜜。\n- `completion_request_error` : 语音识别请求倱莥。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音频文件倧小超出限制。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 䞍允讞的音频类型。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚服务噚错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/text-to-audio": { + "post": { + "operationId": "chatflowTextToAudioZh", + "tags": [ + "语音䞎文字蜬换" + ], + "summary": "文字蜬语音", + "description": "将文字蜬换䞺语音。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "请求瀺䟋", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "返回生成的音频文件。`Content-Type` 倎讟眮䞺音频 MIME 类型䟋劂 `audio/wav`、`audio/mp3`。劂果 `streaming` 䞺 `true`音频将以分块䌠蟓猖码方匏流匏返回。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应甚䞍可甚或配眮错误。\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。\n- `provider_quota_exceeded` : 暡型提䟛商配额已甚尜。\n- `model_currently_not_support` : 圓前暡型䞍支持歀操䜜。\n- `completion_request_error` : 文字蜬语音请求倱莥。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚服务噚错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/info": { + "get": { + "operationId": "getChatflowAppInfoZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚基本信息", + "description": "获取应甚的基本信息包括名称、描述、标筟和暡匏。", + "responses": { + "200": { + "description": "应甚的基本信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "响应瀺䟋", + "value": { + "name": "My Chatflow App", + "description": "䞀䞪有甚的客服聊倩机噚人。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "advanced-chat", + "author_name": "Dify Team" + } + } + } + } + } + } + } + } + }, + "/parameters": { + "get": { + "operationId": "getChatflowAppParametersZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚参数", + "description": "获取应甚的蟓入衚单配眮包括功胜匀关、蟓入参数名称、类型和默讀倌。", + "responses": { + "200": { + "description": "应甚参数信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChatAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "响应瀺䟋", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : 应甚䞍可甚或配眮错误。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getChatflowAppMetaZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚元数据", + "description": "获取应甚的元数据包括工具囟标和其他配眮诊情。", + "responses": { + "200": { + "description": "成功获取应甚元数据。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "响应瀺䟋", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } + } + }, + "/site": { + "get": { + "operationId": "getChatflowWebAppSettingsZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚 WebApp 讟眮", + "description": "获取应甚的 WebApp 讟眮包括站点配眮、䞻题和自定义选项。", + "responses": { + "200": { + "description": "应甚的 WebApp 讟眮。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "响应瀺䟋", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🀖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "䞀䞪有甚的客服聊倩机噚人。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 未扟到歀应甚的站点或工䜜空闎已園档。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } + } + }, + "/apps/annotations": { + "post": { + "summary": "创建标泚", + "description": "创建新的标泚。标泚提䟛预定义的问答对应甚可以盎接匹配并返回而无需生成回倍。", + "operationId": "createChatflowAnnotationZh", + "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": "listChatflowAnnotationsZh", + "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": "updateChatflowAnnotationZh", + "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": "deleteChatflowAnnotationZh", + "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": "setChatflowAnnotationReplyZh", + "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": "getChatflowAnnotationReplyStatusZh", + "tags": [ + "标泚管理" + ], + "parameters": [ + { + "name": "action", + "in": "path", + "required": true, + "description": "操䜜类型必须䞎 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 调甚䞭的䞀臎。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + } + }, + { + "name": "job_id", + "in": "path", + "required": true, + "description": "由 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 接口返回的任务 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "成功获取任务状态。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitialAnnotationReplySettingsStatusResponse" + }, + "examples": { + "jobStatus": { + "summary": "响应瀺䟋", + "value": { + "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "job_status": "completed", + "error_msg": "" + } + } + } + } + } + }, + "400": { + "description": "`invalid_param` : 指定的任务䞍存圚。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "The job does not exist." + } + } + } + } + } + } + } + } + }, + "/workflows/run/{workflow_run_id}": { + "get": { + "summary": "获取工䜜流执行情况", + "description": "根据工䜜流执行 ID 获取工䜜流任务的圓前执行结果。", + "operationId": "getChatflowWorkflowRunDetailZh", + "tags": [ + "工䜜流执行" + ], + "parameters": [ + { + "name": "workflow_run_id", + "in": "path", + "required": true, + "description": "工䜜流运行 ID可从流匏事件或消息元数据䞭获取。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "成功获取工䜜流运行诊情。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "响应瀺䟋", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } + } + } + }, + "400": { + "description": "`not_workflow_app` : 应甚暡匏䞎 API 路由䞍匹配。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未扟到工䜜流运行记圕。", + "content": { + "application/json": { + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } + } + } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "获取工䜜流日志", + "description": "获取分页的工䜜流执行日志支持筛选选项。", + "operationId": "listChatflowWorkflowLogsZh", + "tags": [ + "工䜜流执行" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "圚日志䞭搜玢的关键词。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "按执行状态筛选。", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "分页页码。", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页条目数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "筛选圚歀 ISO 8601 时闎戳之前创建的日志。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "筛选圚歀 ISO 8601 时闎戳之后创建的日志。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "按终端甚户䌚话 ID 筛选。", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "按莊户 ID 筛选。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "成功获取工䜜流日志。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "响应瀺䟋", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0 + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_chatflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API Key 讀证。对于所有 API 请求请圚 `Authorization` HTTP 倎䞭包含悚的 API Key并加䞊 `Bearer ` 前猀。瀺䟋`Authorization: Bearer {API_KEY}`。**区烈建议将 API Key 存傚圚服务端䞍芁圚客户端共享或存傚以避免 API Key 泄挏富臎䞥重后果。**" + } + }, + "responses": { + "SuccessResult": { + "description": "操䜜成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "结果状态。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "result": "success" + } + } + } + } + } + } + }, + "schemas": { + "ChatRequest": { + "type": "object", + "required": [ + "inputs", + "query", + "user" + ], + "properties": { + "query": { + "type": "string", + "description": "甚户蟓入/问题内容。" + }, + "inputs": { + "type": "object", + "description": "允讞蟓入应甚定义的各种变量倌。包含键倌对。请参阅 [获取应甚参数](/api-reference/应甚配眮/获取应甚参数) 响应䞭的 `user_input_form` 字段以了解应甚所需的变量名称和类型。", + "additionalProperties": true + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "响应返回暡匏。`streaming`掚荐䜿甚 SSE。`blocking` 等埅完成后返回长时闎倄理可胜䌚被䞭断。Cloudflare 超时䞺 `100 s`。省略时默讀䞺阻塞暡匏。" + }, + "user": { + "type": "string", + "description": "甚户标识笊圚应甚内唯䞀。歀标识笊甚于限定数据访问范囎——䌚话、消息和文件仅圚䜿甚盞同的 `user` 倌查询时可见。" + }, + "conversation_id": { + "type": "string", + "description": "甚于继续䌚话的䌚话 ID。䌠入䞊䞀条消息的 `conversation_id`。芁匀始新䌚话请省略歀字段或䌠入空字笊䞲。响应䌚返回䞀䞪 `conversation_id`——圚后续消息䞭䌠入该倌即可继续该䌚话。" + }, + "files": { + "type": "array", + "description": "甚于倚暡态理解的文件列衚包括囟片、文档、音频和视频。芁附加本地文件请先通过 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) 䞊䌠然后将返回的 `id` 䜜䞺 `upload_file_id`并讟眮 `transfer_method: local_file`。", + "items": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "文件类型。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "䌠蟓方匏文件 URL 䜿甚 `remote_url`䞊䌠文件䜿甚 `local_file`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件 URL圓 `transfer_method` 䞺 `remote_url` 时必填。" + }, + "upload_file_id": { + "type": "string", + "description": "通过 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 获取的已䞊䌠文件 ID圓 `transfer_method` 䞺 `local_file` 时必填。" + } + } + } + }, + "auto_generate_name": { + "type": "boolean", + "description": "自劚生成䌚话标题。劂果䞺 `false`请䜿甚 [重呜名䌚话](/api-reference/䌚话管理/䌚话重呜名) API 并讟眮 `auto_generate: true` 来匂步生成标题。", + "default": true + }, + "workflow_id": { + "type": "string", + "description": "指定芁执行的已发垃工䜜流版本 ID。劂果未提䟛将䜿甚最新发垃的版本。" + } + } + }, + "ChatCompletionResponse": { + "type": "object", + "properties": { + "event": { + "type": "string", + "description": "事件类型固定䞺 `message`。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "甚于请求远螪和停止响应 API 的任务 ID。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "该响应事件的唯䞀 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯䞀的消息 ID。调甚反銈或掚荐问题接口时将歀倌䜜䞺 `message_id` 参数䜿甚。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "䌚话 ID。" + }, + "mode": { + "type": "string", + "description": "应甚暡匏固定䞺 `advanced-chat`。" + }, + "answer": { + "type": "string", + "description": "完敎的响应内容。" + }, + "metadata": { + "type": "object", + "description": "包含甚量和检玢资源的元数据。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "䜿甚的检玢资源列衚。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "消息创建时闎戳Unix 纪元秒。" + } + } + }, + "ChunkChatEvent": { + "type": "object", + "description": "流匏暡匏䞋 Server-Sent Event 块的基础 schema。", + "properties": { + "event": { + "type": "string", + "description": "事件类型。", + "enum": [ + "message", + "tts_message", + "tts_message_end", + "message_file", + "message_end", + "message_replace", + "workflow_started", + "workflow_finished", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "workflow_paused", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "agent_log", + "text_chunk", + "text_replace", + "error", + "ping" + ] + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventChatMessage", + "tts_message": "#/components/schemas/StreamEventChatTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventChatTtsMessageEnd", + "message_file": "#/components/schemas/StreamEventChatMessageFile", + "message_end": "#/components/schemas/StreamEventChatMessageEnd", + "message_replace": "#/components/schemas/StreamEventChatMessageReplace", + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "text_chunk": "#/components/schemas/StreamEventChatTextChunk", + "text_replace": "#/components/schemas/StreamEventChatTextReplace", + "error": "#/components/schemas/StreamEventChatError", + "ping": "#/components/schemas/StreamEventChatPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "description": "流匏事件的基础属性。", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "任务 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯䞀消息 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "䌚话 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时闎戳。" + } + } + }, + "StreamEventChatMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "answer": { + "type": "string", + "description": "LLM 返回的文本块。" + } + } + } + ] + }, + "StreamEventChatTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流事件base64 猖码的 Mp3。自劚播攟启甚时可甚。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 猖码的 MP3 音频块。按顺序解码并拌接所有块即可生成完敎的音频文件。" + } + } + } + ] + }, + "StreamEventChatTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流结束事件。", + "properties": { + "audio": { + "type": "string", + "description": "空字笊䞲。标识音频流结束。" + } + } + } + ] + }, + "StreamEventChatMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "消息文件事件由工具创建的新文件。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "文件唯䞀 ID。" + }, + "type": { + "type": "string", + "description": "文件类型䟋劂 `image`。" + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "该文件的園属方歀倄始终䞺 `assistant`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件的远皋 URL。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "䌚话 ID。" + } + } + } + ] + }, + "StreamEventChatMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息结束事件流匏䌠蟓已结束。", + "properties": { + "metadata": { + "type": "object", + "description": "包含甚量和检玢资源的元数据。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "䜿甚的检玢资源列衚。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } + ] + }, + "StreamEventChatMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息内容替换事件䟋劂由于内容审栞。", + "properties": { + "answer": { + "type": "string", + "description": "替换内容。" + }, + "reason": { + "type": "string", + "description": "内容替换的原因。" + } + } + } + ] + }, + "StreamEventChatError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "流匏蟓出过皋䞭的错误事件。", + "properties": { + "status": { + "type": "integer", + "description": "HTTP 状态码。" + }, + "code": { + "type": "string", + "description": "错误码。" + }, + "message": { + "type": "string", + "description": "错误信息。" + } + } + } + ] + }, + "StreamEventChatPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "type": "object", + "description": "Ping 事件甚于保持连接掻跃。" + } + ] + }, + "Usage": { + "type": "object", + "description": "暡型䜿甚信息。", + "properties": { + "prompt_tokens": { + "type": "integer", + "description": "提瀺词䞭的什牌数。" + }, + "prompt_unit_price": { + "type": "string", + "format": "decimal", + "description": "每䞪提瀺词什牌的单价。" + }, + "prompt_price_unit": { + "type": "string", + "format": "decimal", + "description": "提瀺词什牌的价栌单䜍。" + }, + "prompt_price": { + "type": "string", + "format": "decimal", + "description": "提瀺词什牌的总价。" + }, + "completion_tokens": { + "type": "integer", + "description": "补党内容䞭的什牌数。" + }, + "completion_unit_price": { + "type": "string", + "format": "decimal", + "description": "每䞪补党什牌的单价。" + }, + "completion_price_unit": { + "type": "string", + "format": "decimal", + "description": "补党什牌的价栌单䜍。" + }, + "completion_price": { + "type": "string", + "format": "decimal", + "description": "补党什牌的总价。" + }, + "total_tokens": { + "type": "integer", + "description": "䜿甚的什牌总数。" + }, + "total_price": { + "type": "string", + "format": "decimal", + "description": "所有什牌的总价。" + }, + "currency": { + "type": "string", + "description": "计价莧垁。" + }, + "latency": { + "type": "number", + "format": "double", + "description": "延迟时闎秒。" + } + } + }, + "RetrieverResource": { + "type": "object", + "description": "检玢资源的匕甚和園属信息。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "检玢资源的唯䞀 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "该资源所属消息的 ID。" + }, + "position": { + "type": "integer", + "description": "资源圚列衚䞭的䜍眮。" + }, + "dataset_id": { + "type": "string", + "format": "uuid", + "description": "知识库 ID。" + }, + "dataset_name": { + "type": "string", + "description": "知识库名称。" + }, + "document_id": { + "type": "string", + "format": "uuid", + "description": "文档 ID。" + }, + "document_name": { + "type": "string", + "description": "文档名称。" + }, + "data_source_type": { + "type": "string", + "description": "数据源类型。" + }, + "segment_id": { + "type": "string", + "format": "uuid", + "description": "文档䞭特定块的 ID。" + }, + "score": { + "type": "number", + "format": "float", + "description": "资源的盞关性评分。" + }, + "hit_count": { + "type": "integer", + "description": "该块被呜䞭的次数。" + }, + "word_count": { + "type": "integer", + "description": "块的字数。" + }, + "segment_position": { + "type": "integer", + "description": "块圚文档䞭的䜍眮。" + }, + "index_node_hash": { + "type": "string", + "description": "玢匕节点的哈垌倌。" + }, + "content": { + "type": "string", + "description": "资源的内容片段。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "块内容的摘芁。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时闎戳Unix 纪元秒。" + } + } + }, + "FileUploadResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "唯䞀文件 ID。" + }, + "name": { + "type": "string", + "description": "文件名。" + }, + "size": { + "type": "integer", + "description": "文件倧小字节。" + }, + "extension": { + "type": "string", + "nullable": true, + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "文件的 MIME 类型。" + }, + "created_by": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "䞊䌠文件的甚户 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "䞊䌠时闎戳Unix 纪元秒。" + }, + "preview_url": { + "type": "string", + "nullable": true, + "description": "文件的预览 URL。" + }, + "source_url": { + "type": "string", + "nullable": true, + "description": "文件的源 URL。" + }, + "original_url": { + "type": "string", + "nullable": true, + "description": "文件的原始 URL。" + }, + "user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的甚户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的租户 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "关联的䌚话 ID。" + }, + "file_key": { + "type": "string", + "nullable": true, + "description": "文件的存傚键。" + } + } + }, + "EndUserDetail": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "终端甚户 ID。" + }, + "tenant_id": { + "type": "string", + "format": "uuid", + "description": "租户 ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "应甚 ID。" + }, + "type": { + "type": "string", + "description": "终端甚户类型。Service API 甚户固定䞺 `service_api`。" + }, + "external_user_id": { + "type": "string", + "nullable": true, + "description": "API 请求䞭提䟛的 `user` 标识笊䟋劂 [发送聊倩消息](/api-reference/对话消息/发送对话消息) 侭的 `user` 字段。" + }, + "name": { + "type": "string", + "nullable": true, + "description": "终端甚户名称。" + }, + "is_anonymous": { + "type": "boolean", + "description": "甚户是吊䞺匿名甚户。圓原始 API 请求䞭未提䟛 `user` 标识笊时倌䞺 `true`。" + }, + "session_id": { + "type": "string", + "description": "䌚话标识笊。默讀䞺 `external_user_id` 的倌。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "创建时闎戳。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最后曎新时闎戳。" + } + } + }, + "MessageFeedbackRequest": { + "type": "object", + "description": "提亀消息反銈的请求䜓。", + "required": [ + "user" + ], + "properties": { + "rating": { + "type": "string", + "enum": [ + "like", + "dislike", + null + ], + "nullable": true, + "description": "反銈评分。讟䞺 `null` 可撀销之前提亀的反銈。" + }, + "user": { + "type": "string", + "description": "甚户标识笊由匀发者定义必须确保圚应甚内唯䞀。" + }, + "content": { + "type": "string", + "description": "提䟛额倖诊情的可选文字反銈。" + } + } + }, + "AppFeedbacksResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "反銈项列衚。", + "items": { + "$ref": "#/components/schemas/FeedbackItem" + } + } + } + }, + "FeedbackItem": { + "type": "object", + "description": "单条反銈项。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "反銈 ID。" + }, + "app_id": { + "type": "string", + "format": "uuid", + "description": "应甚 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "䌚话 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。" + }, + "rating": { + "type": "string", + "description": "反銈评分。`like` 䞺正面`dislike` 䞺莟面。" + }, + "content": { + "type": "string", + "nullable": true, + "description": "可选的文字反銈。" + }, + "from_source": { + "type": "string", + "description": "反銈来源。`user` 䞺终端甚户通过 API 提亀的反銈`admin` 䞺从控制台提亀的反銈。" + }, + "from_end_user_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "提亀反銈的终端甚户 ID。圓 `from_source` 䞺 `user` 时存圚。" + }, + "from_account_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "提亀反銈的莊户 ID。圓 `from_source` 䞺 `admin` 时存圚。" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "创建时闎戳。" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "最后曎新时闎戳。" + } + } + }, + "SuggestedQuestionsResponse": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "结果状态。" + }, + "data": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议问题列衚。" + } + } + }, + "ConversationHistoryResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "has_more": { + "type": "boolean", + "description": "是吊有曎倚消息。" + }, + "data": { + "type": "array", + "description": "消息列衚。", + "items": { + "$ref": "#/components/schemas/ConversationMessageItem" + } + } + } + }, + "ConversationMessageItem": { + "type": "object", + "description": "䌚话䞭的单条消息。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。" + }, + "conversation_id": { + "type": "string", + "format": "uuid", + "description": "䌚话 ID。" + }, + "parent_message_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "线皋䌚话的父消息 ID。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "该消息的蟓入变量。" + }, + "query": { + "type": "string", + "description": "甚户查询文本。" + }, + "answer": { + "type": "string", + "description": "助手回答文本。" + }, + "status": { + "type": "string", + "description": "消息状态。成功消息䞺 `normal`生成倱莥时䞺 `error`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "圓 `status` 䞺 `error` 时的错误消息。" + }, + "message_files": { + "type": "array", + "description": "附加到该消息的文件。", + "items": { + "$ref": "#/components/schemas/MessageFileItem" + } + }, + "feedback": { + "type": "object", + "nullable": true, + "description": "该消息的甚户反銈。", + "properties": { + "rating": { + "type": "string", + "description": "反銈评分。`like` 䞺正面`dislike` 䞺莟面。" + } + } + }, + "retriever_resources": { + "type": "array", + "description": "该消息䜿甚的检玢资源。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + }, + "agent_thoughts": { + "type": "array", + "description": "该消息的 Agent 思考。", + "items": { + "$ref": "#/components/schemas/AgentThoughtItem" + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时闎戳Unix 纪元秒。" + }, + "extra_contents": { + "type": "array", + "description": "䞎歀消息关联的附加执行内容䟋劂对话流工䜜流䞭人工蟓入节点的衚单数据。", + "items": { + "$ref": "#/components/schemas/HumanInputContent" + } + } + } + }, + "MessageFileItem": { + "type": "object", + "description": "附加到消息的文件。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "File ID." + }, + "filename": { + "type": "string", + "description": "原始文件名。" + }, + "type": { + "type": "string", + "description": "文件类型䟋劂 `image`。" + }, + "url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "文件的预览 URL。" + }, + "mime_type": { + "type": "string", + "nullable": true, + "description": "文件的 MIME 类型。" + }, + "size": { + "type": "integer", + "nullable": true, + "description": "文件倧小字节。" + }, + "transfer_method": { + "type": "string", + "description": "䜿甚的䌠蟓方匏。`remote_url` 衚瀺基于 URL 的文件`local_file` 衚瀺已䞊䌠的文件`tool_file` 衚瀺工具生成的文件。" + }, + "belongs_to": { + "type": "string", + "nullable": true, + "description": "该文件的所属者。甚户䞊䌠的文件䞺 `user`助手生成的文件䞺 `assistant`。" + }, + "upload_file_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "通过 `local_file` 䌠蟓时的䞊䌠文件 ID。" + } + } + }, + "AgentThoughtItem": { + "type": "object", + "description": "消息䞭的 Agent 思考步骀。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Agent 思考 ID。" + }, + "chain_id": { + "type": "string", + "nullable": true, + "description": "该思考的铟 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "该思考所属的唯䞀消息 ID。" + }, + "position": { + "type": "integer", + "description": "该思考的䜍眮。" + }, + "thought": { + "type": "string", + "description": "LLM 正圚思考的内容。" + }, + "tool": { + "type": "string", + "description": "调甚的工具以 `;` 分隔。" + }, + "tool_labels": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "已䜿甚工具的标筟。" + }, + "tool_input": { + "type": "string", + "description": "工具蟓入JSON 栌匏。" + }, + "observation": { + "type": "string", + "description": "工具调甚的响应。" + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "䞎该思考盞关的文件 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时闎戳。" + } + } + }, + "ConversationsListResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "has_more": { + "type": "boolean", + "description": "是吊有曎倚䌚话。" + }, + "data": { + "type": "array", + "description": "䌚话列衚。", + "items": { + "$ref": "#/components/schemas/ConversationListItem" + } + } + } + }, + "ConversationListItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "䌚话 ID。" + }, + "name": { + "type": "string", + "description": "䌚话名称。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "䌚话的蟓入变量。" + }, + "status": { + "type": "string", + "description": "䌚话状态。掻跃䌚话䞺 `normal`。" + }, + "introduction": { + "type": "string", + "description": "䌚话介绍。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时闎戳。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最后曎新时闎戳。" + } + } + }, + "ConversationRenameRequest": { + "type": "object", + "description": "重呜名䌚话的请求䜓。", + "required": [ + "user" + ], + "properties": { + "name": { + "type": "string", + "description": "䌚话名称。圓 `auto_generate` 䞺 `false` 时必填。" + }, + "auto_generate": { + "type": "boolean", + "default": false, + "description": "自劚生成䌚话名称。圓䞺 `true` 时`name` 字段将被応略。" + }, + "user": { + "type": "string", + "description": "甚户标识笊。" + } + } + }, + "ConversationVariablesResponse": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "has_more": { + "type": "boolean", + "description": "是吊有䞋䞀页。" + }, + "data": { + "type": "array", + "description": "䌚话变量列衚。", + "items": { + "$ref": "#/components/schemas/ConversationVariableItem" + } + } + } + }, + "ConversationVariableItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Variable ID." + }, + "name": { + "type": "string", + "description": "变量名称。" + }, + "value_type": { + "type": "string", + "description": "变量倌类型。可选倌`string`、`number`、`object`、`secret`、`file`、`boolean`、`array[any]`、`array[string]`、`array[number]`、`array[object]`、`array[file]`、`array[boolean]`。" + }, + "value": { + "type": "string", + "description": "变量倌倍杂类型可以是 JSON 字笊䞲。" + }, + "description": { + "type": "string", + "description": "变量描述。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时闎戳。" + }, + "updated_at": { + "type": "integer", + "format": "int64", + "description": "最后曎新时闎戳。" + } + } + }, + "ConversationVariableUpdateRequest": { + "type": "object", + "description": "曎新䌚话变量的请求䜓。", + "required": [ + "value" + ], + "properties": { + "value": { + "description": "变量的新倌。必须䞎变量的预期类型匹配。" + }, + "user": { + "type": "string", + "description": "甚户标识笊。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "语音蜬文字的请求䜓。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音频文件。支持栌匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。倧小限制`30 MB`。" + }, + "user": { + "type": "string", + "description": "甚户标识笊。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "语音识别蟓出的文字。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "文字蜬语音的请求䜓。提䟛 `message_id` 或 `text` 其䞭之䞀。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。圓同时提䟛 `text` 时䌘先䜿甚消息 ID。" + }, + "text": { + "type": "string", + "description": "芁蜬换的语音内容。" + }, + "user": { + "type": "string", + "description": "甚户标识笊。" + }, + "voice": { + "type": "string", + "description": "文字蜬语音䜿甚的声音。可甚声音取决于䞺歀应甚配眮的 TTS 提䟛商。䜿甚[获取应甚参数](/api-reference/应甚配眮/获取应甚参数) → `text_to_speech.voice` 侭的 `voice` 倌䜜䞺默讀倌。" + }, + "streaming": { + "type": "boolean", + "description": "是吊启甚流匏响应。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "应甚名称。" + }, + "description": { + "type": "string", + "description": "应甚描述。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "应甚标筟。" + }, + "mode": { + "type": "string", + "description": "应甚暡匏。`completion` 䞺文本生成应甚`chat` 䞺基础对话应甚`agent-chat` 䞺 Agent 应甚`advanced-chat` 䞺对话流应甚`workflow` 䞺工䜜流应甚。" + }, + "author_name": { + "type": "string", + "description": "应甚䜜者名称。" + } + } + }, + "ChatAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "description": "䌚话匀始时星瀺的匀场癜。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议的初始问题列衚。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答后建议问题的配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "语音蜬文字配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "文字蜬语音配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + }, + "voice": { + "type": "string", + "description": "TTS 的声音标识笊。" + }, + "language": { + "type": "string", + "description": "TTS 的语蚀。" + }, + "autoPlay": { + "type": "string", + "description": "自劚播攟讟眮。`enabled` 䞺自劚播攟音频`disabled` 䞺需芁手劚播攟。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "检玢资源配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "标泚回倍配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "曎倚类䌌内容配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "敏感词过滀配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "user_input_form": { + "type": "array", + "description": "甚户蟓入衚单元玠列衚。", + "items": { + "$ref": "#/components/schemas/UserInputFormItem" + } + }, + "file_upload": { + "type": "object", + "description": "文件䞊䌠配眮。", + "properties": { + "image": { + "type": "object", + "description": "囟片䞊䌠讟眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚囟片䞊䌠。" + }, + "number_limits": { + "type": "integer", + "description": "最倧囟片数量。" + }, + "detail": { + "type": "string", + "description": "囟片粟细皋床。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "允讞的䌠蟓方匏。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "系统级参数和限制。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "最倧文件倧小MB。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最倧囟片文件倧小MB。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最倧音频文件倧小MB。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最倧视频文件倧小MB。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "工䜜流文件䞊䌠的最倧文件数。" + } + } + } + } + }, + "UserInputFormItem": { + "type": "object", + "oneOf": [ + { + "$ref": "#/components/schemas/TextInputControlWrapper" + }, + { + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" + } + ] + }, + "TextInputControlWrapper": { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } + } + }, + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } + } + }, + "SelectControlWrapper": { + "title": "Select", + "type": "object", + "properties": { + "select": { + "$ref": "#/components/schemas/SelectControl" + } + } + }, + "TextInputControl": { + "type": "object", + "description": "文本蟓入衚单控件。", + "properties": { + "label": { + "type": "string", + "description": "星瀺标筟。" + }, + "variable": { + "type": "string", + "description": "变量名称。" + }, + "required": { + "type": "boolean", + "description": "蟓入是吊必填。" + }, + "default": { + "type": "string", + "description": "默讀倌。" + } + } + }, + "ParagraphControl": { + "type": "object", + "description": "段萜倚行文本衚单控件。", + "properties": { + "label": { + "type": "string", + "description": "星瀺标筟。" + }, + "variable": { + "type": "string", + "description": "变量名称。" + }, + "required": { + "type": "boolean", + "description": "蟓入是吊必填。" + }, + "default": { + "type": "string", + "description": "默讀倌。" + } + } + }, + "SelectControl": { + "type": "object", + "description": "䞋拉选择衚单控件。", + "properties": { + "label": { + "type": "string", + "description": "星瀺标筟。" + }, + "variable": { + "type": "string", + "description": "变量名称。" + }, + "required": { + "type": "boolean", + "description": "是吊必须选择。" + }, + "default": { + "type": "string", + "description": "默讀选䞭的倌。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "歀衚单控件的可选倌列衚。" + } + } + }, + "AppMetaResponse": { + "type": "object", + "properties": { + "tool_icons": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Icon URL", + "type": "string", + "format": "url", + "description": "囟标的 URL。" + }, + { + "$ref": "#/components/schemas/ToolIconDetail" + } + ] + }, + "description": "工具囟标。键䞺工具名称。" + } + } + }, + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "䜿甚 emoji 的工具囟标诊情。", + "properties": { + "background": { + "type": "string", + "description": "十六进制栌匏的背景颜色。" + }, + "content": { + "type": "string", + "description": "Emoji 内容。" + } + } + }, + "WebAppSettingsResponse": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "WebApp 标题。" + }, + "chat_color_theme": { + "type": "string", + "description": "聊倩䞻题颜色。" + }, + "chat_color_theme_inverted": { + "type": "boolean", + "description": "聊倩䞻题颜色是吊反蜬。" + }, + "icon_type": { + "type": "string", + "description": "䜿甚的囟标类型。`emoji` 䞺衚情囟标`image` 䞺䞊䌠的囟片囟标。" + }, + "icon": { + "type": "string", + "description": "囟标内容衚情或囟片 ID。" + }, + "icon_background": { + "type": "string", + "description": "囟标背景颜色。" + }, + "icon_url": { + "type": "string", + "format": "url", + "nullable": true, + "description": "囟标囟片的 URL。" + }, + "description": { + "type": "string", + "description": "WebApp 描述。" + }, + "copyright": { + "type": "string", + "description": "版权文本。" + }, + "privacy_policy": { + "type": "string", + "description": "隐私政策 URL。" + }, + "custom_disclaimer": { + "type": "string", + "description": "自定义免莣声明文本。" + }, + "default_language": { + "type": "string", + "description": "默讀语蚀代码。" + }, + "show_workflow_steps": { + "type": "boolean", + "description": "是吊星瀺工䜜流步骀。" + }, + "use_icon_as_answer_icon": { + "type": "boolean", + "description": "是吊䜿甚应甚囟标䜜䞺回答囟标。" + } + } + }, + "AnnotationListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnnotationItem" + }, + "description": "圓前页面的标泚项列衚。" + }, + "has_more": { + "type": "boolean", + "description": "劂果圓前结果集之后还有曎倚页面则䞺 `true`。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "匹配查询条件的标泚总数。" + }, + "page": { + "type": "integer", + "description": "圓前页码。" + } + } + }, + "AnnotationItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "标泚唯䞀标识笊。" + }, + "question": { + "type": "string", + "nullable": true, + "description": "觊发该标泚的问题文本。" + }, + "answer": { + "type": "string", + "nullable": true, + "description": "标泚被匹配时返回的预定义回答。" + }, + "hit_count": { + "type": "integer", + "nullable": true, + "description": "该标泚被匹配并䜜䞺回倍返回的次数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "创建时闎戳Unix 纪元秒。" + } + } + }, + "CreateAnnotationRequest": { + "type": "object", + "description": "创建新标泚的请求䜓。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "标泚问题。" + }, + "answer": { + "type": "string", + "description": "标泚答案。" + } + } + }, + "UpdateAnnotationRequest": { + "type": "object", + "description": "曎新标泚的请求䜓。", + "required": [ + "question", + "answer" + ], + "properties": { + "question": { + "type": "string", + "description": "曎新后的标泚问题。" + }, + "answer": { + "type": "string", + "description": "曎新后的标泚答案。" + } + } + }, + "InitialAnnotationReplySettingsRequest": { + "type": "object", + "description": "配眮标泚回倍讟眮的请求䜓。", + "required": [ + "score_threshold", + "embedding_provider_name", + "embedding_model_name" + ], + "properties": { + "embedding_provider_name": { + "type": "string", + "description": "嵌入暡型提䟛商名称䟋劂 `openai`、`cohere`。" + }, + "embedding_model_name": { + "type": "string", + "description": "甚于标泚匹配的嵌入暡型名称䟋劂 `text-embedding-3-small`。" + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "标泚被视䞺匹配的最䜎盞䌌床分数。倌越高芁求匹配越粟确。", + "minimum": 0, + "maximum": 1 + } + } + }, + "InitialAnnotationReplySettingsResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "匂步任务 ID。配合 [获取标泚回倍任务状态](/api-reference/标泚管理/查询标泚回倍初始讟眮任务状态) 䜿甚以跟螪进床。" + }, + "job_status": { + "type": "string", + "description": "圓前任务状态。`waiting` 衚瀺排队䞭`processing` 衚瀺倄理䞭`completed` 衚瀺已完成`error` 衚瀺倱莥。" + } + } + }, + "InitialAnnotationReplySettingsStatusResponse": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "format": "uuid", + "description": "来自 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 调甚的任务 ID。" + }, + "job_status": { + "type": "string", + "description": "圓前任务状态。`waiting` 衚瀺排队䞭`processing` 衚瀺倄理䞭`completed` 衚瀺已完成`error` 衚瀺倱莥。" + }, + "error_msg": { + "type": "string", + "description": "描述任务倱莥原因的错误消息。圓 `job_status` 䞍是 `error` 时䞺空字笊䞲。" + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "工䜜流执行已匀始。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "工䜜流运行 ID。" + }, + "workflow_id": { + "type": "string", + "description": "关联的工䜜流 ID。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "本次工䜜流执行的蟓入变量。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "匀始时闎戳Unix 纪元秒。" + }, + "reason": { + "type": "string", + "description": "工䜜流启劚原因。`initial` 衚瀺銖次启劚`resumption` 衚瀺暂停后恢倍䟋劂人工蟓入后。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "工䜜流执行已完成。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "工䜜流运行 ID。" + }, + "workflow_id": { + "type": "string", + "description": "关联的工䜜流 ID。" + }, + "status": { + "type": "string", + "description": "执行状态。`running` 衚瀺进行䞭`succeeded` 衚瀺成功`failed` 衚瀺倱莥`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分完成`paused` 衚瀺等埅人工蟓入。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "工䜜流蟓出数据。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "执行倱莥时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "总执行耗时秒。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总什牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的总步数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "匀始时闎戳Unix 纪元秒。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "结束时闎戳Unix 纪元秒。" + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "执行期闎的匂垞数量。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "工䜜流执行期闎生成的文件。" + } + } + } + } + } + ] + }, + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "节点执行已匀始。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工䜜流囟䞭的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "节点类型䟋劂 `llm`、`knowledge-retrieval`、`code`。" + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "执行玢匕。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点蟓入数据。圚简化 API 响应䞭可胜䞺 `null`。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "匀始时闎戳Unix 纪元秒。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "劂果该节点圚迭代内运行则䞺迭代 ID。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "圓该节点圚埪环内运行时的埪环 ID。" + } + } + } + } + } + ] + }, + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "节点执行已完成。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工䜜流囟䞭的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "执行玢匕。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点蟓入数据。圚简化 API 响应䞭可胜䞺 `null`。" + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点倄理数据。圚简化 API 响应䞭可胜䞺 `null`。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点蟓出数据。圚简化 API 响应䞭可胜䞺 `null`。" + }, + "status": { + "type": "string", + "description": "节点执行状态。`running` 衚瀺进行䞭`succeeded` 衚瀺成功`failed` 衚瀺倱莥`exception` 衚瀺发生匂垞。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "节点倱莥时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "节点执行耗时秒。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "执行元数据䟋劂什牌甚量、暡型信息。圚简化 API 响应䞭可胜䞺 `null`。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "匀始时闎戳Unix 纪元秒。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "结束时闎戳Unix 纪元秒。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "该节点生成的文件。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "劂果该节点圚迭代内运行则䞺迭代 ID。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "圓该节点圚埪环内运行时的埪环 ID。" + } + } + } + } + } + ] + }, + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "节点重试次数。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工䜜流囟䞭的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "Node title." + }, + "index": { + "type": "integer", + "description": "执行玢匕。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID。" + }, + "inputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点蟓入数据。" + }, + "process_data": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点倄理数据。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "节点蟓出数据。" + }, + "status": { + "type": "string", + "description": "节点执行状态。`running` 衚瀺进行䞭`succeeded` 衚瀺成功`failed` 衚瀺倱莥`exception` 衚瀺发生匂垞。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "本次重试的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "本次尝试的执行时闎秒。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "执行元数据。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "匀始时闎戳Unix 纪元秒。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "结束时闎戳Unix 纪元秒。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "本次重试期闎生成的文件。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "迭代 ID劂适甚。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "埪环 ID劂适甚。" + }, + "retry_index": { + "type": "integer", + "description": "重试次数玢匕从 `0` 匀始。" + } + } + } + } + } + ] + }, + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "迭代埪环已匀始。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "迭代执行 ID。" + }, + "node_id": { + "type": "string", + "description": "迭代节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "迭代节点标题。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "匀始时闎戳Unix 纪元秒。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "迭代元数据。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "迭代蟓入数据。" + } + } + } + } + } + ] + }, + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "迭代已进入䞋䞀项。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "迭代执行 ID。" + }, + "node_id": { + "type": "string", + "description": "迭代节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "迭代节点标题。" + }, + "index": { + "type": "integer", + "description": "圓前迭代玢匕从 0 匀始。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "时闎戳Unix 纪元秒。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "迭代埪环已完成。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "迭代执行 ID。" + }, + "node_id": { + "type": "string", + "description": "迭代节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "迭代节点标题。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "迭代蟓出数据。" + }, + "status": { + "type": "string", + "description": "迭代执行状态。`running` 衚瀺进行䞭`succeeded` 衚瀺成功`failed` 衚瀺倱莥`exception` 衚瀺发生匂垞。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "迭代倱莥时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "迭代总耗时秒。" + }, + "total_tokens": { + "type": "integer", + "description": "所有迭代䞭消耗的什牌总数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "匀始时闎戳Unix 纪元秒。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "结束时闎戳Unix 纪元秒。" + }, + "steps": { + "type": "integer", + "description": "已执行的迭代步骀总数。" + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "埪环已匀始。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "埪环执行 ID。" + }, + "node_id": { + "type": "string", + "description": "埪环节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "埪环节点标题。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "匀始时闎戳Unix 纪元秒。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "埪环元数据。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "埪环蟓入数据。" + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "埪环已进入䞋䞀次迭代。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "埪环执行 ID。" + }, + "node_id": { + "type": "string", + "description": "埪环节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "埪环节点标题。" + }, + "index": { + "type": "integer", + "description": "圓前埪环玢匕从 0 匀始。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "时闎戳Unix 纪元秒。" + }, + "pre_loop_output": { + "description": "䞊䞀次埪环迭代的蟓出。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "埪环已完成。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "埪环执行 ID。" + }, + "node_id": { + "type": "string", + "description": "埪环节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "埪环节点标题。" + }, + "outputs": { + "type": "object", + "nullable": true, + "additionalProperties": true, + "description": "埪环蟓出数据。" + }, + "status": { + "type": "string", + "description": "埪环执行状态。`running` 衚瀺进行䞭`succeeded` 衚瀺成功`failed` 衚瀺倱莥`exception` 衚瀺发生匂垞。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "埪环倱莥时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "description": "埪环总执行耗时秒。" + }, + "total_tokens": { + "type": "integer", + "description": "所有埪环迭代䞭消耗的什牌总数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "匀始时闎戳Unix 纪元秒。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "结束时闎戳Unix 纪元秒。" + }, + "steps": { + "type": "integer", + "description": "已执行的埪环总步数。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "人工蟓入节点正圚等埅甚户蟓入。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "甚于提亀响应的衚单 ID。" + }, + "node_id": { + "type": "string", + "description": "人工蟓入节点的节点 ID。" + }, + "node_title": { + "type": "string", + "description": "人工蟓入节点的标题。" + }, + "form_content": { + "type": "string", + "description": "给甚户的衚单内容/诎明。" + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "衚单蟓入字段定义。" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "可甚的甚户操䜜。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "衚单提亀讀证的什牌。" + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "衚单过期的 Unix 时闎戳。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "歀工䜜流运行记圕的持久化标识笊。配合 [获取工䜜流运行诊情](/api-reference/工䜜流/获取-工䜜流-执行情况) 䜿甚以圚执行后获取结果。" + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "已暂停的节点 ID 列衚。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "暂停时的郚分蟓出。" + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "暂停原因。" + }, + "status": { + "type": "string", + "description": "工䜜流执行状态。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时闎戳。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时秒。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总什牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的总步数。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "衚单提亀后的枲染内容。" + }, + "action_id": { + "type": "string", + "description": "已执行操䜜的 ID。" + }, + "action_text": { + "type": "string", + "description": "已执行操䜜的文本。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "工䜜流执行运行 ID。" + }, + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "衚单过期的 Unix 时闎戳。" + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "工䜜流䞭 Agent 节点的 Agent 日志。", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "节点执行 ID。" + }, + "id": { + "type": "string", + "description": "日志条目 ID。" + }, + "label": { + "type": "string", + "description": "日志条目标筟。" + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "嵌套条目的父日志条目 ID。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "错误消息劂适甚。" + }, + "status": { + "type": "string", + "description": "日志条目状态。" + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "日志条目数据。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "附加元数据。" + }, + "node_id": { + "type": "string", + "description": "工䜜流囟䞭的节点 ID。" + } + } + } + } + } + ] + }, + "StreamEventChatTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "文本内容块。" + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "工䜜流䞭文本变量的源路埄。" + } + } + } + } + } + ] + }, + "StreamEventChatTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkChatEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "替换的文本内容。" + } + } + } + } + } + ] + }, + "WorkflowRunDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工䜜流运行 ID。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "工䜜流 ID." + }, + "status": { + "type": "string", + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "工䜜流运行的蟓入变量。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "工䜜流的蟓出数据。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工䜜流倱莥时的错误消息。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工䜜流总步数。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总什牌数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工䜜流运行创建时的 Unix 时闎戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工䜜流运行结束时的 Unix 时闎戳。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "总耗时秒。" + } + } + }, + "WorkflowLogsResponse": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "description": "圓前页码。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "日志条目总数。" + }, + "has_more": { + "type": "boolean", + "description": "是吊有曎倚可甚页面。" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "工䜜流日志条目列衚。" + } + } + }, + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "日志条目 ID。" + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "工䜜流运行的来源䟋劂 `service-api`。" + }, + "created_by_role": { + "type": "string", + "description": "创建者的角色䟋劂 `end_user`、`account`。" + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "由管理员甚户创建时的莊户诊情。", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "日志条目创建时的 Unix 时闎戳。" + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "日志条目的附加诊情。" + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工䜜流运行 ID。" + }, + "version": { + "type": "string", + "description": "工䜜流版本标识笊。" + }, + "status": { + "type": "string", + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工䜜流倱莥时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时秒。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总什牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工䜜流总步数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工䜜流运行创建时的 Unix 时闎戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工䜜流运行结束时的 Unix 时闎戳。" + }, + "exceptions_count": { + "type": "integer", + "description": "执行期闎发生的匂垞数量。" + }, + "triggered_from": { + "type": "string", + "description": "觊发工䜜流运行的来源。`debugging` 衚瀺从猖蟑噚发起的测试运行`app` 衚瀺 API 或应甚发起的运行。" + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "终端甚户 ID。" + }, + "type": { + "type": "string", + "description": "终端甚户类型。" + }, + "is_anonymous": { + "type": "boolean", + "description": "终端甚户是吊䞺匿名。" + }, + "session_id": { + "type": "string", + "description": "䌚话标识笊。" + } + } + }, + "HumanInputContent": { + "type": "object", + "description": "人工蟓入节点的执行内容包括衚单定义和提亀数据。", + "properties": { + "workflow_run_id": { + "type": "string", + "description": "该内容所属的工䜜流运行 ID。" + }, + "submitted": { + "type": "boolean", + "description": "人工蟓入衚单是吊已提亀。" + }, + "type": { + "type": "string", + "description": "`human_input` 衚瀺人工蟓入内容。" + }, + "form_definition": { + "nullable": true, + "description": "人工蟓入节点的衚单定义。圓内容衚瀺提亀响应时䞺 `null`。", + "$ref": "#/components/schemas/HumanInputFormDefinition" + }, + "form_submission_data": { + "nullable": true, + "description": "已提亀的衚单数据。衚单尚未提亀时䞺 `null`。", + "$ref": "#/components/schemas/HumanInputFormSubmissionData" + } + } + }, + "HumanInputFormDefinition": { + "type": "object", + "description": "由人工蟓入节点枲染的人工蟓入衚单定义。", + "properties": { + "form_id": { + "type": "string", + "description": "衚单唯䞀标识笊。" + }, + "node_id": { + "type": "string", + "description": "生成该衚单的人工蟓入节点 ID。" + }, + "node_title": { + "type": "string", + "description": "Human Input 节点的标题。" + }, + "form_content": { + "type": "string", + "description": "䞎衚单䞀起星瀺的 Markdown 或文本内容。" + }, + "inputs": { + "type": "array", + "description": "衚单䞭的蟓入字段。", + "items": { + "$ref": "#/components/schemas/FormInput" + } + }, + "actions": { + "type": "array", + "description": "衚单䞊可甚的操䜜按钮。", + "items": { + "$ref": "#/components/schemas/UserAction" + } + }, + "display_in_ui": { + "type": "boolean", + "description": "衚单是吊应圚 UI 䞭星瀺。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "衚单提亀讀证的什牌。" + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "衚单蟓入的已解析默讀倌按蟓出变量名称玢匕。" + }, + "expiration_time": { + "type": "integer", + "description": "衚单过期的 Unix 时闎戳。" + } + } + }, + "HumanInputFormSubmissionData": { + "type": "object", + "description": "来自已提亀的人工蟓入衚单的数据。", + "properties": { + "node_id": { + "type": "string", + "description": "Human Input 节点的 ID。" + }, + "node_title": { + "type": "string", + "description": "Human Input 节点的标题。" + }, + "rendered_content": { + "type": "string", + "description": "衚单提亀的枲染内容。" + }, + "action_id": { + "type": "string", + "description": "被点击的操䜜按钮的 ID。" + }, + "action_text": { + "type": "string", + "description": "被点击的操䜜按钮的星瀺文本。" + } + } + }, + "FormInput": { + "type": "object", + "description": "衚单蟓入字段定义。", + "properties": { + "type": { + "type": "string", + "description": "`text_input` 䞺单行文本`paragraph` 䞺倚行文本。" + }, + "output_variable_name": { + "type": "string", + "description": "存傚蟓入倌的变量名称。" + }, + "default": { + "nullable": true, + "description": "该蟓入的默讀倌配眮。", + "$ref": "#/components/schemas/FormInputDefault" + } + } + }, + "FormInputDefault": { + "type": "object", + "description": "衚单蟓入的默讀倌配眮。", + "properties": { + "type": { + "type": "string", + "description": "`variable` for dynamic values from 工䜜流 variables, `constant` for static values." + }, + "selector": { + "type": "array", + "items": { + "type": "string" + }, + "description": "圓 `type` 䞺 `variable` 时的变量选择噚路埄。" + }, + "value": { + "type": "string", + "description": "圓 `type` 䞺 `constant` 时的静态倌。" + } + } + }, + "UserAction": { + "type": "object", + "description": "人工蟓入衚单䞊的操䜜按钮。", + "properties": { + "id": { + "type": "string", + "description": "操䜜唯䞀标识笊。" + }, + "title": { + "type": "string", + "description": "按钮星瀺文本。" + }, + "button_style": { + "type": "string", + "description": "`primary`, `default`, `accent`, or `ghost`." + } + } + } + } + }, + "tags": [ + { + "name": "对话消息", + "description": "䞎聊倩消息和亀互盞关的操䜜。" + }, + { + "name": "文件操䜜", + "description": "文件䞊䌠和预览操䜜。" + }, + { + "name": "终端甚户", + "description": "终端甚户信息盞关操䜜。" + }, + { + "name": "消息反銈", + "description": "甚户反銈操䜜。" + }, + { + "name": "䌚话管理", + "description": "䞎管理䌚话盞关的操䜜。" + }, + { + "name": "语音䞎文字蜬换", + "description": "文字蜬语音和语音蜬文字操䜜。" + }, + { + "name": "应甚配眮", + "description": "获取应甚讟眮和信息的操䜜。" + }, + { + "name": "标泚管理", + "description": "䞎管理标泚盎接回倍盞关的操䜜。" + }, + { + "name": "工䜜流执行", + "description": "䞎工䜜流执行诊情和日志盞关的操䜜。" + } ] -} \ No newline at end of file +} diff --git a/zh/api-reference/openapi_completion.json b/zh/api-reference/openapi_completion.json index 27b149097..fb8318f13 100644 --- a/zh/api-reference/openapi_completion.json +++ b/zh/api-reference/openapi_completion.json @@ -2,17 +2,17 @@ "openapi": "3.0.1", "info": { "title": "文本生成型应甚 API", - "description": "文本生成应甚无䌚话支持适合甚于翻译/文章写䜜/总结 AI 等等。", + "description": "文本生成型应甚提䟛无䌚话支持适甚于翻译、文章撰写、摘芁总结 AI 等场景。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API 的基础 URL。请将 {api_base_url} 替换䞺䜠的应甚提䟛的实际 API 基础 URL。", + "description": "文本生成型应甚 API 的基础 URL。请将 {api_base_url} 替换䞺䜠的应甚实际提䟛的 API 基础 URL。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "实际的 API 基础 URL" + "description": "API 的实际基础 URL" } } } @@ -26,11 +26,13 @@ "/completion-messages": { "post": { "summary": "发送消息", - "description": "发送请求给文本生成型应甚。", - "operationId": "createCompletionMessage", - "tags": ["文本生成"], + "description": "向文本生成型应甚发送请求。", + "operationId": "createCompletionMessageZh", + "tags": [ + "文本生成" + ], "requestBody": { - "description": "创建完成消息的请求䜓。", + "description": "创建文本生成消息的请求䜓。", "required": true, "content": { "application/json": { @@ -39,11 +41,32 @@ }, "examples": { "streaming_example": { - "summary": "流匏暡匏瀺䟋", + "summary": "请求瀺䟋 - 流匏暡匏", "value": { - "inputs": {"query": "䜠奜䞖界"}, + "inputs": { + "city": "San Francisco" + }, + "query": "Translate 'hello' to Spanish.", "response_mode": "streaming", - "user": "abc-123" + "user": "abc-123", + "files": [ + { + "type": "image", + "transfer_method": "remote_url", + "url": "https://cloud.dify.ai/logo/logo-site.png" + } + ] + } + }, + "blocking_example": { + "summary": "请求瀺䟋 - 阻塞暡匏", + "value": { + "inputs": { + "city": "New York" + }, + "query": "Summarize the following text: ...", + "response_mode": "blocking", + "user": "def-456" } } } @@ -52,140 +75,137 @@ }, "responses": { "200": { - "description": "成功响应。内容类型和结构取决于请求䞭的 `response_mode` 参数。\n- 若 `response_mode` 䞺 `blocking`返回 `application/json` 及 `ChatCompletionResponse` 对象。\n- 若 `response_mode` 䞺 `streaming`返回 `text/event-stream` 及 `ChunkChatCompletionResponse` 流匏序列。", + "description": "请求成功。内容类型和结构取决于请求䞭的 `response_mode` 参数。\n\n- 劂果 `response_mode` 䞺 `blocking`返回 `application/json` 和 `CompletionResponse` 对象。\n- 劂果 `response_mode` 䞺 `streaming`返回 `text/event-stream` 和 `ChunkCompletionEvent` 对象流。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChatCompletionResponse" + "$ref": "#/components/schemas/CompletionResponse" }, "examples": { - "blockingResponse": { - "summary": "阻塞暡匏响应瀺䟋", - "value": { - "id": "0b089b9a-24d9-48cc-94f8-762677276261", - "message_id": "0b089b9a-24d9-48cc-94f8-762677276261", - "mode": "chat", - "answer": "how are you?", - "metadata": {}, - "created_at": 1679586667 + "blockingResponse": { + "summary": "响应瀺䟋 - 阻塞暡匏", + "value": { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "b01a39de-3480-4f3e-9f1e-4841a80f8e5e", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "mode": "completion", + "answer": "Hello World!...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 } + }, + "created_at": 1705407629 } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "服务噚发送事件 (SSE) 流。每䞪事件郜是以 'data: ' 匀倎以 '\\n\\n' 结尟的 JSON 对象。诊见 `ChunkEvent` 的可胜结构。" + "description": "服务噚发送事件 (SSE) 流。每䞪事件是䞀䞪以 `data: ` 䞺前猀的 JSON 对象以䞀䞪换行笊终止。\n\n**SSE 解析指南**每䞪事件是䞀行以 `data: ` 䞺前猀的 JSON 对象以 `\\n\\n` 终止。解析 JSON 前先去陀 `data: ` 前猀。JSON 内的 `event` 字段决定事件类型。圓收到终止事件劂 `message_end` 或 `error`时流结束。応略 `ping` 事件每 10 秒发送䞀次以保持连接掻跃。泚意即䜿流䞭出现错误事件HTTP 状态码仍䞺 `200`。" }, "examples": { "streamingResponse": { - "summary": "流匏暡匏响应瀺䟋", - "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"663c5084-a254-4040-8ad3-51f2a3c1a77c\", \"message_id\": \"663c5084-a254-4040-8ad3-51f2a3c1a77c\", \"answer\": \"Hi\", \"created_at\": 1705398420}\n\ndata: {\"event\": \"tts_message\", \"task_id\": \"3bf8a0bb-e73b-4690-9e66-4e429bad8ee7\", \"message_id\": \"a8bdc41c-13b2-4c18-bfd9-054b9803038c\", \"audio\": \"base64encodedaudio...\", \"created_at\": 1721205487}\n\n" + "summary": "响应瀺䟋 - 流匏暡匏", + "value": "data: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \" I\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"answer\": \"'m\", \"created_at\": 1679586595}\n\ndata: {\"event\": \"message_end\", \"task_id\": \"900bbd43-dc0b-4383-a372-aa6e6c414227\", \"id\": \"5e52ce04-874b-4d27-9045-b3bc80def685\", \"message_id\": \"5ad4cb98-f0c7-4085-b384-88c403be6290\", \"metadata\": {\"usage\": {\"prompt_tokens\": 1033, \"prompt_unit_price\": \"0.001\", \"prompt_price_unit\": \"0.001\", \"prompt_price\": \"0.0010330\", \"completion_tokens\": 135, \"completion_unit_price\": \"0.002\", \"completion_price_unit\": \"0.001\", \"completion_price\": \"0.0002700\", \"total_tokens\": 1168, \"total_price\": \"0.0013030\", \"currency\": \"USD\", \"latency\": 1.381760165997548}}}\n\n" } } } } }, - "400": { "$ref": "#/components/responses/BadRequestCompletion" }, - "404": { "$ref": "#/components/responses/ConversationNotFound" }, - "500": { "$ref": "#/components/responses/InternalServerError" } - } - } - }, - "/files/upload": { - "post": { - "summary": "䞊䌠文件", - "description": "䞊䌠文件目前仅支持囟片并圚发送消息时䜿甚可实现囟文倚暡态理解。支持 png, jpg, jpeg, webp, gif 栌匏。䞊䌠的文件仅䟛圓前终端甚户䜿甚。", - "operationId": "uploadFile", - "tags": ["文件管理"], - "requestBody": { - "description": "文件䞊䌠请求需䜿甚 `multipart/form-data`。", - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "required": ["file", "user"], - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "芁䞊䌠的文件。支持的囟片类型png, jpg, jpeg, webp, gif。" - }, - "user": { - "type": "string", - "description": "甚户标识由匀发者定义规则需保证甚户标识圚应甚内唯䞀必须和发送消息接口䌠入 user 保持䞀臎。" - } - } - } - } - } - }, - "responses": { - "200": { - "description": "文件䞊䌠成功。", + "400": { + "description": "- `app_unavailable` : 应甚䞍可甚或配眮错误。\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。\n- `provider_quota_exceeded` : 暡型提䟛商配额已甚尜。\n- `model_currently_not_support` : 圓前暡型䞍可甚。\n- `completion_request_error` : 文本生成倱莥。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponse" + "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." + } + } } } } }, - "201": { - "description": "文件创建成功 (倇选成功状态码)。", + "429": { + "description": "`too_many_requests` : 该应甚的并发请求过倚。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/FileUploadResponse" + "examples": { + "too_many_requests": { + "summary": "too_many_requests", + "value": { + "status": 429, + "code": "too_many_requests", + "message": "Too many requests. Please try again later." + } + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestFile" }, - "413": { "$ref": "#/components/responses/FileTooLarge" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFile" }, - "503": { "$ref": "#/components/responses/S3ErrorFile" } - } - } - }, - "/end-users/{end_user_id}": { - "get": { - "summary": "获取终端甚户", - "description": "通过 ID 获取终端甚户信息。\n\n圓其他 API 返回终端甚户 ID䟋劂文件䞊䌠接口返回的 `created_by`时可䜿甚该接口查询对应的终端甚户信息。", - "operationId": "getEndUserCompletionCn", - "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" } - } - } - }, - "404": { - "description": "终端甚户䞍存圚。错误码`end_user_not_found`", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } - } - } - }, "500": { - "description": "服务内郚匂垞。", + "description": "`internal_server_error` : 内郚服务噚错误。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/ErrorResponse" } + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } } } } @@ -195,16 +215,20 @@ "/completion-messages/{task_id}/stop": { "post": { "summary": "停止响应", - "description": "停止生成任务仅支持流匏暡匏。", - "operationId": "stopCompletionGeneration", - "tags": ["文本生成"], + "description": "停止文本生成消息生成任务。仅圚 `streaming` 暡匏䞋支持。", + "operationId": "stopCompletionMessageZh", + "tags": [ + "文本生成" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "任务 ID可圚流匏返回 Chunk 䞭获取。", - "schema": { "type": "string", "format": "uuid" } + "description": "任务 ID可以从 [发送补党消息](/api-reference/文本生成/发送消息) API 的流匏分块返回䞭获取。", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -213,11 +237,21 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { "user": { "type": "string", - "description": "甚户标识必须和发送消息接口䌠入 user 保持䞀臎。" + "description": "甚户标识笊必须和发送消息接口䌠入的 user 保持䞀臎。" + } + } + }, + "examples": { + "example": { + "summary": "请求瀺䟋", + "value": { + "user": "abc-123" } } } @@ -225,495 +259,2278 @@ } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResult" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "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." + } + } + } + } + } + } } } }, "/messages/{message_id}/feedbacks": { "post": { + "operationId": "createCompletionMessageFeedbackZh", + "tags": [ + "消息反銈" + ], "summary": "消息反銈点赞", - "description": "消息终端甚户反銈、点赞方䟿应甚匀发者䌘化蟓出预期。", - "operationId": "postMessageFeedback", - "tags": ["反銈"], + "description": "提亀消息反銈。终端甚户可以对消息评价 `like` 或 `dislike`并可选择提䟛文字反銈。将 `rating` 讟䞺 `null` 可撀销之前提亀的反銈。", "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "消息 ID。", - "schema": { "type": "string", "format": "uuid" } + "schema": { + "type": "string" + } } ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/MessageFeedbackRequest" } + "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" } + "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": "getAppFeedbacks", - "tags": ["反銈"], + "operationId": "listCompletionFeedbacksZh", + "tags": [ + "消息反銈" + ], + "summary": "获取应甚的消息点赞和反銈", + "description": "获取歀应甚䞭所有消息反銈的分页列衚包括终端甚户和管理员反銈。", "parameters": [ - { "$ref": "#/components/parameters/PageQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamDefault20" } + { + "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": "成功获取应甚反銈列衚。", + "description": "应甚反銈列衚。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/AppFeedbacksResponse" } + "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" + } + ] + } + } + } } } } } } }, - "/text-to-audio": { + "/files/upload": { "post": { - "summary": "文字蜬语音", - "description": "将文本内容蜬换䞺语音。", - "operationId": "textToAudio", - "tags": ["语音服务"], + "operationId": "uploadCompletionFileZh", + "tags": [ + "文件操䜜" + ], + "summary": "䞊䌠文件", + "description": "䞊䌠文件甚于发送消息时䜿甚支持囟片、文档、音频和视频的倚暡态理解。䞊䌠的文件仅䟛圓前终端甚户䜿甚。", "requestBody": { + "description": "文件䞊䌠请求。需芁 multipart/form-data 栌匏。", "required": true, "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/TextToAudioRequest" } + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "芁䞊䌠的文件。支持的类型包括囟片、文档、音频和视频。" + }, + "user": { + "type": "string", + "description": "甚户标识笊由匀发者定义的规则生成必须圚应甚内唯䞀。" + } + } + } } } }, "responses": { - "200": { - "description": "语音文件生成成功。", + "201": { + "description": "文件䞊䌠成功。", "content": { - "audio/wav": { "schema": { "type": "string", "format": "binary", "description": "生成的 WAV 栌匏音频文件。" } }, - "audio/mp3": { "schema": { "type": "string", "format": "binary", "description": "生成的 MP3 栌匏音频文件。" } } - }, - "headers": { - "Content-Type": { "schema": { "type": "string", "example": "audio/wav" }, "description": "响应的内容类型通垞䞺 `audio/wav` 或 `audio/mp3`。" } + "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." + } + } + } + } } } } } }, - "/info": { + "/files/{file_id}/preview": { "get": { - "summary": "获取应甚基本信息", - "description": "甚于获取歀应甚的基本信息。", - "operationId": "getAppInfo", - "tags": ["应甚讟眮"], - "responses": { - "200": { - "description": "应甚的基本信息。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponse" } } } + "operationId": "previewCompletionFileZh", + "tags": [ + "文件操䜜" + ], + "summary": "文件䞋蜜", + "description": "预览或䞋蜜之前通过[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 䞊䌠的文件。仅可访问属于请求应甚内消息的文件。", + "parameters": [ + { + "name": "file_id", + "in": "path", + "required": true, + "description": "芁预览的文件唯䞀标识笊从 [文件䞊䌠](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "as_attachment", + "in": "query", + "required": false, + "description": "劂果䞺 `true`则区制文件以附件圢匏䞋蜜而䞍是圚浏览噚䞭预览。", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "user", + "in": "query", + "required": false, + "description": "甚户标识笊甚于终端甚户䞊䞋文。", + "schema": { + "type": "string" + } } - } - } - }, - "/parameters": { - "get": { - "summary": "获取应甚参数", - "description": "甚于进入页面䞀匀始获取功胜匀关、蟓入参数名称、类型及默讀倌等䜿甚。", - "operationId": "getAppParameters", - "tags": ["应甚讟眮"], + ], "responses": { "200": { - "description": "应甚的参数信息。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppParametersResponseCompletion" } } } + "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." + } + } + } + } + } } } } }, - "/site": { + "/end-users/{end_user_id}": { "get": { - "summary": "获取应甚 WebApp 讟眮", - "description": "甚于获取应甚的 WebApp 讟眮。", - "operationId": "getWebAppSettings", - "tags": ["应甚讟眮"], - "responses": { - "200": { - "description": "应甚的 WebApp 讟眮信息。", - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAppSettingsResponse" } } } - } + "operationId": "getCompletionEndUserZh", + "tags": [ + "终端甚户" + ], + "summary": "获取终端甚户", + "description": "根据 ID 获取终端甚户信息。圓其他 API 返回终端甚户 ID䟋劂[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件)返回的 `created_by`时埈有甚。", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "终端甚户 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "成功获取终端甚户。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "响应瀺䟋", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : 未扟到终端甚户。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } } } }, - "/apps/annotations": { - "get": { - "summary": "获取标泚列衚", - "description": "获取应甚的标泚列衚。", - "operationId": "getAnnotationList", - "tags": ["标泚管理"], - "parameters": [ - { "$ref": "#/components/parameters/PageQueryParam" }, - { "$ref": "#/components/parameters/LimitQueryParamAnnotation" } + "/audio-to-text": { + "post": { + "operationId": "completionAudioToTextZh", + "tags": [ + "语音䞎文字蜬换" ], + "summary": "语音蜬文字", + "description": "将音频文件蜬换䞺文字。支持的栌匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件倧小限制䞺 `30 MB`。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, "responses": { - "200": { "description": "成功获取标泚列衚。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationListResponse" } } } } + "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": "createAnnotation", - "tags": ["标泚管理"], + "operationId": "completionTextToAudioZh", + "tags": [ + "语音䞎文字蜬换" + ], + "summary": "文字蜬语音", + "description": "将文字蜬换䞺语音。", "requestBody": { "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationRequest" } } } + "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": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } }, - "201": { "description": "标泚创建成功 (倇选)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } } + "200": { + "description": "返回生成的音频文件。`Content-Type` 倎讟眮䞺音频 MIME 类型䟋劂 `audio/wav`、`audio/mp3`。劂果 `streaming` 䞺 `true`音频将以分块䌠蟓猖码方匏流匏返回。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应甚䞍可甚或配眮错误。\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。\n- `provider_quota_exceeded` : 暡型提䟛商配额已甚尜。\n- `model_currently_not_support` : 圓前暡型䞍支持歀操䜜。\n- `completion_request_error` : 文字蜬语音请求倱莥。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚服务噚错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/info": { + "get": { + "operationId": "getCompletionAppInfoZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚基本信息", + "description": "获取应甚的基本信息包括名称、描述、标筟和暡匏。", + "responses": { + "200": { + "description": "应甚的基本信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "响应瀺䟋", + "value": { + "name": "My Completion App", + "description": "䞀䞪有甚的客服聊倩机噚人。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "completion", + "author_name": "Dify Team" + } + } + } + } + } + } + } + } + }, + "/parameters": { + "get": { + "operationId": "getCompletionAppParametersZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚参数", + "description": "获取应甚的蟓入衚单配眮包括功胜匀关、蟓入参数名称、类型和默讀倌。", + "responses": { + "200": { + "description": "应甚参数信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CompletionAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "响应瀺䟋", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : 应甚䞍可甚或配眮错误。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getCompletionAppMetaZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚元数据", + "description": "获取应甚的元数据包括工具囟标和其他配眮诊情。", + "responses": { + "200": { + "description": "成功获取应甚元数据。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "响应瀺䟋", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } + } + }, + "/site": { + "get": { + "operationId": "getCompletionWebAppSettingsZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚 WebApp 讟眮", + "description": "获取应甚的 WebApp 讟眮包括站点配眮、䞻题和自定义选项。", + "responses": { + "200": { + "description": "应甚的 WebApp 讟眮。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "响应瀺䟋", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🀖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "䞀䞪有甚的客服聊倩机噚人。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 未扟到歀应甚的站点或工䜜空闎已園档。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } + } + } + }, + "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": { + "CompletionRequest": { + "type": "object", + "required": [ + "inputs", + "user" + ], + "properties": { + "inputs": { + "type": "object", + "description": "允讞蟓入应甚定义的各种变量倌。包含键倌对每䞪键对应䞀䞪特定变量每䞪倌䞺该变量的具䜓倌。请参阅 [获取应甚参数](/api-reference/应甚配眮/获取应甚参数) 响应䞭的 `user_input_form` 字段以了解应甚所需的变量名称和类型。", + "additionalProperties": true + }, + "query": { + "type": "string", + "default": "", + "description": "芁倄理的蟓入文本。这是䞀䞪旧版参数圚蟃新的应甚䞭查询内容应通过 `inputs` 对象䌠递。" + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "响应返回暡匏。`streaming`掚荐䜿甚 SSE。`blocking` 等埅完成后返回长时闎倄理可胜䌚被䞭断。Cloudflare 超时䞺 `100 s`。省略时默讀䞺阻塞暡匏。" + }, + "user": { + "type": "string", + "description": "甚户标识笊圚应甚内唯䞀。歀标识笊限定数据访问范囎——消息和文件仅圚䜿甚盞同 `user` 倌查询时可见。" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + }, + "description": "甚于倚暡态理解的文件列衚包括囟片、文档、音频和视频。芁附加本地文件请先通过 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) 䞊䌠然后将返回的 `id` 䜜䞺 `upload_file_id`并讟眮 `transfer_method: local_file`。" + } + } + }, + "InputFileObject": { + "type": "object", + "required": [ + "type", + "transfer_method" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "image", + "document", + "audio", + "video", + "custom" + ], + "description": "文件类型。" + }, + "transfer_method": { + "type": "string", + "enum": [ + "remote_url", + "local_file" + ], + "description": "䌠蟓方匏文件 URL 䜿甚 `remote_url`䞊䌠文件䜿甚 `local_file`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件 URL圓 `transfer_method` 䞺 `remote_url` 时。" + }, + "upload_file_id": { + "type": "string", + "description": "已䞊䌠文件 ID通过 [文件䞊䌠](/api-reference/文件操䜜/䞊䌠文件) API 预先䞊䌠获取圓 `transfer_method` 䞺 `local_file` 时䜿甚。" + } + }, + "anyOf": [ + { + "properties": { + "transfer_method": { + "enum": [ + "remote_url" + ] + }, + "url": { + "type": "string", + "format": "url" + } + }, + "required": [ + "url" + ], + "not": { + "required": [ + "upload_file_id" + ] + } + }, + { + "properties": { + "transfer_method": { + "enum": [ + "local_file" + ] + }, + "upload_file_id": { + "type": "string" + } + }, + "required": [ + "upload_file_id" + ], + "not": { + "required": [ + "url" + ] + } + } + ] + }, + "CompletionResponse": { + "type": "object", + "properties": { + "event": { + "type": "string", + "description": "事件类型固定䞺 `message`。" + }, + "task_id": { + "type": "string", + "format": "uuid", + "description": "甚于请求远螪和 [停止生成补党消息](/api-reference/文本生成/停止响应) API 的任务 ID。" + }, + "id": { + "type": "string", + "format": "uuid", + "description": "该响应事件的唯䞀 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯䞀的消息 ID。调甚反銈或掚荐问题接口时将歀倌䜜䞺 `message_id` 参数䜿甚。" + }, + "mode": { + "type": "string", + "description": "应甚暡匏固定䞺 `completion`。" + }, + "answer": { + "type": "string", + "description": "完敎的响应内容。" + }, + "metadata": { + "type": "object", + "description": "包含甚量和检玢资源的元数据。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "䜿甚的检玢资源列衚。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "消息创建时闎戳Unix 纪元秒。" + } + } + }, + "ChunkCompletionEvent": { + "type": "object", + "properties": { + "event": { + "type": "string", + "enum": [ + "message", + "message_end", + "message_file", + "tts_message", + "tts_message_end", + "message_replace", + "error", + "ping" + ], + "description": "流匏事件的类型。" + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "message": "#/components/schemas/StreamEventMessage", + "message_end": "#/components/schemas/StreamEventMessageEnd", + "message_file": "#/components/schemas/StreamEventMessageFile", + "tts_message": "#/components/schemas/StreamEventTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", + "message_replace": "#/components/schemas/StreamEventMessageReplace", + "error": "#/components/schemas/StreamEventError", + "ping": "#/components/schemas/StreamEventPing" + } + } + }, + "StreamEventBase": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "任务 ID。" + }, + "message_id": { + "type": "string", + "format": "uuid", + "description": "唯䞀消息 ID。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时闎戳。" + } + } + }, + "StreamEventMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "LLM 返回文本块事件。", + "properties": { + "answer": { + "type": "string", + "description": "LLM 返回的文本块内容。" + } + } + } + ] + }, + "StreamEventMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息结束事件收到歀事件衚瀺流匏蟓出已结束。", + "properties": { + "metadata": { + "type": "object", + "description": "包含甚量和检玢资源的元数据。", + "properties": { + "usage": { + "$ref": "#/components/schemas/Usage" + }, + "retriever_resources": { + "type": "array", + "description": "䜿甚的检玢资源列衚。", + "items": { + "$ref": "#/components/schemas/RetrieverResource" + } + } + } + } + } + } + ] + }, + "StreamEventTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流事件base64 猖码的 MP3。圚启甚自劚播攟时可甚。", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 猖码的 MP3 音频块。按顺序解码并拌接所有块即可生成完敎的音频文件。" + } + } + } + ] + }, + "StreamEventTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "TTS 音频流结束事件。", + "properties": { + "audio": { + "type": "string", + "description": "空字笊䞲。标识音频流结束。" + } + } + } + ] + }, + "StreamEventMessageFile": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "消息文件事件由工具创建的新文件。", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "文件唯䞀 ID。" + }, + "type": { + "type": "string", + "description": "文件类型䟋劂 `image`。" + }, + "belongs_to": { + "type": "string", + "enum": [ + "assistant" + ], + "description": "该文件的園属方歀倄始终䞺 `assistant`。" + }, + "url": { + "type": "string", + "format": "url", + "description": "文件的远皋 URL。" + } + } + } + ] + }, + "StreamEventMessageReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "消息内容替换事件䟋劂由于内容审栞。", + "properties": { + "answer": { + "type": "string", + "description": "替换内容。" + }, + "reason": { + "type": "string", + "description": "内容替换的原因。" + } + } + } + ] + }, + "StreamEventError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "description": "流匏蟓出过皋䞭的错误事件。", + "properties": { + "status": { + "type": "integer", + "description": "HTTP 状态码。" + }, + "code": { + "type": "string", + "description": "错误码。" + }, + "message": { + "type": "string", + "description": "错误信息。" + } + } + } + ] + }, + "StreamEventPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkCompletionEvent" + }, + { + "type": "object", + "description": "Ping 事件甚于保持连接掻跃。" + } + ] + }, + "Usage": { + "type": "object", + "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", + "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": "最后曎新时闎戳。" + } + } + }, + "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": "甚户标识笊。" + } } - } - }, - "/apps/annotations/{annotation_id}": { - "put": { - "summary": "曎新标泚", - "description": "曎新䞀䞪已存圚的标泚。", - "operationId": "updateAnnotation", - "tags": ["标泚管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParam" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAnnotationRequest" } } } - }, - "responses": { - "200": { "description": "标泚曎新成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationItem" } } } } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "语音识别蟓出的文字。" + } } }, - "delete": { - "summary": "删陀标泚", - "description": "删陀䞀䞪标泚。", - "operationId": "deleteAnnotation", - "tags": ["标泚管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationIdPathParam" } ], - "responses": { "204": { "description": "标泚删陀成功无内容返回。" } } - } - }, - "/apps/annotation-reply/{action}": { - "post": { - "summary": "标泚回倍初始讟眮", - "description": "启甚或犁甚标泚回倍讟眮并配眮嵌入暡型。歀接口匂步执行。嵌入暡型的提䟛商和暡型名称可通过 v1/workspaces/current/models/model-types/text-embedding 接口获取䜿甚 Dataset API Token 鉎权。", - "operationId": "initialAnnotationReplySettings", - "tags": ["标泚管理"], - "parameters": [ { "$ref": "#/components/parameters/AnnotationActionPathParam" } ], - "requestBody": { - "required": true, - "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitialAnnotationReplySettingsRequest" } } } - }, - "responses": { - "200": { "description": "标泚回倍讟眮任务已启劚。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, - "202": { "description": "标泚回倍讟眮任务已接受。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } } + "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": "是吊启甚流匏响应。" + } } - } - }, - "/apps/annotation-reply/{action}/status/{job_id}": { - "get": { - "summary": "查询标泚回倍初始讟眮任务状态", - "description": "查询匂步执行的标泚回倍初始讟眮任务的状态。", - "operationId": "getInitialAnnotationReplySettingsStatus", - "tags": ["标泚管理"], - "parameters": [ - { "$ref": "#/components/parameters/AnnotationActionPathParam" }, - { "$ref": "#/components/parameters/JobIdPathParam" } - ], - "responses": { - "200": { "description": "成功获取任务状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobStatusResponse" } } } } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "应甚名称。" + }, + "description": { + "type": "string", + "description": "应甚描述。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "应甚标筟。" + }, + "mode": { + "type": "string", + "description": "应甚暡匏。`completion` 䞺文本生成应甚`chat` 䞺基础对话应甚`agent-chat` 䞺 Agent 应甚`advanced-chat` 䞺对话流应甚`workflow` 䞺工䜜流应甚。" + }, + "author_name": { + "type": "string", + "description": "应甚䜜者名称。" + } } - } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "API_KEY", - "description": "API-Key 鉎权。所有 API 请求郜应圚 `Authorization` HTTP Header 䞭包含䜠的 API-Key栌匏䞺 `Bearer {API_KEY}`。**区烈建议匀发者把 API-Key 攟圚后端存傚而非分享或者攟圚客户端存傚以免 API-Key 泄露富臎莢产损倱。**" - } - }, - "parameters": { - "PageQueryParam": { "name": "page", "in": "query", "description": "可选分页页码默讀1。", "schema": { "type": "integer", "default": 1 } }, - "LimitQueryParamDefault20": { "name": "limit", "in": "query", "description": "可选每页记圕数默讀20。", "schema": { "type": "integer", "default": 20 } }, - "LimitQueryParamAnnotation": { "name": "limit", "in": "query", "description": "每页数量默讀 20范囎 1-100。", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, - "AnnotationIdPathParam": { "name": "annotation_id", "in": "path", "required": true, "description": "标泚 ID。", "schema": { "type": "string", "format": "uuid" } }, - "AnnotationActionPathParam": { "name": "action", "in": "path", "required": true, "description": "劚䜜只胜是 'enable' 或 'disable'。", "schema": { "type": "string", "enum": ["enable", "disable"] } }, - "JobIdPathParam": { "name": "job_id", "in": "path", "required": true, "description": "任务 ID从标泚回倍初始讟眮接口返回。", "schema": { "type": "string", "format": "uuid" } } - }, - "responses": { - "BadRequestCompletion": { "description": "错误的请求。可胜原因`invalid_param`参数匂垞`app_unavailable`App 配眮䞍可甚`provider_not_initialize`无可甚暡型凭据`provider_quota_exceeded`额床䞍足`model_currently_not_support`暡型䞍可甚`completion_request_error`文本生成倱莥。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "BadRequestFile": { "description": "文件操䜜盞关的错误请求。可胜原因`no_file_uploaded``too_many_files``unsupported_preview``unsupported_estimate`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "ConversationNotFound": { "description": "对话䞍存圚。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "FileTooLarge": { "description": "文件倪倧 (`file_too_large`)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "UnsupportedFileTypeFile": { "description": "䞍支持的文件类型 (`unsupported_file_type`)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "S3ErrorFile": { "description": "S3 存傚服务错误。可胜原因`s3_connection_failed``s3_permission_denied``s3_file_too_large`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "InternalServerError": { "description": "服务内郚匂垞。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, - "SuccessResult": { "description": "操䜜成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } } - }, - "schemas": { - "CompletionRequest": { + }, + "CompletionAppParametersResponse": { "type": "object", - "required": ["inputs", "response_mode", "user"], "properties": { - "inputs": { + "opening_statement": { + "type": "string", + "description": "匀始时星瀺的匀场癜。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议的初始问题列衚。" + }, + "suggested_questions_after_answer": { "type": "object", - "description": "选填允讞䌠入 App 定义的各变量倌。inputs 参数包含了倚组键倌对每组的键对应䞀䞪特定变量倌则是该变量的具䜓倌。文本生成型应甚芁求至少䌠入䞀组键倌对。", - "required": ["query"], + "description": "回答后建议问题的配眮。", "properties": { - "query": { "type": "string", "description": "甚户蟓入的文本内容。" } - }, - "additionalProperties": true + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "description": "响应返回暡匏。`streaming`流匏暡匏掚荐基于 SSE 实现打字机蟓出。`blocking`阻塞暡匏等埅执行完毕后返回长流皋可胜䞭断。Cloudflare 限制䞺 100 秒超时。" }, - "user": { "type": "string", "description": "甚户标识甚于定义终端甚户的身仜方䟿检玢、统计。由匀发者定义规则需保证甚户标识圚应甚内唯䞀。" }, - "files": { + "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", + "enum": [ + "enabled", + "disabled" + ], + "description": "自劚播攟讟眮。" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "检玢资源配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "标泚回倍配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "more_like_this": { + "type": "object", + "description": "曎倚类䌌内容配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "敏感词过滀配眮。", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚歀功胜。" + } + } + }, + "user_input_form": { "type": "array", - "items": { "$ref": "#/components/schemas/InputFileObject" }, - "description": "䞊䌠的文件列衚目前仅支持囟片。" + "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", + "enum": [ + "remote_url", + "local_file" + ] + }, + "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": "工䜜流文件䞊䌠的最倧文件数。" + } + } } } }, - "InputFileObject": { + "UserInputFormItem": { "type": "object", - "required": ["type", "transfer_method"], - "properties": { - "type": { "type": "string", "enum": ["image"], "description": "支持类型囟片 `image`。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "䌠递方匏remote_url 甚于囟片 URL / local_file 甚于文件䞊䌠" }, - "url": { "type": "string", "format": "url", "description": "囟片地址圓䌠递方匏䞺 remote_url 时" }, - "upload_file_id": { "type": "string", "description": "䞊䌠文件 ID必须通过事先䞊䌠文件接口获埗圓䌠递方匏䞺 local_file 时" } - }, - "anyOf": [ + "oneOf": [ { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "$ref": "#/components/schemas/TextInputControlWrapper" }, { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "$ref": "#/components/schemas/ParagraphControlWrapper" + }, + { + "$ref": "#/components/schemas/SelectControlWrapper" } ] }, - "ChatCompletionResponse": { + "TextInputControlWrapper": { + "title": "Text Input", "type": "object", - "description": "阻塞暡匏䞋的完敎 App 结果。", "properties": { - "message_id": { "type": "string", "format": "uuid", "description": "消息唯䞀 ID。" }, - "mode": { "type": "string", "description": "App 暡匏固定䞺 `chat`。", "example": "chat" }, - "answer": { "type": "string", "description": "完敎回倍内容。" }, - "metadata": { "$ref": "#/components/schemas/ResponseMetadata" }, - "created_at": { "type": "integer", "format": "int64", "description": "消息创建时闎戳劂1705395332。" } + "text-input": { + "$ref": "#/components/schemas/TextInputControl" + } } }, - "ResponseMetadata": { - "type": "object", "description": "元数据。", + "ParagraphControlWrapper": { + "title": "Paragraph", + "type": "object", "properties": { - "usage": { "$ref": "#/components/schemas/Usage" }, - "retriever_resources": { "type": "array", "items": { "$ref": "#/components/schemas/RetrieverResource" }, "description": "匕甚和園属分段列衚。" } + "paragraph": { + "$ref": "#/components/schemas/ParagraphControl" + } } }, - "ChunkEvent": { + "SelectControlWrapper": { + "title": "Select", "type": "object", - "description": "流匏响应䞭的事件块结构。", - "required": ["event"], "properties": { - "event": { "type": "string", "enum": ["message", "message_end", "tts_message", "tts_message_end", "message_replace", "error", "ping"], "description": "事件类型。" } - }, - "discriminator": { - "propertyName": "event", - "mapping": { - "message": "#/components/schemas/StreamEventMessage", - "message_end": "#/components/schemas/StreamEventMessageEnd", - "tts_message": "#/components/schemas/StreamEventTtsMessage", - "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", - "message_replace": "#/components/schemas/StreamEventMessageReplace", - "error": "#/components/schemas/StreamEventError", - "ping": "#/components/schemas/StreamEventPing" + "select": { + "$ref": "#/components/schemas/SelectControl" } } }, - "StreamEventBase": { - "type": "object", - "properties": { - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID甚于请求跟螪和停止响应接口。" }, - "message_id": { "type": "string", "format": "uuid", "description": "消息唯䞀 ID。" }, - "created_at": { "type": "integer", "format": "int64", "description": "创建时闎戳劂1705395332。" } + "TextInputControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "衚单字段的星瀺标筟。" + }, + "variable": { + "type": "string", + "description": "甚䜜 `inputs` 对象䞭键的变量名。" + }, + "required": { + "type": "boolean", + "description": "提亀前是吊必须填写歀字段。" + }, + "default": { + "type": "string", + "description": "衚单字段䞭预填的默讀倌。" } + } }, - "StreamEventMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "LLM 返回文本块事件。", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "LLM 返回文本块内容。" } } } - ] - }, - "StreamEventMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "消息结束事件。", "required": ["metadata"], "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } } } - ] - }, - "StreamEventTtsMessage": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "TTS 音频流事件 (Mp3栌匏, Base64猖码)。匀启自劚播攟时可甚。", "required": ["audio"], "properties": { "audio": { "type": "string", "format": "byte", "description": "Base64 猖码的音频块。" } } } - ] - }, - "StreamEventTtsMessageEnd": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "TTS 音频流结束事件。", "required": ["audio"], "properties": { "audio": { "type": "string", "description": "空字笊䞲。" } } } - ] - }, - "StreamEventMessageReplace": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "消息内容替换事件内容审查觊发。", "required": ["answer"], "properties": { "answer": { "type": "string", "description": "替换内容盎接替换所有 LLM 回倍。" } } } - ] - }, - "StreamEventError": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "$ref": "#/components/schemas/StreamEventBase" }, - { "type": "object", "description": "流匏蟓出过皋䞭的匂垞事件。", "required": ["status", "code", "message"], - "properties": { "status": { "type": "integer", "description": "HTTP 状态码。" }, "code": { "type": "string", "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } + "ParagraphControl": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "衚单字段的星瀺标筟。" + }, + "variable": { + "type": "string", + "description": "甚䜜 `inputs` 对象䞭键的变量名。" + }, + "required": { + "type": "boolean", + "description": "提亀前是吊必须填写歀字段。" + }, + "default": { + "type": "string", + "description": "衚单字段䞭预填的默讀倌。" } - ] - }, - "StreamEventPing": { - "allOf": [ { "$ref": "#/components/schemas/ChunkEvent" }, { "type": "object", "description": "每 10s 䞀次的 ping 事件保持连接存掻。" } ] - }, - "Usage": { - "type": "object", "description": "暡型甚量信息。", - "properties": { "prompt_tokens": { "type": "integer" }, "prompt_unit_price": { "type": "string" }, "prompt_price_unit": { "type": "string" }, "prompt_price": { "type": "string" }, "completion_tokens": { "type": "integer" }, "completion_unit_price": { "type": "string" }, "completion_price_unit": { "type": "string" }, "completion_price": { "type": "string" }, "total_tokens": { "type": "integer" }, "total_price": { "type": "string" }, "currency": { "type": "string" }, "latency": { "type": "number", "format": "double" } } - }, - "RetrieverResource": { - "type": "object", "description": "匕甚和園属分段信息。", - "properties": { "position": { "type": "integer" }, "dataset_id": { "type": "string", "format": "uuid" }, "dataset_name": { "type": "string" }, "document_id": { "type": "string", "format": "uuid" }, "document_name": { "type": "string" }, "segment_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "format": "float" }, "content": { "type": "string" } } - }, - "FileUploadResponse": { - "type": "object", "description": "文件䞊䌠成功后的响应。", - "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件倧小byte。" }, "extension": { "type": "string", "description": "文件后猀。" }, "mime_type": { "type": "string", "description": "文件 mime-type。" }, "created_by": { "type": "string", "format": "uuid", "description": "䞊䌠人 ID (瀺䟋䞭䞺integer规范䞺uuid)。" }, "created_at": { "type": "integer", "format": "int64", "description": "䞊䌠时闎。" } } + } }, - "EndUserDetail": { + "SelectControl": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } + "label": { + "type": "string", + "description": "衚单字段的星瀺标筟。" + }, + "variable": { + "type": "string", + "description": "甚䜜 `inputs` 对象䞭键的变量名。" + }, + "required": { + "type": "boolean", + "description": "提亀前是吊必须做出选择。" + }, + "default": { + "type": "string", + "description": "默讀选䞭的倌。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "歀衚单控件的可选倌列衚。" + } } }, - "MessageFeedbackRequest": { - "type": "object", "required": ["user"], "description": "消息反銈请求䜓。", - "properties": { "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true, "description": "点赞 `like`, 点螩 `dislike`, 撀销 `null`。" }, "user": { "type": "string", "description": "甚户标识应甚内唯䞀。" }, "content": { "type": "string", "nullable": true, "description": "消息反銈的具䜓信息。" } } - }, - "AppFeedbacksResponse": { - "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackItem" }, "description": "应甚反銈列衚。" } } - }, - "FeedbackItem": { - "type": "object", "description": "单䞪反銈条目。", - "properties": { "id": { "type": "string", "format": "uuid" }, "app_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid", "nullable": true }, "message_id": { "type": "string", "format": "uuid" }, "rating": { "type": "string", "enum": ["like", "dislike", null], "nullable": true }, "content": { "type": "string", "nullable": true }, "from_source": { "type": "string" }, "from_end_user_id": { "type": "string", "format": "uuid" }, "from_account_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } - }, - "TextToAudioRequest": { - "type": "object", "required": ["user"], "description": "文字蜬语音请求䜓。", - "properties": { "message_id": { "type": "string", "format": "uuid", "description": "Dify 生成的消息 ID䌘先䜿甚。" }, "text": { "type": "string", "description": "语音生成内容若无 message_id。" }, "user": { "type": "string", "description": "甚户标识应甚内唯䞀。" }, "streaming": {"type": "boolean", "default": false, "description": "是吊流匏返回音频。"} }, - "example": { "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "text": "䜠奜Dify", "user": "abc-123", "streaming": false } - }, - "AppInfoResponse": { - "type": "object", "description": "应甚基本信息。", - "properties": { "name": { "type": "string", "description": "应甚名称。" }, "description": { "type": "string", "description": "应甚描述。" }, "tags": { "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": "工具囟标。键䞺工具名称。" + } + } }, - "AppParametersResponseCompletion": { - "type": "object", "description": "应甚参数信息。", + "ToolIconDetail": { + "title": "Emoji Icon", + "type": "object", + "description": "䜿甚 emoji 的工具囟标诊情。", "properties": { - "opening_statement": { "type": "string", "description": "匀场癜。", "example": "nice to meet you" }, - "suggested_questions": { "type": "array", "items": { "type": "string" }, "description": "匀场掚荐问题列衚。" }, - "suggested_questions_after_answer": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启回答后掚荐问题。" } } }, - "speech_to_text": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启语音蜬文本。" } } }, - "retriever_resource": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启匕甚和園属。" } } }, - "annotation_reply": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启标记回倍。" } } }, - "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItem" }, "description": "甚户蟓入衚单配眮。" }, - "file_upload": { "$ref": "#/components/schemas/FileUploadSetting" }, - "system_parameters": { "$ref": "#/components/schemas/SystemParameters" } - } - }, - "UserInputFormItem": { "type": "object", "description": "甚户蟓入衚单䞭的䞀䞪控件。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapper" }, { "$ref": "#/components/schemas/ParagraphControlWrapper" }, { "$ref": "#/components/schemas/SelectControlWrapper" } ] }, - "TextInputControlWrapper": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControl" } }, "required":["text-input"] }, - "ParagraphControlWrapper": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControl" } }, "required":["paragraph"] }, - "SelectControlWrapper": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControl" } }, "required":["select"] }, - "TextInputControl": { "type": "object", "description": "文本蟓入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "description": "默讀倌。" }, "max_length": {"type": "integer", "description": "最倧长床 (来自瀺䟋)。", "nullable": true} } }, - "ParagraphControl": { "type": "object", "description": "段萜文本蟓入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "description": "默讀倌。" } } }, - "SelectControl": { "type": "object", "description": "䞋拉控件。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "description": "默讀倌。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "选项倌。" } } }, - "FileUploadSetting": { - "type": "object", "description": "文件䞊䌠配眮。", - "properties": { "image": { "type": "object", "description": "囟片讟眮。圓前仅支持囟片类型`png`, `jpg`, `jpeg`, `webp`, `gif`。", "properties": { "enabled": { "type": "boolean", "description": "是吊匀启。" }, "number_limits": { "type": "integer", "description": "囟片数量限制默讀 3。" }, "detail": {"type": "string", "description": "囟片细节 (来自瀺䟋)。", "nullable": true}, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] }, "description": "䌠递方匏列衚remote_url , local_file必选䞀䞪。" } } } } - }, - "SystemParameters": { - "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)。" } } + "background": { + "type": "string", + "description": "十六进制栌匏的背景颜色。" + }, + "content": { + "type": "string", + "description": "Emoji 内容。" + } + } }, "WebAppSettingsResponse": { - "type": "object", "description": "应甚的 WebApp 讟眮。", - "properties": { "title": { "type": "string", "description": "WebApp 名称。" }, "chat_color_theme": { "type": "string", "description": "聊倩颜色䞻题, hex 栌匏。" }, "chat_color_theme_inverted": { "type": "boolean", "description": "聊倩颜色䞻题是吊反蜬。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "囟标类型, `emoji`-衚情, `image`-囟片。" }, "icon": { "type": "string", "description": "囟标, emoji 或囟片 URL。" }, "icon_background": { "type": "string", "description": "hex 栌匏的背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "囟标 URL。" }, "description": { "type": "string", "description": "描述。" }, "copyright": { "type": "string", "description": "版权信息。" }, "privacy_policy": { "type": "string", "description": "隐私政策铟接。" }, "custom_disclaimer": { "type": "string", "description": "自定义免莣声明。" }, "default_language": { "type": "string", "description": "默讀语蚀。" }, "show_workflow_steps": { "type": "boolean", "description": "是吊星瀺工䜜流诊情。" }, "use_icon_as_answer_icon": { "type": "boolean", "description": "是吊䜿甚 WebApp 囟标替换聊倩䞭的 机噚人囟标。" } } - }, - "AnnotationListResponse": { - "type": "object", "description": "标泚列衚响应。", - "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnnotationItem" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } - }, - "AnnotationItem": { - "type": "object", "description": "单䞪标泚条目。", - "properties": { "id": { "type": "string", "format": "uuid" }, "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" }, "hit_count": { "type": "integer", "description": "呜䞭次数。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎戳。" } } - }, - "CreateAnnotationRequest": { - "type": "object", "required": ["question", "answer"], "description": "创建标泚请求䜓。", - "properties": { "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" } } - }, - "UpdateAnnotationRequest": { - "type": "object", "required": ["question", "answer"], "description": "曎新标泚请求䜓。", - "properties": { "question": { "type": "string", "description": "问题。" }, "answer": { "type": "string", "description": "答案内容。" } } - }, - "InitialAnnotationReplySettingsRequest": { - "type": "object", "required": ["score_threshold"], "description": "标泚回倍初始讟眮请求䜓。", - "properties": { "embedding_provider_name": { "type": "string", "nullable": true, "description": "可选指定的嵌入暡型提䟛商名称。" }, "embedding_model_name": { "type": "string", "nullable": true, "description": "可选指定的嵌入暡型名称。" }, "score_threshold": { "type": "number", "format": "float", "description": "盞䌌床阈倌。" } } - }, - "AsyncJobResponse": { - "type": "object", "description": "匂步任务响应。", - "properties": { "job_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "job_status": { "type": "string", "description": "任务状态。" } } - }, - "AsyncJobStatusResponse": { - "allOf": [ { "$ref": "#/components/schemas/AsyncJobResponse" }, { "type": "object", "properties": { "error_msg": { "type": "string", "nullable": true, "description": "错误信息劂果任务倱莥。" } } } ] - }, - "ErrorResponse": { - "type": "object", "description": "错误响应结构。", - "properties": { "status": { "type": "integer", "description": "HTTP 状态码。", "nullable": true }, "code": { "type": "string", "description": "错误码。", "nullable": true }, "message": { "type": "string", "description": "错误消息。" } } + "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": "是吊䜿甚应甚囟标䜜䞺回答囟标。" + } + } } } }, "tags": [ - { "name": "文本生成", "description": "䞎文本生成和完成盞关的操䜜。" }, - { "name": "文件管理", "description": "䞎文件䞊䌠和管理盞关的操䜜。" }, - { "name": "终端甚户", "description": "终端甚户信息盞关的操䜜。" }, - { "name": "反銈", "description": "䞎甚户反銈盞关的操䜜。" }, - { "name": "语音服务", "description": "䞎文本蜬语音盞关的操䜜。" }, - { "name": "应甚讟眮", "description": "获取应甚基本信息和参数配眮的操䜜。" }, - { "name": "标泚管理", "description": "䞎标泚甚于盎接回倍盞关的操䜜。" } + { + "name": "文本生成", + "description": "文本生成盞关操䜜。" + }, + { + "name": "文件操䜜", + "description": "文件管理盞关操䜜。" + }, + { + "name": "终端甚户", + "description": "终端甚户信息盞关操䜜。" + }, + { + "name": "消息反銈", + "description": "甚户反銈盞关操䜜。" + }, + { + "name": "语音䞎文字蜬换", + "description": "语音蜬文字和文字蜬语音盞关操䜜。" + }, + { + "name": "应甚配眮", + "description": "获取应甚讟眮和信息的操䜜。" + } ] -} \ No newline at end of file +} diff --git a/zh/api-reference/openapi_knowledge.json b/zh/api-reference/openapi_knowledge.json index 0c1e92e6b..f99c73461 100644 --- a/zh/api-reference/openapi_knowledge.json +++ b/zh/api-reference/openapi_knowledge.json @@ -2,13 +2,13 @@ "openapi": "3.0.1", "info": { "title": "知识库 API", - "description": "甚于管理知识库数据集、文档和段萜的 API包括创建、检玢和配眮功胜。", + "description": "甚于管理知识库、文档、分段、元数据和标筟的 API包括创建、检玢和配眮操䜜。**泚意**单䞪知识库 API 密钥有权操䜜同䞀莊户䞋所有可见的知识库。请泚意数据安党。", "version": "1.0.0" }, "servers": [ { "url": "{apiBaseUrl}", - "description": "知识库 API 的基础 URL。", + "description": "Knowledge API 的基础 URL。", "variables": { "apiBaseUrl": { "default": "https://api.dify.ai/v1", @@ -24,127 +24,376 @@ ], "tags": [ { - "name": "数据集", - "description": "䞎管理知识库数据集盞关的操䜜。" + "name": "知识库", + "description": "甚于管理知识库的操䜜包括创建、配眮和检玢。" }, { "name": "文档", - "description": "甚于圚数据集䞭创建、曎新和管理文档的操䜜。" + "description": "甚于圚知识库䞭创建、曎新和管理文档的操䜜。" }, { - "name": "文档块", - "description": "甚于管理文档块段萜的操䜜。" + "name": "分段", + "description": "甚于管理分段和子分段的操䜜。" }, { - "name": "元数据和标筟", - "description": "甚于管理数据集标筟和元数据的操䜜。" + "name": "元数据", + "description": "甚于管理知识库元数据字段和文档元数据倌的操䜜。" + }, + { + "name": "标筟", + "description": "甚于管理知识库标筟和标筟绑定的操䜜。" }, { "name": "æš¡åž‹", - "description": "甚于检玢可甚暡型的操䜜。" + "description": "甚于获取可甚暡型的操䜜。" + }, + { + "name": "知识流氎线", + "description": "甚于管理和运行知识流氎线的操䜜包括数据源插件和流氎线执行。" } ], "paths": { "/datasets": { "post": { "tags": [ - "数据集" + "知识库" ], "summary": "创建空知识库", - "description": "䜿甚指定配眮创建䞀䞪新的空知识库数据集。", - "operationId": "createDataset", + "description": "创建新的空知识库。创建后䜿甚 [通过文本创建文档](/api-reference/文档/从文本创建文档) 或 [通过文件创建文档](/api-reference/文档/从文件创建文档) 添加文档。", + "operationId": "createKnowledgeBaseZh", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateDatasetRequest" + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "知识库名称。" + }, + "description": { + "type": "string", + "maxLength": 400, + "default": "", + "description": "知识库描述。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` 䜿甚嵌入暡型进行粟确搜玢`economy` 䜿甚基于关键词的玢匕。" + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "default": "only_me", + "description": "控制谁可以访问歀知识库。`only_me` 仅限创建者`all_team_members` 授权敎䞪工䜜区访问`partial_members` 授权指定成员访问。" + }, + "provider": { + "type": "string", + "enum": [ + "vendor", + "external" + ], + "default": "vendor", + "description": "`vendor` 䞺内郚知识库`external` 䞺倖郚知识库。" + }, + "embedding_model": { + "type": "string", + "description": "嵌入暡型名称。䜿甚 [获取可甚暡型](/api-reference/æš¡åž‹/获取可甚暡型) äž­ `model_type=text-embedding` 返回的 `model` 字段倌。" + }, + "embedding_model_provider": { + "type": "string", + "description": "嵌入暡型䟛应商。䜿甚 [获取可甚暡型](/api-reference/æš¡åž‹/获取可甚暡型) äž­ `model_type=text-embedding` 返回的 `provider` 字段倌。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检玢暡型配眮。控制查询歀知识库时劂䜕搜玢和排序分段。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "倖郚知识库 API 连接的 ID。" + }, + "external_knowledge_id": { + "type": "string", + "description": "倖郚知识库的 ID。" + }, + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "摘芁玢匕配眮。", + "properties": { + "enable": { + "type": "boolean", + "description": "是吊启甚摘芁玢匕。" + }, + "model_name": { + "type": "string", + "description": "甚于生成摘芁的暡型名称。" + }, + "model_provider_name": { + "type": "string", + "description": "摘芁生成暡型的提䟛商。" + }, + "summary_prompt": { + "type": "string", + "description": "甚于摘芁生成的自定义提瀺词暡板。" + } + } + } + } } } } }, "responses": { "200": { - "description": "成功创建数据集。", + "description": "知识库创建成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "产品 API 技术文档", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "description": "`dataset_name_duplicate` : 知识库名称已存圚请修改名称。", + "content": { + "application/json": { + "examples": { + "dataset_name_duplicate": { + "summary": "dataset_name_duplicate", + "value": { + "status": 409, + "code": "dataset_name_duplicate", + "message": "The dataset name already exists. Please modify your dataset name." + } + } + } + } + } } } }, "get": { "tags": [ - "数据集" + "知识库" ], "summary": "获取知识库列衚", - "description": "检玢知识库列衚支持分页和过滀选项。", - "operationId": "listDatasets", + "description": "返回知识库的分页列衚。支持按关键词和标筟筛选。", + "operationId": "listKnowledgeBasesZh", "parameters": [ { - "name": "keyword", - "in": "query", - "description": "按名称过滀数据集的搜玢关键词。", - "schema": { - "type": "string" - } - }, - { - "name": "tag_ids", + "name": "page", "in": "query", - "description": "芁过滀的标筟 ID 列衚。数据集必须具有所有指定的标筟。", "schema": { - "type": "array", - "items": { - "type": "string" - } + "type": "integer", + "default": 1 }, - "style": "form", - "explode": false + "description": "Page number." }, { - "name": "page", + "name": "limit", "in": "query", - "description": "分页的页码。", "schema": { "type": "integer", - "default": 1 - } + "default": 20 + }, + "description": "每页条目数。" }, { - "name": "limit", + "name": "keyword", "in": "query", - "description": "每页返回的项目数。", "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } + "type": "string" + }, + "description": "按名称筛选的搜玢关键词。" }, { "name": "include_all", "in": "query", - "description": "是吊包含所有数据集。这仅对工䜜区所有者有效。", "schema": { "type": "boolean", "default": false - } + }, + "description": "是吊包含所有知识库无论权限劂䜕。" + }, + { + "name": "tag_ids", + "in": "query", + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "甚于筛选的标筟 ID。" } ], "responses": { "200": { - "description": "数据集的分页列衚。", + "description": "知识库列衚。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "知识库对象数组。", + "items": { + "$ref": "#/components/schemas/Dataset" + } + }, + "has_more": { + "type": "boolean", + "description": "䞋䞀页是吊还有曎倚项目。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "匹配条目的总数。" + }, + "page": { + "type": "integer", + "description": "圓前页码。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": [ + { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "产品 API 技术文档", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } } } } @@ -155,30 +404,118 @@ "/datasets/{dataset_id}": { "get": { "tags": [ - "数据集" + "知识库" ], "summary": "获取知识库诊情", - "description": "通过 ID 获取特定知识库的诊细信息。", - "operationId": "getDatasetDetail", + "description": "获取指定知识库的诊细信息包括嵌入暡型、检玢配眮和文档统计信息。", + "operationId": "getKnowledgeBaseZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的唯䞀标识笊。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "responses": { "200": { - "description": "关于数据集的诊细信息。", + "description": "知识库诊情。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "产品 API 技术文档", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 访问歀知识库的权限䞍足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未扟到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } } } } @@ -187,21 +524,21 @@ }, "patch": { "tags": [ - "数据集" + "知识库" ], "summary": "曎新知识库", - "description": "曎新特定知识库的讟眮。", - "operationId": "updateDataset", + "description": "曎新现有知识库的名称、描述、权限或检玢讟眮。仅曎新请求䜓䞭提䟛的字段。", + "operationId": "updateKnowledgeBaseZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的唯䞀标识笊。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "requestBody": { @@ -209,90 +546,247 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateDatasetRequest" + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "知识库名称。" + }, + "description": { + "type": "string", + "maxLength": 400, + "description": "知识库描述。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "nullable": true, + "description": "`high_quality` 䜿甚嵌入暡型进行粟确搜玢`economy` 䜿甚基于关键词的玢匕。" + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ], + "description": "控制谁可以访问歀知识库。`only_me` 仅限创建者`all_team_members` 授权敎䞪工䜜区访问`partial_members` 授权指定成员访问。" + }, + "embedding_model": { + "type": "string", + "description": "嵌入暡型名称。䜿甚 [获取可甚暡型](/api-reference/æš¡åž‹/获取可甚暡型) äž­ `model_type=text-embedding` 返回的 `model` 字段倌。" + }, + "embedding_model_provider": { + "type": "string", + "description": "嵌入暡型䟛应商。䜿甚 [获取可甚暡型](/api-reference/æš¡åž‹/获取可甚暡型) äž­ `model_type=text-embedding` 返回的 `provider` 字段倌。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检玢暡型配眮。控制查询歀知识库时劂䜕搜玢和排序分段。" + }, + "partial_member_list": { + "type": "array", + "description": "圓 `permission` 䞺 `partial_members` 时有访问权限的团队成员列衚。", + "items": { + "type": "object", + "properties": { + "user_id": { + "type": "string", + "description": "芁授予访问权限的团队成员 ID。" + } + } + } + }, + "external_retrieval_model": { + "type": "object", + "description": "倖郚知识库的检玢讟眮。", + "properties": { + "top_k": { + "type": "integer", + "description": "返回的最倧结果数。" + }, + "score_threshold": { + "type": "number", + "description": "甚于过滀结果的最䜎盞关性分数阈倌。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "是吊启甚分数阈倌过滀。" + } + } + }, + "external_knowledge_id": { + "type": "string", + "description": "倖郚知识库的 ID。" + }, + "external_knowledge_api_id": { + "type": "string", + "description": "倖郚知识库 API 连接的 ID。" + } + } } } } }, "responses": { "200": { - "description": "成功曎新数据集诊情。", + "description": "知识库曎新成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DatasetDetail" + "$ref": "#/components/schemas/Dataset" + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9", + "name": "Product Documentation", + "description": "产品 API 技术文档", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "author_name": "admin", + "created_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "updated_at": 1741267200, + "embedding_model": "text-embedding-3-small", + "embedding_model_provider": "openai", + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 3, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": "text_model", + "external_knowledge_info": null, + "external_retrieval_model": null, + "doc_metadata": [], + "built_in_field_enabled": true, + "pipeline_id": null, + "runtime_mode": null, + "chunk_structure": null, + "icon_info": null, + "summary_index_setting": null, + "is_published": false, + "total_documents": 0, + "total_available_documents": 0, + "enable_api": true, + "is_multimodal": false + } + } } } } }, - "409": { - "$ref": "#/components/responses/DatasetNameDuplicate" + "403": { + "description": "`forbidden` : 访问歀知识库的权限䞍足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions to access this knowledge base." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未扟到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } }, "delete": { "tags": [ - "数据集" + "知识库" ], "summary": "删陀知识库", - "description": "删陀知识库及其所有盞关文档和数据。", - "operationId": "deleteDataset", + "description": "氞久删陀知识库及其所有文档。该知识库䞍胜被任䜕应甚正圚䜿甚。", + "operationId": "deleteKnowledgeBaseZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "芁删陀的知识库的唯䞀标识笊。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "responses": { "204": { - "description": "成功删陀数据集。" - } - } - } - }, - "/datasets/{dataset_id}/document/create-by-text": { - "post": { - "tags": [ - "文档" - ], - "summary": "从文本创建文档", - "description": "盎接从文本内容圚现有知识库䞭创建新文档。", - "operationId": "createDocumentFromText", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "芁添加文档的知识库 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateDocumentByTextRequest" + "description": "Success." + }, + "404": { + "description": "`not_found` : 未扟到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } } } - } - }, - "responses": { - "200": { - "description": "文档创建成功正圚被玢匕。", + }, + "409": { + "description": "`dataset_in_use` : 该知识库正圚被䞀些应甚䜿甚。请先从应甚䞭移陀后再删陀。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "examples": { + "dataset_in_use": { + "summary": "dataset_in_use", + "value": { + "status": 409, + "code": "dataset_in_use", + "message": "The dataset is being used by some apps. Please remove the dataset from the apps before deleting it." + } + } } } } @@ -300,118 +794,247 @@ } } }, - "/datasets/{dataset_id}/document/create-by-file": { + "/datasets/{dataset_id}/document/create-by-text": { "post": { "tags": [ "文档" ], - "summary": "从文件创建文档", - "description": "通过䞊䌠文件圚现有知识库䞭创建新文档。", - "operationId": "createDocumentFromFile", + "summary": "从文本创建文档", + "description": "通过纯文本内容创建文档。文档将匂步倄理——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", + "operationId": "createDocumentByTextZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "芁添加文档的知识库 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "requestBody": { "required": true, "content": { - "multipart/form-data": { + "application/json": { "schema": { "type": "object", + "required": [ + "name", + "text" + ], "properties": { - "data": { + "name": { "type": "string", - "description": "包含文档元数据和倄理规则的 JSON 字笊䞲。诊情请参见 `CreateDocumentByFileRequestData` 暡匏。", - "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\":{\"separator\":\"###\", \"max_tokens\":500}}},\"summary_index_setting\":{\"enable\":true,\"model_name\":\"qwen-vl-plus\",\"model_provider_name\":\"langgenius/tongyi/tongyi\",\"summary_prompt\":\"summarize the text\"}}" + "description": "文档名称。" }, - "file": { + "text": { "type": "string", - "format": "binary", - "description": "芁䞊䌠的文件。" - } - } - } - } - } - }, + "description": "文档文本内容。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ], + "description": "向知识库添加銖䞪文档时必填。后续文档劂果省略歀字段将继承知识库的玢匕方匏。`high_quality` 䜿甚嵌入暡型进行粟确搜玢`economy` 䜿甚基于关键词的玢匕。" + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` 䞺标准文本分段`hierarchical_model` 䞺父子分段结构`qa_model` 䞺问答对提取。" + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "甚于倄理䌘化的文档语蚀。" + }, + "process_rule": { + "type": "object", + "description": "分块倄理规则。", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "倄理暡匏。`automatic` 䜿甚内眮规则`custom` 允讞手劚配眮`hierarchical` 启甚父子分段结构配合 `doc_form: hierarchical_model` 䜿甚。" + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "规则标识笊。" + }, + "enabled": { + "type": "boolean", + "description": "该预倄理规则是吊启甚。" + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "甚于拆分文本的自定义分隔笊。" + }, + "max_tokens": { + "type": "integer", + "description": "每䞪分段的最倧什牌数。" + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "分段之闎的什牌重叠数。" + } + } + } + } + } + } + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检玢暡型配眮。控制查询歀知识库时劂䜕搜玢和排序分段。" + }, + "embedding_model": { + "type": "string", + "description": "嵌入暡型名称。䜿甚 [获取可甚暡型](/api-reference/æš¡åž‹/获取可甚暡型) äž­ `model_type=text-embedding` 返回的 `model` 字段倌。" + }, + "embedding_model_provider": { + "type": "string", + "description": "嵌入暡型䟛应商。䜿甚 [获取可甚暡型](/api-reference/æš¡åž‹/获取可甚暡型) äž­ `model_type=text-embedding` 返回的 `provider` 字段倌。" + }, + "original_document_id": { + "type": "string", + "description": "甚于版本控制的原始文档 ID。" + } + } + } + } + } + }, "responses": { "200": { - "description": "文档创建成功正圚被玢匕。", + "description": "文档创建成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "甚于跟螪玢匕进床的批次 ID。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } } } } }, "400": { - "$ref": "#/components/responses/FileError" - }, - "413": { - "$ref": "#/components/responses/FileTooLarge" - }, - "415": { - "$ref": "#/components/responses/UnsupportedFileType" - } - } - } - }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { - "post": { - "tags": [ - "文档" - ], - "summary": "甚文本曎新文档", - "description": "䜿甚文本曎新现有文档的内容或讟眮。", - "operationId": "updateDocumentByText", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "包含文档的知识库 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "芁曎新的文档 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateDocumentByTextRequest" - } - } - } - }, - "responses": { - "200": { - "description": "文档曎新成功。", + "description": "- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。请前埀讟眮 -> 暡型提䟛商完成凭据配眮。\n- `invalid_param` : 知识库䞍存圚。/ indexing_technique 䞺必填项。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + } } } } @@ -419,34 +1042,24 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { + "/datasets/{dataset_id}/document/create-by-file": { "post": { "tags": [ "文档" ], - "summary": "甚文件曎新文档", - "description": "通过䞊䌠新文件曎新现有文档替换其内容。", - "operationId": "updateDocumentByFile", + "summary": "从文件创建文档", + "description": "通过䞊䌠文件创建文档。支持垞见文档栌匏PDF、TXT、DOCX 等。倄理过皋䞺匂步——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", + "operationId": "createDocumentByFileZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "包含文档的知识库 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "芁曎新的文档 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "requestBody": { @@ -455,16 +1068,19 @@ "multipart/form-data": { "schema": { "type": "object", + "required": [ + "file" + ], "properties": { - "data": { - "type": "string", - "description": "包含可选文档名称和倄理规则的 JSON 字笊䞲。请参见 `UpdateDocumentByFileRequestData` 暡匏。", - "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" - }, "file": { "type": "string", "format": "binary", - "description": "芁䞊䌠的新文件。" + "description": "芁䞊䌠的文件。" + }, + "data": { + "type": "string", + "description": "包含配眮信息的 JSON 字笊䞲。接受䞎 [通过文本创建文档](/api-reference/文档/从文本创建文档) 盞同的字段`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`䜆䞍包括 `name` 和 `text`。", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } } @@ -473,11 +1089,155 @@ }, "responses": { "200": { - "description": "文档曎新成功。", + "description": "文档创建成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentCreationResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "甚于跟螪玢匕进床的批次 ID。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 0, + "indexing_status": "indexing", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "indexing", + "word_count": 0, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : 请䞊䌠文件。\n- `too_many_files` : 仅允讞䞊䌠䞀䞪文件。\n- `filename_not_exists_error` : 指定的文件名䞍存圚。\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。请前埀讟眮 -> 暡型提䟛商完成凭据配眮。\n- `invalid_param` : 知识库䞍存圚、䞍支持倖郚数据集、文件过倧、䞍支持的文件类型或猺少必填字段。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + }, + "invalid_param_indexing": { + "summary": "invalid_param (indexing_technique)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "indexing_technique is required." + } + }, + "invalid_param_process_rule": { + "summary": "invalid_param (process_rule)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "process_rule is required." + } + } } } } @@ -485,38 +1245,72 @@ } } }, - "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "/datasets/{dataset_id}/documents": { "get": { "tags": [ "文档" ], - "summary": "获取文档嵌入状态进床", - "description": "检玢文档批次的玢匕状态星瀺嵌入和倄理的进床。", - "operationId": "getDocumentIndexingStatus", + "summary": "获取知识库的文档列衚", + "description": "返回知识库䞭的文档分页列衚。支持按关键词和玢匕状态进行筛选。", + "operationId": "listDocumentsZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { - "name": "batch", - "in": "path", - "required": true, - "description": "从文档创建端点返回的批次号。", + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1 + }, + "description": "Page number." + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20 + }, + "description": "每页的项目数量。服务噚䞊限䞺 `100`。" + }, + { + "name": "keyword", + "in": "query", "schema": { "type": "string" - } + }, + "description": "按文档名称筛选的搜玢关键词。" + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "queuing", + "indexing", + "paused", + "error", + "available", + "disabled", + "archived" + ] + }, + "description": "按星瀺状态筛选。" } ], "responses": { "200": { - "description": "批次䞭文档的玢匕状态。", + "description": "文档列衚。", "content": { "application/json": { "schema": { @@ -524,9 +1318,94 @@ "properties": { "data": { "type": "array", + "description": "知识库对象数组。", "items": { - "$ref": "#/components/schemas/IndexingStatus" + "$ref": "#/components/schemas/Document" } + }, + "has_more": { + "type": "boolean", + "description": "䞋䞀页是吊还有曎倚项目。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "匹配条目的总数。" + }, + "page": { + "type": "integer", + "description": "圓前页码。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 知识库未扟到。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." } } } @@ -542,33 +1421,32 @@ "文档" ], "summary": "获取文档诊情", - "description": "检玢单䞪文档的诊细信息包括其倄理规则和状态。", - "operationId": "getDocumentDetail", + "description": "获取指定文档的诊细信息包括玢匕状态、元数据和倄理统计信息。", + "operationId": "getDocumentZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "metadata", "in": "query", - "description": "元数据过滀噚`all` 返回所有元数据`only` 仅返回自定义元数据`without` 䞍返回元数据。", "schema": { "type": "string", "enum": [ @@ -577,311 +1455,607 @@ "without" ], "default": "all" - } + }, + "description": "`all` 返回所有字段包括元数据。`only` 仅返回 `id`、`doc_type` 和 `doc_metadata`。`without` 返回陀 `doc_metadata` 倖的所有字段。" } ], "responses": { "200": { - "description": "关于文档的诊细信息。", + "description": "文档诊情。响应结构根据 `metadata` 查询参数的䞍同而变化。圓 `metadata` 䞺 `only` 时仅返回 `id`、`doc_type` 和 `doc_metadata`。圓 `metadata` 䞺 `without` 时省略 `doc_type` 和 `doc_metadata`。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DocumentDetail" - } - } - } - } - } - }, - "delete": { - "tags": [ - "文档" - ], - "summary": "删陀文档", - "description": "从知识库䞭删陀特定文档。", - "operationId": "deleteDocument", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "知识库的 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "芁删陀的文档 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "responses": { - "204": { - "description": "成功删陀文档。" - } - } - } - }, - "/datasets/{dataset_id}/documents": { - "get": { - "tags": [ - "文档" - ], - "summary": "获取知识库的文档列衚", - "description": "检玢指定知识库䞭所有文档的分页列衚。", - "operationId": "listDocuments", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "知识库的 ID。", - "schema": { - "type": "string", - "format": "uuid" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "文档标识笊。" + }, + "position": { + "type": "integer", + "description": "圚知识库䞭的䜍眮玢匕。" + }, + "data_source_type": { + "type": "string", + "description": "文档的䞊䌠方匏。文件䞊䌠䞺 `upload_file`Notion 富入䞺 `notion_import`。" + }, + "data_source_info": { + "type": "object", + "description": "原始数据源信息。" + }, + "dataset_process_rule_id": { + "type": "string", + "description": "应甚于该文档的倄理规则 ID。" + }, + "dataset_process_rule": { + "type": "object", + "description": "知识库级别的倄理规则配眮。" + }, + "document_process_rule": { + "type": "object", + "description": "文档级别的倄理规则配眮。" + }, + "name": { + "type": "string", + "description": "文档名称。" + }, + "created_from": { + "type": "string", + "description": "文档来源。通过 API 创建时䞺 `api`通过 UI 创建时䞺 `web`。" + }, + "created_by": { + "type": "string", + "description": "创建该文档的甚户 ID。" + }, + "created_at": { + "type": "number", + "description": "文档创建的 Unix 时闎戳。" + }, + "tokens": { + "type": "integer", + "description": "文档䞭的什牌数。" + }, + "indexing_status": { + "type": "string", + "description": "圓前玢匕状态䟋劂 `waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、`error`、`paused`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "玢匕倱莥时的错误消息吊则䞺 `null`。" + }, + "enabled": { + "type": "boolean", + "description": "该文档是吊启甚检玢。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "文档被犁甚的 Unix 时闎戳启甚时䞺 `null`。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "犁甚该文档的甚户 ID启甚时䞺 `null`。" + }, + "archived": { + "type": "boolean", + "description": "文档是吊已園档。" + }, + "display_status": { + "type": "string", + "description": "适合 UI 星瀺的玢匕状态。" + }, + "word_count": { + "type": "integer", + "description": "文档的总字数。" + }, + "hit_count": { + "type": "integer", + "description": "该文档被检玢的次数。" + }, + "doc_form": { + "type": "string", + "description": "文档分块暡匏。`text_model` 衚瀺标准文本`hierarchical_model` 衚瀺父子结构`qa_model` 衚瀺问答对。" + }, + "doc_language": { + "type": "string", + "description": "文档内容的语蚀。" + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "文档类型分类未讟眮时䞺 `null`。" + }, + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识笊。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段类型。" + }, + "value": { + "type": "string", + "description": "歀文档的元数据字段倌。" + } + } + } + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "倄理完成的 Unix 时闎戳尚未完成时䞺 `null`。" + }, + "updated_at": { + "type": "number", + "nullable": true, + "description": "最后曎新的 Unix 时闎戳从未曎新时䞺 `null`。" + }, + "indexing_latency": { + "type": "number", + "nullable": true, + "description": "玢匕耗时秒未完成时䞺 `null`。" + }, + "segment_count": { + "type": "integer", + "description": "文档䞭的分段数。" + }, + "average_segment_length": { + "type": "number", + "description": "分段的平均字笊长床。" + }, + "summary_index_status": { + "type": "string", + "nullable": true, + "description": "摘芁玢匕的状态未启甚摘芁玢匕时䞺 `null`。" + }, + "need_summary": { + "type": "boolean", + "description": "该文档是吊需芁生成摘芁。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "dataset_process_rule": { + "id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "mode": "custom" + }, + "document_process_rule": { + "mode": "custom", + "rules": { + "pre_processing_rules": [], + "segmentation": { + "separator": "###", + "max_tokens": 500, + "chunk_overlap": 50 + } + } + }, + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_language": "English", + "doc_type": null, + "doc_metadata": [], + "completed_at": 1741267260, + "updated_at": 1741267260, + "indexing_latency": 60.0, + "segment_count": 5, + "average_segment_length": 70.0, + "summary_index_status": null, + "need_summary": false + } + } + } + } } }, - { - "name": "keyword", - "in": "query", - "description": "圚文档名称䞭搜玢的关键词。", - "schema": { - "type": "string" + "400": { + "description": "`invalid_metadata` : 指定键的元数据倌无效。", + "content": { + "application/json": { + "examples": { + "invalid_metadata": { + "summary": "invalid_metadata", + "value": { + "status": 400, + "code": "invalid_metadata", + "message": "Invalid metadata value: {metadata_key}" + } + } + } + } } }, - { - "name": "page", - "in": "query", - "description": "分页的页码。", - "schema": { - "type": "integer", - "default": 1 + "403": { + "description": "`forbidden` : 没有权限。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } } }, - { - "name": "limit", - "in": "query", - "description": "每页返回的项目数。", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } - } - ], - "responses": { - "200": { - "description": "文档的分页列衚。", + "404": { + "description": "`not_found` : 未扟到文档。", "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/DocumentListResponse" + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } } } - } - }, - "/datasets/{dataset_id}/documents/status/{action}": { - "patch": { + }, + "delete": { "tags": [ "文档" ], - "summary": "曎新文档状态", - "description": "执行批量操䜜以曎新䞀䞪或倚䞪文档的状态䟋劂启甚、犁甚、園档。", - "operationId": "batchUpdateDocumentStatus", + "summary": "删陀文档", + "description": "从知识库䞭氞久删陀文档及其所有分段。", + "operationId": "deleteDocumentZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { - "name": "action", + "name": "document_id", "in": "path", "required": true, - "description": "对文档执行的操䜜。", "schema": { "type": "string", - "enum": [ - "enable", - "disable", - "archive", - "un_archive" - ] - } + "format": "uuid" + }, + "description": "Document ID." } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "document_ids" - ], - "properties": { - "document_ids": { - "type": "array", - "description": "芁执行操䜜的文档 ID 列衚。", - "items": { - "type": "string", - "format": "uuid" + "responses": { + "204": { + "description": "Success." + }, + "400": { + "description": "`document_indexing` : 玢匕期闎无法删陀文档。", + "content": { + "application/json": { + "examples": { + "document_indexing": { + "summary": "document_indexing", + "value": { + "status": 400, + "code": "document_indexing", + "message": "Cannot delete document during indexing." + } + } + } + } + } + }, + "403": { + "description": "`archived_document_immutable` : 已園档的文档䞍可猖蟑。", + "content": { + "application/json": { + "examples": { + "archived_document_immutable": { + "summary": "archived_document_immutable", + "value": { + "status": 403, + "code": "archived_document_immutable", + "message": "The archived document is not editable." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 文档䞍存圚。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document Not Exists." } } } } } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" } } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments": { - "post": { + "/datasets/{dataset_id}/documents/{document_id}/download": { + "get": { "tags": [ - "文档块" + "文档" ], - "summary": "向文档添加块", - "description": "向特定文档添加䞀䞪或倚䞪新块段萜。这对于手劚添加粟心策划的内容埈有甚。", - "operationId": "createSegments", + "summary": "䞋蜜文档", + "description": "获取文档原始䞊䌠文件的筟名䞋蜜 URL。", + "operationId": "downloadDocumentZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateSegmentsRequest" - } - } - } - }, "responses": { "200": { - "description": "新创建的段萜列衚。", + "description": "䞋蜜 URL 生成成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentListResponse" + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "甚于䞋蜜原始䞊䌠文件的筟名 URL。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600" + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 没有权限访问歀文档。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "No permission." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未扟到文档。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } } } - }, + } + }, + "/datasets/{dataset_id}/documents/{batch}/indexing-status": { "get": { "tags": [ - "文档块" + "文档" ], - "summary": "从文档获取块", - "description": "从特定文档检玢块段萜的分页列衚。", - "operationId": "listSegments", + "summary": "获取文档嵌入状态进床", + "description": "检查批量文档的玢匕进床。返回每䞪文档的圓前倄理阶段和分段完成计数。请蜮询歀接口盎到 `indexing_status` 变䞺 `completed` 或 `error`。状态按以䞋顺序掚进`waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`。", + "operationId": "getDocumentIndexingStatusZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { - "name": "document_id", + "name": "batch", "in": "path", "required": true, - "description": "文档的 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "keyword", - "in": "query", - "description": "按内容过滀段萜的关键词。", "schema": { "type": "string" - } - }, - { - "name": "status", - "in": "query", - "description": "按玢匕状态过滀段萜。", - "schema": { - "type": "string", - "example": "completed" - } - }, - { - "name": "page", - "in": "query", - "description": "分页的页码。", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "limit", - "in": "query", - "description": "每页返回的项目数。", - "schema": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 100 - } + }, + "description": "创建文档时返回的批次 ID。" } ], "responses": { "200": { - "description": "段萜的分页列衚。", + "description": "批次䞭文档的玢匕状态。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentPaginatedResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "文档标识笊。" + }, + "indexing_status": { + "type": "string", + "description": "圓前玢匕状态`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed` 或 `error`。" + }, + "processing_started_at": { + "type": "number", + "description": "倄理匀始的 Unix 时闎戳。" + }, + "parsing_completed_at": { + "type": "number", + "description": "解析完成的 Unix 时闎戳。" + }, + "cleaning_completed_at": { + "type": "number", + "description": "枅掗完成的 Unix 时闎戳。" + }, + "splitting_completed_at": { + "type": "number", + "description": "拆分完成的 Unix 时闎戳。" + }, + "completed_at": { + "type": "number", + "description": "玢匕完成的 Unix 时闎戳。" + }, + "paused_at": { + "type": "number", + "nullable": true + }, + "error": { + "type": "string", + "nullable": true + }, + "stopped_at": { + "type": "number", + "nullable": true + }, + "completed_segments": { + "type": "integer", + "description": "已玢匕的分段数。" + }, + "total_segments": { + "type": "integer", + "description": "埅玢匕的分段总数。" + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": [ + { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "indexing_status": "completed", + "processing_started_at": 1741267200, + "parsing_completed_at": 1741267200, + "cleaning_completed_at": 1741267200, + "splitting_completed_at": 1741267200, + "completed_at": 1741267200, + "paused_at": null, + "error": null, + "stopped_at": null, + "completed_segments": 5, + "total_segments": 5 + } + ] + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 知识库未扟到。/ 文档未扟到。", + "content": { + "application/json": { + "examples": { + "dataset_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + }, + "documents_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Documents not found." + } + } } } } @@ -889,185 +2063,444 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { - "get": { + "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { + "post": { "tags": [ - "文档块" + "文档" ], - "summary": "获取文档䞭的块诊情", - "description": "检玢文档䞭特定块段萜的诊情。", - "operationId": "getSegmentDetail", + "summary": "甚文本曎新文档", + "description": "曎新现有文档的文本内容、名称或倄理配眮。内容变曎时将重新觊发玢匕——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", + "operationId": "updateDocumentByTextZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "段萜的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "文档名称。圓提䟛 `text` 时必填。" + }, + "text": { + "type": "string", + "description": "文档文本内容。" + }, + "process_rule": { + "type": "object", + "description": "分块倄理规则。", + "required": [ + "mode" + ], + "properties": { + "mode": { + "type": "string", + "enum": [ + "automatic", + "custom", + "hierarchical" + ], + "description": "倄理暡匏。`automatic` 䜿甚内眮规则`custom` 允讞手劚配眮`hierarchical` 启甚父子分段结构配合 `doc_form: hierarchical_model` 䜿甚。" + }, + "rules": { + "type": "object", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "enum": [ + "remove_stopwords", + "remove_extra_spaces", + "remove_urls_emails" + ], + "description": "规则标识笊。" + }, + "enabled": { + "type": "boolean", + "description": "该预倄理规则是吊启甚。" + } + } + } + }, + "segmentation": { + "type": "object", + "properties": { + "separator": { + "type": "string", + "default": "\n", + "description": "甚于拆分文本的自定义分隔笊。" + }, + "max_tokens": { + "type": "integer", + "description": "每䞪分段的最倧什牌数。" + }, + "chunk_overlap": { + "type": "integer", + "default": 0, + "description": "分段之闎的什牌重叠数。" + } + } + } + } + } + } + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ], + "default": "text_model", + "description": "`text_model` 䞺标准文本分段`hierarchical_model` 䞺父子分段结构`qa_model` 䞺问答对提取。" + }, + "doc_language": { + "type": "string", + "default": "English", + "description": "甚于倄理䌘化的文档语蚀。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检玢暡型配眮。控制查询歀知识库时劂䜕搜玢和排序分段。" + } + } + } + } + } + }, "responses": { "200": { - "description": "关于段萜的诊细信息。", + "description": "文档曎新成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "甚于跟螪玢匕进床的批次 ID。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } + } + } + } + }, + "400": { + "description": "- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。请前埀讟眮 -> 暡型提䟛商完成凭据配眮。\n- `invalid_param` : 知识库䞍存圚或提䟛文本时 name 䞺必填项。", + "content": { + "application/json": { + "examples": { + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_name_required": { + "summary": "invalid_param (name required)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "name is required when text is provided." + } + } } } } } } - }, + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { "post": { "tags": [ - "文档块" + "文档" ], - "summary": "曎新文档䞭的块", - "description": "曎新特定块段萜的内容、关键词或状态。", - "operationId": "updateSegment", + "summary": "甚文件曎新文档", + "description": "通过䞊䌠新文件曎新现有文档。将重新觊发玢匕——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", + "operationId": "updateDocumentByFileZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "芁曎新的段萜 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "requestBody": { "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/UpdateSegmentRequest" + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "芁䞊䌠的文件。" + }, + "data": { + "type": "string", + "description": "包含配眮信息的 JSON 字笊䞲。接受䞎 [通过文本创建文档](/api-reference/文档/从文本创建文档) 盞同的字段`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`䜆䞍包括 `name` 和 `text`。", + "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" + } + } } } } }, "responses": { "200": { - "description": "曎新的段萜诊情。", + "description": "文档曎新成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SegmentDetailResponse" + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "甚于跟螪玢匕进床的批次 ID。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "position": 1, + "data_source_type": "upload_file", + "data_source_info": { + "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + }, + "data_source_detail_dict": { + "upload_file": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "guide.txt", + "size": 2048, + "extension": "txt", + "mime_type": "text/plain", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200 + } + }, + "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234", + "name": "guide.txt", + "created_from": "api", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "tokens": 512, + "indexing_status": "completed", + "error": null, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "archived": false, + "display_status": "available", + "word_count": 350, + "hit_count": 0, + "doc_form": "text_model", + "doc_metadata": [], + "summary_index_status": null, + "need_summary": false + }, + "batch": "20250306150245647595" + } + } } } } - } - } - }, - "delete": { - "tags": [ - "文档块" - ], - "summary": "删陀文档䞭的块", - "description": "从文档䞭删陀特定块段萜。", - "operationId": "deleteSegment", - "parameters": [ - { - "name": "dataset_id", - "in": "path", - "required": true, - "description": "知识库的 ID。", - "schema": { - "type": "string", - "format": "uuid" - } }, - { - "name": "document_id", - "in": "path", - "required": true, - "description": "文档的 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "芁删陀的段萜 ID。", - "schema": { - "type": "string", - "format": "uuid" + "400": { + "description": "- `too_many_files` : 仅允讞䞊䌠䞀䞪文件。\n- `filename_not_exists_error` : 指定的文件名䞍存圚。\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。请前埀讟眮 -> 暡型提䟛商完成凭据配眮。\n- `invalid_param` : 知识库䞍存圚、䞍支持倖郚数据集、文件过倧或䞍支持的文件类型。", + "content": { + "application/json": { + "examples": { + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "invalid_param_dataset": { + "summary": "invalid_param (dataset)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Dataset does not exist." + } + }, + "invalid_param_external": { + "summary": "invalid_param (external)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "External datasets are not supported." + } + }, + "invalid_param_file_too_large": { + "summary": "invalid_param (file_too_large)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File size exceeded." + } + }, + "invalid_param_unsupported_file_type": { + "summary": "invalid_param (unsupported_file_type)", + "value": { + "status": 400, + "code": "invalid_param", + "message": "File type not allowed." + } + } + } + } } } - ], - "responses": { - "204": { - "description": "成功删陀段萜。" - } } } }, - "/datasets/{dataset_id}/retrieve": { + "/datasets/{dataset_id}/documents/download-zip": { "post": { "tags": [ - "数据集" + "文档" ], - "summary": "从知识库检玢块 / 测试检玢", - "description": "对知识库执行搜玢查询以检玢最盞关的块段萜。歀端点可甚于生产检玢和测试检玢。", - "operationId": "retrieveSegments", + "summary": "批量䞋蜜文档ZIP", + "description": "将倚䞪䞊䌠文件文档䞋蜜䞺单䞪 ZIP 压猩包。最倚接受 `100` 䞪文档 ID。", + "operationId": "downloadDocumentsZipZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "芁检玢的知识库 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" } ], "requestBody": { @@ -1075,18 +2508,69 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RetrieveRequest" - } - } - } - }, - "responses": { + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "minItems": 1, + "maxItems": 100, + "items": { + "type": "string", + "format": "uuid" + }, + "description": "芁包含圚 ZIP 压猩包䞭的文档 ID 数组。" + } + } + } + } + } + }, + "responses": { "200": { - "description": "䞎查询匹配的检玢段萜列衚。", + "description": "包含所请求文档的 ZIP 压猩包。", "content": { - "application/json": { + "application/zip": { "schema": { - "$ref": "#/components/schemas/RetrieveResponse" + "type": "string", + "format": "binary", + "description": "ZIP 压猩包二进制流。" + } + } + } + }, + "403": { + "description": "`forbidden` : 权限䞍足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 文档或知识库未扟到。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Document not found." + } + } } } } @@ -1094,27 +2578,133 @@ } } }, - "/workspaces/current/models/model-types/text-embedding": { - "get": { + "/datasets/{dataset_id}/documents/status/{action}": { + "patch": { "tags": [ - "æš¡åž‹" + "文档" + ], + "summary": "批量曎新文档状态", + "description": "批量启甚、犁甚、園档或取消園档倚䞪文档。", + "operationId": "batchUpdateDocumentStatusZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable", + "archive", + "un_archive" + ] + }, + "description": "`enable` 启甚`disable` 停甚`archive` 園档`un_archive` 从園档䞭恢倍。" + } ], - "summary": "获取可甚的嵌入暡型", - "description": "获取可甚于创建和查询知识库的所有可甚文本嵌入暡型列衚。", - "operationId": "getAvailableEmbeddingModels", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "芁曎新的文档 ID 列衚。" + } + } + } + } + } + }, "responses": { "200": { - "description": "按提䟛商分组的可甚嵌入暡型列衚。", + "description": "文档曎新成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ModelProvider" - } + "result": { + "type": "string", + "description": "操䜜结果。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "result": "success" + } + } + } + } + } + }, + "400": { + "description": "`invalid_action` : 无效的操䜜。", + "content": { + "application/json": { + "examples": { + "invalid_action": { + "summary": "invalid_action", + "value": { + "status": 400, + "code": "invalid_action", + "message": "Invalid action." + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 权限䞍足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 知识库未扟到。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." } } } @@ -1124,44 +2714,34 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { + "/datasets/{dataset_id}/documents/{document_id}/segments": { "post": { "tags": [ - "文档块" + "分段" ], - "summary": "创建子块", - "description": "䜿甚分层暡匏圚文档䞭的父段萜䞋创建新的子块。", - "operationId": "createChildChunk", + "summary": "向文档添加分段", + "description": "圚文档䞭创建䞀䞪或倚䞪分段。每䞪分段可以包含可选的关键词和答案字段适甚于 QA 暡匏文档。", + "operationId": "createChunksZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "segment_id", - "in": "path", - "required": true, - "description": "父段萜的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." } ], "requestBody": { @@ -1169,18 +2749,134 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateChildChunkRequest" + "type": "object", + "required": [ + "segments" + ], + "properties": { + "segments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "分段文本内容。" + }, + "answer": { + "type": "string", + "description": "QA 暡匏的回答内容。" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "分段的关键词。" + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "附件文件 ID。" + } + } + }, + "description": "芁创建的分段对象数组。" + } + } } } } }, "responses": { "200": { - "description": "成功创建子块。", + "description": "分段创建成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string", + "description": "该文档䜿甚的分块暡匏。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model" + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 文档未完成或已犁甚。", + "content": { + "application/json": { + "examples": { + "not_found_not_completed": { + "summary": "not_found (not completed)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is not completed." + } + }, + "not_found_disabled": { + "summary": "not_found (disabled)", + "value": { + "status": 404, + "code": "not_found", + "message": "Document is disabled." + } + } } } } @@ -1189,77 +2885,154 @@ }, "get": { "tags": [ - "文档块" + "分段" ], - "summary": "获取子块", - "description": "检玢特定父段萜的子块列衚。", - "operationId": "getChildChunks", + "summary": "从文档获取分段", + "description": "返回文档内分段的分页列衚。支持按关键词和状态筛选。", + "operationId": "listChunksZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { - "name": "segment_id", - "in": "path", - "required": true, - "description": "父段萜的 ID。", + "name": "page", + "in": "query", "schema": { - "type": "string", - "format": "uuid" - } + "type": "integer", + "default": 1 + }, + "description": "Page number." }, { - "name": "keyword", + "name": "limit", "in": "query", - "description": "过滀子块的搜玢关键词。", "schema": { - "type": "string" - } + "type": "integer", + "default": 20 + }, + "description": "每页的项目数量。服务噚䞊限䞺 `100`。" }, { - "name": "page", + "name": "status", "in": "query", - "description": "分页的页码。", "schema": { - "type": "integer", - "default": 1 - } + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true, + "description": "按玢匕状态筛选分段䟋劂 `completed`、`indexing`、`error`。" }, { - "name": "limit", + "name": "keyword", "in": "query", - "description": "每页返回的项目数。", "schema": { - "type": "integer", - "default": 20, - "maximum": 100 - } + "type": "string" + }, + "description": "搜玢关键词。" } ], "responses": { "200": { - "description": "子块的分页列衚。", + "description": "分段列衚。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkListResponse" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string", + "description": "该文档䜿甚的分块暡匏。" + }, + "total": { + "type": "integer", + "description": "匹配的分段总数。" + }, + "has_more": { + "type": "boolean", + "description": "䞋䞀页是吊还有曎倚项目。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "page": { + "type": "integer", + "description": "圓前页码。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": [ + { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + } + ], + "doc_form": "text_model", + "total": 1, + "has_more": false, + "limit": 20, + "page": 1 + } + } } } } @@ -1267,143 +3040,148 @@ } } }, - "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { - "patch": { + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { + "get": { "tags": [ - "文档块" + "分段" ], - "summary": "曎新子块", - "description": "曎新特定子块的内容。", - "operationId": "updateChildChunk", + "summary": "获取文档䞭的分段诊情", + "description": "获取指定分段的诊细信息包括内容、关键词和玢匕状态。", + "operationId": "getChunkZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "父段萜的 ID。", "schema": { "type": "string", "format": "uuid" - } - }, - { - "name": "child_chunk_id", - "in": "path", - "required": true, - "description": "芁曎新的子块 ID。", - "schema": { - "type": "string", - "format": "uuid" - } + }, + "description": "Chunk ID." } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateChildChunkRequest" - } - } - } - }, "responses": { "200": { - "description": "成功曎新子块。", + "description": "分段诊情。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChildChunkResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "该文档䜿甚的分块暡匏。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } } } }, - "delete": { + "post": { "tags": [ - "文档块" + "分段" ], - "summary": "删陀子块", - "description": "删陀特定的子块。", - "operationId": "deleteChildChunk", + "summary": "曎新文档䞭的分段", + "description": "曎新分段的内容、关键词或回答。修改后的分段将重新觊发玢匕。", + "operationId": "updateChunkZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "知识库的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" }, { "name": "document_id", "in": "path", "required": true, - "description": "文档的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "Document ID." }, { "name": "segment_id", "in": "path", "required": true, - "description": "父段萜的 ID。", - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "child_chunk_id", - "in": "path", - "required": true, - "description": "芁删陀的子块 ID。", "schema": { "type": "string", "format": "uuid" - } - } - ], - "responses": { - "204": { - "description": "成功删陀子块。" + }, + "description": "Chunk ID." } - } - } - }, - "/datasets/tags": { - "post": { - "tags": [ - "元数据和标筟" ], - "summary": "创建新的知识库类型标筟", - "description": "创建可甚于分类知识库的新标筟。", - "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { @@ -1411,13 +3189,50 @@ "schema": { "type": "object", "required": [ - "name" + "segment" ], "properties": { - "name": { - "type": "string", - "description": "新标筟的名称。", - "maxLength": 50 + "segment": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "分段文本内容。" + }, + "answer": { + "type": "string", + "description": "QA 暡匏的回答内容。" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + }, + "description": "分段的关键词。" + }, + "enabled": { + "type": "boolean", + "description": "分段是吊已启甚。" + }, + "regenerate_child_chunks": { + "type": "boolean", + "default": false, + "description": "是吊重新生成子分段。" + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "description": "附件文件 ID。" + }, + "summary": { + "type": "string", + "nullable": true, + "description": "摘芁玢匕的摘芁内容。" + } + }, + "description": "芁曎新的分段数据。" } } } @@ -1426,47 +3241,153 @@ }, "responses": { "200": { - "description": "成功创建标筟。", + "description": "分段曎新成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string", + "description": "该文档䜿甚的分块暡匏。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 0, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "updated_at": 1741267200, + "updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "child_chunks": [], + "attachments": [], + "summary": null + }, + "doc_form": "text_model" + } + } } } } } } }, - "get": { + "delete": { "tags": [ - "元数据和标筟" + "分段" + ], + "summary": "删陀文档䞭的分段", + "description": "从文档䞭氞久删陀䞀䞪分段。", + "operationId": "deleteChunkZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + } ], - "summary": "获取知识库类型标筟", - "description": "检玢所有可甚知识库标筟的列衚。", - "operationId": "getKnowledgeTags", "responses": { - "200": { - "description": "标筟列衚。", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Tag" - } - } - } - } + "204": { + "description": "Success." } } - }, - "patch": { + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { + "post": { "tags": [ - "元数据和标筟" + "分段" + ], + "summary": "创建子分段", + "description": "圚父分段䞋创建子分段。仅适甚于䜿甚 `hierarchical_model` 分块暡匏的文档。", + "operationId": "createChildChunkZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + } ], - "summary": "修改知识库类型标筟名称", - "description": "曎新现有标筟的名称。", - "operationId": "updateKnowledgeTag", "requestBody": { "required": true, "content": { @@ -1474,19 +3395,12 @@ "schema": { "type": "object", "required": [ - "tag_id", - "name" + "content" ], "properties": { - "tag_id": { - "type": "string", - "description": "芁修改的标筟 ID。", - "format": "uuid" - }, - "name": { + "content": { "type": "string", - "description": "标筟的新名称。", - "maxLength": 50 + "description": "子分段文本内容。" } } } @@ -1495,159 +3409,126 @@ }, "responses": { "200": { - "description": "成功曎新标筟。", + "description": "子分段创建成功。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Tag" - } - } - } - } - } - }, - "delete": { - "tags": [ - "元数据和标筟" - ], - "summary": "删陀知识库类型标筟", - "description": "删陀标筟。标筟䞍埗绑定到任䜕知识库。", - "operationId": "deleteKnowledgeTag", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "tag_id" - ], - "properties": { - "tag_id": { - "type": "string", - "description": "芁删陀的标筟 ID。", - "format": "uuid" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } } - } - } - } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" - } - } - } - }, - "/datasets/tags/binding": { - "post": { - "tags": [ - "元数据和标筟" - ], - "summary": "将数据集绑定到知识库类型标筟", - "description": "将䞀䞪或倚䞪标筟绑定到特定知识库。", - "operationId": "bindTagsToDataset", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "target_id", - "tag_ids" - ], - "properties": { - "target_id": { - "type": "string", - "description": "芁绑定标筟的数据集 ID。", - "format": "uuid" - }, - "tag_ids": { - "type": "array", - "description": "芁绑定的标筟 ID 列衚。", - "items": { - "type": "string", - "format": "uuid" + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } } } } } } - } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" - } - } - } - }, - "/datasets/tags/unbinding": { - "post": { - "tags": [ - "元数据和标筟" - ], - "summary": "解绑数据集和知识库类型标筟", - "description": "从知识库解绑特定标筟。", - "operationId": "unbindTagFromDataset", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "target_id", - "tag_id" - ], - "properties": { - "target_id": { - "type": "string", - "description": "数据集的 ID。", - "format": "uuid" - }, - "tag_id": { - "type": "string", - "description": "芁解绑的标筟 ID。", - "format": "uuid" + }, + "400": { + "description": "`invalid_param` : 创建子分段玢匕倱莥。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } } } } } } - }, - "responses": { - "200": { - "$ref": "#/components/responses/Success" - } } - } - }, - "/datasets/{dataset_id}/tags": { + }, "get": { "tags": [ - "元数据和标筟" + "分段" ], - "summary": "查询绑定到数据集的标筟", - "description": "检玢圓前绑定到特定数据集的所有标筟。", - "operationId": "queryDatasetTags", + "summary": "获取子分段", + "description": "返回特定父分段䞋子分段的分页列衚。", + "operationId": "listChildChunksZh", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, - "description": "数据集的 ID。", "schema": { "type": "string", "format": "uuid" - } + }, + "description": "知识库 ID。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "Page number." + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1 + }, + "description": "每页的项目数量。服务噚䞊限䞺 `100`。" + }, + { + "name": "keyword", + "in": "query", + "schema": { + "type": "string" + }, + "description": "搜玢关键词。" } ], "responses": { "200": { - "description": "绑定到数据集的标筟列衚。", + "description": "子分段列衚。", "content": { "application/json": { "schema": { @@ -1656,20 +3537,47 @@ "data": { "type": "array", "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - } - } + "$ref": "#/components/schemas/ChildChunk" } }, "total": { - "type": "integer" + "type": "integer", + "description": "子分段总数。" + }, + "total_pages": { + "type": "integer", + "description": "总页数。" + }, + "page": { + "type": "integer", + "description": "圓前页码。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": [ + { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + ], + "total": 1, + "total_pages": 1, + "page": 1, + "limit": 20 } } } @@ -1678,1432 +3586,3054 @@ } } } - } - }, - "components": { - "securitySchemes": { - "ApiKeyAuth": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "API_KEY", - "description": "API-Key 鉎权。所有 API 请求郜应圚 `Authorization` HTTP Header 䞭包含䜠的 API-Key栌匏䞺 `Bearer {API_KEY}`。**区烈建议匀发者把 API-Key 攟圚后端存傚而非分享或者攟圚客户端存傚以免 API-Key 泄露富臎莢产损倱。**" - } }, - "responses": { - "Success": { - "description": "操䜜成功。", - "content": { - "application/json": { + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { + "patch": { + "tags": [ + "分段" + ], + "summary": "曎新子分段", + "description": "曎新现有子分段的内容。", + "operationId": "updateChildChunkZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, "schema": { - "type": "object", - "properties": { - "result": { - "type": "string", - "example": "success" + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + }, + { + "name": "child_chunk_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "子分段 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "子分段文本内容。" + } } } } } - } - }, - "FileError": { - "description": "䞎文件䞊䌠盞关的错误请求。可胜是 `no_file_uploaded` 或 `too_many_files`。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" + }, + "responses": { + "200": { + "description": "子分段曎新成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": { + "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", + "segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "content": "Dify is an open-source platform.", + "position": 1, + "word_count": 6, + "type": "automatic", + "created_at": 1741267200, + "updated_at": 1741267200 + } + } + } + } + } } - } - } - }, - "FileTooLarge": { - "description": "文件倧小超出限制。", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" + }, + "400": { + "description": "`invalid_param` : 曎新子分段玢匕倱莥。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Create child chunk index failed: {error details}" + } + } + } + } } } } }, - "UnsupportedFileType": { - "description": "䞍允讞的文件类型。", - "content": { - "application/json": { + "delete": { + "tags": [ + "分段" + ], + "summary": "删陀子分段", + "description": "从父分段䞭氞久删陀䞀䞪子分段。", + "operationId": "deleteChildChunkZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "DatasetNameDuplicate": { - "description": "数据集名称已存圚。", - "content": { - "application/json": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Document ID." + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Chunk ID." + }, + { + "name": "child_chunk_id", + "in": "path", + "required": true, "schema": { - "$ref": "#/components/schemas/ErrorResponse" + "type": "string", + "format": "uuid" + }, + "description": "子分段 ID。" + } + ], + "responses": { + "204": { + "description": "Success." + }, + "400": { + "description": "`invalid_param` : 删陀子分段玢匕倱莥。", + "content": { + "application/json": { + "examples": { + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Delete child chunk index failed: {error details}" + } + } + } + } } } } } }, - "schemas": { - "ErrorResponse": { - "type": "object", - "properties": { - "code": { - "type": "string", - "description": "机噚可读的错误代码。" - }, - "message": { - "type": "string", - "description": "人类可读的错误消息。" - }, - "status": { - "type": "integer", - "description": "HTTP 状态码。" + "/datasets/{dataset_id}/retrieve": { + "post": { + "tags": [ + "知识库" + ], + "summary": "从知识库检玢分段 / 测试检玢", + "description": "对知识库执行搜玢查询检玢最盞关的分段。歀接口可甚于生产环境检玢和测试检玢。", + "operationId": "searchKnowledgeBaseZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" } - }, - "example": { - "code": "no_file_uploaded", - "message": "请䞊䌠䜠的文件。", - "status": 400 - } - }, - "RetrievalModel": { - "type": "object", - "properties": { - "search_method": { - "type": "string", - "description": "甚于检玢的搜玢方法。", - "enum": [ - "hybrid_search", - "semantic_search", - "full_text_search", - "keyword_search" - ] - }, - "reranking_enable": { - "type": "boolean", - "description": "是吊启甚重新排序暡型以改善搜玢结果。" - }, - "reranking_mode": { - "type": "string", - "description": "重新排序暡匏。", - "default": "reranking_model", - "enum": [ - "reranking_model", - "weighted_score" - ] - }, - "reranking_model": { - "type": "object", - "description": "重新排序暡型的配眮。", - "properties": { - "reranking_provider_name": { - "type": "string", - "description": "重新排序暡型的提䟛商。" - }, - "reranking_model_name": { - "type": "string", - "description": "重新排序暡型的名称。" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "maxLength": 250, + "description": "搜玢查询文本。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel", + "description": "检玢暡型配眮。控制查询歀知识库时劂䜕搜玢和排序分段。" + }, + "external_retrieval_model": { + "type": "object", + "description": "倖郚知识库的检玢讟眮。", + "properties": { + "top_k": { + "type": "integer", + "description": "返回的最倧结果数。" + }, + "score_threshold": { + "type": "number", + "description": "甚于过滀结果的最䜎盞关性分数阈倌。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "是吊启甚分数阈倌过滀。" + } + } + }, + "attachment_ids": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "芁包含圚检玢䞊䞋文䞭的附件 ID 列衚。" + } + } } - }, - "nullable": true - }, - "top_k": { - "type": "integer", - "description": "返回的顶郚匹配结果数量。" - }, - "score_threshold_enabled": { - "type": "boolean", - "description": "是吊应甚分数阈倌来过滀结果。" - }, - "score_threshold": { - "type": "number", - "format": "float", - "description": "结果包含的最䜎分数。", - "nullable": true - }, - "weights": { - "type": "number", - "format": "float", - "description": "混合搜玢暡匏䞭语义搜玢的权重。", - "nullable": true - } - } - }, - "SummaryIndexSetting": { - "type": "object", - "description": "摘芁自劚生成配眮。", - "properties": { - "enable": { - "type": "boolean", - "description": "是吊启甚摘芁自劚生成。" - }, - "model_name": { - "type": "string", - "description": "甚于生成摘芁的暡型名称。" - }, - "model_provider_name": { - "type": "string", - "description": "摘芁暡型的提䟛商。" - }, - "summary_prompt": { - "type": "string", - "description": "甚于生成摘芁的提瀺词暡板。" + } } }, - "required": [ - "enable" - ] - }, - "PreprocessingRule": { - "type": "object", - "description": "文档内容预倄理规则。", - "properties": { - "id": { - "type": "string", - "description": "预倄理规则的唯䞀标识笊。", - "enum": [ - "remove_extra_spaces", - "remove_urls_emails" - ] + "responses": { + "200": { + "description": "检玢结果。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "query": { + "type": "object", + "description": "原始查询对象。", + "properties": { + "content": { + "type": "string", + "description": "查询文本。" + } + } + }, + "records": { + "type": "array", + "items": { + "type": "object", + "properties": { + "segment": { + "type": "object", + "description": "从知识库䞭匹配的分段。", + "properties": { + "id": { + "type": "string", + "description": "分段的唯䞀标识笊。" + }, + "position": { + "type": "integer", + "description": "分段圚文档䞭的䜍眮。" + }, + "document_id": { + "type": "string", + "description": "该分段所属文档的 ID。" + }, + "content": { + "type": "string", + "description": "分段的文本内容。" + }, + "sign_content": { + "type": "string", + "description": "甚于完敎性验证的筟名内容哈垌。" + }, + "answer": { + "type": "string", + "description": "回答内容甚于问答暡匏文档。" + }, + "word_count": { + "type": "integer", + "description": "分段内容的字数。" + }, + "tokens": { + "type": "integer", + "description": "分段内容的什牌数。" + }, + "keywords": { + "type": "array", + "description": "䞎该分段关联的关键词甚于基于关键词的检玢。", + "items": { + "type": "string" + } + }, + "index_node_id": { + "type": "string", + "description": "向量存傚䞭玢匕节点的 ID。" + }, + "index_node_hash": { + "type": "string", + "description": "玢匕内容的哈垌倌甚于检测变曎。" + }, + "hit_count": { + "type": "integer", + "description": "该分段圚检玢查询䞭被匹配的次数。" + }, + "enabled": { + "type": "boolean", + "description": "该分段是吊启甚检玢。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "分段被犁甚的时闎戳。启甚时䞺 `null`。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "犁甚该分段的甚户 ID。启甚时䞺 `null`。" + }, + "status": { + "type": "string", + "description": "分段的玢匕状态。" + }, + "created_by": { + "type": "string", + "description": "创建该分段的甚户 ID。" + }, + "created_at": { + "type": "number", + "description": "创建时闎戳Unix 纪元单䜍䞺秒。" + }, + "indexing_at": { + "type": "number", + "nullable": true, + "description": "玢匕匀始的时闎戳。尚未匀始时䞺 `null`。" + }, + "completed_at": { + "type": "number", + "nullable": true, + "description": "玢匕完成的时闎戳。尚未完成时䞺 `null`。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "玢匕倱莥时的错误消息。无错误时䞺 `null`。" + }, + "stopped_at": { + "type": "number", + "nullable": true, + "description": "玢匕停止的时闎戳。未停止时䞺 `null`。" + }, + "document": { + "type": "object", + "description": "匹配分段的父文档信息。", + "properties": { + "id": { + "type": "string", + "description": "文档的唯䞀标识笊。" + }, + "data_source_type": { + "type": "string", + "description": "文档的创建方匏。" + }, + "name": { + "type": "string", + "description": "文档名称。" + }, + "doc_type": { + "type": "string", + "nullable": true, + "description": "文档类型分类。未讟眮时䞺 `null`。" + }, + "doc_metadata": { + "type": "object", + "nullable": true, + "description": "文档的元数据倌。未配眮元数据时䞺 `null`。" + } + } + } + } + }, + "child_chunks": { + "type": "array", + "description": "䜿甚分层玢匕时分段内匹配的子分段。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "子分段的唯䞀标识笊。" + }, + "content": { + "type": "string", + "description": "子分段的文本内容。" + }, + "position": { + "type": "integer", + "description": "子分段圚父分段䞭的䜍眮。" + }, + "score": { + "type": "number", + "description": "子分段的盞关性埗分。" + } + } + } + }, + "score": { + "type": "number", + "description": "盞关性埗分。" + }, + "tsne_position": { + "type": "object", + "nullable": true, + "description": "t-SNE 可视化䜍眮。" + }, + "files": { + "type": "array", + "description": "附加到该分段的文件。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "附件文件标识笊。" + }, + "name": { + "type": "string", + "description": "原始文件名。" + }, + "size": { + "type": "integer", + "description": "文件倧小字节。" + }, + "extension": { + "type": "string", + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "description": "文件的 MIME 类型。" + }, + "source_url": { + "type": "string", + "description": "访问附件的 URL。" + } + } + } + }, + "summary": { + "type": "string", + "nullable": true, + "description": "通过摘芁玢匕检玢到的摘芁内容。" + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "query": { + "content": "What is Dify?" + }, + "records": [ + { + "segment": { + "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1", + "position": 1, + "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "content": "Dify is an open-source LLM app development platform.", + "sign_content": "", + "answer": "", + "word_count": 9, + "tokens": 12, + "keywords": [ + "dify", + "platform", + "llm" + ], + "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001", + "index_node_hash": "abc123def456", + "hit_count": 1, + "enabled": true, + "disabled_at": null, + "disabled_by": null, + "status": "completed", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": 1741267200, + "indexing_at": 1741267200, + "completed_at": 1741267200, + "error": null, + "stopped_at": null, + "document": { + "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac", + "data_source_type": "upload_file", + "name": "guide.txt", + "doc_type": null, + "doc_metadata": null + } + }, + "child_chunks": [], + "score": 0.92, + "tsne_position": null, + "files": [], + "summary": null + } + ] + } + } + } + } + } }, - "enabled": { - "type": "boolean", - "description": "歀规则是吊启甚。" - } - } - }, - "SegmentationRule": { - "type": "object", - "description": "将文档内容分割成块的规则。", - "properties": { - "separator": { - "type": "string", - "description": "甚于分犻段萜的自定义分隔笊。" + "400": { + "description": "- `dataset_not_initialized` : 知识库仍圚初始化或玢匕䞭。请皍候。\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。请前埀讟眮 -> 暡型提䟛商完成凭据配眮。\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "dataset_not_initialized": { + "summary": "dataset_not_initialized", + "value": { + "status": 400, + "code": "dataset_not_initialized", + "message": "The dataset is still being initialized or indexing. Please wait a moment." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Invalid parameter value." + } + } + } + } + } }, - "max_tokens": { - "type": "integer", - "description": "单䞪段萜䞭允讞的最倧什牌数。" - } - } - }, - "SubChunkSegmentationRule": { - "type": "object", - "description": "将父块分割䞺蟃小子块的规则甚于分层暡匏。", - "properties": { - "separator": { - "type": "string", - "description": "子块的分隔笊。" + "403": { + "description": "`forbidden` : 权限䞍足。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Insufficient permissions." + } + } + } + } + } }, - "max_tokens": { - "type": "integer", - "description": "子块的最倧什牌长床。" + "404": { + "description": "`not_found` : 知识库未扟到。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } }, - "chunk_overlap": { - "type": "integer", - "description": "盞邻子块之闎的重叠什牌数。" + "500": { + "description": "`internal_server_error` : 检玢过皋䞭发生内郚错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "An internal error occurred." + } + } + } + } + } } } - }, - "ProcessRule": { - "type": "object", - "description": "甚于倄理文档的规则集包括枅理和分割。", - "properties": { - "mode": { - "type": "string", - "description": "倄理暡匏automatic、custom 或 hierarchical。", - "enum": [ - "automatic", - "custom", - "hierarchical" - ] - }, - "rules": { - "type": "object", - "description": "芁应甚的特定规则圓暡匏䞺 'custom' 或 'hierarchical' 时䜿甚。", - "properties": { - "pre_processing_rules": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PreprocessingRule" + } + }, + "/datasets/tags": { + "post": { + "tags": [ + "标筟" + ], + "summary": "创建知识库标筟", + "description": "创建新标筟以组织知识库。", + "operationId": "createKnowledgeTagZh", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "Tag name." + } } - }, - "segmentation": { - "$ref": "#/components/schemas/SegmentationRule" - }, - "parent_mode": { - "type": "string", - "description": "分层暡匏䞭父块的检玢暡匏。", - "enum": [ - "full-doc", - "paragraph" - ] - }, - "subchunk_segmentation": { - "$ref": "#/components/schemas/SubChunkSegmentationRule" } - }, - "nullable": true + } + } + }, + "responses": { + "200": { + "description": "标筟创建成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "标筟标识笊。" + }, + "name": { + "type": "string", + "description": "标筟星瀺名称。" + }, + "type": { + "type": "string", + "description": "标筟类型。知识库标筟始终䞺 `knowledge`。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "绑定到该标筟的知识库数量。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } + } + } + } } } }, - "CreateDocumentByTextRequest": { - "type": "object", - "required": [ - "name", - "text" + "get": { + "tags": [ + "标筟" ], - "properties": { - "name": { - "type": "string", - "description": "文档名称。" - }, - "text": { - "type": "string", - "description": "文档的完敎文本内容。" - }, - "indexing_technique": { - "type": "string", - "description": "文档的玢匕技术。", - "enum": [ - "high_quality", - "economy" - ] - }, - "doc_form": { - "type": "string", - "description": "玢匕内容的栌匏。", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] - }, - "doc_language": { - "type": "string", - "description": "文档的语蚀圚 Q&A 暡匏䞭埈重芁。", - "example": "äž­æ–‡" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { - "type": "string", - "description": "芁䜿甚的嵌入暡型名称。" - }, - "embedding_model_provider": { - "type": "string", - "description": "嵌入暡型的提䟛商。" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "摘芁自劚生成配眮。" + "summary": "获取知识库标筟列衚", + "description": "返回工䜜区䞭所有知识库标筟的列衚。", + "operationId": "listKnowledgeTagsZh", + "responses": { + "200": { + "description": "标筟列衚。", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "标筟标识笊。" + }, + "name": { + "type": "string", + "description": "标筟星瀺名称。" + }, + "type": { + "type": "string", + "description": "标筟类型。知识库标筟始终䞺 `knowledge`。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "绑定到该标筟的知识库数量。" + } + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + ] + } + } + } + } } } }, - "CreateDocumentByFileRequestData": { - "type": "object", - "description": "从文件创建文档的元数据和规则。", - "properties": { - "original_document_id": { - "type": "string", - "description": "芁重新䞊䌠或修改的现有文档 ID。", - "format": "uuid" - }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] - }, - "doc_form": { - "type": "string", - "enum": [ - "text_model", - "hierarchical_model", - "qa_model" - ] - }, - "doc_language": { - "type": "string", - "example": "äž­æ–‡" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "embedding_model": { - "type": "string" - }, - "embedding_model_provider": { - "type": "string" - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "摘芁自劚生成配眮。" + "patch": { + "tags": [ + "标筟" + ], + "summary": "修改知识库标筟", + "description": "重呜名现有的知识库标筟。", + "operationId": "updateKnowledgeTagZh", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_id", + "name" + ], + "properties": { + "tag_id": { + "type": "string", + "description": "芁曎新的标筟 ID。" + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "新标筟名称。" + } + } + } + } } - } - }, - "UpdateDocumentByTextRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "文档的新名称可选。" - }, - "text": { - "type": "string", - "description": "文档的新文本内容可选。" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + }, + "responses": { + "200": { + "description": "标筟曎新成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "标筟标识笊。" + }, + "name": { + "type": "string", + "description": "标筟星瀺名称。" + }, + "type": { + "type": "string", + "description": "标筟类型。知识库标筟始终䞺 `knowledge`。" + }, + "binding_count": { + "type": "string", + "nullable": true, + "description": "绑定到该标筟的知识库数量。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs", + "type": "knowledge", + "binding_count": "0" + } + } + } + } + } } } }, - "UpdateDocumentByFileRequestData": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "文档的新名称可选。" - }, - "process_rule": { - "$ref": "#/components/schemas/ProcessRule" + "delete": { + "tags": [ + "标筟" + ], + "summary": "删陀知识库标筟", + "description": "氞久删陀知识库标筟。䞍䌚删陀已被标记的知识库。", + "operationId": "deleteKnowledgeTagZh", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_id" + ], + "properties": { + "tag_id": { + "type": "string", + "description": "芁删陀的标筟 ID。" + } + } + } + } } - } - }, - "Document": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "position": { - "type": "integer" - }, - "data_source_type": { - "type": "string" - }, - "data_source_info": { - "type": "object", - "nullable": true - }, - "dataset_process_rule_id": { - "type": "string", - "format": "uuid", - "nullable": true - }, - "name": { - "type": "string" - }, - "created_from": { - "type": "string" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - }, - "tokens": { - "type": "integer" - }, - "indexing_status": { - "type": "string" - }, - "error": { - "type": "string", - "nullable": true - }, - "enabled": { - "type": "boolean" - }, - "disabled_at": { - "type": "integer", - "format": "int64", - "nullable": true - }, - "disabled_by": { - "type": "string", - "format": "uuid", - "nullable": true - }, - "archived": { - "type": "boolean" - }, - "display_status": { - "type": "string" - }, - "word_count": { - "type": "integer" - }, - "hit_count": { - "type": "integer" - }, - "doc_form": { - "type": "string" + }, + "responses": { + "204": { + "description": "Success." } } - }, - "DocumentCreationResponse": { - "type": "object", - "properties": { - "document": { - "$ref": "#/components/schemas/Document" - }, - "batch": { - "type": "string", - "description": "甚于跟螪玢匕进床的批次标识笊。" + } + }, + "/datasets/tags/binding": { + "post": { + "tags": [ + "标筟" + ], + "summary": "绑定标筟到知识库", + "description": "将䞀䞪或倚䞪标筟绑定到知识库。䞀䞪知识库可以有倚䞪标筟。", + "operationId": "bindKnowledgeTagsZh", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_ids", + "target_id" + ], + "properties": { + "tag_ids": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "description": "芁绑定的标筟 ID。" + }, + "target_id": { + "type": "string", + "description": "知识库 ID。" + } + } + } + } + } + }, + "responses": { + "204": { + "description": "Success." } } - }, - "CreateDatasetRequest": { - "type": "object", - "required": [ - "name" + } + }, + "/datasets/tags/unbinding": { + "post": { + "tags": [ + "标筟" ], - "properties": { - "name": { - "type": "string", - "description": "知识库的名称。" - }, - "description": { - "type": "string", - "description": "知识库的描述可选。" - }, - "indexing_technique": { - "type": "string", - "description": "芁䜿甚的玢匕技术。", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "description": "知识库的访问权限。", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "provider": { - "type": "string", - "description": "知识库的提䟛商。", - "enum": [ - "vendor", - "external" - ] - }, - "external_knowledge_api_id": { - "type": "string", - "description": "倖郚知识 API 的 ID劂果提䟛商是 'external'。" - }, - "external_knowledge_id": { - "type": "string", - "description": "倖郚知识的 ID劂果提䟛商是 'external'。" - }, - "embedding_model": { - "type": "string", - "description": "嵌入暡型的名称。" + "summary": "解陀标筟䞎知识库的绑定", + "description": "移陀知识库的标筟绑定。", + "operationId": "unbindKnowledgeTagZh", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tag_id", + "target_id" + ], + "properties": { + "tag_id": { + "type": "string", + "description": "芁解绑的标筟 ID。" + }, + "target_id": { + "type": "string", + "description": "知识库 ID。" + } + } + } + } + } + }, + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/{dataset_id}/tags": { + "get": { + "tags": [ + "标筟" + ], + "summary": "获取知识库绑定的标筟", + "description": "返回绑定到特定知识库的标筟列衚。", + "operationId": "getKnowledgeBaseTagsZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "responses": { + "200": { + "description": "绑定到知识库的标筟。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "标筟标识笊。" + }, + "name": { + "type": "string", + "description": "标筟星瀺名称。" + } + } + } + }, + "total": { + "type": "integer", + "description": "绑定到该知识库的标筟总数。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": [ + { + "id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d", + "name": "Product Docs" + } + ], + "total": 1 + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata": { + "post": { + "tags": [ + "元数据" + ], + "summary": "创建元数据字段", + "description": "䞺知识库创建自定义元数据字段。元数据字段可甚于䞺文档添加结构化信息标泚。", + "operationId": "createMetadataFieldZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "string", + "number", + "time" + ], + "description": "`string` 䞺文本倌`number` 䞺数倌`time` 䞺日期/时闎倌。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "元数据字段创建成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识笊。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段类型。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "get": { + "tags": [ + "元数据" + ], + "summary": "获取元数据字段列衚", + "description": "返回知识库的所有元数据字段列衚包括自定义和内眮字段以及䜿甚每䞪字段的文档数量。", + "operationId": "listMetadataFieldsZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "responses": { + "200": { + "description": "知识库的元数据字段。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "doc_metadata": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识笊。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段类型。" + }, + "count": { + "type": "integer", + "description": "䜿甚该元数据字段的文档数量。" + } + } + } + }, + "built_in_field_enabled": { + "type": "boolean", + "description": "该知识库是吊启甚了内眮元数据字段。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "doc_metadata": [ + { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string", + "count": 3 + } + ], + "built_in_field_enabled": true + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/{metadata_id}": { + "patch": { + "tags": [ + "元数据" + ], + "summary": "曎新元数据字段", + "description": "重呜名自定义元数据字段。", + "operationId": "updateMetadataFieldZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" }, - "embedding_model_provider": { - "type": "string", - "description": "嵌入暡型的提䟛商。" + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "元数据字段 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "新元数据字段名称。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "元数据字段曎新成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识笊。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段类型。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e", + "name": "author", + "type": "string" + } + } + } + } + } + } + } + }, + "delete": { + "tags": [ + "元数据" + ], + "summary": "删陀元数据字段", + "description": "氞久删陀自定义元数据字段。䜿甚歀字段的文档将䞢倱其对应的元数据倌。", + "operationId": "deleteMetadataFieldZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" + { + "name": "metadata_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "元数据字段 ID。" + } + ], + "responses": { + "204": { + "description": "Success." + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in": { + "get": { + "tags": [ + "元数据" + ], + "summary": "获取内眮元数据字段", + "description": "返回系统提䟛的内眮元数据字段列衚䟋劂文档类型、来源 URL。", + "operationId": "getBuiltInMetadataFieldsZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "responses": { + "200": { + "description": "内眮元数据字段。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "fields": { + "type": "array", + "description": "系统提䟛的元数据字段列衚。", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "内眮字段标识笊。`document_name` 衚瀺文档标题`uploader` 衚瀺创建者`upload_date` 衚瀺创建时闎`last_update_date` 衚瀺最后修改时闎`source` 衚瀺文档来源。" + }, + "type": { + "type": "string", + "description": "字段数据类型。文本倌䞺 `string`日期/时闎倌䞺 `time`。" + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "fields": [ + { + "name": "document_name", + "type": "string" + }, + { + "name": "uploader", + "type": "string" + }, + { + "name": "upload_date", + "type": "time" + }, + { + "name": "last_update_date", + "type": "time" + }, + { + "name": "source", + "type": "string" + } + ] + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/metadata/built-in/{action}": { + "post": { + "tags": [ + "元数据" + ], + "summary": "曎新内眮元数据字段", + "description": "启甚或犁甚知识库的内眮元数据字段。", + "operationId": "toggleBuiltInMetadataFieldZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "摘芁自劚生成配眮。" + { + "name": "action", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "enable", + "disable" + ] + }, + "description": "`enable` 启甚内眮元数据字段`disable` 停甚内眮元数据字段。" + } + ], + "responses": { + "200": { + "description": "内眮元数据字段切换成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操䜜结果。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "result": "success" + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/metadata": { + "post": { + "tags": [ + "元数据" + ], + "summary": "批量曎新文档元数据", + "description": "批量曎新倚䞪文档的元数据倌。请求䞭的每䞪文档将接收指定的元数据键倌对。", + "operationId": "batchUpdateDocumentMetadataZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "operation_data" + ], + "properties": { + "operation_data": { + "type": "array", + "items": { + "type": "object", + "required": [ + "document_id", + "metadata_list" + ], + "properties": { + "document_id": { + "type": "string", + "description": "芁曎新元数据的文档 ID。" + }, + "metadata_list": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { + "type": "string", + "description": "元数据字段 ID。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "value": { + "description": "元数据倌。可以是字笊䞲、数字或 `null`。" + } + } + } + }, + "partial_update": { + "type": "boolean", + "default": false, + "description": "是吊郚分曎新元数据保留未指定字段的现有倌。" + } + } + }, + "description": "文档元数据曎新操䜜数组。每䞪条目将䞀䞪文档 ID 映射到其元数据键倌对。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "文档元数据曎新成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "description": "操䜜结果。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "result": "success" + } + } + } + } + } } } - }, - "Dataset": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string", - "nullable": true - }, - "provider": { - "type": "string" - }, - "permission": { - "type": "string" - }, - "data_source_type": { - "type": "string", - "nullable": true - }, - "indexing_technique": { - "type": "string", - "nullable": true - }, - "app_count": { - "type": "integer" - }, - "document_count": { - "type": "integer" - }, - "word_count": { - "type": "integer" - }, - "created_by": { - "type": "string", - "format": "uuid" - }, - "created_at": { - "type": "integer", - "format": "int64" - }, - "updated_by": { - "type": "string", - "format": "uuid" - }, - "updated_at": { - "type": "integer", - "format": "int64" - }, - "embedding_model": { - "type": "string", - "nullable": true - }, - "embedding_model_provider": { - "type": "string", - "nullable": true - }, - "embedding_available": { - "type": "boolean", - "nullable": true - }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "该数据集的摘芁自劚生成配眮。", - "nullable": true + } + }, + "/workspaces/current/models/model-types/{model_type}": { + "get": { + "tags": [ + "æš¡åž‹" + ], + "summary": "获取可甚暡型", + "description": "按类型获取可甚暡型列衚。䞻芁甚于查询知识库配眮所需的 `text-embedding` 和 `rerank` 暡型。", + "operationId": "getAvailableModelsZh", + "parameters": [ + { + "name": "model_type", + "in": "path", + "required": true, + "schema": { + "type": "string", + "enum": [ + "text-embedding", + "rerank", + "llm", + "tts", + "speech2text", + "moderation" + ] + }, + "description": "芁获取的暡型类型。对于知识库配眮䜿甚 `text-embedding` 获取嵌入暡型䜿甚 `rerank` 获取重排序暡型。" + } + ], + "responses": { + "200": { + "description": "指定类型的可甚暡型。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "暡型提䟛商及其可甚暡型的列衚。", + "items": { + "type": "object", + "properties": { + "provider": { + "type": "string", + "description": "暡型提䟛商标识笊䟋劂 `openai`、`cohere`。" + }, + "label": { + "type": "object", + "description": "提䟛商的本地化星瀺名称。", + "properties": { + "en_US": { + "type": "string" + }, + "zh_Hans": { + "type": "string" + } + } + }, + "icon_small": { + "type": "object", + "description": "提䟛商小囟标的 URL。", + "properties": { + "en_US": { + "type": "string" + } + } + }, + "icon_large": { + "type": "object", + "description": "提䟛商倧囟标的 URL。", + "properties": { + "en_US": { + "type": "string" + } + } + }, + "status": { + "type": "string", + "description": "提䟛商状态。凭证已配眮䞔有效时䞺 `active`。" + }, + "models": { + "type": "array", + "description": "该提䟛商的可甚暡型列衚。", + "items": { + "type": "object", + "properties": { + "model": { + "type": "string", + "description": "暡型标识笊。创建或曎新知识库时将歀倌䜜䞺 `embedding_model` 参数䜿甚。" + }, + "label": { + "type": "object", + "description": "暡型的本地化星瀺名称。", + "properties": { + "en_US": { + "type": "string" + }, + "zh_Hans": { + "type": "string" + } + } + }, + "model_type": { + "type": "string", + "description": "暡型类型䞎 `model_type` 路埄参数匹配。" + }, + "features": { + "type": "array", + "nullable": true, + "description": "暡型支持的功胜无功胜时䞺 `null`。", + "items": { + "type": "string" + } + }, + "fetch_from": { + "type": "string", + "description": "暡型定义的来源。`predefined-model` 衚瀺内眮暡型`customizable-model` 衚瀺甚户自配眮的暡型。" + }, + "model_properties": { + "type": "object", + "description": "暡型特定的属性䟋劂 `context_size`。" + }, + "status": { + "type": "string", + "description": "暡型可甚状态。就绪时䞺 `active`。" + } + } + } + } + } + } + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "data": [ + { + "provider": "openai", + "label": { + "en_US": "OpenAI", + "zh_Hans": "OpenAI" + }, + "icon_small": { + "en_US": "https://example.com/openai-small.svg" + }, + "icon_large": { + "en_US": "https://example.com/openai-large.svg" + }, + "status": "active", + "models": [ + { + "model": "text-embedding-3-small", + "label": { + "en_US": "text-embedding-3-small", + "zh_Hans": "text-embedding-3-small" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8191 + }, + "status": "active" + } + ] + } + ] + } + } + } + } + } } } - }, - "DatasetListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Dataset" + } + }, + "/datasets/pipeline/file-upload": { + "post": { + "tags": [ + "知识流氎线" + ], + "summary": "䞊䌠流氎线文件", + "description": "䞊䌠文件以圚知识流氎线䞭䜿甚。通过 `multipart/form-data` 接受单䞪文件。", + "operationId": "uploadPipelineFileZh", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "芁䞊䌠的文件。" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "文件䞊䌠成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "已䞊䌠文件的唯䞀标识笊。" + }, + "name": { + "type": "string", + "description": "原始文件名。" + }, + "size": { + "type": "integer", + "description": "文件倧小字节。" + }, + "extension": { + "type": "string", + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "description": "文件的 MIME 类型。" + }, + "created_by": { + "type": "string", + "description": "䞊䌠文件的甚户 ID。" + }, + "created_at": { + "type": "string", + "description": "䞊䌠时闎戳ISO 8601 栌匏。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "report.pdf", + "size": 524288, + "extension": "pdf", + "mime_type": "application/pdf", + "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4", + "created_at": "2025-03-06T12:00:00" + } + } + } + } + } + }, + "400": { + "description": "- `no_file_uploaded` : 请䞊䌠文件。\n- `filename_not_exists_error` : 指定的文件名䞍存圚。\n- `too_many_files` : 仅允讞䞊䌠䞀䞪文件。", + "content": { + "application/json": { + "examples": { + "no_file_uploaded": { + "summary": "no_file_uploaded", + "value": { + "status": 400, + "code": "no_file_uploaded", + "message": "Please upload your file." + } + }, + "filename_not_exists_error": { + "summary": "filename_not_exists_error", + "value": { + "status": 400, + "code": "filename_not_exists_error", + "message": "The specified filename does not exist." + } + }, + "too_many_files": { + "summary": "too_many_files", + "value": { + "status": 400, + "code": "too_many_files", + "message": "Only one file is allowed." + } + } + } + } } }, - "has_more": { - "type": "boolean" + "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." + } + } + } + } + } }, - "limit": { - "type": "integer" + "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." + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/pipeline/datasource-plugins": { + "get": { + "tags": [ + "知识流氎线" + ], + "summary": "获取数据源插件列衚", + "description": "列出知识流氎线可甚的所有数据源插件。根据 `is_published` 查询参数返回已发垃或草皿状态的插件。", + "operationId": "listDatasourcePluginsZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" }, - "total": { - "type": "integer" + { + "name": "is_published", + "in": "query", + "schema": { + "type": "boolean", + "default": true + }, + "description": "获取已发垃还是草皿状态的数据源插件。`true` 返回已发垃的插件`false` 返回草皿插件。" + } + ], + "responses": { + "200": { + "description": "数据源插件列衚。", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "数据源插件的唯䞀标识笊。" + }, + "name": { + "type": "string", + "description": "数据源插件的星瀺名称。" + }, + "type": { + "type": "string", + "description": "数据源插件类型。" + } + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": [ + { + "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", + "name": "Web Scraper", + "type": "online_document" + } + ] + } + } + } + } }, - "page": { - "type": "integer" + "404": { + "description": "`not_found` : 未扟到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } - }, - "DatasetDetail": { - "allOf": [ + } + }, + "/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": { + "post": { + "tags": [ + "知识流氎线" + ], + "summary": "执行数据源节点", + "description": "圚知识流氎线䞭执行单䞪数据源节点。返回包含节点执行结果的流匏响应。", + "operationId": "runDatasourceNodeZh", + "parameters": [ { - "$ref": "#/components/schemas/Dataset" + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" }, { - "type": "object", - "properties": { - "retrieval_model_dict": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "tags": { - "type": "array", - "items": { - "type": "object" + "name": "node_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "芁执行的数据源节点 ID。" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "is_published" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "数据源节点的蟓入变量。" + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "数据源类型。" + }, + "credential_id": { + "type": "string", + "nullable": true, + "description": "甚于数据源讀证的凭证 ID。" + }, + "is_published": { + "type": "boolean", + "description": "运行节点的已发垃版本还是草皿版本。`true` 运行已发垃版本`false` 运行草皿版本。" + } } - }, - "doc_form": { - "type": "string", - "nullable": true } } } - ] - }, - "UpdateDatasetRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "知识库的新名称。" - }, - "description": { - "type": "string", - "description": "知识库的新描述。" - }, - "indexing_technique": { - "type": "string", - "enum": [ - "high_quality", - "economy" - ] - }, - "permission": { - "type": "string", - "enum": [ - "only_me", - "all_team_members", - "partial_members" - ] - }, - "embedding_model_provider": { - "type": "string" - }, - "embedding_model": { - "type": "string" - }, - "retrieval_model": { - "$ref": "#/components/schemas/RetrievalModel" - }, - "partial_member_list": { - "type": "array", - "description": "'partial_members' 权限可访问的成员列衚。", - "items": { - "type": "object", - "required": [ - "user_id" - ], - "properties": { - "user_id": { + }, + "responses": { + "200": { + "description": "包含节点执行事件的流匏响应。", + "content": { + "text/event-stream": { + "schema": { "type": "string", - "description": "成员的甚户 ID。" + "description": "包含节点执行进床和结果的 Server-Sent Events 流。" } } } }, - "summary_index_setting": { - "$ref": "#/components/schemas/SummaryIndexSetting", - "description": "摘芁自劚生成配眮。" + "404": { + "description": "`not_found` : 未扟到知识库。", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Dataset not found." + } + } + } + } + } } } - }, - "IndexingStatus": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "indexing_status": { - "type": "string" - }, - "processing_started_at": { - "type": "number", - "format": "float" - }, - "parsing_completed_at": { - "type": "number", - "format": "float" - }, - "cleaning_completed_at": { - "type": "number", - "format": "float" - }, - "splitting_completed_at": { - "type": "number", - "format": "float" - }, - "completed_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "paused_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "error": { - "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "number", - "format": "float", - "nullable": true - }, - "completed_segments": { - "type": "integer" - }, - "total_segments": { - "type": "integer" + } + }, + "/datasets/{dataset_id}/pipeline/run": { + "post": { + "tags": [ + "知识流氎线" + ], + "summary": "运行流氎线", + "description": "䞺知识库执行完敎的知识流氎线。支持流匏和阻塞䞀种响应暡匏。", + "operationId": "runPipelineZh", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "知识库 ID。" } - } - }, - "DocumentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "inputs", + "datasource_type", + "datasource_info_list", + "start_node_id", + "is_published", + "response_mode" + ], + "properties": { + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "流氎线的蟓入变量。" + }, + "datasource_type": { + "type": "string", + "enum": [ + "online_document", + "local_file", + "website_crawl", + "online_drive" + ], + "description": "数据源类型。" + }, + "datasource_info_list": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "䟛流氎线倄理的数据源信息对象列衚。" + }, + "start_node_id": { + "type": "string", + "description": "流氎线匀始执行的节点 ID。" + }, + "is_published": { + "type": "boolean", + "description": "运行流氎线的已发垃版本还是草皿版本。`true` 运行已发垃版本`false` 运行草皿版本。" + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "流氎线执行的响应暡匏。`streaming` 返回服务噚发送事件流`blocking` 等埅并返回完敎结果。" + } + } + } } - }, - "has_more": { - "type": "boolean" - }, - "limit": { - "type": "integer" - }, - "total": { - "type": "integer" - }, - "page": { - "type": "integer" } - } - }, - "DocumentDetail": { - "allOf": [ - { - "$ref": "#/components/schemas/Document" - }, - { - "type": "object", - "properties": { - "dataset_process_rule": { - "$ref": "#/components/schemas/ProcessRule" + }, + "responses": { + "200": { + "description": "流氎线执行结果。栌匏取决于 `response_mode`流匏返回 `text/event-stream`阻塞返回完敎的 JSON 结果。", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "description": "包含流氎线执行进床和结果的服务噚发送事件流。圓 `response_mode` 䞺 `streaming` 时返回。" + } }, - "document_process_rule": { - "allOf": [ - { - "$ref": "#/components/schemas/ProcessRule" - }, - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "dataset_id": { - "type": "string" + "application/json": { + "schema": { + "type": "object", + "description": "完敎的流氎线执行结果。圓 `response_mode` 䞺 `blocking` 时返回。", + "additionalProperties": true + }, + "examples": { + "success": { + "summary": "Blocking Response Example", + "value": { + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "data": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321", + "status": "succeeded", + "outputs": {}, + "created_at": 1741267200, + "finished_at": 1741267210 } } } - ] - }, - "indexing_latency": { - "type": "number", - "format": "float", - "nullable": true - }, - "segment_count": { - "type": "integer" - }, - "average_segment_length": { - "type": "integer" - }, - "doc_language": { - "type": "string", - "nullable": true + } + } + } + }, + "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": "Dataset not found." + } + } + } + } + } + }, + "500": { + "description": "`pipeline_run_error` : 流氎线执行倱莥。", + "content": { + "application/json": { + "examples": { + "pipeline_run_error": { + "summary": "pipeline_run_error", + "value": { + "status": 500, + "code": "pipeline_run_error", + "message": "Pipeline execution failed: connection timeout" + } + } + } } } } - ] - }, - "Segment": { + } + } + } + }, + "components": { + "schemas": { + "Dataset": { "type": "object", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "知识库的唯䞀标识笊。" }, - "position": { - "type": "integer" - }, - "document_id": { + "name": { "type": "string", - "format": "uuid" + "description": "知识库的星瀺名称。圚工䜜区内唯䞀。" }, - "content": { - "type": "string" - }, - "answer": { + "description": { "type": "string", - "nullable": true + "description": "描述知识库甚途或内容的可选文本。" }, - "word_count": { - "type": "integer" - }, - "tokens": { - "type": "integer" - }, - "keywords": { - "type": "array", - "items": { - "type": "string" - } - }, - "index_node_id": { - "type": "string" + "provider": { + "type": "string", + "description": "提䟛商类型。内郚管理䞺 `vendor`倖郚知识库连接䞺 `external`。" }, - "index_node_hash": { - "type": "string" + "permission": { + "type": "string", + "description": "控制谁可以访问歀知识库。可选倌`only_me`、`all_team_members`、`partial_members`。" }, - "hit_count": { - "type": "integer" + "data_source_type": { + "type": "string", + "description": "文档的数据源类型尚未配眮时䞺 `null`。" }, - "enabled": { - "type": "boolean" + "indexing_technique": { + "type": "string", + "description": "`high_quality` 䜿甚嵌入暡型进行粟确搜玢`economy` 䜿甚基于关键词的玢匕。" }, - "disabled_at": { + "app_count": { "type": "integer", - "format": "int64", - "nullable": true + "description": "圓前䜿甚该知识库的应甚数量。" }, - "disabled_by": { - "type": "string", - "format": "uuid", - "nullable": true + "document_count": { + "type": "integer", + "description": "知识库䞭的文档总数。" }, - "status": { - "type": "string" + "word_count": { + "type": "integer", + "description": "所有文档的总字数。" }, "created_by": { "type": "string", - "format": "uuid" + "description": "创建该知识库的甚户 ID。" + }, + "author_name": { + "type": "string", + "description": "创建者的星瀺名称。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "创建时闎戳Unix 纪元单䜍䞺秒。" }, - "indexing_at": { - "type": "integer", - "format": "int64" + "updated_by": { + "type": "string", + "description": "最后曎新该知识库的甚户 ID。" }, - "completed_at": { - "type": "integer", - "format": "int64" + "updated_at": { + "type": "number", + "description": "最后曎新时闎戳Unix 纪元单䜍䞺秒。" }, - "error": { + "embedding_model": { "type": "string", - "nullable": true - }, - "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true + "description": "甚于玢匕的嵌入暡型名称。" }, - "summary": { + "embedding_model_provider": { "type": "string", - "nullable": true - } - } - }, - "CreateSegmentsRequest": { - "type": "object", - "properties": { - "segments": { + "description": "嵌入暡型䟛应商。䜿甚 [获取可甚暡型](/api-reference/æš¡åž‹/获取可甚暡型) äž­ `model_type=text-embedding` 返回的 `provider` 字段倌。" + }, + "embedding_available": { + "type": "boolean", + "description": "配眮的嵌入暡型圓前是吊可甚。" + }, + "retrieval_model_dict": { + "type": "object", + "description": "知识库的检玢配眮。", + "properties": { + "search_method": { + "type": "string", + "description": "甚于检玢的搜玢方匏。`keyword_search` 衚瀺关键词匹配`semantic_search` 衚瀺基于嵌入的语义盞䌌床`full_text_search` 衚瀺党文玢匕`hybrid_search` 衚瀺语义和关键词混合搜玢。" + }, + "reranking_enable": { + "type": "boolean", + "description": "是吊启甚重排序。" + }, + "reranking_mode": { + "type": "string", + "nullable": true, + "description": "重排序暡匏。`reranking_model` 衚瀺基于暡型的重排序`weighted_score` 衚瀺基于分数的加权。重排序犁甚时䞺 `null`。" + }, + "reranking_model": { + "type": "object", + "description": "重排序暡型配眮。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "重排序暡型的提䟛商名称。" + }, + "reranking_model_name": { + "type": "string", + "description": "重排序暡型名称。" + } + } + }, + "weights": { + "type": "object", + "nullable": true, + "description": "混合搜玢的权重配眮。", + "properties": { + "weight_type": { + "type": "string", + "description": "平衡语义搜玢和关键词搜玢权重的策略。" + }, + "vector_setting": { + "type": "object", + "description": "语义搜玢权重讟眮。", + "properties": { + "vector_weight": { + "type": "number", + "description": "分配给语义向量搜玢结果的权重。" + }, + "embedding_provider_name": { + "type": "string", + "description": "甚于向量搜玢的嵌入暡型提䟛商。" + }, + "embedding_model_name": { + "type": "string", + "description": "甚于向量搜玢的嵌入暡型名称。" + } + } + }, + "keyword_setting": { + "type": "object", + "description": "关键词搜玢权重讟眮。", + "properties": { + "keyword_weight": { + "type": "number", + "description": "分配给关键词搜玢结果的权重。" + } + } + } + } + }, + "top_k": { + "type": "integer", + "description": "返回的最倧结果数。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "是吊启甚分数阈倌过滀。" + }, + "score_threshold": { + "type": "number", + "description": "结果的最䜎盞关性分数。仅圚 `score_threshold_enabled` 䞺 `true` 时生效。" + } + } + }, + "summary_index_setting": { + "type": "object", + "nullable": true, + "description": "摘芁玢匕配眮。", + "properties": { + "enable": { + "type": "boolean", + "description": "是吊已启甚摘芁玢匕。" + }, + "model_name": { + "type": "string", + "description": "甚于生成摘芁的暡型名称。" + }, + "model_provider_name": { + "type": "string", + "description": "摘芁生成暡型的提䟛商。" + }, + "summary_prompt": { + "type": "string", + "description": "甚于摘芁生成的提瀺词暡板。" + } + } + }, + "tags": { "type": "array", + "description": "䞎该知识库关联的标筟。", "items": { "type": "object", - "required": [ - "content" - ], "properties": { - "content": { + "id": { "type": "string", - "description": "块的文本内容Q&A 暡匏䞭䞺问题。" + "description": "标筟标识笊。" }, - "answer": { + "name": { "type": "string", - "description": "答案内容劂果文档倄于 Q&A 暡匏则必需。" + "description": "Tag name." }, - "keywords": { - "type": "array", - "description": "䞎块关联的关键词。", - "items": { - "type": "string" - } + "type": { + "type": "string", + "description": "标筟类型。知识库标筟始终䞺 `knowledge`。" } } } - } - } - }, - "SegmentListResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Segment" - } }, "doc_form": { - "type": "string" - } - } - }, - "SegmentPaginatedResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/SegmentListResponse" + "type": "string", + "description": "文档分块暡匏。`text_model` 衚瀺标准文本分块`hierarchical_model` 衚瀺父子结构`qa_model` 衚瀺问答对提取。" }, - { + "external_knowledge_info": { "type": "object", + "nullable": true, + "description": "倖郚知识库的连接诊情。圓 `provider` 䞺 `external` 时存圚。", "properties": { - "has_more": { - "type": "boolean" + "external_knowledge_id": { + "type": "string", + "description": "倖郚知识库的 ID。" }, - "limit": { - "type": "integer" + "external_knowledge_api_id": { + "type": "string", + "description": "倖郚知识库 API 连接的 ID。" }, - "total": { - "type": "integer" + "external_knowledge_api_name": { + "type": "string", + "description": "倖郚知识库 API 的星瀺名称。" }, - "page": { - "type": "integer" + "external_knowledge_api_endpoint": { + "type": "string", + "description": "倖郚知识库 API 的端点 URL。" } } - } - ] - }, - "SegmentDetailResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Segment" }, - "doc_form": { - "type": "string" - } - } - }, - "UpdateSegmentRequest": { - "type": "object", - "properties": { - "segment": { + "external_retrieval_model": { "type": "object", - "required": [ - "content" - ], + "nullable": true, + "description": "倖郚知识库的检玢讟眮。内郚知识库时䞺 `null`。", "properties": { - "content": { - "type": "string" - }, - "answer": { - "type": "string" + "top_k": { + "type": "integer", + "description": "从倖郚知识库返回的最倧结果数量。" }, - "keywords": { - "type": "array", - "items": { - "type": "string" - } - }, - "enabled": { - "type": "boolean" + "score_threshold": { + "type": "number", + "description": "最䜎盞关性埗分阈倌。" }, - "regenerate_child_chunks": { + "score_threshold_enabled": { "type": "boolean", - "description": "是吊重新生成子块分层暡匏。" + "description": "是吊启甚分数阈倌过滀。" } } - } - } - }, - "RetrieveRequest": { - "type": "object", - "required": [ - "query" - ], - "properties": { - "query": { - "type": "string", - "description": "搜玢查询字笊䞲。" }, - "retrieval_model": { - "allOf": [ - { - "$ref": "#/components/schemas/RetrievalModel" - }, - { - "type": "object", - "properties": { - "metadata_filtering_conditions": { - "type": "object", - "description": "基于元数据过滀结果的条件。", - "properties": { - "logical_operator": { - "type": "string", - "enum": [ - "and", - "or" - ] - }, - "conditions": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "元数据字段的名称。" - }, - "comparison_operator": { - "type": "string", - "description": "比蟃的运算笊。" - }, - "value": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } - ], - "nullable": true, - "description": "芁比蟃的倌。" - } - } - } - } - } - } - } - } - ] - } - } - }, - "RetrievedSegment": { - "type": "object", - "properties": { - "segment": { - "allOf": [ - { - "$ref": "#/components/schemas/Segment" - }, - { - "type": "object", - "properties": { - "document": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "data_source_type": { - "type": "string" - }, - "name": { - "type": "string" - } - } - } + "doc_metadata": { + "type": "array", + "description": "知识库的元数据字段定义。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识笊。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段倌类型。" } } - ] + } }, - "score": { - "type": "number", - "format": "float" - } - } - }, - "RetrieveResponse": { - "type": "object", - "properties": { - "query": { + "built_in_field_enabled": { + "type": "boolean", + "description": "是吊启甚内眮元数据字段䟋劂 `document_name`、`uploader`。" + }, + "pipeline_id": { + "type": "string", + "nullable": true, + "description": "自定义倄理流氎线的 ID劂果已配眮。" + }, + "runtime_mode": { + "type": "string", + "nullable": true, + "description": "运行时倄理暡匏。" + }, + "chunk_structure": { + "type": "string", + "nullable": true, + "description": "分段结构配眮。" + }, + "icon_info": { "type": "object", + "nullable": true, + "description": "知识库的囟标星瀺配眮。", "properties": { - "content": { - "type": "string" + "icon_type": { + "type": "string", + "description": "囟标类型。" + }, + "icon": { + "type": "string", + "description": "囟标标识笊或衚情笊号。" + }, + "icon_background": { + "type": "string", + "description": "囟标的背景颜色。" + }, + "icon_url": { + "type": "string", + "description": "自定义囟标囟片的 URL。" } } }, - "records": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RetrievedSegment" - } + "is_published": { + "type": "boolean", + "description": "知识库是吊已发垃。" + }, + "total_documents": { + "type": "integer", + "description": "文档总数。" + }, + "total_available_documents": { + "type": "integer", + "description": "已启甚䞔可甚的文档数量。" + }, + "enable_api": { + "type": "boolean", + "description": "该知识库是吊启甚 API 访问。" + }, + "is_multimodal": { + "type": "boolean", + "description": "是吊启甚倚暡态内容倄理。" } } }, - "Model": { + "Document": { "type": "object", "properties": { - "model": { - "type": "string" + "id": { + "type": "string", + "description": "文档的唯䞀标识笊。" + }, + "position": { + "type": "integer", + "description": "文档圚列衚䞭的星瀺䜍眮。" + }, + "data_source_type": { + "type": "string", + "description": "文档的创建方匏。文件䞊䌠䞺 `upload_file`Notion 富入䞺 `notion_import`。" + }, + "data_source_info": { + "type": "object", + "description": "原始数据源信息随 `data_source_type` 而匂。" + }, + "data_source_detail_dict": { + "type": "object", + "description": "诊细的数据源信息包括文件诊情。" + }, + "dataset_process_rule_id": { + "type": "string", + "description": "应甚于该文档的倄理规则 ID。" + }, + "name": { + "type": "string", + "description": "文档名称。" + }, + "created_from": { + "type": "string", + "description": "文档来源。通过 API 创建时䞺 `api`通过 UI 创建时䞺 `web`。" }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } + "created_by": { + "type": "string", + "description": "创建该文档的甚户 ID。" }, - "model_type": { - "type": "string" + "created_at": { + "type": "number", + "description": "创建时闎戳Unix 纪元单䜍䞺秒。" }, - "features": { - "type": "array", - "items": {}, - "nullable": true + "tokens": { + "type": "integer", + "description": "文档䞭的什牌总数。" }, - "fetch_from": { - "type": "string" + "indexing_status": { + "type": "string", + "description": "圓前玢匕状态。`waiting` 衚瀺排队䞭`parsing` 衚瀺正圚提取内容`cleaning` 衚瀺正圚去噪`splitting` 衚瀺正圚分块`indexing` 衚瀺正圚构建向量`completed` 衚瀺就绪`error` 衚瀺倱莥`paused` 衚瀺手劚暂停。" }, - "model_properties": { - "type": "object", - "properties": { - "context_size": { - "type": "integer" - } - } + "error": { + "type": "string", + "nullable": true, + "description": "玢匕倱莥时的错误消息。无错误时䞺 `null`。" }, - "deprecated": { - "type": "boolean" + "enabled": { + "type": "boolean", + "description": "该文档是吊启甚检玢。" }, - "status": { - "type": "string" + "disabled_at": { + "type": "number", + "nullable": true, + "description": "文档被犁甚的时闎戳。启甚时䞺 `null`。" }, - "load_balancing_enabled": { - "type": "boolean" - } - } - }, - "ModelProvider": { - "type": "object", - "properties": { - "provider": { - "type": "string" + "disabled_by": { + "type": "string", + "nullable": true, + "description": "犁甚该文档的甚户 ID。启甚时䞺 `null`。" }, - "label": { - "type": "object", - "additionalProperties": { - "type": "string" - } + "archived": { + "type": "boolean", + "description": "文档是吊已園档。" }, - "icon_small": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } + "display_status": { + "type": "string", + "description": "基于 `indexing_status` 和 `enabled` 状态掟生的面向甚户的星瀺状态。" }, - "icon_large": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uri" - } + "word_count": { + "type": "integer", + "description": "文档的总字数。" }, - "status": { - "type": "string" + "hit_count": { + "type": "integer", + "description": "该文档圚检玢查询䞭被匹配的次数。" + }, + "doc_form": { + "type": "string", + "description": "文档分块暡匏。`text_model` 衚瀺标准文本分块`hierarchical_model` 衚瀺父子结构`qa_model` 衚瀺问答对提取。" }, - "models": { + "doc_metadata": { "type": "array", + "description": "分配给该文档的元数据倌。", "items": { - "$ref": "#/components/schemas/Model" + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "元数据字段标识笊。" + }, + "name": { + "type": "string", + "description": "元数据字段名称。" + }, + "type": { + "type": "string", + "description": "元数据字段倌类型。" + }, + "value": { + "type": "string", + "description": "歀文档的元数据倌。" + } + } } + }, + "summary_index_status": { + "type": "string", + "nullable": true, + "description": "该文档的摘芁玢匕状态。未配眮摘芁玢匕时䞺 `null`。" + }, + "need_summary": { + "type": "boolean", + "description": "是吊需芁䞺该文档生成摘芁。" } } }, - "ChildChunk": { + "Segment": { "type": "object", - "description": "衚瀺分层分割䞭的子块。", "properties": { "id": { "type": "string", - "format": "uuid" + "description": "分段的唯䞀标识笊。" }, - "segment_id": { + "position": { + "type": "integer", + "description": "分段圚文档䞭的䜍眮。" + }, + "document_id": { "type": "string", - "format": "uuid" + "description": "该分段所属文档的 ID。" }, "content": { - "type": "string" + "type": "string", + "description": "分段的文本内容。" + }, + "sign_content": { + "type": "string", + "description": "甚于完敎性验证的筟名内容哈垌。" + }, + "answer": { + "type": "string", + "description": "回答内容甚于问答暡匏文档。" }, "word_count": { - "type": "integer" + "type": "integer", + "description": "分段内容的字数。" }, "tokens": { - "type": "integer" + "type": "integer", + "description": "分段内容的什牌数。" + }, + "keywords": { + "type": "array", + "description": "䞎该分段关联的关键词甚于基于关键词的检玢。", + "items": { + "type": "string" + } }, "index_node_id": { - "type": "string" + "type": "string", + "description": "向量存傚䞭玢匕节点的 ID。" }, "index_node_hash": { - "type": "string" + "type": "string", + "description": "玢匕内容的哈垌倌甚于检测变曎。" + }, + "hit_count": { + "type": "integer", + "description": "该分段圚检玢查询䞭被匹配的次数。" + }, + "enabled": { + "type": "boolean", + "description": "该分段是吊启甚检玢。" + }, + "disabled_at": { + "type": "number", + "nullable": true, + "description": "分段被犁甚的时闎戳。启甚时䞺 `null`。" + }, + "disabled_by": { + "type": "string", + "nullable": true, + "description": "犁甚该分段的甚户 ID。启甚时䞺 `null`。" }, "status": { - "type": "string" + "type": "string", + "description": "分段的圓前玢匕状态䟋劂 `completed`、`indexing`、`error`。" }, "created_by": { "type": "string", - "format": "uuid" + "description": "创建该分段的甚户 ID。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "创建时闎戳Unix 纪元单䜍䞺秒。" + }, + "updated_at": { + "type": "number", + "description": "最后曎新时闎戳Unix 纪元单䜍䞺秒。" + }, + "updated_by": { + "type": "string", + "description": "最后曎新该分段的甚户 ID。" }, "indexing_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "玢匕匀始的时闎戳。尚未匀始时䞺 `null`。" }, "completed_at": { - "type": "integer", - "format": "int64" + "type": "number", + "nullable": true, + "description": "玢匕完成的时闎戳。尚未完成时䞺 `null`。" }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "玢匕倱莥时的错误消息。无错误时䞺 `null`。" }, "stopped_at": { - "type": "integer", - "format": "int64", - "nullable": true - } - } - }, - "CreateChildChunkRequest": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "子块的内容。" - } - } - }, - "UpdateChildChunkRequest": { - "type": "object", - "required": [ - "content" - ], - "properties": { - "content": { - "type": "string", - "description": "子块的曎新内容。" - } - } - }, - "ChildChunkResponse": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ChildChunk" - } - } - }, - "ChildChunkListResponse": { - "type": "object", - "properties": { - "data": { + "type": "number", + "nullable": true, + "description": "玢匕停止的时闎戳。未停止时䞺 `null`。" + }, + "child_chunks": { "type": "array", + "description": "属于该分段的子分段。仅圚分层暡匏文档䞭存圚。", "items": { "$ref": "#/components/schemas/ChildChunk" } }, - "total": { - "type": "integer" - }, - "total_pages": { - "type": "integer" - }, - "page": { - "type": "integer" + "attachments": { + "type": "array", + "description": "附加到该分段的文件。", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "附件文件标识笊。" + }, + "name": { + "type": "string", + "description": "原始文件名。" + }, + "size": { + "type": "integer", + "description": "文件倧小字节。" + }, + "extension": { + "type": "string", + "description": "文件扩展名。" + }, + "mime_type": { + "type": "string", + "description": "文件的 MIME 类型。" + }, + "source_url": { + "type": "string", + "description": "访问附件的 URL。" + } + } + } }, - "limit": { - "type": "integer" + "summary": { + "type": "string", + "nullable": true, + "description": "AI 生成的分段内容摘芁。未启甚摘芁玢匕时䞺 `null`。" } } }, - "UploadFileResponse": { + "ChildChunk": { "type": "object", "properties": { "id": { "type": "string", - "format": "uuid" - }, - "name": { - "type": "string" + "description": "子分段的唯䞀标识笊。" }, - "size": { - "type": "integer" - }, - "extension": { - "type": "string" - }, - "url": { + "segment_id": { "type": "string", - "format": "uri", - "description": "文件的预览 URL。" + "description": "该子分段所属的父分段 ID。" }, - "download_url": { + "content": { "type": "string", - "format": "uri", - "description": "文件的䞋蜜 URL。" + "description": "子分段的文本内容。" }, - "mime_type": { - "type": "string" + "position": { + "type": "integer", + "description": "子分段圚父分段䞭的䜍眮。" }, - "created_by": { + "word_count": { + "type": "integer", + "description": "子分段内容的字数。" + }, + "type": { "type": "string", - "format": "uuid" + "description": "子分段的创建方匏。系统生成䞺 `automatic`手劚创建䞺 `custom`。" }, "created_at": { - "type": "integer", - "format": "int64" + "type": "number", + "description": "创建时闎戳Unix 纪元单䜍䞺秒。" + }, + "updated_at": { + "type": "number", + "description": "最后曎新时闎戳Unix 纪元单䜍䞺秒。" } } }, - "Tag": { + "RetrievalModel": { "type": "object", + "required": [ + "search_method", + "reranking_enable", + "top_k", + "score_threshold_enabled" + ], "properties": { - "id": { + "search_method": { "type": "string", - "format": "uuid" + "description": "甚于检玢的搜玢方法。", + "enum": [ + "keyword_search", + "semantic_search", + "full_text_search", + "hybrid_search" + ] }, - "name": { - "type": "string" + "reranking_enable": { + "type": "boolean", + "description": "是吊启甚重排序。" }, - "type": { + "reranking_model": { + "type": "object", + "description": "重排序暡型配眮。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "重排序暡型的提䟛商名称。" + }, + "reranking_model_name": { + "type": "string", + "description": "重排序暡型名称。" + } + } + }, + "reranking_mode": { "type": "string", - "example": "knowledge" + "enum": [ + "reranking_model", + "weighted_score" + ], + "nullable": true, + "description": "重排序暡匏。圓 `reranking_enable` 䞺 `true` 时必填。" + }, + "top_k": { + "type": "integer", + "description": "返回的最倧结果数。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "是吊启甚分数阈倌过滀。" }, - "binding_count": { - "type": "integer" + "score_threshold": { + "type": "number", + "nullable": true, + "description": "结果的最䜎盞关性分数。仅圚 `score_threshold_enabled` 䞺 `true` 时生效。" + }, + "weights": { + "type": "object", + "nullable": true, + "description": "混合搜玢的权重配眮。", + "properties": { + "weight_type": { + "type": "string", + "description": "平衡语义搜玢和关键词搜玢权重的策略。", + "enum": [ + "semantic_first", + "keyword_first", + "customized" + ] + }, + "vector_setting": { + "type": "object", + "description": "语义搜玢权重讟眮。", + "properties": { + "vector_weight": { + "type": "number", + "description": "分配给语义向量搜玢结果的权重。" + }, + "embedding_provider_name": { + "type": "string", + "description": "甚于向量搜玢的嵌入暡型提䟛商。" + }, + "embedding_model_name": { + "type": "string", + "description": "甚于向量搜玢的嵌入暡型名称。" + } + } + }, + "keyword_setting": { + "type": "object", + "description": "关键词搜玢权重讟眮。", + "properties": { + "keyword_weight": { + "type": "number", + "description": "分配给关键词搜玢结果的权重。" + } + } + } + } } } } + }, + "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 泄挏富臎䞥重后果。**" + } } } } diff --git a/zh/api-reference/openapi_workflow.json b/zh/api-reference/openapi_workflow.json index ed9742e9a..339dc8812 100644 --- a/zh/api-reference/openapi_workflow.json +++ b/zh/api-reference/openapi_workflow.json @@ -1,18 +1,18 @@ { "openapi": "3.0.1", "info": { - "title": "Workflow 应甚 API", - "description": "Workflow 应甚无䌚话支持适合甚于翻译/文章写䜜/总结 AI 等等。", + "title": "工䜜流应甚 API", + "description": "工䜜流应甚提䟛无䌚话支持适甚于翻译、文章写䜜、摘芁 AI 等场景。", "version": "1.0.0" }, "servers": [ { "url": "{api_base_url}", - "description": "API 的基础 URL。请将 {api_base_url} 替换䞺䜠的应甚提䟛的实际 API 基础 URL。", + "description": "工䜜流应甚 API 的基础 URL。将 {api_base_url} 替换䞺实际的 API 基础 URL。", "variables": { "api_base_url": { "default": "https://api.dify.ai/v1", - "description": "实际的 API 基础 URL" + "description": "API 的实际基础 URL" } } } @@ -25,37 +25,49 @@ "paths": { "/workflows/run": { "post": { - "summary": "执行 workflow", - "description": "执行 workflow没有已发垃的 workflow䞍可执行。", - "operationId": "executeWorkflowCn", - "tags": ["工䜜流执行"], + "summary": "执行工䜜流", + "description": "执行工䜜流。没有已发垃的工䜜流时无法执行。", + "operationId": "runWorkflowZh", + "tags": [ + "工䜜流" + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowExecutionRequestCn" + "$ref": "#/components/schemas/WorkflowExecutionRequest" }, "examples": { - "basic_execution_cn": { - "summary": "基础工䜜流执行瀺䟋", + "streaming_example": { + "summary": "请求瀺䟋 - 流匏暡匏", "value": { "inputs": { - "query": "请总结这段文字..." + "query": "Summarize this text: The quick brown fox jumps over the lazy dog." }, "response_mode": "streaming", - "user": "workflow_user_001" + "user": "user_workflow_123" + } + }, + "blocking_example": { + "summary": "请求瀺䟋 - 阻塞暡匏", + "value": { + "inputs": { + "query": "Translate this to French: Hello world" + }, + "response_mode": "blocking", + "user": "user_workflow_456" } }, - "with_file_array_variable_cn":{ - "summary": "包含文件列衚变量的蟓入瀺䟋", + "with_file_array_variable": { + "summary": "Request Example - File array input", "value": { "inputs": { "my_documents": [ { "type": "document", "transfer_method": "local_file", - "upload_file_id": "已䞊䌠的文件ID_abc" + "upload_file_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }, { "type": "image", @@ -65,7 +77,196 @@ ] }, "response_mode": "blocking", - "user": "workflow_user_002" + "user": "user_workflow_789" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "请求成功。内容类型和结构取决于请求䞭的 `response_mode` 参数。\n\n- 劂果 `response_mode` 䞺 `blocking`返回 `application/json` 和 `WorkflowBlockingResponse` 对象。\n- 劂果 `response_mode` 䞺 `streaming`返回 `text/event-stream` 和 `ChunkWorkflowEvent` 对象流。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "响应瀺䟋 - 阻塞暡匏", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Bonjour le monde" + }, + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630 + } + } + } + } + }, + "text/event-stream": { + "schema": { + "type": "string", + "description": "服务噚发送事件 (SSE) 流。每䞪事件是䞀䞪以 `data: ` 䞺前猀的 JSON 对象以䞀䞪换行笊终止。\n\n**SSE 解析指南**每䞪事件是䞀行以 `data: ` 䞺前猀的 JSON 对象以 `\\n\\n` 终止。解析 JSON 前先去陀 `data: ` 前猀。JSON 内的 `event` 字段决定事件类型。圓收到终止事件劂 `message_end`、`workflow_finished` 或 `error`时流结束。応略 `ping` 事件每 10 秒发送䞀次以保持连接掻跃。泚意即䜿流䞭出现错误事件HTTP 状态码仍䞺 `200`。" + }, + "examples": { + "streamingResponse": { + "summary": "响应瀺䟋 - 流匏暡匏", + "value": "data: {\"event\": \"workflow_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"inputs\": {\"query\": \"Translate this\"}, \"created_at\": 1705407629, \"reason\": \"initial\"}} data: {\"event\": \"node_started\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"node_exec_1\", \"node_id\": \"node_1\", \"node_type\": \"llm\", \"title\": \"LLM Node\", \"index\": 1, \"created_at\": 1705407629}} data: {\"event\": \"text_chunk\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"text\": \"Bonjour\", \"from_variable_selector\": [\"node_1\", \"text\"]}} data: {\"event\": \"workflow_finished\", \"task_id\": \"c3800678-a077-43df-a102-53f23ed20b88\", \"workflow_run_id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"data\": {\"id\": \"fb47b2e6-5e43-4f90-be01-d5c5a088d156\", \"workflow_id\": \"7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345\", \"status\": \"succeeded\", \"outputs\": {\"result\": \"Bonjour le monde\"}, \"elapsed_time\": 1.23, \"total_tokens\": 150, \"total_steps\": 3, \"created_at\": 1705407629, \"finished_at\": 1705407630}}" + } + } + } + } + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。\n- `provider_quota_exceeded` : 暡型提䟛商配额已甚尜。\n- `model_currently_not_support` : 圓前暡型䞍可甚。\n- `completion_request_error` : 工䜜流 execution request failed.\n- `invalid_param` : Invalid parameter value.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "429": { + "description": "- `too_many_requests` : 该应甚的并发请求过倚。\n- `rate_limit_error` : 䞊枞暡型提䟛商的速率限制已超出。", + "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." + } + } + } + } + } + } + } + } + }, + "/workflows/{workflow_id}/run": { + "post": { + "summary": "按 ID 执行工䜜流", + "description": "通过 ID 执行指定的工䜜流版本。适甚于运行工䜜流的特定已发垃版本。", + "operationId": "runWorkflowByIdZh", + "tags": [ + "工䜜流" + ], + "parameters": [ + { + "name": "workflow_id", + "in": "path", + "required": true, + "description": "芁执行的特定版本的工䜜流 ID。歀倌圚 [执行工䜜流](/api-reference/工䜜流/执行-工䜜流) 响应和 [获取工䜜流运行诊情](/api-reference/工䜜流/获取-工䜜流-执行情况) 的 `workflow_id` 字段䞭返回。", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowExecutionRequest" + }, + "examples": { + "example": { + "summary": "请求瀺䟋", + "value": { + "inputs": { + "query": "Summarize this article" + }, + "response_mode": "blocking", + "user": "user_workflow_123" } } } @@ -74,67 +275,417 @@ }, "responses": { "200": { - "description": "工䜜流执行成功。响应结构取决于 `response_mode`。\n- `blocking`: `application/json` 栌匏包含 `WorkflowCompletionResponseCn` 对象。\n- `streaming`: `text/event-stream` 栌匏包含 `ChunkWorkflowEventCn` 事件流。", + "description": "请求成功。内容类型和结构取决于请求䞭的 `response_mode` 参数。\n\n- 劂果 `response_mode` 䞺 `blocking`返回 `application/json` 和 `WorkflowBlockingResponse` 对象。\n- 劂果 `response_mode` 䞺 `streaming`返回 `text/event-stream` 和 `ChunkWorkflowEvent` 对象流。", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkflowCompletionResponseCn" + "$ref": "#/components/schemas/WorkflowBlockingResponse" + }, + "examples": { + "blockingResponse": { + "summary": "响应瀺䟋 - 阻塞暡匏", + "value": { + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "outputs": { + "result": "Article summary here" + }, + "error": null, + "elapsed_time": 2.45, + "total_tokens": 280, + "total_steps": 4, + "created_at": 1705407629, + "finished_at": 1705407631 + } + } + } } }, "text/event-stream": { "schema": { "type": "string", - "description": "SSE 事件流。每䞪事件以 'data: ' 匀倎以 '\\n\\n' 结尟。具䜓结构请参见 `ChunkWorkflowEventCn`。" + "description": "服务噚发送事件 (SSE) 流。每䞪事件是䞀䞪以 `data: ` 䞺前猀的 JSON 对象以䞀䞪换行笊终止。\n\n**SSE 解析指南**每䞪事件是䞀行以 `data: ` 䞺前猀的 JSON 对象以 `\\n\\n` 终止。解析 JSON 前先去陀 `data: ` 前猀。JSON 内的 `event` 字段决定事件类型。圓收到终止事件劂 `message_end`、`workflow_finished` 或 `error`时流结束。応略 `ping` 事件每 10 秒发送䞀次以保持连接掻跃。泚意即䜿流䞭出现错误事件HTTP 状态码仍䞺 `200`。" + } + } + } + }, + "400": { + "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : 工䜜流 is a draft or has an invalid ID format.\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。\n- `provider_quota_exceeded` : 暡型提䟛商配额已甚尜。\n- `model_currently_not_support` : 圓前暡型䞍可甚。\n- `completion_request_error` : 工䜜流 execution request failed.\n- `invalid_param` : Required parameter missing or invalid.", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "bad_request": { + "summary": "bad_request", + "value": { + "status": 400, + "code": "bad_request", + "message": "Workflow is a draft and cannot be executed." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 工䜜流 not found.", + "content": { + "application/json": { + "examples": { + "not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow not found." + } + } + } + } + } + }, + "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" + } + } } } } }, - "400": { "$ref": "#/components/responses/BadRequestWorkflowCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } + "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." + } + } + } + } + } + } } } }, "/workflows/run/{workflow_run_id}": { "get": { - "summary": "获取workflow执行情况", - "description": "根据 workflow 执行 ID 获取 workflow 任务圓前执行结果。", - "operationId": "getWorkflowRunDetailCn", - "tags": ["工䜜流执行"], + "summary": "获取工䜜流执行情况", + "description": "根据工䜜流执行 ID 获取工䜜流任务的圓前执行结果。", + "operationId": "getWorkflowRunDetailZh", + "tags": [ + "工䜜流" + ], "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, - "description": "workflow 执行 ID可圚流匏返回 Chunk 或阻塞暡匏响应䞭获取。", - "schema": { "type": "string", "format": "uuid" } + "description": "工䜜流运行 ID可从工䜜流执行响应或流匏事件䞭获取。", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "成功获取 workflow 执行诊情。", + "description": "成功获取工䜜流运行诊情。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowRunDetailResponse" + }, + "examples": { + "workflowRunDetail": { + "summary": "响应瀺䟋", + "value": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "succeeded", + "inputs": { + "query": "Translate this to French" + }, + "outputs": { + "result": "Traduisez ceci en francais" + }, + "error": null, + "total_steps": 3, + "total_tokens": 150, + "created_at": 1705407629, + "finished_at": 1705407630, + "elapsed_time": 1.23 + } + } + } + } + } + }, + "400": { + "description": "`not_workflow_app` : 应甚暡匏䞎 API 路由䞍匹配。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + } + } + } + } + }, + "404": { + "description": "`not_found` : 未扟到工䜜流运行记圕。", "content": { "application/json": { - "schema": { "$ref": "#/components/schemas/WorkflowRunDetailResponseCn" } + "examples": { + "workflow_run_not_found": { + "summary": "not_found", + "value": { + "status": 404, + "code": "not_found", + "message": "Workflow run not found." + } + } + } } } + } + } + } + }, + "/workflows/logs": { + "get": { + "summary": "获取工䜜流日志", + "description": "获取分页的工䜜流执行日志支持筛选选项。", + "operationId": "listWorkflowLogsZh", + "tags": [ + "工䜜流" + ], + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "圚日志䞭搜玢的关键词。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "按执行状态筛选。", + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "stopped" + ] + } + }, + { + "name": "page", + "in": "query", + "description": "分页页码。", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1, + "maximum": 99999 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页条目数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "created_at__before", + "in": "query", + "description": "筛选圚歀 ISO 8601 时闎戳之前创建的日志。", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "created_at__after", + "in": "query", + "description": "筛选圚歀 ISO 8601 时闎戳之后创建的日志。", + "schema": { + "type": "string", + "format": "date-time" + } }, - "404": {"description": "Workflow 执行记圕未扟到。"} + { + "name": "created_by_end_user_session_id", + "in": "query", + "description": "按终端甚户䌚话 ID 筛选。", + "schema": { + "type": "string" + } + }, + { + "name": "created_by_account", + "in": "query", + "description": "按莊户 ID 筛选。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "成功获取工䜜流日志。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowLogsResponse" + }, + "examples": { + "workflowLogs": { + "summary": "响应瀺䟋", + "value": { + "page": 1, + "limit": 20, + "total": 1, + "has_more": false, + "data": [ + { + "id": "b7e2f8a1-3c4d-5e6f-7890-abcdef123456", + "workflow_run": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "version": "2025-01-16 12:00:00.000000", + "status": "succeeded", + "error": null, + "elapsed_time": 1.23, + "total_tokens": 150, + "total_steps": 3, + "created_at": 1705407629, + "finished_at": 1705407630, + "exceptions_count": 0, + "triggered_from": "app" + }, + "created_from": "service-api", + "created_by_role": "end_user", + "created_by_account": null, + "created_by_end_user": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "type": "service_api", + "is_anonymous": false, + "session_id": "user_workflow_123" + }, + "created_at": 1705407629 + } + ] + } + } + } + } + } + } } } }, "/workflows/tasks/{task_id}/stop": { "post": { - "summary": "停止响应 (Workflow Task)", - "description": "停止 workflow 任务的生成。仅支持流匏暡匏。", - "operationId": "stopWorkflowTaskGenerationCn", - "tags": ["工䜜流执行"], + "summary": "停止工䜜流任务", + "description": "停止正圚运行的工䜜流任务。仅圚 `streaming` 暡匏䞋支持。", + "operationId": "stopWorkflowTaskZh", + "tags": [ + "工䜜流" + ], "parameters": [ { "name": "task_id", "in": "path", "required": true, - "description": "任务 ID可圚流匏返回 Chunk 䞭获取。", - "schema": { "type": "string", "format": "uuid" } + "description": "任务 ID可以从 [执行工䜜流](/api-reference/工䜜流/执行-工䜜流) API 的流匏分块返回䞭获取。", + "schema": { + "type": "string" + } } ], "requestBody": { @@ -143,305 +694,3143 @@ "application/json": { "schema": { "type": "object", - "required": ["user"], + "required": [ + "user" + ], "properties": { - "user": { "type": "string", "description": "甚户标识必须和执行 workflow 接口䌠入的 user 保持䞀臎。" } + "user": { + "type": "string", + "description": "甚户标识笊必须䞎 [执行工䜜流](/api-reference/工䜜流/执行-工䜜流) 请求䞭䌠递的甚户䞀臎。" + } + } + }, + "examples": { + "example": { + "summary": "请求瀺䟋", + "value": { + "user": "user_workflow_123" + } } } } } }, "responses": { - "200": { "$ref": "#/components/responses/SuccessResultCn" } + "200": { + "$ref": "#/components/responses/SuccessResult" + }, + "400": { + "description": "- `not_workflow_app` : 应甚暡匏䞎 API 路由䞍匹配。\n- `invalid_param` : 必芁参数猺倱或无效。", + "content": { + "application/json": { + "examples": { + "not_workflow_app": { + "summary": "not_workflow_app", + "value": { + "status": 400, + "code": "not_workflow_app", + "message": "Please check if your app mode matches the right API route." + } + }, + "invalid_param": { + "summary": "invalid_param", + "value": { + "status": 400, + "code": "invalid_param", + "message": "Arg user must be provided." + } + } + } + } + } + } } } }, "/files/upload": { "post": { - "summary": "䞊䌠文件 (Workflow)", - "description": "䞊䌠文件并圚执行 workflow 时䜿甚。支持䜠的工䜜流皋所支持的任䜕栌匏。䞊䌠的文件仅䟛圓前终端甚户䜿甚。", - "operationId": "uploadWorkflowFileCn", - "tags": ["文件操䜜 (Workflow)"], + "operationId": "uploadWorkflowFileZh", + "tags": [ + "文件操䜜" + ], + "summary": "䞊䌠文件", + "description": "䞊䌠文件甚于发送消息时䜿甚支持囟片、文档、音频和视频的倚暡态理解。䞊䌠的文件仅䟛圓前终端甚户䜿甚。", "requestBody": { + "description": "文件䞊䌠请求。需芁 multipart/form-data 栌匏。", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", - "required": ["file", "user"], + "required": [ + "file" + ], "properties": { - "file": { "type": "string", "format": "binary", "description": "芁䞊䌠的文件。" }, - "user": { "type": "string", "description": "甚户标识。" } + "file": { + "type": "string", + "format": "binary", + "description": "芁䞊䌠的文件。支持的类型包括囟片、文档、音频和视频。" + }, + "user": { + "type": "string", + "description": "甚户标识笊由匀发者定义的规则生成必须圚应甚内唯䞀。" + } } } } } }, "responses": { - "200": { "description": "文件䞊䌠成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseCn" } } } }, - "201": { "description": "文件创建成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseCn" } } } }, - "400": { "$ref": "#/components/responses/BadRequestFileCn" }, - "413": { "$ref": "#/components/responses/FileTooLargeCn" }, - "415": { "$ref": "#/components/responses/UnsupportedFileTypeFileCn" }, - "503": { "$ref": "#/components/responses/S3ErrorFileCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } + "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." + } + } + } + } + } + } } } }, - "/end-users/{end_user_id}": { + "/files/{file_id}/preview": { "get": { - "summary": "获取终端甚户", - "description": "通过 ID 获取终端甚户信息。\n\n圓其他 API 返回终端甚户 ID䟋劂文件䞊䌠接口返回的 `created_by`时可䜿甚该接口查询对应的终端甚户信息。", - "operationId": "getEndUserWorkflowCn", - "tags": ["终端甚户"], + "operationId": "downloadWorkflowFileZh", + "tags": [ + "文件操䜜" + ], + "summary": "文件䞋蜜", + "description": "预览或䞋蜜之前通过[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 䞊䌠的文件。仅可访问属于请求应甚内消息的文件。", "parameters": [ { - "name": "end_user_id", + "name": "file_id", "in": "path", "required": true, - "description": "终端甚户 ID。", - "schema": { "type": "string", "format": "uuid" } + "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": "成功获取终端甚户信息。", + "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": { - "schema": { "$ref": "#/components/schemas/EndUserDetailCn" } + "examples": { + "file_access_denied": { + "summary": "file_access_denied", + "value": { + "status": 403, + "code": "file_access_denied", + "message": "Access to the requested file is denied." + } + } + } } } }, - "404": { "$ref": "#/components/responses/EndUserNotFoundCn" }, - "500": { "$ref": "#/components/responses/InternalServerErrorCn" } - } - } - }, - "/workflows/logs": { - "get": { - "summary": "获取 workflow 日志", - "description": "倒序返回 workflow 日志。", - "operationId": "getWorkflowLogsCn", - "tags": ["工䜜流执行"], - "parameters": [ - { "name": "keyword", "in": "query", "description": "可选关键字。", "schema": { "type": "string" } }, - { "name": "status", "in": "query", "description": "可选执行状态succeeded, failed, stopped, running。", "schema": { "type": "string", "enum": ["succeeded", "failed", "stopped", "running"] } }, - { "name": "page", "in": "query", "description": "可选圓前页码, 默讀1。", "schema": { "type": "integer", "default": 1 } }, - { "name": "limit", "in": "query", "description": "可选每页条数, 默讀20。", "schema": { "type": "integer", "default": 20 } } - ], - "responses": { - "200": { "description": "成功获取 workflow 日志。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowLogsResponseCn" } } } } + "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." + } + } + } + } } + } } + } }, - "/info": { + "/end-users/{end_user_id}": { + "get": { + "operationId": "getWorkflowEndUserZh", + "tags": [ + "终端甚户" + ], + "summary": "获取终端甚户", + "description": "根据 ID 获取终端甚户信息。圓其他 API 返回终端甚户 ID䟋劂[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件)返回的 `created_by`时埈有甚。", + "parameters": [ + { + "name": "end_user_id", + "in": "path", + "required": true, + "description": "终端甚户 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "成功获取终端甚户。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EndUserDetail" + }, + "examples": { + "endUserDetail": { + "summary": "响应瀺䟋", + "value": { + "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", + "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00", + "app_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "type": "service_api", + "external_user_id": "abc-123", + "name": null, + "is_anonymous": false, + "session_id": "abc-123", + "created_at": "2024-01-16T12:00:29Z", + "updated_at": "2024-01-16T12:00:29Z" + } + } + } + } + } + }, + "404": { + "description": "`end_user_not_found` : 未扟到终端甚户。", + "content": { + "application/json": { + "examples": { + "end_user_not_found": { + "summary": "end_user_not_found", + "value": { + "status": 404, + "code": "end_user_not_found", + "message": "End user not found." + } + } + } + } + } + } + } + } + }, + "/audio-to-text": { + "post": { + "operationId": "workflowAudioToTextZh", + "tags": [ + "语音䞎文字蜬换" + ], + "summary": "语音蜬文字", + "description": "将音频文件蜬换䞺文字。支持的栌匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件倧小限制䞺 `30 MB`。", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/AudioToTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "语音蜬文字成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AudioToTextResponse" + }, + "examples": { + "audioToTextSuccess": { + "summary": "响应瀺䟋", + "value": { + "text": "Hello, I would like to know more about the iPhone 13 Pro Max." + } + } + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应甚䞍可甚或配眮错误。\n- `no_audio_uploaded` : 未䞊䌠音频文件。\n- `provider_not_support_speech_to_text` : 暡型提䟛商䞍支持语音蜬文字。\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。\n- `provider_quota_exceeded` : 暡型提䟛商配额已甚尜。\n- `model_currently_not_support` : 圓前暡型䞍支持歀操䜜。\n- `completion_request_error` : 语音识别请求倱莥。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "no_audio_uploaded": { + "summary": "no_audio_uploaded", + "value": { + "status": 400, + "code": "no_audio_uploaded", + "message": "Please upload your audio." + } + }, + "provider_not_support_speech_to_text": { + "summary": "provider_not_support_speech_to_text", + "value": { + "status": 400, + "code": "provider_not_support_speech_to_text", + "message": "Provider not support speech to text." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "413": { + "description": "`audio_too_large` : 音频文件倧小超出限制。", + "content": { + "application/json": { + "examples": { + "audio_too_large": { + "summary": "audio_too_large", + "value": { + "status": 413, + "code": "audio_too_large", + "message": "Audio size exceeded." + } + } + } + } + } + }, + "415": { + "description": "`unsupported_audio_type` : 䞍允讞的音频类型。", + "content": { + "application/json": { + "examples": { + "unsupported_audio_type": { + "summary": "unsupported_audio_type", + "value": { + "status": 415, + "code": "unsupported_audio_type", + "message": "Audio type not allowed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚服务噚错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/text-to-audio": { + "post": { + "operationId": "workflowTextToAudioZh", + "tags": [ + "语音䞎文字蜬换" + ], + "summary": "文字蜬语音", + "description": "将文字蜬换䞺语音。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TextToAudioRequest" + }, + "examples": { + "textToAudioExample": { + "summary": "请求瀺䟋", + "value": { + "text": "Hello, welcome to our service.", + "user": "abc-123", + "voice": "alloy", + "streaming": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "返回生成的音频文件。`Content-Type` 倎讟眮䞺音频 MIME 类型䟋劂 `audio/wav`、`audio/mp3`。劂果 `streaming` 䞺 `true`音频将以分块䌠蟓猖码方匏流匏返回。", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "- `app_unavailable` : 应甚䞍可甚或配眮错误。\n- `provider_not_initialize` : 未扟到有效的暡型提䟛商凭据。\n- `provider_quota_exceeded` : 暡型提䟛商配额已甚尜。\n- `model_currently_not_support` : 圓前暡型䞍支持歀操䜜。\n- `completion_request_error` : 文字蜬语音请求倱莥。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + }, + "provider_not_initialize": { + "summary": "provider_not_initialize", + "value": { + "status": 400, + "code": "provider_not_initialize", + "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials." + } + }, + "provider_quota_exceeded": { + "summary": "provider_quota_exceeded", + "value": { + "status": 400, + "code": "provider_quota_exceeded", + "message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials." + } + }, + "model_currently_not_support": { + "summary": "model_currently_not_support", + "value": { + "status": 400, + "code": "model_currently_not_support", + "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model." + } + }, + "completion_request_error": { + "summary": "completion_request_error", + "value": { + "status": 400, + "code": "completion_request_error", + "message": "Completion request failed." + } + } + } + } + } + }, + "500": { + "description": "`internal_server_error` : 内郚服务噚错误。", + "content": { + "application/json": { + "examples": { + "internal_server_error": { + "summary": "internal_server_error", + "value": { + "status": 500, + "code": "internal_server_error", + "message": "Internal server error." + } + } + } + } + } + } + } + } + }, + "/info": { "get": { - "summary": "获取应甚基本信息 (Workflow)", - "operationId": "getWorkflowAppInfoCn", - "tags": ["应甚配眮 (Workflow)"], - "responses": { "200": { "description": "应甚基本信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInfoResponseCn" } } } } } + "operationId": "getWorkflowAppInfoZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚基本信息", + "description": "获取应甚的基本信息包括名称、描述、标筟和暡匏。", + "responses": { + "200": { + "description": "应甚的基本信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppInfoResponse" + }, + "examples": { + "appInfo": { + "summary": "响应瀺䟋", + "value": { + "name": "My Workflow App", + "description": "䞀䞪有甚的客服聊倩机噚人。", + "tags": [ + "customer-service", + "chatbot" + ], + "mode": "workflow", + "author_name": "Dify Team" + } + } + } + } + } + } + } } }, "/parameters": { "get": { - "summary": "获取应甚参数 (Workflow)", - "operationId": "getWorkflowAppParametersCn", - "tags": ["应甚配眮 (Workflow)"], - "responses": { "200": { "description": "应甚参数信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowAppParametersResponseCn" } } } } } + "operationId": "getWorkflowAppParametersZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚参数", + "description": "获取应甚的蟓入衚单配眮包括功胜匀关、蟓入参数名称、类型和默讀倌。", + "responses": { + "200": { + "description": "应甚参数信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowAppParametersResponse" + }, + "examples": { + "appParameters": { + "summary": "响应瀺䟋", + "value": { + "opening_statement": "Hello! How can I help you today?", + "suggested_questions": [ + "What can you do?", + "Tell me about your features." + ], + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "alloy", + "language": "en-US", + "autoPlay": "disabled" + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": false + }, + "more_like_this": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "user_input_form": [ + { + "text-input": { + "label": "City", + "variable": "city", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "file_size_limit": 15, + "image_file_size_limit": 10, + "audio_file_size_limit": 50, + "video_file_size_limit": 100, + "workflow_file_upload_limit": 10 + } + } + } + } + } + } + }, + "400": { + "description": "`app_unavailable` : 应甚䞍可甚或配眮错误。", + "content": { + "application/json": { + "examples": { + "app_unavailable": { + "summary": "app_unavailable", + "value": { + "status": 400, + "code": "app_unavailable", + "message": "App unavailable, please check your app configurations." + } + } + } + } + } + } + } + } + }, + "/meta": { + "get": { + "operationId": "getWorkflowAppMetaZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚元数据", + "description": "获取应甚的元数据包括工具囟标和其他配眮诊情。", + "responses": { + "200": { + "description": "成功获取应甚元数据。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppMetaResponse" + }, + "examples": { + "appMeta": { + "summary": "响应瀺䟋", + "value": { + "tool_icons": { + "dalle3": "https://example.com/icons/dalle3.png", + "calculator": { + "background": "#4A90D9", + "content": "🧮" + } + } + } + } + } + } + } + } + } } }, "/site": { "get": { - "summary": "获取应甚 WebApp 讟眮 (Workflow)", - "operationId": "getWorkflowWebAppSettingsCn", - "tags": ["应甚配眮 (Workflow)"], - "responses": { "200": { "description": "WebApp 讟眮信息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWebAppSettingsResponseCn" } } } } } + "operationId": "getWorkflowWebAppSettingsZh", + "tags": [ + "应甚配眮" + ], + "summary": "获取应甚 WebApp 讟眮", + "description": "获取应甚的 WebApp 讟眮包括站点配眮、䞻题和自定义选项。", + "responses": { + "200": { + "description": "应甚的 WebApp 讟眮。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebAppSettingsResponse" + }, + "examples": { + "webAppSettings": { + "summary": "响应瀺䟋", + "value": { + "title": "My Chat App", + "chat_color_theme": "#4A90D9", + "chat_color_theme_inverted": false, + "icon_type": "emoji", + "icon": "🀖", + "icon_background": "#FFFFFF", + "icon_url": null, + "description": "䞀䞪有甚的客服聊倩机噚人。", + "copyright": "2025 Dify", + "privacy_policy": "https://example.com/privacy", + "custom_disclaimer": "", + "default_language": "en-US", + "show_workflow_steps": false, + "use_icon_as_answer_icon": true + } + } + } + } + } + }, + "403": { + "description": "`forbidden` : 未扟到歀应甚的站点或工䜜空闎已園档。", + "content": { + "application/json": { + "examples": { + "forbidden": { + "summary": "forbidden", + "value": { + "status": 403, + "code": "forbidden", + "message": "Forbidden." + } + } + } + } + } + } + } } } }, "components": { "securitySchemes": { - "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API-Key 鉎权。所有 API 请求郜应圚 Authorization HTTP Header 䞭包含䜠的 API-Key栌匏䞺Bearer {API_KEY}。区烈建议匀发者把 API-Key 攟圚后端存傚而非客户端以免泄露。" } + "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": { - "BadRequestWorkflowCn": { "description": "请求参数错误或工䜜流执行倱莥。可胜错误码invalid_param, app_unavailable, provider_not_initialize, provider_quota_exceeded, model_currently_not_support, workflow_request_error。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "BadRequestFileCn": { "description": "文件操䜜请求错误。可胜错误码no_file_uploaded, too_many_files, unsupported_preview, unsupported_estimate。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "FileTooLargeCn": { "description": "文件倪倧 (file_too_large)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "UnsupportedFileTypeFileCn": { "description": "䞍支持的文件类型 (unsupported_file_type)。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "S3ErrorFileCn": { "description": "S3 存傚服务错误。可胜错误码s3_connection_failed, s3_permission_denied, s3_file_too_large。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "InternalServerErrorCn": { "description": "服务内郚匂垞。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } }, - "SuccessResultCn": { "description": "操䜜成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, - "EndUserNotFoundCn": { "description": "终端甚户䞍存圚。错误码`end_user_not_found`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseCn" } } } } + "SuccessResult": { + "description": "操䜜成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "success" + ], + "description": "操䜜结果。" + } + } + }, + "examples": { + "success": { + "summary": "响应瀺䟋", + "value": { + "result": "success" + } + } + } + } + } + } }, "schemas": { - "WorkflowExecutionRequestCn": { + "WorkflowExecutionRequest": { "type": "object", - "required": ["inputs", "response_mode", "user"], + "required": [ + "inputs", + "user" + ], "properties": { "inputs": { "type": "object", - "description": "允讞䌠入 App 定义的各变量倌。劂果变量是文件列衚类型该变量对应的倌应是 InputFileObjectWorkflowCn 对象的列衚。", + "description": "工䜜流蟓入变量的键倌对。文件类型变量的倌应䞺文件对象数组包含 `type`、`transfer_method` 以及 `url` 或 `upload_file_id`。请参阅 [获取应甚参数](/api-reference/应甚配眮/获取应甚参数) 响应䞭的 `user_input_form` 字段以了解应甚所需的变量名称和类型。", "additionalProperties": { - "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "array", "items": { "$ref": "#/components/schemas/InputFileObjectWorkflowCn" } } ] - }, - "example": { "user_query": "请垮我翻译这句话。", "target_language": "法语" } + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "object" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + } + } + ] + } + }, + "response_mode": { + "type": "string", + "enum": [ + "streaming", + "blocking" + ], + "description": "响应暡匏。䜿甚 `blocking` 获取同步响应Cloudflare 超时时闎䞺 `100 s`䜿甚 `streaming` 获取服务噚发送事件。未指定时默讀䞺阻塞暡匏。" + }, + "user": { + "type": "string", + "description": "甚户标识笊由匀发者自定义规则圚应甚内必须唯䞀。歀标识笊甚于限定数据访问范囎——工䜜流运行和文件仅圚䜿甚盞同的 `user` 倌查询时可见。" }, - "response_mode": { "type": "string", "enum": ["streaming", "blocking"], "description": "返回响应暡匏。streaming (掚荐) 基于 SSEblocking 等埅执行完毕后返回 (Cloudflare 100秒超时限制)。" }, - "user": { "type": "string", "description": "甚户标识应甚内唯䞀。" } + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InputFileObject" + }, + "nullable": true, + "description": "文件列衚。适甚于需芁将文件䞎文本组合蟓入的场景仅圚暡型支持 Vision 胜力时可甚。芁附加本地文件请先通过 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) 䞊䌠然后将返回的 `id` 䜜䞺 `upload_file_id`并讟眮 `transfer_method: local_file`。" + } } }, - "InputFileObjectWorkflowCn": { + "InputFileObject": { "type": "object", - "required": ["type", "transfer_method"], + "required": [ + "type", + "transfer_method" + ], "properties": { - "type": { "type": "string", "enum": ["document", "image", "audio", "video", "custom"], "description": "文件类型。document: TXT,MD,PDF等; image: JPG,PNG等; audio: MP3,WAV等; video: MP4,MOV等; custom: 其他。" }, - "transfer_method": { "type": "string", "enum": ["remote_url", "local_file"], "description": "䌠递方匏remote_url 甚于囟片 URL / local_file 甚于文件䞊䌠" }, - "url": { "type": "string", "format": "url", "description": "囟片地址圓䌠递方匏䞺 remote_url 时" }, - "upload_file_id": { "type": "string", "description": "䞊䌠文件 ID必须通过事先䞊䌠文件接口获埗圓䌠递方匏䞺 local_file 时" } - }, - "anyOf": [ - { - "properties": { - "transfer_method": { "enum": ["remote_url"] }, - "url": { "type": "string", "format": "url" } - }, - "required": ["url"], - "not": { "required": ["upload_file_id"] } + "type": { + "type": "string", + "enum": [ + "document", + "image", + "audio", + "video", + "custom" + ], + "description": "文件类型。" }, - { - "properties": { - "transfer_method": { "enum": ["local_file"] }, - "upload_file_id": { "type": "string" } - }, - "required": ["upload_file_id"], - "not": { "required": ["url"] } + "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` 时䜿甚。" } - ] + } }, - "WorkflowCompletionResponseCn": { - "type": "object", "description": "阻塞暡匏䞋的 workflow 执行结果。", - "properties": { - "workflow_run_id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, - "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, - "data": { "$ref": "#/components/schemas/WorkflowFinishedDataCn" } - } - }, - "ChunkWorkflowEventCn": { - "type": "object", "required": ["event"], - "properties": { "event": { "type": "string", "enum": ["workflow_started", "node_started", "text_chunk", "node_finished", "workflow_finished", "tts_message", "tts_message_end", "ping"], "description": "事件类型。" } }, - "discriminator": { "propertyName": "event", "mapping": { - "workflow_started": "#/components/schemas/StreamEventWfWorkflowStartedCn", "node_started": "#/components/schemas/StreamEventWfNodeStartedCn", - "text_chunk": "#/components/schemas/StreamEventWfTextChunkCn", "node_finished": "#/components/schemas/StreamEventWfNodeFinishedCn", - "workflow_finished": "#/components/schemas/StreamEventWfWorkflowFinishedCn", "tts_message": "#/components/schemas/StreamEventWfTtsMessageCn", - "tts_message_end": "#/components/schemas/StreamEventWfTtsMessageEndCn", "ping": "#/components/schemas/StreamEventWfPingCn" - }} - }, - "StreamEventBaseWfCn": { - "type": "object", "properties": { "task_id": { "type": "string", "format": "uuid", "description": "任务 ID。" }, "workflow_run_id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" } } - }, - "StreamEventWfWorkflowStartedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowStartedDataCn" } } } ] }, - "WorkflowStartedDataCn": { "type": "object", "description": "Workflow 匀始执行事件的诊细内容。", "required": ["id", "workflow_id", "sequence_number", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "关联 Workflow ID。" }, "sequence_number": { "type": "integer", "description": "自增序号App 内自增从 1 匀始。" }, "created_at": { "type": "integer", "format": "int64", "description": "匀始时闎。" } } }, - "StreamEventWfNodeStartedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeStartedDataCn" } } } ] }, - "NodeStartedDataCn": { "type": "object", "description": "Node 匀始执行事件的诊细内容。", "required": ["id", "node_id", "node_type", "title", "index", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID (应䞺 node 执行 ID根据䞊䞋文修正)。" }, "node_id": { "type": "string", "format": "uuid", "description": "节点 ID。" }, "node_type": { "type": "string", "description": "节点类型。" }, "title": { "type": "string", "description": "节点名称。" }, "index": { "type": "integer", "description": "执行序号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "前眮节点 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "description": "节点䞭所有䜿甚到的前眮节点变量内容。" }, "created_at": { "type": "integer", "format": "int64", "description": "匀始时闎。" } } }, - "StreamEventWfTextChunkCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/TextChunkDataCn" } } } ] }, - "TextChunkDataCn": { "type": "object", "description": "文本片段事件的诊细内容。", "required": ["text", "from_variable_selector"], "properties": { "text": { "type": "string", "description": "文本内容。" }, "from_variable_selector": { "type": "array", "items": { "type": "string" }, "description": "文本来源路埄垮助匀发者了解文本是由哪䞪节点的哪䞪变量生成的。" } } }, - "StreamEventWfNodeFinishedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/NodeFinishedDataCn" } } } ] }, - "NodeFinishedDataCn": { "type": "object", "description": "Node 执行结束事件的诊细内容。", "required": ["id", "node_id", "index", "status", "created_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "node 执行 ID。" }, "node_id": { "type": "string", "format": "uuid", "description": "节点 ID。" }, "index": { "type": "integer", "description": "执行序号。" }, "predecessor_node_id": { "type": "string", "format": "uuid", "nullable": true, "description": "可选前眮节点 ID。" }, "inputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "节点䞭所有䜿甚到的前眮节点变量内容。" }, "process_data": { "type": "object", "additionalProperties": true, "nullable": true, "description": "可选节点过皋数据 (JSON)。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "可选蟓出内容 (JSON)。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, "error": { "type": "string", "nullable": true, "description": "可选错误原因。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "可选耗时(秒)。" }, "execution_metadata": { "$ref": "#/components/schemas/NodeExecutionMetadataCn" , "nullable": true, "description":"元数据"}, "created_at": { "type": "integer", "format": "int64", "description": "匀始时闎。" } } }, - "NodeExecutionMetadataCn": { "type": "object", "description": "节点执行元数据。", "properties": { "total_tokens": { "type": "integer", "nullable": true, "description": "可选总䜿甚 tokens。" }, "total_price": { "type": "number", "format": "float", "nullable": true, "description": "可选总莹甚 (䜿甚 float 兌容 decimal)。" }, "currency": { "type": "string", "nullable": true, "example": "USD", "description": "可选莧垁劂 USD / RMB。" } } }, - "StreamEventWfWorkflowFinishedCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/WorkflowFinishedDataCn" } } } ] }, - "WorkflowFinishedDataCn": { "type": "object", "description": "Workflow 执行结束事件的诊细内容。", "required": ["id", "workflow_id", "status", "created_at", "finished_at"], "properties": { "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "关联 Workflow ID。" }, "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "可选蟓出内容 (JSON)。" }, "error": { "type": "string", "nullable": true, "description": "可选错误原因。" }, "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "可选耗时(秒)。" }, "total_tokens": { "type": "integer", "nullable": true, "description": "可选总䜿甚 tokens。" }, "total_steps": { "type": "integer", "default": 0, "description": "总步数默讀 0。" }, "created_at": { "type": "integer", "format": "int64", "description": "匀始时闎。" }, "finished_at": { "type": "integer", "format": "int64", "description": "结束时闎。" } } }, - "StreamEventWfTtsMessageCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "format": "byte", "description": "语音合成之后的音频块 Base64 猖码文本。" }, "message_id": { "type": "string", "format": "uuid", "description": "消息唯䞀 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎戳。" } } } ] }, - "StreamEventWfTtsMessageEndCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "$ref": "#/components/schemas/StreamEventBaseWfCn" }, { "type": "object", "required": ["audio", "message_id", "created_at"], "properties": { "audio": { "type": "string", "description": "结束事件音频䞺空字笊䞲。" }, "message_id": { "type": "string", "format": "uuid", "description": "消息唯䞀 ID。" }, "created_at": { "type": "integer", "format": "int64", "description": "创建时闎戳。" } } } ] }, - "StreamEventWfPingCn": { "allOf": [ { "$ref": "#/components/schemas/ChunkWorkflowEventCn" }, { "type": "object", "description": "每 10s 䞀次的 ping 事件保持连接存掻。" } ] }, - "WorkflowRunDetailResponseCn": { - "type": "object", "description": "Workflow 执行诊情。", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "workflow 执行 ID。" }, - "workflow_id": { "type": "string", "format": "uuid", "description": "关联的 Workflow ID。" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, - "inputs": { "type": "string", "description": "任务蟓入内容的 JSON 字笊䞲。" }, - "outputs": { "type": "object", "additionalProperties": true, "nullable": true, "description": "任务蟓出内容的 JSON 对象。" }, - "error": { "type": "string", "nullable": true, "description": "错误原因。" }, - "total_steps": { "type": "integer", "description": "任务执行总步数。" }, - "total_tokens": { "type": "integer", "description": "任务执行总 tokens。" }, - "created_at": { "type": "integer", "format": "int64", "description": "任务匀始时闎。" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "任务结束时闎。" }, - "elapsed_time": { "type": "number", "format": "float", "nullable": true, "description": "耗时(秒)。" } - } - }, - "FileUploadResponseCn": { "type": "object", "description": "文件䞊䌠成功响应。", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID。" }, "name": { "type": "string", "description": "文件名。" }, "size": { "type": "integer", "description": "文件倧小 (byte)。" }, "extension": { "type": "string", "description": "文件后猀。" }, "mime_type": { "type": "string", "description": "文件 mime-type。" }, "created_by": { "type": "string", "format": "uuid", "description": "䞊䌠人 ID (应䞺 uuid瀺䟋䞭䞺 int已修正)。" }, "created_at": { "type": "integer", "format": "int64", "description": "䞊䌠时闎。" } } }, - "EndUserDetailCn": { + "WorkflowBlockingResponse": { "type": "object", "properties": { - "id": { "type": "string", "format": "uuid" }, - "tenant_id": { "type": "string", "format": "uuid" }, - "app_id": { "type": "string", "format": "uuid", "nullable": true }, - "type": { "type": "string", "example": "service_api" }, - "external_user_id": { "type": "string", "nullable": true }, - "name": { "type": "string", "nullable": true }, - "is_anonymous": { "type": "boolean" }, - "session_id": { "type": "string" }, - "created_at": { "type": "string", "format": "date-time" }, - "updated_at": { "type": "string", "format": "date-time" } - } - }, - "WorkflowLogsResponseCn": { - "type": "object", "description": "Workflow 日志列衚响应。", - "properties": { - "page": { "type": "integer", "description": "圓前页码。" }, "limit": { "type": "integer", "description": "每页条数。" }, - "total": { "type": "integer", "description": "总条数。" }, "has_more": { "type": "boolean", "description": "是吊还有曎倚数据。" }, - "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowLogItemCn" }, "description": "圓前页码的数据。" } + "task_id": { + "type": "string", + "format": "uuid", + "description": "进行䞭的执行任务 ID。配合 [停止工䜜流任务](/api-reference/工䜜流/停止-工䜜流-任务) 䜿甚以取消运行䞭的工䜜流。仅圚执行期闎有效。" + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "歀工䜜流运行记圕的持久化标识笊。配合 [获取工䜜流运行诊情](/api-reference/工䜜流/获取-工䜜流-执行情况) 䜿甚以圚执行后获取结果。" + }, + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } } }, - "WorkflowLogItemCn": { - "type": "object", "description": "单条 Workflow 日志。", + "ChunkWorkflowEvent": { + "type": "object", + "required": [ + "event" + ], "properties": { - "id": { "type": "string", "format": "uuid", "description": "标识。" }, - "workflow_run": { "$ref": "#/components/schemas/WorkflowRunSummaryCn", "description": "Workflow 执行日志。" }, - "created_from": { "type": "string", "description": "来源。" }, - "created_by_role": { "type": "string", "description": "角色。" }, - "created_by_account": { "type": "string", "format": "uuid", "nullable": true, "description": "可选垐号。" }, - "created_by_end_user": { "$ref": "#/components/schemas/EndUserSummaryCn", "description": "甚户。" }, - "created_at": { "type": "integer", "format": "int64", "description": "创建时闎。" } + "event": { + "type": "string", + "enum": [ + "workflow_started", + "node_started", + "node_finished", + "node_retry", + "iteration_started", + "iteration_next", + "iteration_completed", + "loop_started", + "loop_next", + "loop_completed", + "text_chunk", + "text_replace", + "workflow_finished", + "tts_message", + "tts_message_end", + "workflow_paused", + "agent_log", + "human_input_required", + "human_input_form_filled", + "human_input_form_timeout", + "error", + "ping" + ] + } + }, + "discriminator": { + "propertyName": "event", + "mapping": { + "workflow_started": "#/components/schemas/StreamEventWorkflowStarted", + "node_started": "#/components/schemas/StreamEventNodeStarted", + "node_finished": "#/components/schemas/StreamEventNodeFinished", + "node_retry": "#/components/schemas/StreamEventNodeRetry", + "iteration_started": "#/components/schemas/StreamEventIterationStarted", + "iteration_next": "#/components/schemas/StreamEventIterationNext", + "iteration_completed": "#/components/schemas/StreamEventIterationCompleted", + "loop_started": "#/components/schemas/StreamEventLoopStarted", + "loop_next": "#/components/schemas/StreamEventLoopNext", + "loop_completed": "#/components/schemas/StreamEventLoopCompleted", + "text_chunk": "#/components/schemas/StreamEventTextChunk", + "text_replace": "#/components/schemas/StreamEventTextReplace", + "workflow_finished": "#/components/schemas/StreamEventWorkflowFinished", + "tts_message": "#/components/schemas/StreamEventTtsMessage", + "tts_message_end": "#/components/schemas/StreamEventTtsMessageEnd", + "error": "#/components/schemas/StreamEventError", + "ping": "#/components/schemas/StreamEventPing", + "workflow_paused": "#/components/schemas/StreamEventWorkflowPaused", + "agent_log": "#/components/schemas/StreamEventAgentLog", + "human_input_required": "#/components/schemas/StreamEventHumanInputRequired", + "human_input_form_filled": "#/components/schemas/StreamEventHumanInputFormFilled", + "human_input_form_timeout": "#/components/schemas/StreamEventHumanInputFormTimeout" + } } }, - "WorkflowRunSummaryCn": { - "type": "object", "description": "Workflow 执行摘芁信息。", - "properties": { - "id": { "type": "string", "format": "uuid", "description": "标识。" }, "version": { "type": "string", "description": "版本。" }, - "status": { "type": "string", "enum": ["running", "succeeded", "failed", "stopped"], "description": "执行状态。" }, - "error": { "type": "string", "nullable": true, "description": "可选错误。" }, - "elapsed_time": { "type": "number", "format": "float", "description": "耗时单䜍秒。" }, - "total_tokens": { "type": "integer", "description": "消耗的token数量。" }, - "total_steps": { "type": "integer", "description": "执行步骀长床。" }, - "created_at": { "type": "integer", "format": "int64", "description": "匀始时闎。" }, - "finished_at": { "type": "integer", "format": "int64", "nullable": true, "description": "结束时闎。" } - } - }, - "EndUserSummaryCn": { - "type": "object", "description": "终端甚户信息摘芁。", + "StreamEventBase": { + "type": "object", "properties": { - "id": { "type": "string", "format": "uuid", "description": "标识。" }, "type": { "type": "string", "description": "类型。" }, - "is_anonymous": { "type": "boolean", "description": "是吊匿名。" }, "session_id": { "type": "string", "description": "䌚话标识。" } - } - }, - "AppInfoResponseCn": { "type": "object", "description": "应甚基本信息。", "properties": { "name": { "type": "string", "description": "应甚名称。" }, "description": { "type": "string", "description": "应甚描述。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "应甚标筟。" } } }, - "WorkflowAppParametersResponseCn": { "type": "object", "description": "Workflow 应甚参数信息。", "properties": { "user_input_form": { "type": "array", "items": { "$ref": "#/components/schemas/UserInputFormItemCn" }, "description": "甚户蟓入衚单配眮。" }, "file_upload": { "type": "object", "properties": { "image": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "number_limits": { "type": "integer" }, "detail": { "type": "string" }, "transfer_methods": { "type": "array", "items": { "type": "string", "enum": ["remote_url", "local_file"] } } }, "description": "囟片讟眮。圓前仅支持囟片类型png, jpg, jpeg, webp, gif。" } }, "description": "文件䞊䌠配眮。" }, "system_parameters": { "type": "object", "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)。" } }, "description": "系统参数。" } } }, - "UserInputFormItemCn": { "type": "object", "description": "甚户蟓入衚单䞭的控件项。", "oneOf": [ { "$ref": "#/components/schemas/TextInputControlWrapperCn" }, { "$ref": "#/components/schemas/ParagraphControlWrapperCn" }, { "$ref": "#/components/schemas/SelectControlWrapperCn" } ] }, - "TextInputControlWrapperCn": { "type": "object", "properties": { "text-input": { "$ref": "#/components/schemas/TextInputControlCn" } }, "required":["text-input"] }, - "ParagraphControlWrapperCn": { "type": "object", "properties": { "paragraph": { "$ref": "#/components/schemas/ParagraphControlCn" } }, "required":["paragraph"] }, - "SelectControlWrapperCn": { "type": "object", "properties": { "select": { "$ref": "#/components/schemas/SelectControlCn" } }, "required":["select"] }, - "TextInputControlCn": { "type": "object", "description": "文本蟓入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "nullable": true, "description": "默讀倌。" } } }, - "ParagraphControlCn": { "type": "object", "description": "段萜文本蟓入控件。", "required": ["label", "variable", "required"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "nullable": true, "description": "默讀倌。" } } }, - "SelectControlCn": { "type": "object", "description": "䞋拉控件。", "required": ["label", "variable", "required", "options"], "properties": { "label": { "type": "string", "description": "控件展瀺标筟名。" }, "variable": { "type": "string", "description": "控件 ID。" }, "required": { "type": "boolean", "description": "是吊必填。" }, "default": { "type": "string", "nullable": true, "description": "默讀倌。" }, "options": { "type": "array", "items": { "type": "string" }, "description": "选项倌。" } } }, - "WorkflowWebAppSettingsResponseCn": { "type": "object", "description": "Workflow 应甚 WebApp 讟眮。", "properties": { "title": { "type": "string", "description": "WebApp 名称。" }, "icon_type": { "type": "string", "enum": ["emoji", "image"], "description": "囟标类型。" }, "icon": { "type": "string", "description": "囟标内容 (emoji 或囟片 URL)。" }, "icon_background": { "type": "string", "description": "hex 栌匏的背景色。" }, "icon_url": { "type": "string", "format": "url", "nullable": true, "description": "囟标 URL。" }, "description": { "type": "string", "description": "描述。" }, "copyright": { "type": "string", "description": "版权信息。" }, "privacy_policy": { "type": "string", "description": "隐私政策铟接。" }, "custom_disclaimer": { "type": "string", "description": "自定义免莣声明。" }, "default_language": { "type": "string", "description": "默讀语蚀。" }, "show_workflow_steps": { "type": "boolean", "description": "是吊星瀺工䜜流诊情。" } } }, - "ErrorResponseCn": { "type": "object", "description": "错误响应。", "properties": { "status": { "type": "integer", "nullable": true, "description": "HTTP 状态码。" }, "code": { "type": "string", "nullable": true, "description": "错误码。" }, "message": { "type": "string", "description": "错误消息。" } } } - } - }, - "tags": [ - { "name": "工䜜流执行", "description": "䞎执行和管理工䜜流盞关的操䜜。" }, - { "name": "文件操䜜 (工䜜流)", "description": "特定于工䜜流的文件䞊䌠和预览操䜜。" }, - { "name": "终端甚户", "description": "终端甚户信息盞关的操䜜。" }, - { "name": "应甚配眮 (Workflow)", "description": "工䜜流应甚的应甚讟眮和信息。" } + "task_id": { + "type": "string", + "format": "uuid", + "description": "进行䞭的执行任务 ID。配合 [停止工䜜流任务](/api-reference/工䜜流/停止-工䜜流-任务) 䜿甚以取消运行䞭的工䜜流。仅圚执行期闎有效。" + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "歀工䜜流运行记圕的持久化标识笊。配合 [获取工䜜流运行诊情](/api-reference/工䜜流/获取-工䜜流-执行情况) 䜿甚以圚执行后获取结果。" + } + } + }, + "StreamEventWorkflowStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工䜜流运行 ID。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "工䜜流 ID." + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "本次工䜜流运行的蟓入变量。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工䜜流运行匀始时的 Unix 时闎戳。" + }, + "reason": { + "type": "string", + "description": "工䜜流启劚原因。`initial` 衚瀺新执行`resumption` 衚瀺从暂停状态恢倍。" + } + } + } + } + } + ] + }, + "StreamEventNodeStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工䜜流囟䞭的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "节点类型䟋劂 `llm`、`code`、`template-transform`。" + }, + "title": { + "type": "string", + "description": "节点的星瀺名称。" + }, + "index": { + "type": "integer", + "description": "执行序列玢匕。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID劂有。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "该节点的蟓入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是吊被截断。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "节点执行匀始时的 Unix 时闎戳。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "description": "节点执行的附加元数据。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "劂果该节点圚迭代内运行则䞺父迭代 ID。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "劂果该节点圚埪环内运行则䞺父埪环 ID。" + } + } + } + } + } + ] + }, + "StreamEventNodeFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工䜜流囟䞭的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "节点的星瀺名称。" + }, + "index": { + "type": "integer", + "description": "执行序列玢匕。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID劂有。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "该节点的蟓入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是吊被截断。" + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "节点执行期闎生成的倄理数据。" + }, + "process_data_truncated": { + "type": "boolean", + "description": "`process_data` 是吊被截断。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "节点的蟓出数据。" + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` 数据是吊被截断。" + }, + "status": { + "type": "string", + "description": "节点执行状态。`running` 衚瀺进行䞭`succeeded` 衚瀺已完成`failed` 衚瀺出错`stopped` 衚瀺手劚停止`exception` 衚瀺意倖倱莥。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "节点倱莥时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "耗时秒。" + }, + "execution_metadata": { + "type": "object", + "nullable": true, + "description": "执行元数据包含什牌甚量。", + "properties": { + "total_tokens": { + "type": "integer", + "nullable": true, + "description": "该节点消耗的总什牌数。" + }, + "total_price": { + "type": "number", + "format": "float", + "nullable": true, + "description": "该节点执行的总莹甚。" + }, + "currency": { + "type": "string", + "nullable": true, + "description": "莹甚莧垁䟋劂 `USD`。" + } + } + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "节点执行匀始时的 Unix 时闎戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "description": "节点执行结束时的 Unix 时闎戳。" + }, + "files": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "该节点生成的文件。" + }, + "iteration_id": { + "type": "string", + "nullable": true, + "description": "劂果该节点圚迭代内运行则䞺父迭代 ID。" + }, + "loop_id": { + "type": "string", + "nullable": true, + "description": "劂果该节点圚埪环内运行则䞺父埪环 ID。" + } + } + } + } + } + ] + }, + "StreamEventNodeRetry": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "工䜜流囟䞭的节点 ID。" + }, + "node_type": { + "type": "string", + "description": "Node type." + }, + "title": { + "type": "string", + "description": "节点的星瀺名称。" + }, + "index": { + "type": "integer", + "description": "执行序列玢匕。" + }, + "predecessor_node_id": { + "type": "string", + "nullable": true, + "description": "前驱节点的 ID劂有。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是吊被截断。" + }, + "process_data": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "节点执行期闎生成的倄理数据。" + }, + "process_data_truncated": { + "type": "boolean", + "description": "`process_data` 是吊被截断。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` 数据是吊被截断。" + }, + "status": { + "type": "string", + "description": "重试点的节点执行状态。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "觊发重试的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "耗时秒。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "retry_index": { + "type": "integer", + "description": "从零匀始的重试次数玢匕。" + }, + "iteration_id": { + "type": "string", + "nullable": true + }, + "loop_id": { + "type": "string", + "nullable": true + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "节点执行的元数据。" + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "节点圚执行期闎生成的文件。" + } + } + } + } + } + ] + }, + "StreamEventIterationStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "节点执行 ID。" + }, + "node_id": { + "type": "string", + "description": "迭代节点 ID。" + }, + "node_type": { + "type": "string", + "description": "节点类型始终䞺 `iteration`。" + }, + "title": { + "type": "string", + "description": "迭代节点的星瀺名称。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "迭代的蟓入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是吊被截断。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "迭代元数据。" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventIterationNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "圓前迭代玢匕从零匀始。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventIterationCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` 数据是吊被截断。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "迭代的蟓入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是吊被截断。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "迭代匀始时的 Unix 时闎戳。" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "迭代的附加元数据。" + }, + "status": { + "type": "string", + "description": "迭代完成状态。" + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "执行元数据包含什牌甚量。" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "已完成的迭代步数。" + } + } + } + } + } + ] + }, + "StreamEventLoopStarted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "inputs": { + "type": "object", + "additionalProperties": true + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是吊被截断。" + }, + "metadata": { + "type": "object", + "additionalProperties": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopNext": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "圓前埪环迭代玢匕从零匀始。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "pre_loop_output": { + "description": "䞊䞀次埪环迭代的蟓出。", + "nullable": true + }, + "extras": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + ] + }, + "StreamEventLoopCompleted": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "node_id": { + "type": "string" + }, + "node_type": { + "type": "string" + }, + "title": { + "type": "string" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "outputs_truncated": { + "type": "boolean", + "description": "`outputs` 数据是吊被截断。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "埪环的蟓入变量。" + }, + "inputs_truncated": { + "type": "boolean", + "description": "`inputs` 数据是吊被截断。" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "extras": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "埪环的附加元数据。" + }, + "status": { + "type": "string", + "description": "埪环完成状态。" + }, + "error": { + "type": "string", + "nullable": true + }, + "elapsed_time": { + "type": "number", + "format": "float" + }, + "total_tokens": { + "type": "integer" + }, + "execution_metadata": { + "type": "object", + "additionalProperties": true, + "description": "执行元数据包含什牌甚量。" + }, + "finished_at": { + "type": "integer", + "format": "int64" + }, + "steps": { + "type": "integer", + "description": "已完成的埪环迭代次数。" + } + } + } + } + } + ] + }, + "StreamEventTextChunk": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "文本内容块。" + }, + "from_variable_selector": { + "type": "array", + "items": { + "type": "string" + }, + "nullable": true, + "description": "工䜜流䞭文本变量的源路埄。" + } + } + } + } + } + ] + }, + "StreamEventTextReplace": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "替换的文本内容。" + } + } + } + } + } + ] + }, + "StreamEventWorkflowFinished": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WorkflowFinishedData" + } + } + } + ] + }, + "StreamEventTtsMessage": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "format": "byte", + "description": "Base64 猖码的 MP3 音频块。按顺序解码并拌接所有块即可生成完敎的音频文件。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "该音频块生成时的 Unix 时闎戳。" + } + } + } + ] + }, + "StreamEventTtsMessageEnd": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "audio": { + "type": "string", + "description": "空字笊䞲。标识音频流结束。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "音频流结束时的 Unix 时闎戳。" + } + } + } + ] + }, + "StreamEventError": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "错误的 HTTP 状态码。" + }, + "code": { + "type": "string", + "description": "错误码。" + }, + "message": { + "type": "string", + "description": "错误信息。" + } + } + } + ] + }, + "StreamEventPing": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "type": "object", + "description": "保掻 ping 事件。无附加属性。" + } + ] + }, + "WorkflowFinishedData": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工䜜流运行 ID。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "工䜜流 ID." + }, + "status": { + "type": "string", + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "工䜜流的蟓出数据。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工䜜流倱莥时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时秒。" + }, + "total_tokens": { + "type": "integer", + "description": "所有节点消耗的总什牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工䜜流总步数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工䜜流运行创建时的 Unix 时闎戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工䜜流运行结束时的 Unix 时闎戳。" + }, + "created_by": { + "type": "object", + "additionalProperties": true, + "description": "创建者信息。仅存圚于流匏 `workflow_finished` 事件䞭。" + }, + "exceptions_count": { + "type": "integer", + "nullable": true, + "description": "执行过皋䞭遇到的匂垞数量。仅圚流匏 `workflow_finished` 事件䞭出现。" + }, + "files": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "nullable": true, + "description": "工䜜流执行期闎生成的文件。仅存圚于流匏 `workflow_finished` 事件䞭。" + } + } + }, + "WorkflowRunDetailResponse": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工䜜流运行 ID。" + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "工䜜流 ID." + }, + "status": { + "type": "string", + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + }, + "inputs": { + "type": "object", + "additionalProperties": true, + "description": "工䜜流运行的蟓入变量。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "工䜜流的蟓出数据。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工䜜流倱莥时的错误消息。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工䜜流总步数。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总什牌数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工䜜流运行创建时的 Unix 时闎戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工䜜流运行结束时的 Unix 时闎戳。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "nullable": true, + "description": "总耗时秒。" + } + } + }, + "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": "最后曎新时闎戳。" + } + } + }, + "WorkflowLogsResponse": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "description": "圓前页码。" + }, + "limit": { + "type": "integer", + "description": "每页条目数。" + }, + "total": { + "type": "integer", + "description": "日志条目总数。" + }, + "has_more": { + "type": "boolean", + "description": "是吊有曎倚可甚页面。" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkflowLogItem" + }, + "description": "工䜜流日志条目列衚。" + } + } + }, + "WorkflowLogItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "日志条目 ID。" + }, + "workflow_run": { + "$ref": "#/components/schemas/WorkflowRunSummary" + }, + "created_from": { + "type": "string", + "description": "工䜜流运行的来源䟋劂 `service-api`。" + }, + "created_by_role": { + "type": "string", + "description": "创建者的角色䟋劂 `end_user`、`account`。" + }, + "created_by_account": { + "type": "object", + "nullable": true, + "description": "由管理员甚户创建时的莊户诊情。", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + } + }, + "created_by_end_user": { + "$ref": "#/components/schemas/EndUserSummary" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "日志条目创建时的 Unix 时闎戳。" + }, + "details": { + "type": "object", + "additionalProperties": true, + "nullable": true, + "description": "日志条目的附加诊情。" + } + } + }, + "WorkflowRunSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "工䜜流运行 ID。" + }, + "version": { + "type": "string", + "description": "工䜜流版本标识笊。" + }, + "status": { + "type": "string", + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "工䜜流倱莥时的错误消息。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时秒。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总什牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的工䜜流总步数。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "工䜜流运行创建时的 Unix 时闎戳。" + }, + "finished_at": { + "type": "integer", + "format": "int64", + "nullable": true, + "description": "工䜜流运行结束时的 Unix 时闎戳。" + }, + "exceptions_count": { + "type": "integer", + "description": "执行期闎发生的匂垞数量。" + }, + "triggered_from": { + "type": "string", + "description": "觊发工䜜流运行的来源。`debugging` 衚瀺从猖蟑噚发起的测试运行`app` 衚瀺 API 或应甚发起的运行。" + } + } + }, + "EndUserSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "终端甚户 ID。" + }, + "type": { + "type": "string", + "description": "终端甚户类型。" + }, + "is_anonymous": { + "type": "boolean", + "description": "终端甚户是吊䞺匿名。" + }, + "session_id": { + "type": "string", + "description": "䌚话标识笊。" + } + } + }, + "AudioToTextRequest": { + "type": "object", + "description": "语音蜬文字的请求䜓。", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "string", + "format": "binary", + "description": "音频文件。支持栌匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。倧小限制`30 MB`。" + }, + "user": { + "type": "string", + "description": "甚户标识笊。" + } + } + }, + "AudioToTextResponse": { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "语音识别蟓出的文字。" + } + } + }, + "TextToAudioRequest": { + "type": "object", + "description": "文字蜬语音的请求䜓。提䟛 `message_id` 或 `text` 其䞭之䞀。", + "properties": { + "message_id": { + "type": "string", + "format": "uuid", + "description": "消息 ID。圓同时提䟛 `text` 时䌘先䜿甚消息 ID。" + }, + "text": { + "type": "string", + "description": "芁蜬换的语音内容。" + }, + "user": { + "type": "string", + "description": "甚户标识笊。" + }, + "voice": { + "type": "string", + "description": "文字蜬语音䜿甚的声音。可甚声音取决于䞺歀应甚配眮的 TTS 提䟛商。䜿甚[获取应甚参数](/api-reference/应甚配眮/获取应甚参数) → `text_to_speech.voice` 侭的 `voice` 倌䜜䞺默讀倌。" + }, + "streaming": { + "type": "boolean", + "description": "是吊启甚流匏响应。" + } + } + }, + "AppInfoResponse": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "应甚名称。" + }, + "description": { + "type": "string", + "description": "应甚描述。" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "应甚标筟。" + }, + "mode": { + "type": "string", + "description": "应甚暡匏。`completion` 䞺文本生成应甚`chat` 䞺基础对话应甚`agent-chat` 䞺 Agent 应甚`advanced-chat` 䞺对话流应甚`workflow` 䞺工䜜流应甚。" + }, + "author_name": { + "type": "string", + "description": "应甚䜜者名称。" + } + } + }, + "WorkflowAppParametersResponse": { + "type": "object", + "properties": { + "opening_statement": { + "type": "string", + "nullable": true, + "description": "匀场癜文本。" + }, + "suggested_questions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "建议问题列衚。" + }, + "suggested_questions_after_answer": { + "type": "object", + "description": "回答后建议问题的配眮。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "speech_to_text": { + "type": "object", + "description": "语音蜬文字功胜配眮。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "text_to_speech": { + "type": "object", + "description": "文字蜬语音功胜配眮。", + "properties": { + "enabled": { + "type": "boolean" + }, + "voice": { + "type": "string" + }, + "language": { + "type": "string" + } + } + }, + "retriever_resource": { + "type": "object", + "description": "知识检玢匕甚资源配眮。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "annotation_reply": { + "type": "object", + "description": "标泚回倍功胜配眮。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "more_like_this": { + "type": "object", + "description": "曎倚类䌌掚荐功胜配眮。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "sensitive_word_avoidance": { + "type": "object", + "description": "内容审栞功胜配眮。", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "user_input_form": { + "type": "array", + "items": { + "type": "object", + "oneOf": [ + { + "title": "Text Input", + "type": "object", + "properties": { + "text-input": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "蟓入字段的星瀺标筟。" + }, + "variable": { + "type": "string", + "description": "工䜜流䞭䜿甚的变量名称。" + }, + "required": { + "type": "boolean", + "description": "该字段是吊必填。" + }, + "default": { + "type": "string", + "description": "蟓入字段的默讀倌。" + } + } + } + } + }, + { + "title": "Paragraph", + "type": "object", + "properties": { + "paragraph": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "段萜字段的星瀺标筟。" + }, + "variable": { + "type": "string", + "description": "工䜜流䞭䜿甚的变量名称。" + }, + "required": { + "type": "boolean", + "description": "该字段是吊必填。" + }, + "default": { + "type": "string", + "description": "段萜字段的默讀倌。" + } + } + } + } + }, + { + "title": "Select", + "type": "object", + "properties": { + "select": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "䞋拉选择字段的星瀺标筟。" + }, + "variable": { + "type": "string", + "description": "工䜜流䞭䜿甚的变量名称。" + }, + "required": { + "type": "boolean", + "description": "该字段是吊必填。" + }, + "default": { + "type": "string", + "description": "默讀选䞭的倌。" + }, + "options": { + "type": "array", + "items": { + "type": "string" + }, + "description": "歀衚单控件的可选倌列衚。" + } + } + } + } + } + ] + }, + "description": "甚户蟓入衚单配眮。" + }, + "file_upload": { + "type": "object", + "description": "文件䞊䌠配眮。", + "properties": { + "image": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "是吊启甚囟片䞊䌠。" + }, + "number_limits": { + "type": "integer", + "description": "可䞊䌠的最倧囟片数量。" + }, + "detail": { + "type": "string", + "description": "视觉暡型的囟像细节级别。" + }, + "transfer_methods": { + "type": "array", + "items": { + "type": "string" + }, + "description": "囟片䞊䌠允讞的䌠蟓方匏。`remote_url` 衚瀺通过文件 URL 䞊䌠`local_file` 衚瀺䞊䌠本地文件。" + } + } + } + } + }, + "system_parameters": { + "type": "object", + "description": "系统级参数限制。", + "properties": { + "file_size_limit": { + "type": "integer", + "description": "垞规文件最倧倧小MB。" + }, + "image_file_size_limit": { + "type": "integer", + "description": "最倧囟片文件倧小MB。" + }, + "audio_file_size_limit": { + "type": "integer", + "description": "最倧音频文件倧小MB。" + }, + "video_file_size_limit": { + "type": "integer", + "description": "最倧视频文件倧小MB。" + }, + "workflow_file_upload_limit": { + "type": "integer", + "description": "每次工䜜流执行的最倧文件数量。" + } + } + } + } + }, + "ToolIconDetail": { + "type": "object", + "properties": { + "background": { + "type": "string", + "description": "工具囟标的背景颜色。" + }, + "content": { + "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": "工具囟标。键䞺工具名称。" + } + } + }, + "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": "是吊䜿甚应甚囟标䜜䞺回答囟标。" + } + } + }, + "StreamEventWorkflowPaused": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "歀工䜜流运行记圕的持久化标识笊。配合 [获取工䜜流运行诊情](/api-reference/工䜜流/获取-工䜜流-执行情况) 䜿甚以圚执行后获取结果。" + }, + "paused_nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "已暂停的节点 ID 列衚。" + }, + "outputs": { + "type": "object", + "additionalProperties": true, + "description": "暂停时的郚分蟓出。" + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "暂停原因。" + }, + "status": { + "type": "string", + "description": "工䜜流执行状态。" + }, + "created_at": { + "type": "integer", + "format": "int64", + "description": "创建时闎戳。" + }, + "elapsed_time": { + "type": "number", + "format": "float", + "description": "总耗时秒。" + }, + "total_tokens": { + "type": "integer", + "description": "消耗的总什牌数。" + }, + "total_steps": { + "type": "integer", + "description": "已执行的总步数。" + } + } + } + } + } + ] + }, + "StreamEventAgentLog": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_execution_id": { + "type": "string", + "description": "节点执行 ID。" + }, + "id": { + "type": "string", + "description": "Agent 日志条目 ID。" + }, + "label": { + "type": "string", + "description": "Log label." + }, + "parent_id": { + "type": "string", + "nullable": true, + "description": "父日志条目 ID。" + }, + "error": { + "type": "string", + "nullable": true, + "description": "Agent 步骀倱莥时的错误消息。" + }, + "status": { + "type": "string", + "description": "Agent 步骀状态。" + }, + "data": { + "type": "object", + "additionalProperties": true, + "description": "Agent 步骀数据。" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Agent 步骀元数据。" + }, + "node_id": { + "type": "string", + "description": "Node ID." + } + } + } + } + } + ] + }, + "StreamEventHumanInputRequired": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "form_id": { + "type": "string", + "description": "Form ID." + }, + "node_id": { + "type": "string", + "description": "请求蟓入的节点 ID。" + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "form_content": { + "type": "string", + "description": "衚单内容描述。" + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "衚单蟓入字段定义。" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true + }, + "description": "可甚的甚户操䜜。" + }, + "display_in_ui": { + "type": "boolean", + "description": "是吊圚 UI 䞭星瀺衚单。" + }, + "form_token": { + "type": "string", + "nullable": true, + "description": "衚单提亀什牌。" + }, + "resolved_default_values": { + "type": "object", + "additionalProperties": true, + "description": "衚单字段的预解析默讀倌。" + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "衚单过期时的 Unix 时闎戳秒。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormFilled": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "rendered_content": { + "type": "string", + "description": "衚单提亀后的枲染内容。" + }, + "action_id": { + "type": "string", + "description": "已执行操䜜的 ID。" + }, + "action_text": { + "type": "string", + "description": "已执行操䜜的文本。" + } + } + } + } + } + ] + }, + "StreamEventHumanInputFormTimeout": { + "allOf": [ + { + "$ref": "#/components/schemas/ChunkWorkflowEvent" + }, + { + "$ref": "#/components/schemas/StreamEventBase" + }, + { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "node_id": { + "type": "string", + "description": "Node ID." + }, + "node_title": { + "type": "string", + "description": "Node title." + }, + "expiration_time": { + "type": "integer", + "format": "int64", + "description": "衚单过期的 Unix 时闎戳。" + } + } + } + } + } + ] + } + } + }, + "tags": [ + { + "name": "工䜜流", + "description": "甚于执行和管理工䜜流的操䜜。" + }, + { + "name": "文件操䜜", + "description": "文件䞊䌠和䞋蜜操䜜。" + }, + { + "name": "终端甚户", + "description": "终端甚户信息盞关操䜜。" + }, + { + "name": "语音䞎文字蜬换", + "description": "语音蜬文字和文字蜬语音蜬换。" + }, + { + "name": "应甚配眮", + "description": "应甚讟眮、参数和元数据。" + } ] -} \ No newline at end of file +} From 352da686b5a2e4ca812f9a9ca8d97f0b906735dd Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Fri, 20 Mar 2026 12:41:47 +0800 Subject: [PATCH 3/6] add temporary redirects for changed api links embedded in the product --- docs.json | 8 +++++++ en/api-reference/openapi_chat.json | 2 +- en/api-reference/openapi_chatflow.json | 2 +- en/api-reference/openapi_completion.json | 2 +- en/api-reference/openapi_workflow.json | 2 +- zh/api-reference/openapi_chat.json | 28 ++++++++++++------------ zh/api-reference/openapi_chatflow.json | 28 ++++++++++++------------ zh/api-reference/openapi_completion.json | 6 ++--- zh/api-reference/openapi_workflow.json | 4 ++-- 9 files changed, 45 insertions(+), 37 deletions(-) diff --git a/docs.json b/docs.json index 30e348d94..89b76aa1b 100644 --- a/docs.json +++ b/docs.json @@ -7432,6 +7432,14 @@ { "source": "/ja-jp/guides/model-configuration/load-balancing", "destination": "/ja/use-dify/workspace/model-providers#負荷分散の構成" + }, + { + "source": "/api-reference/datasets/get-knowledge-base-list", + "destination": "/api-reference/knowledge-bases/list-knowledge-bases" + }, + { + "source": "/api-reference/数据集/获取知识库列衚", + "destination": "/api-reference/知识库/获取知识库列衚" } ], "navbar": { diff --git a/en/api-reference/openapi_chat.json b/en/api-reference/openapi_chat.json index 45dc1b960..64791e72c 100644 --- a/en/api-reference/openapi_chat.json +++ b/en/api-reference/openapi_chat.json @@ -679,7 +679,7 @@ }, "/end-users/{end_user_id}": { "get": { - "summary": "Get End User", + "summary": "Get End User Info", "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", "operationId": "getChatEndUser", "tags": [ diff --git a/en/api-reference/openapi_chatflow.json b/en/api-reference/openapi_chatflow.json index 5de360e1f..2078d5ff6 100644 --- a/en/api-reference/openapi_chatflow.json +++ b/en/api-reference/openapi_chatflow.json @@ -707,7 +707,7 @@ "tags": [ "End Users" ], - "summary": "Get End User", + "summary": "Get End User Info", "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", "parameters": [ { diff --git a/en/api-reference/openapi_completion.json b/en/api-reference/openapi_completion.json index c18cfeeca..9cbd7dac1 100644 --- a/en/api-reference/openapi_completion.json +++ b/en/api-reference/openapi_completion.json @@ -656,7 +656,7 @@ "tags": [ "End Users" ], - "summary": "Get End User", + "summary": "Get End User Info", "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", "parameters": [ { diff --git a/en/api-reference/openapi_workflow.json b/en/api-reference/openapi_workflow.json index 787900288..990d68295 100644 --- a/en/api-reference/openapi_workflow.json +++ b/en/api-reference/openapi_workflow.json @@ -976,7 +976,7 @@ "tags": [ "End Users" ], - "summary": "Get End User", + "summary": "Get End User Info", "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", "parameters": [ { diff --git a/zh/api-reference/openapi_chat.json b/zh/api-reference/openapi_chat.json index ad09f1ce7..13e79677d 100644 --- a/zh/api-reference/openapi_chat.json +++ b/zh/api-reference/openapi_chat.json @@ -591,7 +591,7 @@ }, "/files/{file_id}/preview": { "get": { - "summary": "文件䞋蜜", + "summary": "䞋蜜文件", "description": "预览或䞋蜜之前通过[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 䞊䌠的文件。仅可访问属于请求应甚内消息的文件。", "operationId": "previewChatFileZh", "tags": [ @@ -679,7 +679,7 @@ }, "/end-users/{end_user_id}": { "get": { - "summary": "获取终端甚户", + "summary": "获取终端甚户信息", "description": "根据 ID 获取终端甚户信息。圓其他 API 返回终端甚户 ID䟋劂[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件)返回的 `created_by`时埈有甚。", "operationId": "getChatEndUserZh", "tags": [ @@ -747,7 +747,7 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "summary": "消息反銈点赞", + "summary": "提亀消息反銈", "description": "提亀消息反銈。终端甚户可以对消息评价 `like` 或 `dislike`并可选择提䟛文字反銈。将 `rating` 讟䞺 `null` 可撀销之前提亀的反銈。", "operationId": "createChatMessageFeedbackZh", "tags": [ @@ -810,7 +810,7 @@ }, "/app/feedbacks": { "get": { - "summary": "获取应甚的消息点赞和反銈", + "summary": "获取应甚的消息反銈", "description": "获取歀应甚䞭所有消息反銈的分页列衚包括终端甚户和管理员反銈。", "operationId": "listChatFeedbacksZh", "tags": [ @@ -1282,7 +1282,7 @@ }, "/conversations/{conversation_id}/name": { "post": { - "summary": "䌚话重呜名", + "summary": "重呜名䌚话", "description": "重呜名䌚话或自劚生成名称。䌚话名称甚于圚支持倚䌚话的客户端䞊星瀺。", "operationId": "renameChatConversationZh", "tags": [ @@ -2379,8 +2379,8 @@ }, "/apps/annotation-reply/{action}": { "post": { - "summary": "标泚回倍初始讟眮", - "description": "启甚或犁甚标泚回倍功胜。启甚时需芁配眮嵌入暡型。匂步执行——䜿甚 [获取标泚回倍任务状态](/api-reference/标泚管理/查询标泚回倍初始讟眮任务状态) 跟螪进床。", + "summary": "配眮标泚回倍", + "description": "启甚或犁甚标泚回倍功胜。启甚时需芁配眮嵌入暡型。匂步执行——䜿甚 [获取标泚回倍任务状态](/api-reference/标泚管理/查询标泚回倍配眮任务状态) 跟螪进床。", "operationId": "setChatAnnotationReplyZh", "tags": [ "标泚管理" @@ -2445,8 +2445,8 @@ }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { - "summary": "查询标泚回倍初始讟眮任务状态", - "description": "获取由 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 发起的匂步标泚回倍配眮任务的状态。", + "summary": "查询标泚回倍配眮任务状态", + "description": "获取由 [配眮标泚回倍](/api-reference/标泚管理/配眮标泚回倍) 发起的匂步标泚回倍配眮任务的状态。", "operationId": "getChatAnnotationReplyStatusZh", "tags": [ "标泚管理" @@ -2456,7 +2456,7 @@ "name": "action", "in": "path", "required": true, - "description": "操䜜类型必须䞎 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 调甚䞭的䞀臎。", + "description": "操䜜类型必须䞎 [配眮标泚回倍](/api-reference/标泚管理/配眮标泚回倍) 调甚䞭的䞀臎。", "schema": { "type": "string", "enum": [ @@ -2469,7 +2469,7 @@ "name": "job_id", "in": "path", "required": true, - "description": "由 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 接口返回的任务 ID。", + "description": "由 [配眮标泚回倍](/api-reference/标泚管理/配眮标泚回倍) 接口返回的任务 ID。", "schema": { "type": "string", "format": "uuid" @@ -2630,7 +2630,7 @@ }, "auto_generate_name": { "type": "boolean", - "description": "自劚生成䌚话标题。劂果䞺 `false`请䜿甚 [重呜名䌚话](/api-reference/䌚话管理/䌚话重呜名) API 并讟眮 `auto_generate: true` 来匂步生成标题。", + "description": "自劚生成䌚话标题。劂果䞺 `false`请䜿甚 [重呜名䌚话](/api-reference/䌚话管理/重呜名䌚话) API 并讟眮 `auto_generate: true` 来匂步生成标题。", "default": true } } @@ -4356,7 +4356,7 @@ "job_id": { "type": "string", "format": "uuid", - "description": "匂步任务 ID。配合 [获取标泚回倍任务状态](/api-reference/标泚管理/查询标泚回倍初始讟眮任务状态) 䜿甚以跟螪进床。" + "description": "匂步任务 ID。配合 [查询标泚回倍配眮任务状态](/api-reference/标泚管理/查询标泚回倍配眮任务状态) 䜿甚以跟螪进床。" }, "job_status": { "type": "string", @@ -4370,7 +4370,7 @@ "job_id": { "type": "string", "format": "uuid", - "description": "来自 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 调甚的任务 ID。" + "description": "来自 [配眮标泚回倍](/api-reference/标泚管理/配眮标泚回倍) 调甚的任务 ID。" }, "job_status": { "type": "string", diff --git a/zh/api-reference/openapi_chatflow.json b/zh/api-reference/openapi_chatflow.json index c80828f74..36964d91e 100644 --- a/zh/api-reference/openapi_chatflow.json +++ b/zh/api-reference/openapi_chatflow.json @@ -619,7 +619,7 @@ "tags": [ "文件操䜜" ], - "summary": "文件䞋蜜", + "summary": "䞋蜜文件", "description": "预览或䞋蜜之前通过[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 䞊䌠的文件。仅可访问属于请求应甚内消息的文件。", "parameters": [ { @@ -707,7 +707,7 @@ "tags": [ "终端甚户" ], - "summary": "获取终端甚户", + "summary": "获取终端甚户信息", "description": "根据 ID 获取终端甚户信息。圓其他 API 返回终端甚户 ID䟋劂[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件)返回的 `created_by`时埈有甚。", "parameters": [ { @@ -775,7 +775,7 @@ "tags": [ "消息反銈" ], - "summary": "消息反銈点赞", + "summary": "提亀消息反銈", "description": "提亀消息反銈。终端甚户可以对消息评价 `like` 或 `dislike`并可选择提䟛文字反銈。将 `rating` 讟䞺 `null` 可撀销之前提亀的反銈。", "parameters": [ { @@ -838,7 +838,7 @@ "tags": [ "消息反銈" ], - "summary": "获取应甚的消息点赞和反銈", + "summary": "获取应甚的消息反銈", "description": "获取歀应甚䞭所有消息反銈的分页列衚包括终端甚户和管理员反銈。", "parameters": [ { @@ -1305,7 +1305,7 @@ }, "/conversations/{conversation_id}/name": { "post": { - "summary": "䌚话重呜名", + "summary": "重呜名䌚话", "description": "重呜名䌚话或自劚生成名称。䌚话名称甚于圚支持倚䌚话的客户端䞊星瀺。", "operationId": "renameChatflowConversationZh", "tags": [ @@ -2402,8 +2402,8 @@ }, "/apps/annotation-reply/{action}": { "post": { - "summary": "标泚回倍初始讟眮", - "description": "启甚或犁甚标泚回倍功胜。启甚时需芁配眮嵌入暡型。匂步执行——䜿甚 [获取标泚回倍任务状态](/api-reference/标泚管理/查询标泚回倍初始讟眮任务状态) 跟螪进床。", + "summary": "配眮标泚回倍", + "description": "启甚或犁甚标泚回倍功胜。启甚时需芁配眮嵌入暡型。匂步执行——䜿甚 [查询标泚回倍配眮任务状态](/api-reference/标泚管理/查询标泚回倍配眮任务状态) 跟螪进床。", "operationId": "setChatflowAnnotationReplyZh", "tags": [ "标泚管理" @@ -2468,8 +2468,8 @@ }, "/apps/annotation-reply/{action}/status/{job_id}": { "get": { - "summary": "查询标泚回倍初始讟眮任务状态", - "description": "获取由 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 发起的匂步标泚回倍配眮任务的状态。", + "summary": "查询标泚回倍配眮任务状态", + "description": "获取由 [配眮标泚回倍](/api-reference/标泚管理/配眮标泚回倍) 发起的匂步标泚回倍配眮任务的状态。", "operationId": "getChatflowAnnotationReplyStatusZh", "tags": [ "标泚管理" @@ -2479,7 +2479,7 @@ "name": "action", "in": "path", "required": true, - "description": "操䜜类型必须䞎 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 调甚䞭的䞀臎。", + "description": "操䜜类型必须䞎 [配眮标泚回倍](/api-reference/标泚管理/配眮标泚回倍) 调甚䞭的䞀臎。", "schema": { "type": "string", "enum": [ @@ -2492,7 +2492,7 @@ "name": "job_id", "in": "path", "required": true, - "description": "由 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 接口返回的任务 ID。", + "description": "由 [配眮标泚回倍](/api-reference/标泚管理/配眮标泚回倍) 接口返回的任务 ID。", "schema": { "type": "string", "format": "uuid" @@ -2881,7 +2881,7 @@ }, "auto_generate_name": { "type": "boolean", - "description": "自劚生成䌚话标题。劂果䞺 `false`请䜿甚 [重呜名䌚话](/api-reference/䌚话管理/䌚话重呜名) API 并讟眮 `auto_generate: true` 来匂步生成标题。", + "description": "自劚生成䌚话标题。劂果䞺 `false`请䜿甚 [重呜名䌚话](/api-reference/䌚话管理/重呜名䌚话) API 并讟眮 `auto_generate: true` 来匂步生成标题。", "default": true }, "workflow_id": { @@ -4580,7 +4580,7 @@ "job_id": { "type": "string", "format": "uuid", - "description": "匂步任务 ID。配合 [获取标泚回倍任务状态](/api-reference/标泚管理/查询标泚回倍初始讟眮任务状态) 䜿甚以跟螪进床。" + "description": "匂步任务 ID。配合 [查询标泚回倍配眮任务状态](/api-reference/标泚管理/查询标泚回倍配眮任务状态) 䜿甚以跟螪进床。" }, "job_status": { "type": "string", @@ -4594,7 +4594,7 @@ "job_id": { "type": "string", "format": "uuid", - "description": "来自 [配眮标泚回倍](/api-reference/标泚管理/标泚回倍初始讟眮) 调甚的任务 ID。" + "description": "来自 [配眮标泚回倍](/api-reference/标泚管理/配眮标泚回倍) 调甚的任务 ID。" }, "job_status": { "type": "string", diff --git a/zh/api-reference/openapi_completion.json b/zh/api-reference/openapi_completion.json index fb8318f13..b3943ec07 100644 --- a/zh/api-reference/openapi_completion.json +++ b/zh/api-reference/openapi_completion.json @@ -288,7 +288,7 @@ "tags": [ "消息反銈" ], - "summary": "消息反銈点赞", + "summary": "提亀消息反銈", "description": "提亀消息反銈。终端甚户可以对消息评价 `like` 或 `dislike`并可选择提䟛文字反銈。将 `rating` 讟䞺 `null` 可撀销之前提亀的反銈。", "parameters": [ { @@ -351,7 +351,7 @@ "tags": [ "消息反銈" ], - "summary": "获取应甚的消息点赞和反銈", + "summary": "获取应甚的消息反銈", "description": "获取歀应甚䞭所有消息反銈的分页列衚包括终端甚户和管理员反銈。", "parameters": [ { @@ -568,7 +568,7 @@ "tags": [ "文件操䜜" ], - "summary": "文件䞋蜜", + "summary": "䞋蜜文件", "description": "预览或䞋蜜之前通过[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 䞊䌠的文件。仅可访问属于请求应甚内消息的文件。", "parameters": [ { diff --git a/zh/api-reference/openapi_workflow.json b/zh/api-reference/openapi_workflow.json index 339dc8812..0e1771783 100644 --- a/zh/api-reference/openapi_workflow.json +++ b/zh/api-reference/openapi_workflow.json @@ -888,7 +888,7 @@ "tags": [ "文件操䜜" ], - "summary": "文件䞋蜜", + "summary": "䞋蜜文件", "description": "预览或䞋蜜之前通过[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 䞊䌠的文件。仅可访问属于请求应甚内消息的文件。", "parameters": [ { @@ -976,7 +976,7 @@ "tags": [ "终端甚户" ], - "summary": "获取终端甚户", + "summary": "获取终端甚户信息", "description": "根据 ID 获取终端甚户信息。圓其他 API 返回终端甚户 ID䟋劂[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件)返回的 `created_by`时埈有甚。", "parameters": [ { From 34698d779bab4b3cd12a95a2923e3f3173a04cb2 Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Fri, 20 Mar 2026 14:27:51 +0800 Subject: [PATCH 4/6] Restore original operationIds to preserve SDK compatibility Co-Authored-By: Claude Opus 4.6 (1M context) --- en/api-reference/openapi_chat.json | 38 +++++++-------- en/api-reference/openapi_chatflow.json | 50 +++++++++---------- en/api-reference/openapi_completion.json | 18 +++---- en/api-reference/openapi_knowledge.json | 38 +++++++-------- en/api-reference/openapi_workflow.json | 8 +-- ja/api-reference/openapi_chat.json | 38 +++++++-------- ja/api-reference/openapi_chatflow.json | 38 +++++++-------- ja/api-reference/openapi_completion.json | 20 ++++---- ja/api-reference/openapi_knowledge.json | 62 ++++++++++++------------ ja/api-reference/openapi_workflow.json | 18 +++---- zh/api-reference/openapi_chat.json | 38 +++++++-------- zh/api-reference/openapi_chatflow.json | 50 +++++++++---------- zh/api-reference/openapi_completion.json | 20 ++++---- zh/api-reference/openapi_knowledge.json | 62 ++++++++++++------------ zh/api-reference/openapi_workflow.json | 18 +++---- 15 files changed, 258 insertions(+), 258 deletions(-) diff --git a/en/api-reference/openapi_chat.json b/en/api-reference/openapi_chat.json index 64791e72c..a43a3383c 100644 --- a/en/api-reference/openapi_chat.json +++ b/en/api-reference/openapi_chat.json @@ -27,7 +27,7 @@ "post": { "summary": "Send Chat Message", "description": "Send a request to the chat application.", - "operationId": "createChatMessage", + "operationId": "sendChatMessage", "tags": [ "Chats" ], @@ -274,7 +274,7 @@ "post": { "summary": "Stop Chat Message Generation", "description": "Stops a chat message generation task. Only supported in `streaming` mode.", - "operationId": "stopChatMessage", + "operationId": "stopChatMessageGeneration", "tags": [ "Chats" ], @@ -344,7 +344,7 @@ "get": { "summary": "Get Next Suggested Questions", "description": "Get next questions suggestions for the current message.", - "operationId": "getChatSuggestedQuestions", + "operationId": "getSuggestedQuestions", "tags": [ "Chats" ], @@ -681,7 +681,7 @@ "get": { "summary": "Get End User Info", "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", - "operationId": "getChatEndUser", + "operationId": "getEndUserChat", "tags": [ "End Users" ], @@ -749,7 +749,7 @@ "post": { "summary": "Submit Message Feedback", "description": "Submit feedback for a message. End users can rate messages as `like` or `dislike`, and optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback.", - "operationId": "createChatMessageFeedback", + "operationId": "postChatMessageFeedback", "tags": [ "Feedback" ], @@ -812,7 +812,7 @@ "get": { "summary": "List App Feedbacks", "description": "Retrieve a paginated list of all feedback submitted for messages in this application, including both end-user and admin feedback.", - "operationId": "listChatFeedbacks", + "operationId": "getChatAppFeedbacks", "tags": [ "Feedback" ], @@ -894,7 +894,7 @@ "get": { "summary": "List Conversations", "description": "Retrieve the conversation list for the current user, ordered by most recently active.", - "operationId": "listChatConversations", + "operationId": "getConversationsList", "tags": [ "Conversations" ], @@ -1020,7 +1020,7 @@ "get": { "summary": "List Conversation Messages", "description": "Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order.", - "operationId": "listChatMessages", + "operationId": "getConversationHistory", "tags": [ "Conversations" ], @@ -1156,7 +1156,7 @@ "get": { "summary": "List Conversation Variables", "description": "Retrieve variables from a specific conversation.", - "operationId": "listChatConversationVariables", + "operationId": "getConversationVariables", "tags": [ "Conversations" ], @@ -1284,7 +1284,7 @@ "post": { "summary": "Rename Conversation", "description": "Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations.", - "operationId": "renameChatConversation", + "operationId": "renameConversation", "tags": [ "Conversations" ], @@ -1513,7 +1513,7 @@ "delete": { "summary": "Delete Conversation", "description": "Delete a conversation.", - "operationId": "deleteChatConversation", + "operationId": "deleteConversation", "tags": [ "Conversations" ], @@ -1597,7 +1597,7 @@ "post": { "summary": "Convert Audio to Text", "description": "Convert audio file to text. Supported formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`. File size limit is `30 MB`.", - "operationId": "chatAudioToText", + "operationId": "audioToText", "tags": [ "TTS" ], @@ -1753,7 +1753,7 @@ "post": { "summary": "Convert Text to Audio", "description": "Convert text to speech.", - "operationId": "chatTextToAudio", + "operationId": "textToAudioChat", "tags": [ "TTS" ], @@ -2099,7 +2099,7 @@ "post": { "summary": "Create Annotation", "description": "Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response.", - "operationId": "createChatAnnotation", + "operationId": "createAnnotation", "tags": [ "Annotations" ], @@ -2150,7 +2150,7 @@ "get": { "summary": "List Annotations", "description": "Retrieves a paginated list of annotations for the application. Supports keyword search filtering.", - "operationId": "listChatAnnotations", + "operationId": "getAnnotationList", "tags": [ "Annotations" ], @@ -2223,7 +2223,7 @@ "put": { "summary": "Update Annotation", "description": "Updates the question and answer of an existing annotation.", - "operationId": "updateChatAnnotation", + "operationId": "updateAnnotation", "tags": [ "Annotations" ], @@ -2320,7 +2320,7 @@ "delete": { "summary": "Delete Annotation", "description": "Deletes an annotation and its associated hit history.", - "operationId": "deleteChatAnnotation", + "operationId": "deleteAnnotation", "tags": [ "Annotations" ], @@ -2381,7 +2381,7 @@ "post": { "summary": "Configure Annotation Reply", "description": "Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Retrieve Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.", - "operationId": "setChatAnnotationReply", + "operationId": "initialAnnotationReplySettings", "tags": [ "Annotations" ], @@ -2447,7 +2447,7 @@ "get": { "summary": "Get Annotation Reply Job Status", "description": "Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", - "operationId": "getChatAnnotationReplyStatus", + "operationId": "getInitialAnnotationReplySettingsStatus", "tags": [ "Annotations" ], diff --git a/en/api-reference/openapi_chatflow.json b/en/api-reference/openapi_chatflow.json index 2078d5ff6..c02b6b410 100644 --- a/en/api-reference/openapi_chatflow.json +++ b/en/api-reference/openapi_chatflow.json @@ -27,7 +27,7 @@ "post": { "summary": "Send Chat Message", "description": "Send a request to the chat application.", - "operationId": "createChatflowMessage", + "operationId": "sendAdvancedChatMessage", "tags": [ "Chats" ], @@ -298,7 +298,7 @@ "post": { "summary": "Stop Chat Message Generation", "description": "Stops a chat message generation task. Only supported in `streaming` mode.", - "operationId": "stopChatflowMessage", + "operationId": "stopAdvancedChatMessageGeneration", "tags": [ "Chats" ], @@ -368,7 +368,7 @@ "get": { "summary": "Get Next Suggested Questions", "description": "Get next questions suggestions for the current message.", - "operationId": "getChatflowSuggestedQuestions", + "operationId": "getAdvancedSuggestedQuestions", "tags": [ "Chats" ], @@ -480,7 +480,7 @@ }, "/files/upload": { "post": { - "operationId": "uploadChatflowFile", + "operationId": "uploadAdvancedChatFile", "tags": [ "Files" ], @@ -615,7 +615,7 @@ }, "/files/{file_id}/preview": { "get": { - "operationId": "previewChatflowFile", + "operationId": "previewChatFlowFile", "tags": [ "Files" ], @@ -703,7 +703,7 @@ }, "/end-users/{end_user_id}": { "get": { - "operationId": "getChatflowEndUser", + "operationId": "getEndUserChatflow", "tags": [ "End Users" ], @@ -771,7 +771,7 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "operationId": "createChatflowMessageFeedback", + "operationId": "postAdvancedChatMessageFeedback", "tags": [ "Feedback" ], @@ -834,7 +834,7 @@ }, "/app/feedbacks": { "get": { - "operationId": "listChatflowFeedbacks", + "operationId": "getAdvancedChatAppFeedbacks", "tags": [ "Feedback" ], @@ -918,7 +918,7 @@ "get": { "summary": "List Conversations", "description": "Retrieve the conversation list for the current user, ordered by most recently active.", - "operationId": "listChatflowConversations", + "operationId": "getAdvancedConversationsList", "tags": [ "Conversations" ], @@ -1044,7 +1044,7 @@ "get": { "summary": "List Conversation Messages", "description": "Returns historical chat records in a scrolling load format, with the first page returning the latest `limit` messages, i.e., in reverse order.", - "operationId": "listChatflowMessages", + "operationId": "getAdvancedConversationHistory", "tags": [ "Conversations" ], @@ -1179,7 +1179,7 @@ "get": { "summary": "List Conversation Variables", "description": "Retrieve variables from a specific conversation.", - "operationId": "listChatflowConversationVariables", + "operationId": "getAdvancedConversationVariables", "tags": [ "Conversations" ], @@ -1307,7 +1307,7 @@ "post": { "summary": "Rename Conversation", "description": "Rename a conversation or auto-generate a name. The conversation name is used for display on clients that support multiple conversations.", - "operationId": "renameChatflowConversation", + "operationId": "renameAdvancedConversation", "tags": [ "Conversations" ], @@ -1536,7 +1536,7 @@ "delete": { "summary": "Delete Conversation", "description": "Delete a conversation.", - "operationId": "deleteChatflowConversation", + "operationId": "deleteAdvancedConversation", "tags": [ "Conversations" ], @@ -1618,7 +1618,7 @@ }, "/audio-to-text": { "post": { - "operationId": "chatflowAudioToText", + "operationId": "advancedAudioToText", "tags": [ "TTS" ], @@ -1774,7 +1774,7 @@ }, "/text-to-audio": { "post": { - "operationId": "chatflowTextToAudio", + "operationId": "advancedTextToAudio", "tags": [ "TTS" ], @@ -1884,7 +1884,7 @@ }, "/info": { "get": { - "operationId": "getChatflowAppInfo", + "operationId": "getAdvancedChatAppInfo", "tags": [ "Applications" ], @@ -1921,7 +1921,7 @@ }, "/parameters": { "get": { - "operationId": "getChatflowAppParameters", + "operationId": "getAdvancedChatAppParameters", "tags": [ "Applications" ], @@ -2024,7 +2024,7 @@ }, "/meta": { "get": { - "operationId": "getChatflowAppMeta", + "operationId": "getAdvancedChatAppMeta", "tags": [ "Applications" ], @@ -2060,7 +2060,7 @@ }, "/site": { "get": { - "operationId": "getChatflowWebAppSettings", + "operationId": "getAdvancedChatWebAppSettings", "tags": [ "Applications" ], @@ -2122,7 +2122,7 @@ "post": { "summary": "Create Annotation", "description": "Creates a new annotation. Annotations provide predefined question-answer pairs that the app can match and return directly instead of generating a response.", - "operationId": "createChatflowAnnotation", + "operationId": "createAdvancedAnnotation", "tags": [ "Annotations" ], @@ -2173,7 +2173,7 @@ "get": { "summary": "List Annotations", "description": "Retrieves a paginated list of annotations for the application. Supports keyword search filtering.", - "operationId": "listChatflowAnnotations", + "operationId": "getAdvancedAnnotationList", "tags": [ "Annotations" ], @@ -2246,7 +2246,7 @@ "put": { "summary": "Update Annotation", "description": "Updates the question and answer of an existing annotation.", - "operationId": "updateChatflowAnnotation", + "operationId": "updateAdvancedAnnotation", "tags": [ "Annotations" ], @@ -2343,7 +2343,7 @@ "delete": { "summary": "Delete Annotation", "description": "Deletes an annotation and its associated hit history.", - "operationId": "deleteChatflowAnnotation", + "operationId": "deleteAdvancedAnnotation", "tags": [ "Annotations" ], @@ -2404,7 +2404,7 @@ "post": { "summary": "Configure Annotation Reply", "description": "Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.", - "operationId": "setChatflowAnnotationReply", + "operationId": "initialAdvancedAnnotationReplySettings", "tags": [ "Annotations" ], @@ -2470,7 +2470,7 @@ "get": { "summary": "Get Annotation Reply Job Status", "description": "Retrieves the status of an asynchronous annotation reply configuration job started by [Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply).", - "operationId": "getChatflowAnnotationReplyStatus", + "operationId": "getAdvancedInitialAnnotationReplySettingsStatus", "tags": [ "Annotations" ], diff --git a/en/api-reference/openapi_completion.json b/en/api-reference/openapi_completion.json index 9cbd7dac1..ab95f5f9f 100644 --- a/en/api-reference/openapi_completion.json +++ b/en/api-reference/openapi_completion.json @@ -216,7 +216,7 @@ "post": { "summary": "Stop Completion Message Generation", "description": "Stops a completion message generation task. Only supported in `streaming` mode.", - "operationId": "stopCompletionMessage", + "operationId": "stopGenerate", "tags": [ "Completions" ], @@ -284,7 +284,7 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "operationId": "createCompletionMessageFeedback", + "operationId": "postMessageFeedback", "tags": [ "Feedback" ], @@ -347,7 +347,7 @@ }, "/app/feedbacks": { "get": { - "operationId": "listCompletionFeedbacks", + "operationId": "getAppFeedbacks", "tags": [ "Feedback" ], @@ -429,7 +429,7 @@ }, "/files/upload": { "post": { - "operationId": "uploadCompletionFile", + "operationId": "uploadFile", "tags": [ "Files" ], @@ -652,7 +652,7 @@ }, "/end-users/{end_user_id}": { "get": { - "operationId": "getCompletionEndUser", + "operationId": "getEndUserCompletion", "tags": [ "End Users" ], @@ -876,7 +876,7 @@ }, "/text-to-audio": { "post": { - "operationId": "completionTextToAudio", + "operationId": "textToAudio", "tags": [ "TTS" ], @@ -986,7 +986,7 @@ }, "/info": { "get": { - "operationId": "getCompletionAppInfo", + "operationId": "getAppInfo", "tags": [ "Applications" ], @@ -1023,7 +1023,7 @@ }, "/parameters": { "get": { - "operationId": "getCompletionAppParameters", + "operationId": "getAppParameters", "tags": [ "Applications" ], @@ -1162,7 +1162,7 @@ }, "/site": { "get": { - "operationId": "getCompletionWebAppSettings", + "operationId": "getWebAppSettings", "tags": [ "Applications" ], diff --git a/en/api-reference/openapi_knowledge.json b/en/api-reference/openapi_knowledge.json index fd28026c9..d2cc0e2f8 100644 --- a/en/api-reference/openapi_knowledge.json +++ b/en/api-reference/openapi_knowledge.json @@ -60,7 +60,7 @@ ], "summary": "Create an Empty Knowledge Base", "description": "Create a new empty knowledge base. After creation, use [Create Document by Text](/api-reference/documents/create-document-by-text) or [Create Document by File](/api-reference/documents/create-document-by-file) to add documents.", - "operationId": "createKnowledgeBase", + "operationId": "createDataset", "requestBody": { "required": true, "content": { @@ -249,7 +249,7 @@ ], "summary": "List Knowledge Bases", "description": "Returns a paginated list of knowledge bases. Supports filtering by keyword and tags.", - "operationId": "listKnowledgeBases", + "operationId": "listDatasets", "parameters": [ { "name": "page", @@ -408,7 +408,7 @@ ], "summary": "Get Knowledge Base", "description": "Retrieve detailed information about a specific knowledge base, including its embedding model, retrieval configuration, and document statistics.", - "operationId": "getKnowledgeBase", + "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", @@ -528,7 +528,7 @@ ], "summary": "Update Knowledge Base", "description": "Update the name, description, permissions, or retrieval settings of an existing knowledge base. Only the fields provided in the request body are updated.", - "operationId": "updateKnowledgeBase", + "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", @@ -740,7 +740,7 @@ ], "summary": "Delete Knowledge Base", "description": "Permanently delete a knowledge base and all its documents. The knowledge base must not be in use by any application.", - "operationId": "deleteKnowledgeBase", + "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", @@ -801,7 +801,7 @@ ], "summary": "Create Document by Text", "description": "Create a document from raw text content. The document is processed asynchronously — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", - "operationId": "createDocumentByText", + "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", @@ -1049,7 +1049,7 @@ ], "summary": "Create Document by File", "description": "Create a document by uploading a file. Supports common document formats (PDF, TXT, DOCX, etc.). Processing is asynchronous — use the returned `batch` ID with [Get Document Indexing Status](/api-reference/documents/get-document-indexing-status) to track progress.", - "operationId": "createDocumentByFile", + "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", @@ -1422,7 +1422,7 @@ ], "summary": "Get Document", "description": "Retrieve detailed information about a specific document, including its indexing status, metadata, and processing statistics.", - "operationId": "getDocument", + "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", @@ -2721,7 +2721,7 @@ ], "summary": "Create Chunks", "description": "Create one or more chunks within a document. Each chunk can include optional keywords and an answer field (for QA-mode documents).", - "operationId": "createChunks", + "operationId": "createSegments", "parameters": [ { "name": "dataset_id", @@ -2889,7 +2889,7 @@ ], "summary": "List Chunks", "description": "Returns a paginated list of chunks within a document. Supports filtering by keyword and status.", - "operationId": "listChunks", + "operationId": "listSegments", "parameters": [ { "name": "dataset_id", @@ -3047,7 +3047,7 @@ ], "summary": "Get Chunk", "description": "Retrieve detailed information about a specific chunk, including its content, keywords, and indexing status.", - "operationId": "getChunk", + "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", @@ -3149,7 +3149,7 @@ ], "summary": "Update Chunk", "description": "Update a chunk's content, keywords, or answer. Re-triggers indexing for the modified chunk.", - "operationId": "updateChunk", + "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", @@ -3308,7 +3308,7 @@ ], "summary": "Delete Chunk", "description": "Permanently delete a chunk from the document.", - "operationId": "deleteChunk", + "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", @@ -3465,7 +3465,7 @@ ], "summary": "List Child Chunks", "description": "Returns a paginated list of child chunks under a specific parent chunk.", - "operationId": "listChildChunks", + "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", @@ -3788,7 +3788,7 @@ ], "summary": "Retrieve Chunks from a Knowledge Base / Test Retrieval", "description": "Performs a search query against a knowledge base to retrieve the most relevant chunks. This endpoint can be used for both production retrieval and test retrieval.", - "operationId": "searchKnowledgeBase", + "operationId": "retrieveSegments", "parameters": [ { "name": "dataset_id", @@ -4328,7 +4328,7 @@ ], "summary": "List Knowledge Tags", "description": "Returns the list of all knowledge base tags in the workspace.", - "operationId": "listKnowledgeTags", + "operationId": "getKnowledgeTags", "responses": { "200": { "description": "List of tags.", @@ -4493,7 +4493,7 @@ ], "summary": "Create Tag Binding", "description": "Bind one or more tags to a knowledge base. A knowledge base can have multiple tags.", - "operationId": "bindKnowledgeTags", + "operationId": "bindTagsToDataset", "requestBody": { "required": true, "content": { @@ -4536,7 +4536,7 @@ ], "summary": "Delete Tag Binding", "description": "Remove a tag binding from a knowledge base.", - "operationId": "unbindKnowledgeTag", + "operationId": "unbindTagFromDataset", "requestBody": { "required": true, "content": { @@ -4575,7 +4575,7 @@ ], "summary": "Get Knowledge Base Tags", "description": "Returns the list of tags bound to a specific knowledge base.", - "operationId": "getKnowledgeBaseTags", + "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", diff --git a/en/api-reference/openapi_workflow.json b/en/api-reference/openapi_workflow.json index 990d68295..d61975f15 100644 --- a/en/api-reference/openapi_workflow.json +++ b/en/api-reference/openapi_workflow.json @@ -27,7 +27,7 @@ "post": { "summary": "Run Workflow", "description": "Execute a workflow. Cannot be executed without a published workflow.", - "operationId": "runWorkflow", + "operationId": "executeWorkflow", "tags": [ "Workflows" ], @@ -533,7 +533,7 @@ "get": { "summary": "List Workflow Logs", "description": "Retrieve paginated workflow execution logs with filtering options.", - "operationId": "listWorkflowLogs", + "operationId": "getWorkflowLogs", "tags": [ "Workflows" ], @@ -673,7 +673,7 @@ "post": { "summary": "Stop Workflow Task", "description": "Stop a running workflow task. Only supported in `streaming` mode.", - "operationId": "stopWorkflowTask", + "operationId": "stopWorkflowTaskGeneration", "tags": [ "Workflows" ], @@ -972,7 +972,7 @@ }, "/end-users/{end_user_id}": { "get": { - "operationId": "getWorkflowEndUser", + "operationId": "getEndUserWorkflow", "tags": [ "End Users" ], diff --git a/ja/api-reference/openapi_chat.json b/ja/api-reference/openapi_chat.json index f951fd298..13f2a3145 100644 --- a/ja/api-reference/openapi_chat.json +++ b/ja/api-reference/openapi_chat.json @@ -27,7 +27,7 @@ "post": { "summary": "チャットメッセヌゞを送信", "description": "チャットアプリケヌションにリク゚ストを送信したす。", - "operationId": "createChatMessageJa", + "operationId": "sendBasicChatMessageJa", "tags": [ "チャットメッセヌゞ" ], @@ -274,7 +274,7 @@ "post": { "summary": "生成を停止", "description": "チャットメッセヌゞ生成タスクを停止したす。`streaming` モヌドでのみサポヌトされたす。", - "operationId": "stopChatMessageJa", + "operationId": "stopBasicChatMessageGenerationJa", "tags": [ "チャットメッセヌゞ" ], @@ -344,7 +344,7 @@ "get": { "summary": "次の掚奚質問", "description": "珟圚のメッセヌゞに察する次の質問の提案を取埗したす。", - "operationId": "getChatSuggestedQuestionsJa", + "operationId": "getBasicChatSuggestedQuestionsJa", "tags": [ "チャットメッセヌゞ" ], @@ -458,7 +458,7 @@ "post": { "summary": "ファむルアップロヌド", "description": "メッセヌゞ送信時に䜿甚するファむルをアップロヌドしたす。画像、ドキュメント、音声、動画のマルチモヌダル理解が可胜です。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", - "operationId": "uploadChatFileJa", + "operationId": "uploadBasicChatFileJa", "tags": [ "ファむル操䜜" ], @@ -593,7 +593,7 @@ "get": { "summary": "ファむルダりンロヌド", "description": "以前[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", - "operationId": "previewChatFileJa", + "operationId": "previewBasicChatFileJa", "tags": [ "ファむル操䜜" ], @@ -681,7 +681,7 @@ "get": { "summary": "゚ンドナヌザヌ取埗", "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド)の `created_by`に䟿利です。", - "operationId": "getChatEndUserJa", + "operationId": "getEndUserChatJa", "tags": [ "゚ンドナヌザヌ" ], @@ -749,7 +749,7 @@ "post": { "summary": "メッセヌゞフィヌドバック", "description": "メッセヌゞに察するフィヌドバックを送信したす。゚ンドナヌザヌはメッセヌゞを `like` たたは `dislike` で評䟡でき、任意でテキストフィヌドバックを提䟛できたす。`rating` に `null` を枡すず、以前送信したフィヌドバックを取り消せたす。", - "operationId": "createChatMessageFeedbackJa", + "operationId": "postBasicChatMessageFeedbackJa", "tags": [ "メッセヌゞフィヌドバック" ], @@ -812,7 +812,7 @@ "get": { "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", "description": "このアプリケヌションのメッセヌゞに察しお送信されたすべおのフィヌドバックのペヌゞネヌション付きリストを取埗したす。゚ンドナヌザヌず管理者のフィヌドバックの䞡方が含たれたす。", - "operationId": "listChatFeedbacksJa", + "operationId": "getBasicChatAppFeedbacksJa", "tags": [ "メッセヌゞフィヌドバック" ], @@ -894,7 +894,7 @@ "get": { "summary": "䌚話を取埗", "description": "珟圚のナヌザヌの䌚話リストを、最近アクティブな順に取埗したす。", - "operationId": "listChatConversationsJa", + "operationId": "getBasicChatConversationsListJa", "tags": [ "䌚話管理" ], @@ -1020,7 +1020,7 @@ "get": { "summary": "䌚話履歎メッセヌゞを取埗", "description": "スクロヌル読み蟌み圢匏で過去のチャット蚘録を返したす。最初のペヌゞは最新の `limit` 件のメッセヌゞを返したす時系列の逆順。", - "operationId": "listChatMessagesJa", + "operationId": "getBasicChatConversationHistoryJa", "tags": [ "䌚話管理" ], @@ -1156,7 +1156,7 @@ "get": { "summary": "䌚話倉数の取埗", "description": "特定の䌚話から倉数を取埗したす。", - "operationId": "listChatConversationVariablesJa", + "operationId": "getBasicChatConversationVariablesJa", "tags": [ "䌚話管理" ], @@ -1284,7 +1284,7 @@ "post": { "summary": "䌚話の名前を倉曎", "description": "䌚話の名前を倉曎するか、自動的に生成したす。䌚話名は耇数の䌚話をサポヌトするクラむアントでの衚瀺に䜿甚されたす。", - "operationId": "renameChatConversationJa", + "operationId": "renameBasicChatConversationJa", "tags": [ "䌚話管理" ], @@ -1513,7 +1513,7 @@ "delete": { "summary": "䌚話を削陀", "description": "䌚話を削陀したす。", - "operationId": "deleteChatConversationJa", + "operationId": "deleteBasicChatConversationJa", "tags": [ "䌚話管理" ], @@ -1597,7 +1597,7 @@ "post": { "summary": "音声からテキストぞ", "description": "音声ファむルをテキストに倉換したす。サポヌトされる圢匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファむルサむズの䞊限は `30 MB` です。", - "operationId": "chatAudioToTextJa", + "operationId": "basicChatAudioToTextJa", "tags": [ "音声・テキスト倉換" ], @@ -1753,7 +1753,7 @@ "post": { "summary": "テキストから音声ぞ", "description": "テキストを音声に倉換したす。", - "operationId": "chatTextToAudioJa", + "operationId": "basicChatTextToAudioJa", "tags": [ "音声・テキスト倉換" ], @@ -1863,7 +1863,7 @@ "get": { "summary": "アプリケヌションの基本情報を取埗", "description": "このアプリケヌションの基本情報名前、説明、タグ、モヌドを取埗したす。", - "operationId": "getChatAppInfoJa", + "operationId": "getBasicChatAppInfoJa", "tags": [ "アプリケヌション蚭定" ], @@ -1900,7 +1900,7 @@ "get": { "summary": "アプリケヌションのパラメヌタ情報を取埗", "description": "アプリケヌションの入力フォヌム蚭定機胜スむッチ、入力パラメヌタ名、タむプ、デフォルト倀を取埗したす。", - "operationId": "getChatAppParametersJa", + "operationId": "getBasicChatAppParametersJa", "tags": [ "アプリケヌション蚭定" ], @@ -2003,7 +2003,7 @@ "get": { "summary": "アプリケヌションのメタ情報を取埗", "description": "このアプリケヌションのメタデヌタツヌルアむコンやその他の蚭定詳现を取埗したす。", - "operationId": "getChatAppMetaJa", + "operationId": "getBasicChatAppMetaJa", "tags": [ "アプリケヌション蚭定" ], @@ -2039,7 +2039,7 @@ "get": { "summary": "アプリの WebApp 蚭定を取埗", "description": "このアプリケヌションの WebApp 蚭定サむト蚭定、テヌマ、カスタマむズオプションを取埗したす。", - "operationId": "getChatWebAppSettingsJa", + "operationId": "getBasicChatWebAppSettingsJa", "tags": [ "アプリケヌション蚭定" ], diff --git a/ja/api-reference/openapi_chatflow.json b/ja/api-reference/openapi_chatflow.json index 84358e0bd..4d6321983 100644 --- a/ja/api-reference/openapi_chatflow.json +++ b/ja/api-reference/openapi_chatflow.json @@ -27,7 +27,7 @@ "post": { "summary": "チャットメッセヌゞを送信", "description": "チャットアプリケヌションにリク゚ストを送信したす。", - "operationId": "createChatflowMessageJa", + "operationId": "sendChatflowMessageJp", "tags": [ "チャットメッセヌゞ" ], @@ -298,7 +298,7 @@ "post": { "summary": "生成を停止", "description": "チャットメッセヌゞ生成タスクを停止したす。`streaming` モヌドでのみサポヌトされたす。", - "operationId": "stopChatflowMessageJa", + "operationId": "stopChatflowMessageGenerationJp", "tags": [ "チャットメッセヌゞ" ], @@ -368,7 +368,7 @@ "get": { "summary": "次の掚奚質問", "description": "珟圚のメッセヌゞに察する次の質問の提案を取埗したす。", - "operationId": "getChatflowSuggestedQuestionsJa", + "operationId": "getChatflowSuggestedQuestionsJp", "tags": [ "チャットメッセヌゞ" ], @@ -480,7 +480,7 @@ }, "/files/upload": { "post": { - "operationId": "uploadChatflowFileJa", + "operationId": "uploadChatflowFileJp", "tags": [ "ファむル操䜜" ], @@ -615,7 +615,7 @@ }, "/files/{file_id}/preview": { "get": { - "operationId": "previewChatflowFileJa", + "operationId": "previewChatflowFileJp", "tags": [ "ファむル操䜜" ], @@ -703,7 +703,7 @@ }, "/end-users/{end_user_id}": { "get": { - "operationId": "getChatflowEndUserJa", + "operationId": "getEndUserChatflowJp", "tags": [ "゚ンドナヌザヌ" ], @@ -771,7 +771,7 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "operationId": "createChatflowMessageFeedbackJa", + "operationId": "postChatflowMessageFeedbackJp", "tags": [ "メッセヌゞフィヌドバック" ], @@ -834,7 +834,7 @@ }, "/app/feedbacks": { "get": { - "operationId": "listChatflowFeedbacksJa", + "operationId": "getChatflowAppFeedbacksJp", "tags": [ "メッセヌゞフィヌドバック" ], @@ -918,7 +918,7 @@ "get": { "summary": "䌚話を取埗", "description": "珟圚のナヌザヌの䌚話リストを、最近アクティブな順に取埗したす。", - "operationId": "listChatflowConversationsJa", + "operationId": "getChatflowConversationsListJp", "tags": [ "䌚話管理" ], @@ -1044,7 +1044,7 @@ "get": { "summary": "䌚話履歎メッセヌゞを取埗", "description": "スクロヌル読み蟌み圢匏で過去のチャット蚘録を返したす。最初のペヌゞは最新の `limit` 件のメッセヌゞを返したす時系列の逆順。", - "operationId": "listChatflowMessagesJa", + "operationId": "getChatflowConversationHistoryJp", "tags": [ "䌚話管理" ], @@ -1179,7 +1179,7 @@ "get": { "summary": "䌚話倉数の取埗", "description": "特定の䌚話から倉数を取埗したす。", - "operationId": "listChatflowConversationVariablesJa", + "operationId": "getChatflowConversationVariablesJp", "tags": [ "䌚話管理" ], @@ -1307,7 +1307,7 @@ "post": { "summary": "䌚話の名前を倉曎", "description": "䌚話の名前を倉曎するか、自動的に生成したす。䌚話名は耇数の䌚話をサポヌトするクラむアントでの衚瀺に䜿甚されたす。", - "operationId": "renameChatflowConversationJa", + "operationId": "renameChatflowConversationJp", "tags": [ "䌚話管理" ], @@ -1536,7 +1536,7 @@ "delete": { "summary": "䌚話を削陀", "description": "䌚話を削陀したす。", - "operationId": "deleteChatflowConversationJa", + "operationId": "deleteChatflowConversationJp", "tags": [ "䌚話管理" ], @@ -1618,7 +1618,7 @@ }, "/audio-to-text": { "post": { - "operationId": "chatflowAudioToTextJa", + "operationId": "chatflowAudioToTextJp", "tags": [ "音声・テキスト倉換" ], @@ -1774,7 +1774,7 @@ }, "/text-to-audio": { "post": { - "operationId": "chatflowTextToAudioJa", + "operationId": "chatflowTextToAudioJp", "tags": [ "音声・テキスト倉換" ], @@ -1884,7 +1884,7 @@ }, "/info": { "get": { - "operationId": "getChatflowAppInfoJa", + "operationId": "getChatflowAppInfoJp", "tags": [ "アプリケヌション蚭定" ], @@ -1921,7 +1921,7 @@ }, "/parameters": { "get": { - "operationId": "getChatflowAppParametersJa", + "operationId": "getChatflowAppParametersJp", "tags": [ "アプリケヌション蚭定" ], @@ -2024,7 +2024,7 @@ }, "/meta": { "get": { - "operationId": "getChatflowAppMetaJa", + "operationId": "getChatflowAppMetaJp", "tags": [ "アプリケヌション蚭定" ], @@ -2060,7 +2060,7 @@ }, "/site": { "get": { - "operationId": "getChatflowWebAppSettingsJa", + "operationId": "getChatflowWebAppSettingsJp", "tags": [ "アプリケヌション蚭定" ], diff --git a/ja/api-reference/openapi_completion.json b/ja/api-reference/openapi_completion.json index abcb2940e..2c60e1036 100644 --- a/ja/api-reference/openapi_completion.json +++ b/ja/api-reference/openapi_completion.json @@ -27,7 +27,7 @@ "post": { "summary": "完了メッセヌゞの䜜成", "description": "テキスト生成アプリケヌションにリク゚ストを送信したす。", - "operationId": "createCompletionMessageJa", + "operationId": "createCompletionMessageJp", "tags": [ "完了メッセヌゞ" ], @@ -216,7 +216,7 @@ "post": { "summary": "生成を停止", "description": "テキスト生成メッセヌゞ生成タスクを停止したす。`streaming` モヌドでのみサポヌトされおいたす。", - "operationId": "stopCompletionMessageJa", + "operationId": "stopCompletionGenerationJp", "tags": [ "完了メッセヌゞ" ], @@ -284,7 +284,7 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "operationId": "createCompletionMessageFeedbackJa", + "operationId": "postCompletionMessageFeedbackJp", "tags": [ "メッセヌゞフィヌドバック" ], @@ -347,7 +347,7 @@ }, "/app/feedbacks": { "get": { - "operationId": "listCompletionFeedbacksJa", + "operationId": "getAppFeedbacksCompletionJp", "tags": [ "メッセヌゞフィヌドバック" ], @@ -429,7 +429,7 @@ }, "/files/upload": { "post": { - "operationId": "uploadCompletionFileJa", + "operationId": "uploadCompletionFileJp", "tags": [ "ファむル操䜜" ], @@ -652,7 +652,7 @@ }, "/end-users/{end_user_id}": { "get": { - "operationId": "getCompletionEndUserJa", + "operationId": "getEndUserCompletionJp", "tags": [ "゚ンドナヌザヌ" ], @@ -876,7 +876,7 @@ }, "/text-to-audio": { "post": { - "operationId": "completionTextToAudioJa", + "operationId": "textToAudioCompletionJp", "tags": [ "音声・テキスト倉換" ], @@ -986,7 +986,7 @@ }, "/info": { "get": { - "operationId": "getCompletionAppInfoJa", + "operationId": "getCompletionAppInfoJp", "tags": [ "アプリケヌション蚭定" ], @@ -1023,7 +1023,7 @@ }, "/parameters": { "get": { - "operationId": "getCompletionAppParametersJa", + "operationId": "getCompletionAppParametersJp", "tags": [ "アプリケヌション蚭定" ], @@ -1162,7 +1162,7 @@ }, "/site": { "get": { - "operationId": "getCompletionWebAppSettingsJa", + "operationId": "getCompletionWebAppSettingsJp", "tags": [ "アプリケヌション蚭定" ], diff --git a/ja/api-reference/openapi_knowledge.json b/ja/api-reference/openapi_knowledge.json index 824e3c44f..9e65b0a08 100644 --- a/ja/api-reference/openapi_knowledge.json +++ b/ja/api-reference/openapi_knowledge.json @@ -60,7 +60,7 @@ ], "summary": "空のナレッゞベヌスを䜜成", "description": "新しい空のナレッゞベヌスを䜜成したす。䜜成埌、[テキストでドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) たたは [ファむルでドキュメントを䜜成](/api-reference/ドキュメント/ファむルからドキュメントを䜜成) を䜿甚しおドキュメントを远加したす。", - "operationId": "createKnowledgeBaseJa", + "operationId": "createDataset", "requestBody": { "required": true, "content": { @@ -249,7 +249,7 @@ ], "summary": "ナレッゞベヌスリストを取埗", "description": "ナレッゞベヌスのペヌゞネヌションリストを返したす。キヌワヌドずタグによるフィルタリングをサポヌトしおいたす。", - "operationId": "listKnowledgeBasesJa", + "operationId": "listDatasets", "parameters": [ { "name": "page", @@ -408,7 +408,7 @@ ], "summary": "ナレッゞベヌス詳现を取埗", "description": "特定のナレッゞベヌスの詳现情報埋め蟌みモデル、怜玢蚭定、ドキュメント統蚈を含むを取埗したす。", - "operationId": "getKnowledgeBaseJa", + "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", @@ -528,7 +528,7 @@ ], "summary": "ナレッゞベヌスを曎新", "description": "既存のナレッゞベヌスの名前、説明、暩限、たたは怜玢蚭定を曎新したす。リク゚ストボディで指定されたフィヌルドのみが曎新されたす。", - "operationId": "updateKnowledgeBaseJa", + "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", @@ -740,7 +740,7 @@ ], "summary": "ナレッゞベヌスを削陀", "description": "ナレッゞベヌスずそのすべおのドキュメントを完党に削陀したす。察象のナレッゞベヌスはどのアプリケヌションでも䜿甚されおいない必芁がありたす。", - "operationId": "deleteKnowledgeBaseJa", + "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", @@ -801,7 +801,7 @@ ], "summary": "テキストからドキュメントを䜜成", "description": "テキストコンテンツからドキュメントを䜜成したす。ドキュメントは非同期で凊理されたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", - "operationId": "createDocumentByTextJa", + "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", @@ -1049,7 +1049,7 @@ ], "summary": "ファむルからドキュメントを䜜成", "description": "ファむルをアップロヌドしおドキュメントを䜜成したす。䞀般的なドキュメント圢匏PDF、TXT、DOCX などをサポヌトしおいたす。凊理は非同期で行われたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", - "operationId": "createDocumentByFileJa", + "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", @@ -1252,7 +1252,7 @@ ], "summary": "ナレッゞベヌスのドキュメントリストを取埗", "description": "ナレッゞベヌス内のドキュメントのペヌゞネヌションされた䞀芧を返したす。キヌワヌドやむンデックスステヌタスによるフィルタリングをサポヌトしおいたす。", - "operationId": "listDocumentsJa", + "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", @@ -1422,7 +1422,7 @@ ], "summary": "ドキュメント詳现を取埗", "description": "特定のドキュメントの詳现情報むンデックスステヌタス、メタデヌタ、凊理統蚈を含むを取埗したす。", - "operationId": "getDocumentJa", + "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", @@ -1741,7 +1741,7 @@ ], "summary": "ドキュメントを削陀", "description": "ナレッゞベヌスからドキュメントずそのすべおのチャンクを完党に削陀したす。", - "operationId": "deleteDocumentJa", + "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", @@ -1921,7 +1921,7 @@ ], "summary": "ドキュメント埋め蟌みステヌタス進捗を取埗", "description": "バッチ内のドキュメントのむンデックス進捗を確認したす。各ドキュメントの珟圚の凊理段階ずチャンク完了数を返したす。`indexing_status` が `completed` たたは `error` に達するたでこの゚ンドポむントをポヌリングしおください。ステヌタスは次の順序で進行したす`waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`。", - "operationId": "getDocumentIndexingStatusJa", + "operationId": "getDocumentIndexingStatus", "parameters": [ { "name": "dataset_id", @@ -2070,7 +2070,7 @@ ], "summary": "テキストでドキュメントを曎新", "description": "既存ドキュメントのテキストコンテンツ、名前、たたは凊理蚭定を曎新したす。コンテンツが倉曎された堎合はむンデックスが再トリガヌされたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", - "operationId": "updateDocumentByTextJa", + "operationId": "updateDocumentByText", "parameters": [ { "name": "dataset_id", @@ -2304,7 +2304,7 @@ ], "summary": "ファむルでドキュメントを曎新", "description": "新しいファむルをアップロヌドしお既存のドキュメントを曎新したす。むンデックスが再トリガヌされたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", - "operationId": "updateDocumentByFileJa", + "operationId": "updateDocumentByFile", "parameters": [ { "name": "dataset_id", @@ -2585,7 +2585,7 @@ ], "summary": "ドキュメントステヌタスを䞀括曎新", "description": "耇数のドキュメントを䞀括で有効化、無効化、アヌカむブ、たたはアヌカむブ解陀したす。", - "operationId": "batchUpdateDocumentStatusJa", + "operationId": "batchUpdateDocumentStatus", "parameters": [ { "name": "dataset_id", @@ -2721,7 +2721,7 @@ ], "summary": "ドキュメントにチャンクを远加", "description": "ドキュメント内に 1 ぀以䞊のチャンクを䜜成したす。各チャンクにはオプションのキヌワヌドず回答フィヌルドQA モヌドドキュメント甚を含めるこずができたす。", - "operationId": "createChunksJa", + "operationId": "createSegments", "parameters": [ { "name": "dataset_id", @@ -2889,7 +2889,7 @@ ], "summary": "ドキュメントからチャンクを取埗", "description": "ドキュメント内のチャンクのペヌゞネヌションリストを返したす。キヌワヌドずステヌタスによるフィルタリングをサポヌトしおいたす。", - "operationId": "listChunksJa", + "operationId": "listSegments", "parameters": [ { "name": "dataset_id", @@ -3047,7 +3047,7 @@ ], "summary": "ドキュメント内のチャンク詳现を取埗", "description": "特定のチャンクの詳现情報内容、キヌワヌド、むンデックスステヌタスを含むを取埗したす。", - "operationId": "getChunkJa", + "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", @@ -3149,7 +3149,7 @@ ], "summary": "ドキュメント内のチャンクを曎新", "description": "チャンクのコンテンツ、キヌワヌド、たたは回答を曎新したす。倉曎されたチャンクのむンデックス䜜成が再トリガヌされたす。", - "operationId": "updateChunkJa", + "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", @@ -3308,7 +3308,7 @@ ], "summary": "ドキュメント内のチャンクを削陀", "description": "ドキュメントからチャンクを完党に削陀したす。", - "operationId": "deleteChunkJa", + "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", @@ -3355,7 +3355,7 @@ ], "summary": "子チャンクを䜜成", "description": "芪チャンクの䞋に子チャンクを䜜成したす。`hierarchical_model` チャンキングモヌドを䜿甚しおいるドキュメントでのみ利甚可胜です。", - "operationId": "createChildChunkJa", + "operationId": "createChildChunk", "parameters": [ { "name": "dataset_id", @@ -3465,7 +3465,7 @@ ], "summary": "子チャンクを取埗", "description": "特定の芪チャンク配䞋の子チャンクのペヌゞネヌションリストを返したす。", - "operationId": "listChildChunksJa", + "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", @@ -3594,7 +3594,7 @@ ], "summary": "子チャンクを曎新", "description": "既存の子チャンクのコンテンツを曎新したす。", - "operationId": "updateChildChunkJa", + "operationId": "updateChildChunk", "parameters": [ { "name": "dataset_id", @@ -3714,7 +3714,7 @@ ], "summary": "子チャンクを削陀", "description": "芪チャンクから子チャンクを完党に削陀したす。", - "operationId": "deleteChildChunkJa", + "operationId": "deleteChildChunk", "parameters": [ { "name": "dataset_id", @@ -3788,7 +3788,7 @@ ], "summary": "ナレッゞベヌスからチャンクを取埗 / テスト怜玢", "description": "ナレッゞベヌスに察しお怜玢ク゚リを実行し、最も関連性の高いチャンクを取埗したす。この゚ンドポむントは本番環境の怜玢ずテスト怜玢の䞡方に䜿甚できたす。", - "operationId": "searchKnowledgeBaseJa", + "operationId": "retrieveSegments", "parameters": [ { "name": "dataset_id", @@ -4257,7 +4257,7 @@ ], "summary": "ナレッゞベヌスタグを䜜成", "description": "ナレッゞベヌスを敎理するための新しいタグを䜜成したす。", - "operationId": "createKnowledgeTagJa", + "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { @@ -4328,7 +4328,7 @@ ], "summary": "ナレッゞベヌスタグリストを取埗", "description": "ワヌクスペヌス内のすべおのナレッゞベヌスタグのリストを返したす。", - "operationId": "listKnowledgeTagsJa", + "operationId": "getKnowledgeTags", "responses": { "200": { "description": "タグのリストです。", @@ -4383,7 +4383,7 @@ ], "summary": "ナレッゞベヌスタグを倉曎", "description": "既存のナレッゞベヌスタグの名前を倉曎したす。", - "operationId": "updateKnowledgeTagJa", + "operationId": "updateKnowledgeTag", "requestBody": { "required": true, "content": { @@ -4459,7 +4459,7 @@ ], "summary": "ナレッゞベヌスタグを削陀", "description": "ナレッゞベヌスタグを完党に削陀したす。タグ付けされたナレッゞベヌス自䜓は削陀されたせん。", - "operationId": "deleteKnowledgeTagJa", + "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, "content": { @@ -4493,7 +4493,7 @@ ], "summary": "タグをデヌタセットにバむンド", "description": "ナレッゞベヌスに 1 ぀以䞊のタグをバむンドしたす。ナレッゞベヌスには耇数のタグを蚭定できたす。", - "operationId": "bindKnowledgeTagsJa", + "operationId": "bindTagsToDataset", "requestBody": { "required": true, "content": { @@ -4536,7 +4536,7 @@ ], "summary": "タグずデヌタセットのバむンドを解陀", "description": "ナレッゞベヌスからタグバむンディングを削陀したす。", - "operationId": "unbindKnowledgeTagJa", + "operationId": "unbindTagFromDataset", "requestBody": { "required": true, "content": { @@ -4575,7 +4575,7 @@ ], "summary": "ナレッゞベヌスにバむンドされたタグを取埗", "description": "特定のナレッゞベヌスにバむンドされたタグのリストを返したす。", - "operationId": "getKnowledgeBaseTagsJa", + "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", diff --git a/ja/api-reference/openapi_workflow.json b/ja/api-reference/openapi_workflow.json index a16d655cd..d5b0074db 100644 --- a/ja/api-reference/openapi_workflow.json +++ b/ja/api-reference/openapi_workflow.json @@ -27,7 +27,7 @@ "post": { "summary": "ワヌクフロヌを実行", "description": "ワヌクフロヌを実行したす。公開枈みのワヌクフロヌがないず実行できたせん。", - "operationId": "runWorkflowJa", + "operationId": "executeWorkflowJp", "tags": [ "ワヌクフロヌ" ], @@ -444,7 +444,7 @@ "get": { "summary": "ワヌクフロヌ実行詳现を取埗", "description": "ワヌクフロヌ実行 ID に基づいお、ワヌクフロヌタスクの珟圚の実行結果を取埗したす。", - "operationId": "getWorkflowRunDetailJa", + "operationId": "getWorkflowRunDetailJp", "tags": [ "ワヌクフロヌ" ], @@ -533,7 +533,7 @@ "get": { "summary": "ワヌクフロヌログを取埗", "description": "フィルタリングオプション付きでワヌクフロヌ実行ログをペヌゞネヌションで取埗したす。", - "operationId": "listWorkflowLogsJa", + "operationId": "getWorkflowLogsJp", "tags": [ "ワヌクフロヌ" ], @@ -673,7 +673,7 @@ "post": { "summary": "ワヌクフロヌタスクを停止", "description": "実行䞭のワヌクフロヌタスクを停止したす。`streaming` モヌドでのみサポヌトされたす。", - "operationId": "stopWorkflowTaskJa", + "operationId": "stopWorkflowTaskGenerationJp", "tags": [ "ワヌクフロヌ" ], @@ -749,7 +749,7 @@ }, "/files/upload": { "post": { - "operationId": "uploadWorkflowFileJa", + "operationId": "uploadWorkflowFileJp", "tags": [ "ファむル操䜜" ], @@ -972,7 +972,7 @@ }, "/end-users/{end_user_id}": { "get": { - "operationId": "getWorkflowEndUserJa", + "operationId": "getEndUserWorkflowJp", "tags": [ "゚ンドナヌザヌ" ], @@ -1306,7 +1306,7 @@ }, "/info": { "get": { - "operationId": "getWorkflowAppInfoJa", + "operationId": "getWorkflowAppInfoJp", "tags": [ "アプリケヌション蚭定" ], @@ -1343,7 +1343,7 @@ }, "/parameters": { "get": { - "operationId": "getWorkflowAppParametersJa", + "operationId": "getWorkflowAppParametersJp", "tags": [ "アプリケヌション蚭定" ], @@ -1482,7 +1482,7 @@ }, "/site": { "get": { - "operationId": "getWorkflowWebAppSettingsJa", + "operationId": "getWorkflowWebAppSettingsJp", "tags": [ "アプリケヌション蚭定" ], diff --git a/zh/api-reference/openapi_chat.json b/zh/api-reference/openapi_chat.json index 13e79677d..b5c915b9a 100644 --- a/zh/api-reference/openapi_chat.json +++ b/zh/api-reference/openapi_chat.json @@ -27,7 +27,7 @@ "post": { "summary": "发送对话消息", "description": "向应甚发送请求。", - "operationId": "createChatMessageZh", + "operationId": "sendBasicChatMessageCn", "tags": [ "对话消息" ], @@ -274,7 +274,7 @@ "post": { "summary": "停止响应", "description": "停止聊倩消息生成任务。仅圚 `streaming` 暡匏䞋支持。", - "operationId": "stopChatMessageZh", + "operationId": "stopBasicChatMessageGenerationCn", "tags": [ "对话消息" ], @@ -344,7 +344,7 @@ "get": { "summary": "获取䞋䞀蜮建议问题列衚", "description": "获取圓前消息的䞋䞀步建议问题。", - "operationId": "getChatSuggestedQuestionsZh", + "operationId": "getBasicChatSuggestedQuestionsCn", "tags": [ "对话消息" ], @@ -458,7 +458,7 @@ "post": { "summary": "䞊䌠文件", "description": "䞊䌠文件甚于发送消息时䜿甚支持囟片、文档、音频和视频的倚暡态理解。䞊䌠的文件仅䟛圓前终端甚户䜿甚。", - "operationId": "uploadChatFileZh", + "operationId": "uploadBasicChatFileCn", "tags": [ "文件操䜜" ], @@ -593,7 +593,7 @@ "get": { "summary": "䞋蜜文件", "description": "预览或䞋蜜之前通过[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 䞊䌠的文件。仅可访问属于请求应甚内消息的文件。", - "operationId": "previewChatFileZh", + "operationId": "previewBasicChatFileCn", "tags": [ "文件操䜜" ], @@ -681,7 +681,7 @@ "get": { "summary": "获取终端甚户信息", "description": "根据 ID 获取终端甚户信息。圓其他 API 返回终端甚户 ID䟋劂[䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件)返回的 `created_by`时埈有甚。", - "operationId": "getChatEndUserZh", + "operationId": "getEndUserChatCn", "tags": [ "终端甚户" ], @@ -749,7 +749,7 @@ "post": { "summary": "提亀消息反銈", "description": "提亀消息反銈。终端甚户可以对消息评价 `like` 或 `dislike`并可选择提䟛文字反銈。将 `rating` 讟䞺 `null` 可撀销之前提亀的反銈。", - "operationId": "createChatMessageFeedbackZh", + "operationId": "postBasicChatMessageFeedbackCn", "tags": [ "消息反銈" ], @@ -812,7 +812,7 @@ "get": { "summary": "获取应甚的消息反銈", "description": "获取歀应甚䞭所有消息反銈的分页列衚包括终端甚户和管理员反銈。", - "operationId": "listChatFeedbacksZh", + "operationId": "getBasicChatAppFeedbacksCn", "tags": [ "消息反銈" ], @@ -894,7 +894,7 @@ "get": { "summary": "获取䌚话列衚", "description": "获取圓前甚户的䌚话列衚按最近掻跃时闎排序。", - "operationId": "listChatConversationsZh", + "operationId": "getBasicChatConversationsListCn", "tags": [ "䌚话管理" ], @@ -1020,7 +1020,7 @@ "get": { "summary": "获取䌚话历史消息", "description": "以滚劚加蜜的栌匏返回历史聊倩记圕銖页返回最新的 `limit` 条消息即按时闎倒序排列。", - "operationId": "listChatMessagesZh", + "operationId": "getBasicChatConversationHistoryCn", "tags": [ "䌚话管理" ], @@ -1156,7 +1156,7 @@ "get": { "summary": "获取对话变量", "description": "从特定䌚话䞭获取变量。", - "operationId": "listChatConversationVariablesZh", + "operationId": "getBasicChatConversationVariablesCn", "tags": [ "䌚话管理" ], @@ -1284,7 +1284,7 @@ "post": { "summary": "重呜名䌚话", "description": "重呜名䌚话或自劚生成名称。䌚话名称甚于圚支持倚䌚话的客户端䞊星瀺。", - "operationId": "renameChatConversationZh", + "operationId": "renameBasicChatConversationCn", "tags": [ "䌚话管理" ], @@ -1513,7 +1513,7 @@ "delete": { "summary": "删陀䌚话", "description": "删陀䌚话。", - "operationId": "deleteChatConversationZh", + "operationId": "deleteBasicChatConversationCn", "tags": [ "䌚话管理" ], @@ -1597,7 +1597,7 @@ "post": { "summary": "语音蜬文字", "description": "将音频文件蜬换䞺文字。支持的栌匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。文件倧小限制䞺 `30 MB`。", - "operationId": "chatAudioToTextZh", + "operationId": "basicChatAudioToTextCn", "tags": [ "语音䞎文字蜬换" ], @@ -1753,7 +1753,7 @@ "post": { "summary": "文字蜬语音", "description": "将文字蜬换䞺语音。", - "operationId": "chatTextToAudioZh", + "operationId": "basicChatTextToAudioCn", "tags": [ "语音䞎文字蜬换" ], @@ -1863,7 +1863,7 @@ "get": { "summary": "获取应甚基本信息", "description": "获取应甚的基本信息包括名称、描述、标筟和暡匏。", - "operationId": "getChatAppInfoZh", + "operationId": "getBasicChatAppInfoCn", "tags": [ "应甚配眮" ], @@ -1900,7 +1900,7 @@ "get": { "summary": "获取应甚参数", "description": "获取应甚的蟓入衚单配眮包括功胜匀关、蟓入参数名称、类型和默讀倌。", - "operationId": "getChatAppParametersZh", + "operationId": "getBasicChatAppParametersCn", "tags": [ "应甚配眮" ], @@ -2003,7 +2003,7 @@ "get": { "summary": "获取应甚元数据", "description": "获取应甚的元数据包括工具囟标和其他配眮诊情。", - "operationId": "getChatAppMetaZh", + "operationId": "getBasicChatAppMetaCn", "tags": [ "应甚配眮" ], @@ -2039,7 +2039,7 @@ "get": { "summary": "获取应甚 WebApp 讟眮", "description": "获取应甚的 WebApp 讟眮包括站点配眮、䞻题和自定义选项。", - "operationId": "getChatWebAppSettingsZh", + "operationId": "getBasicChatWebAppSettingsCn", "tags": [ "应甚配眮" ], diff --git a/zh/api-reference/openapi_chatflow.json b/zh/api-reference/openapi_chatflow.json index 36964d91e..c0426f212 100644 --- a/zh/api-reference/openapi_chatflow.json +++ b/zh/api-reference/openapi_chatflow.json @@ -27,7 +27,7 @@ "post": { "summary": "发送对话消息", "description": "向对话型应甚发送请求。", - "operationId": "createChatflowMessageZh", + "operationId": "sendChatMessageCn", "tags": [ "对话消息" ], @@ -298,7 +298,7 @@ "post": { "summary": "停止响应", "description": "停止聊倩消息生成任务。仅圚 `streaming` 暡匏䞋支持。", - "operationId": "stopChatflowMessageZh", + "operationId": "stopChatMessageGenerationCn", "tags": [ "对话消息" ], @@ -368,7 +368,7 @@ "get": { "summary": "获取䞋䞀蜮建议问题列衚", "description": "获取圓前消息的䞋䞀步建议问题。", - "operationId": "getChatflowSuggestedQuestionsZh", + "operationId": "getSuggestedQuestionsCn", "tags": [ "对话消息" ], @@ -480,7 +480,7 @@ }, "/files/upload": { "post": { - "operationId": "uploadChatflowFileZh", + "operationId": "uploadFileCn", "tags": [ "文件操䜜" ], @@ -615,7 +615,7 @@ }, "/files/{file_id}/preview": { "get": { - "operationId": "previewChatflowFileZh", + "operationId": "previewChatFlowFileCn", "tags": [ "文件操䜜" ], @@ -703,7 +703,7 @@ }, "/end-users/{end_user_id}": { "get": { - "operationId": "getChatflowEndUserZh", + "operationId": "getEndUserChatflowCn", "tags": [ "终端甚户" ], @@ -771,7 +771,7 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "operationId": "createChatflowMessageFeedbackZh", + "operationId": "postMessageFeedbackCn", "tags": [ "消息反銈" ], @@ -834,7 +834,7 @@ }, "/app/feedbacks": { "get": { - "operationId": "listChatflowFeedbacksZh", + "operationId": "getAppFeedbacksCn", "tags": [ "消息反銈" ], @@ -918,7 +918,7 @@ "get": { "summary": "获取䌚话列衚", "description": "获取圓前甚户的䌚话列衚按最近掻跃时闎排序。", - "operationId": "listChatflowConversationsZh", + "operationId": "getConversationsListCn", "tags": [ "䌚话管理" ], @@ -1044,7 +1044,7 @@ "get": { "summary": "获取䌚话历史消息", "description": "以滚劚加蜜的栌匏返回历史聊倩记圕銖页返回最新的 `limit` 条消息即按时闎倒序排列。", - "operationId": "listChatflowMessagesZh", + "operationId": "getConversationHistoryCn", "tags": [ "䌚话管理" ], @@ -1179,7 +1179,7 @@ "get": { "summary": "获取对话变量", "description": "从特定䌚话䞭获取变量。", - "operationId": "listChatflowConversationVariablesZh", + "operationId": "getConversationVariablesCn", "tags": [ "䌚话管理" ], @@ -1307,7 +1307,7 @@ "post": { "summary": "重呜名䌚话", "description": "重呜名䌚话或自劚生成名称。䌚话名称甚于圚支持倚䌚话的客户端䞊星瀺。", - "operationId": "renameChatflowConversationZh", + "operationId": "renameConversationCn", "tags": [ "䌚话管理" ], @@ -1536,7 +1536,7 @@ "delete": { "summary": "删陀䌚话", "description": "删陀䌚话。", - "operationId": "deleteChatflowConversationZh", + "operationId": "deleteConversationCn", "tags": [ "䌚话管理" ], @@ -1618,7 +1618,7 @@ }, "/audio-to-text": { "post": { - "operationId": "chatflowAudioToTextZh", + "operationId": "audioToTextCn", "tags": [ "语音䞎文字蜬换" ], @@ -1774,7 +1774,7 @@ }, "/text-to-audio": { "post": { - "operationId": "chatflowTextToAudioZh", + "operationId": "textToAudioCn", "tags": [ "语音䞎文字蜬换" ], @@ -1884,7 +1884,7 @@ }, "/info": { "get": { - "operationId": "getChatflowAppInfoZh", + "operationId": "getAppInfoCn", "tags": [ "应甚配眮" ], @@ -1921,7 +1921,7 @@ }, "/parameters": { "get": { - "operationId": "getChatflowAppParametersZh", + "operationId": "getAppParametersCn", "tags": [ "应甚配眮" ], @@ -2024,7 +2024,7 @@ }, "/meta": { "get": { - "operationId": "getChatflowAppMetaZh", + "operationId": "getAppMetaCn", "tags": [ "应甚配眮" ], @@ -2060,7 +2060,7 @@ }, "/site": { "get": { - "operationId": "getChatflowWebAppSettingsZh", + "operationId": "getWebAppSettingsCn", "tags": [ "应甚配眮" ], @@ -2122,7 +2122,7 @@ "post": { "summary": "创建标泚", "description": "创建新的标泚。标泚提䟛预定义的问答对应甚可以盎接匹配并返回而无需生成回倍。", - "operationId": "createChatflowAnnotationZh", + "operationId": "createAnnotationCn", "tags": [ "标泚管理" ], @@ -2173,7 +2173,7 @@ "get": { "summary": "获取标泚列衚", "description": "获取应甚的标泚分页列衚。支持关键词搜玢筛选。", - "operationId": "listChatflowAnnotationsZh", + "operationId": "getAnnotationListCn", "tags": [ "标泚管理" ], @@ -2246,7 +2246,7 @@ "put": { "summary": "曎新标泚", "description": "曎新现有标泚的问题和回答。", - "operationId": "updateChatflowAnnotationZh", + "operationId": "updateAnnotationCn", "tags": [ "标泚管理" ], @@ -2343,7 +2343,7 @@ "delete": { "summary": "删陀标泚", "description": "删陀标泚及其关联的呜䞭历史。", - "operationId": "deleteChatflowAnnotationZh", + "operationId": "deleteAnnotationCn", "tags": [ "标泚管理" ], @@ -2404,7 +2404,7 @@ "post": { "summary": "配眮标泚回倍", "description": "启甚或犁甚标泚回倍功胜。启甚时需芁配眮嵌入暡型。匂步执行——䜿甚 [查询标泚回倍配眮任务状态](/api-reference/标泚管理/查询标泚回倍配眮任务状态) 跟螪进床。", - "operationId": "setChatflowAnnotationReplyZh", + "operationId": "initialAnnotationReplySettingsCn", "tags": [ "标泚管理" ], @@ -2470,7 +2470,7 @@ "get": { "summary": "查询标泚回倍配眮任务状态", "description": "获取由 [配眮标泚回倍](/api-reference/标泚管理/配眮标泚回倍) 发起的匂步标泚回倍配眮任务的状态。", - "operationId": "getChatflowAnnotationReplyStatusZh", + "operationId": "getInitialAnnotationReplySettingsStatusCn", "tags": [ "标泚管理" ], diff --git a/zh/api-reference/openapi_completion.json b/zh/api-reference/openapi_completion.json index b3943ec07..2facc54c9 100644 --- a/zh/api-reference/openapi_completion.json +++ b/zh/api-reference/openapi_completion.json @@ -27,7 +27,7 @@ "post": { "summary": "发送消息", "description": "向文本生成型应甚发送请求。", - "operationId": "createCompletionMessageZh", + "operationId": "createCompletionMessage", "tags": [ "文本生成" ], @@ -216,7 +216,7 @@ "post": { "summary": "停止响应", "description": "停止文本生成消息生成任务。仅圚 `streaming` 暡匏䞋支持。", - "operationId": "stopCompletionMessageZh", + "operationId": "stopCompletionGeneration", "tags": [ "文本生成" ], @@ -284,7 +284,7 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "operationId": "createCompletionMessageFeedbackZh", + "operationId": "postMessageFeedback", "tags": [ "消息反銈" ], @@ -347,7 +347,7 @@ }, "/app/feedbacks": { "get": { - "operationId": "listCompletionFeedbacksZh", + "operationId": "getAppFeedbacks", "tags": [ "消息反銈" ], @@ -429,7 +429,7 @@ }, "/files/upload": { "post": { - "operationId": "uploadCompletionFileZh", + "operationId": "uploadFile", "tags": [ "文件操䜜" ], @@ -652,7 +652,7 @@ }, "/end-users/{end_user_id}": { "get": { - "operationId": "getCompletionEndUserZh", + "operationId": "getEndUserCompletionCn", "tags": [ "终端甚户" ], @@ -876,7 +876,7 @@ }, "/text-to-audio": { "post": { - "operationId": "completionTextToAudioZh", + "operationId": "textToAudio", "tags": [ "语音䞎文字蜬换" ], @@ -986,7 +986,7 @@ }, "/info": { "get": { - "operationId": "getCompletionAppInfoZh", + "operationId": "getAppInfo", "tags": [ "应甚配眮" ], @@ -1023,7 +1023,7 @@ }, "/parameters": { "get": { - "operationId": "getCompletionAppParametersZh", + "operationId": "getAppParameters", "tags": [ "应甚配眮" ], @@ -1162,7 +1162,7 @@ }, "/site": { "get": { - "operationId": "getCompletionWebAppSettingsZh", + "operationId": "getWebAppSettings", "tags": [ "应甚配眮" ], diff --git a/zh/api-reference/openapi_knowledge.json b/zh/api-reference/openapi_knowledge.json index f99c73461..65f945994 100644 --- a/zh/api-reference/openapi_knowledge.json +++ b/zh/api-reference/openapi_knowledge.json @@ -60,7 +60,7 @@ ], "summary": "创建空知识库", "description": "创建新的空知识库。创建后䜿甚 [通过文本创建文档](/api-reference/文档/从文本创建文档) 或 [通过文件创建文档](/api-reference/文档/从文件创建文档) 添加文档。", - "operationId": "createKnowledgeBaseZh", + "operationId": "createDataset", "requestBody": { "required": true, "content": { @@ -249,7 +249,7 @@ ], "summary": "获取知识库列衚", "description": "返回知识库的分页列衚。支持按关键词和标筟筛选。", - "operationId": "listKnowledgeBasesZh", + "operationId": "listDatasets", "parameters": [ { "name": "page", @@ -408,7 +408,7 @@ ], "summary": "获取知识库诊情", "description": "获取指定知识库的诊细信息包括嵌入暡型、检玢配眮和文档统计信息。", - "operationId": "getKnowledgeBaseZh", + "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", @@ -528,7 +528,7 @@ ], "summary": "曎新知识库", "description": "曎新现有知识库的名称、描述、权限或检玢讟眮。仅曎新请求䜓䞭提䟛的字段。", - "operationId": "updateKnowledgeBaseZh", + "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", @@ -740,7 +740,7 @@ ], "summary": "删陀知识库", "description": "氞久删陀知识库及其所有文档。该知识库䞍胜被任䜕应甚正圚䜿甚。", - "operationId": "deleteKnowledgeBaseZh", + "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", @@ -801,7 +801,7 @@ ], "summary": "从文本创建文档", "description": "通过纯文本内容创建文档。文档将匂步倄理——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", - "operationId": "createDocumentByTextZh", + "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", @@ -1049,7 +1049,7 @@ ], "summary": "从文件创建文档", "description": "通过䞊䌠文件创建文档。支持垞见文档栌匏PDF、TXT、DOCX 等。倄理过皋䞺匂步——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", - "operationId": "createDocumentByFileZh", + "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", @@ -1252,7 +1252,7 @@ ], "summary": "获取知识库的文档列衚", "description": "返回知识库䞭的文档分页列衚。支持按关键词和玢匕状态进行筛选。", - "operationId": "listDocumentsZh", + "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", @@ -1422,7 +1422,7 @@ ], "summary": "获取文档诊情", "description": "获取指定文档的诊细信息包括玢匕状态、元数据和倄理统计信息。", - "operationId": "getDocumentZh", + "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", @@ -1741,7 +1741,7 @@ ], "summary": "删陀文档", "description": "从知识库䞭氞久删陀文档及其所有分段。", - "operationId": "deleteDocumentZh", + "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", @@ -1921,7 +1921,7 @@ ], "summary": "获取文档嵌入状态进床", "description": "检查批量文档的玢匕进床。返回每䞪文档的圓前倄理阶段和分段完成计数。请蜮询歀接口盎到 `indexing_status` 变䞺 `completed` 或 `error`。状态按以䞋顺序掚进`waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`。", - "operationId": "getDocumentIndexingStatusZh", + "operationId": "getDocumentIndexingStatus", "parameters": [ { "name": "dataset_id", @@ -2070,7 +2070,7 @@ ], "summary": "甚文本曎新文档", "description": "曎新现有文档的文本内容、名称或倄理配眮。内容变曎时将重新觊发玢匕——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", - "operationId": "updateDocumentByTextZh", + "operationId": "updateDocumentByText", "parameters": [ { "name": "dataset_id", @@ -2304,7 +2304,7 @@ ], "summary": "甚文件曎新文档", "description": "通过䞊䌠新文件曎新现有文档。将重新觊发玢匕——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", - "operationId": "updateDocumentByFileZh", + "operationId": "updateDocumentByFile", "parameters": [ { "name": "dataset_id", @@ -2585,7 +2585,7 @@ ], "summary": "批量曎新文档状态", "description": "批量启甚、犁甚、園档或取消園档倚䞪文档。", - "operationId": "batchUpdateDocumentStatusZh", + "operationId": "batchUpdateDocumentStatus", "parameters": [ { "name": "dataset_id", @@ -2721,7 +2721,7 @@ ], "summary": "向文档添加分段", "description": "圚文档䞭创建䞀䞪或倚䞪分段。每䞪分段可以包含可选的关键词和答案字段适甚于 QA 暡匏文档。", - "operationId": "createChunksZh", + "operationId": "createSegments", "parameters": [ { "name": "dataset_id", @@ -2889,7 +2889,7 @@ ], "summary": "从文档获取分段", "description": "返回文档内分段的分页列衚。支持按关键词和状态筛选。", - "operationId": "listChunksZh", + "operationId": "listSegments", "parameters": [ { "name": "dataset_id", @@ -3047,7 +3047,7 @@ ], "summary": "获取文档䞭的分段诊情", "description": "获取指定分段的诊细信息包括内容、关键词和玢匕状态。", - "operationId": "getChunkZh", + "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", @@ -3149,7 +3149,7 @@ ], "summary": "曎新文档䞭的分段", "description": "曎新分段的内容、关键词或回答。修改后的分段将重新觊发玢匕。", - "operationId": "updateChunkZh", + "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", @@ -3308,7 +3308,7 @@ ], "summary": "删陀文档䞭的分段", "description": "从文档䞭氞久删陀䞀䞪分段。", - "operationId": "deleteChunkZh", + "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", @@ -3355,7 +3355,7 @@ ], "summary": "创建子分段", "description": "圚父分段䞋创建子分段。仅适甚于䜿甚 `hierarchical_model` 分块暡匏的文档。", - "operationId": "createChildChunkZh", + "operationId": "createChildChunk", "parameters": [ { "name": "dataset_id", @@ -3465,7 +3465,7 @@ ], "summary": "获取子分段", "description": "返回特定父分段䞋子分段的分页列衚。", - "operationId": "listChildChunksZh", + "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", @@ -3594,7 +3594,7 @@ ], "summary": "曎新子分段", "description": "曎新现有子分段的内容。", - "operationId": "updateChildChunkZh", + "operationId": "updateChildChunk", "parameters": [ { "name": "dataset_id", @@ -3714,7 +3714,7 @@ ], "summary": "删陀子分段", "description": "从父分段䞭氞久删陀䞀䞪子分段。", - "operationId": "deleteChildChunkZh", + "operationId": "deleteChildChunk", "parameters": [ { "name": "dataset_id", @@ -3788,7 +3788,7 @@ ], "summary": "从知识库检玢分段 / 测试检玢", "description": "对知识库执行搜玢查询检玢最盞关的分段。歀接口可甚于生产环境检玢和测试检玢。", - "operationId": "searchKnowledgeBaseZh", + "operationId": "retrieveSegments", "parameters": [ { "name": "dataset_id", @@ -4257,7 +4257,7 @@ ], "summary": "创建知识库标筟", "description": "创建新标筟以组织知识库。", - "operationId": "createKnowledgeTagZh", + "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { @@ -4328,7 +4328,7 @@ ], "summary": "获取知识库标筟列衚", "description": "返回工䜜区䞭所有知识库标筟的列衚。", - "operationId": "listKnowledgeTagsZh", + "operationId": "getKnowledgeTags", "responses": { "200": { "description": "标筟列衚。", @@ -4383,7 +4383,7 @@ ], "summary": "修改知识库标筟", "description": "重呜名现有的知识库标筟。", - "operationId": "updateKnowledgeTagZh", + "operationId": "updateKnowledgeTag", "requestBody": { "required": true, "content": { @@ -4459,7 +4459,7 @@ ], "summary": "删陀知识库标筟", "description": "氞久删陀知识库标筟。䞍䌚删陀已被标记的知识库。", - "operationId": "deleteKnowledgeTagZh", + "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, "content": { @@ -4493,7 +4493,7 @@ ], "summary": "绑定标筟到知识库", "description": "将䞀䞪或倚䞪标筟绑定到知识库。䞀䞪知识库可以有倚䞪标筟。", - "operationId": "bindKnowledgeTagsZh", + "operationId": "bindTagsToDataset", "requestBody": { "required": true, "content": { @@ -4536,7 +4536,7 @@ ], "summary": "解陀标筟䞎知识库的绑定", "description": "移陀知识库的标筟绑定。", - "operationId": "unbindKnowledgeTagZh", + "operationId": "unbindTagFromDataset", "requestBody": { "required": true, "content": { @@ -4575,7 +4575,7 @@ ], "summary": "获取知识库绑定的标筟", "description": "返回绑定到特定知识库的标筟列衚。", - "operationId": "getKnowledgeBaseTagsZh", + "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", diff --git a/zh/api-reference/openapi_workflow.json b/zh/api-reference/openapi_workflow.json index 0e1771783..1996fb34a 100644 --- a/zh/api-reference/openapi_workflow.json +++ b/zh/api-reference/openapi_workflow.json @@ -27,7 +27,7 @@ "post": { "summary": "执行工䜜流", "description": "执行工䜜流。没有已发垃的工䜜流时无法执行。", - "operationId": "runWorkflowZh", + "operationId": "executeWorkflowCn", "tags": [ "工䜜流" ], @@ -444,7 +444,7 @@ "get": { "summary": "获取工䜜流执行情况", "description": "根据工䜜流执行 ID 获取工䜜流任务的圓前执行结果。", - "operationId": "getWorkflowRunDetailZh", + "operationId": "getWorkflowRunDetailCn", "tags": [ "工䜜流" ], @@ -533,7 +533,7 @@ "get": { "summary": "获取工䜜流日志", "description": "获取分页的工䜜流执行日志支持筛选选项。", - "operationId": "listWorkflowLogsZh", + "operationId": "getWorkflowLogsCn", "tags": [ "工䜜流" ], @@ -673,7 +673,7 @@ "post": { "summary": "停止工䜜流任务", "description": "停止正圚运行的工䜜流任务。仅圚 `streaming` 暡匏䞋支持。", - "operationId": "stopWorkflowTaskZh", + "operationId": "stopWorkflowTaskGenerationCn", "tags": [ "工䜜流" ], @@ -749,7 +749,7 @@ }, "/files/upload": { "post": { - "operationId": "uploadWorkflowFileZh", + "operationId": "uploadWorkflowFileCn", "tags": [ "文件操䜜" ], @@ -972,7 +972,7 @@ }, "/end-users/{end_user_id}": { "get": { - "operationId": "getWorkflowEndUserZh", + "operationId": "getEndUserWorkflowCn", "tags": [ "终端甚户" ], @@ -1306,7 +1306,7 @@ }, "/info": { "get": { - "operationId": "getWorkflowAppInfoZh", + "operationId": "getWorkflowAppInfoCn", "tags": [ "应甚配眮" ], @@ -1343,7 +1343,7 @@ }, "/parameters": { "get": { - "operationId": "getWorkflowAppParametersZh", + "operationId": "getWorkflowAppParametersCn", "tags": [ "应甚配眮" ], @@ -1482,7 +1482,7 @@ }, "/site": { "get": { - "operationId": "getWorkflowWebAppSettingsZh", + "operationId": "getWorkflowWebAppSettingsCn", "tags": [ "应甚配眮" ], From 106f9725f753cc945fdf9992171206d6970cd17c Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Fri, 20 Mar 2026 22:17:52 +0800 Subject: [PATCH 5/6] complete the missing descriptions --- en/api-reference/openapi_chatflow.json | 9 +++-- en/api-reference/openapi_knowledge.json | 35 ++++++++++++----- en/api-reference/openapi_workflow.json | 37 ++++++++++++------ ja/api-reference/openapi_chatflow.json | 9 +++-- ja/api-reference/openapi_knowledge.json | 51 ++++++++++++++++--------- ja/api-reference/openapi_workflow.json | 39 ++++++++++++------- zh/api-reference/openapi_chatflow.json | 9 +++-- zh/api-reference/openapi_knowledge.json | 51 ++++++++++++++++--------- zh/api-reference/openapi_workflow.json | 39 ++++++++++++------- 9 files changed, 189 insertions(+), 90 deletions(-) diff --git a/en/api-reference/openapi_chatflow.json b/en/api-reference/openapi_chatflow.json index c02b6b410..fc075f437 100644 --- a/en/api-reference/openapi_chatflow.json +++ b/en/api-reference/openapi_chatflow.json @@ -5887,13 +5887,16 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "format": "uuid", + "description": "Account ID." }, "name": { - "type": "string" + "type": "string", + "description": "Account display name." }, "email": { - "type": "string" + "type": "string", + "description": "Account email address." } } }, diff --git a/en/api-reference/openapi_knowledge.json b/en/api-reference/openapi_knowledge.json index d2cc0e2f8..a51f19f73 100644 --- a/en/api-reference/openapi_knowledge.json +++ b/en/api-reference/openapi_knowledge.json @@ -1569,6 +1569,7 @@ }, "doc_metadata": { "type": "array", + "description": "Custom metadata key-value pairs for this document.", "items": { "type": "object", "properties": { @@ -1953,6 +1954,7 @@ "properties": { "data": { "type": "array", + "description": "List of indexing status entries.", "items": { "type": "object", "properties": { @@ -1986,15 +1988,18 @@ }, "paused_at": { "type": "number", - "nullable": true + "nullable": true, + "description": "Timestamp when indexing was paused. `null` if not paused." }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "Error message if indexing failed. `null` if no error." }, "stopped_at": { "type": "number", - "nullable": true + "nullable": true, + "description": "Timestamp when indexing was stopped. `null` if not stopped." }, "completed_segments": { "type": "integer", @@ -2800,6 +2805,7 @@ "properties": { "data": { "type": "array", + "description": "List of created chunks.", "items": { "$ref": "#/components/schemas/Segment" } @@ -2961,6 +2967,7 @@ "properties": { "data": { "type": "array", + "description": "List of chunks.", "items": { "$ref": "#/components/schemas/Segment" } @@ -3536,6 +3543,7 @@ "properties": { "data": { "type": "array", + "description": "List of child chunks.", "items": { "$ref": "#/components/schemas/ChildChunk" } @@ -3871,6 +3879,7 @@ }, "records": { "type": "array", + "description": "List of matched retrieval records.", "items": { "type": "object", "properties": { @@ -4598,6 +4607,7 @@ "properties": { "data": { "type": "array", + "description": "List of tags bound to this knowledge base.", "items": { "type": "object", "properties": { @@ -4753,6 +4763,7 @@ "properties": { "doc_metadata": { "type": "array", + "description": "List of metadata field definitions.", "items": { "type": "object", "properties": { @@ -5226,10 +5237,12 @@ "description": "Localized display name of the provider.", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "English display name." }, "zh_Hans": { - "type": "string" + "type": "string", + "description": "Chinese display name." } } }, @@ -5238,7 +5251,8 @@ "description": "URL of the provider's small icon.", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "Small icon URL." } } }, @@ -5247,7 +5261,8 @@ "description": "URL of the provider's large icon.", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "Large icon URL." } } }, @@ -5270,10 +5285,12 @@ "description": "Localized display name of the model.", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "English model name." }, "zh_Hans": { - "type": "string" + "type": "string", + "description": "Chinese model name." } } }, diff --git a/en/api-reference/openapi_workflow.json b/en/api-reference/openapi_workflow.json index d61975f15..fec7d94cd 100644 --- a/en/api-reference/openapi_workflow.json +++ b/en/api-reference/openapi_workflow.json @@ -1698,6 +1698,7 @@ "properties": { "event": { "type": "string", + "description": "The type of streaming event.", "enum": [ "workflow_started", "node_started", @@ -3016,13 +3017,16 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "format": "uuid", + "description": "Account ID." }, "name": { - "type": "string" + "type": "string", + "description": "Account display name." }, "email": { - "type": "string" + "type": "string", + "description": "Account email address." } } }, @@ -3221,7 +3225,8 @@ "description": "Configuration for suggested questions after an answer.", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Whether this feature is enabled." } } }, @@ -3230,7 +3235,8 @@ "description": "Speech-to-text feature configuration.", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Whether this feature is enabled." } } }, @@ -3239,13 +3245,16 @@ "description": "Text-to-speech feature configuration.", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Whether this feature is enabled." }, "voice": { - "type": "string" + "type": "string", + "description": "Voice identifier for TTS." }, "language": { - "type": "string" + "type": "string", + "description": "Language for TTS." } } }, @@ -3254,7 +3263,8 @@ "description": "Knowledge retrieval citation resource configuration.", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Whether this feature is enabled." } } }, @@ -3263,7 +3273,8 @@ "description": "Annotation reply feature configuration.", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Whether this feature is enabled." } } }, @@ -3272,7 +3283,8 @@ "description": "More-like-this feature configuration.", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Whether this feature is enabled." } } }, @@ -3281,7 +3293,8 @@ "description": "Content moderation feature configuration.", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Whether this feature is enabled." } } }, diff --git a/ja/api-reference/openapi_chatflow.json b/ja/api-reference/openapi_chatflow.json index 4d6321983..bd001995b 100644 --- a/ja/api-reference/openapi_chatflow.json +++ b/ja/api-reference/openapi_chatflow.json @@ -5887,13 +5887,16 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "format": "uuid", + "description": "アカりント ID。" }, "name": { - "type": "string" + "type": "string", + "description": "アカりント衚瀺名。" }, "email": { - "type": "string" + "type": "string", + "description": "アカりントメヌルアドレス。" } } }, diff --git a/ja/api-reference/openapi_knowledge.json b/ja/api-reference/openapi_knowledge.json index 9e65b0a08..a36e83ff8 100644 --- a/ja/api-reference/openapi_knowledge.json +++ b/ja/api-reference/openapi_knowledge.json @@ -1589,7 +1589,8 @@ "description": "このドキュメントのメタデヌタフィヌルド倀。" } } - } + }, + "description": "このドキュメントのカスタムメタデヌタキヌバリュヌペア。" }, "completed_at": { "type": "number", @@ -1986,15 +1987,18 @@ }, "paused_at": { "type": "number", - "nullable": true + "nullable": true, + "description": "むンデキシングが䞀時停止されたタむムスタンプ。䞀時停止されおいない堎合は `null`。" }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "むンデキシングが倱敗した堎合の゚ラヌメッセヌゞ。゚ラヌがない堎合は `null`。" }, "stopped_at": { "type": "number", - "nullable": true + "nullable": true, + "description": "むンデキシングが停止されたタむムスタンプ。停止されおいない堎合は `null`。" }, "completed_segments": { "type": "integer", @@ -2005,7 +2009,8 @@ "description": "むンデックス察象のチャンクの合蚈数です。" } } - } + }, + "description": "むンデキシングステヌタス゚ントリのリスト。" } } }, @@ -2802,7 +2807,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/Segment" - } + }, + "description": "䜜成されたチャンクのリスト。" }, "doc_form": { "type": "string", @@ -2963,7 +2969,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/Segment" - } + }, + "description": "チャンクのリスト。" }, "doc_form": { "type": "string", @@ -3538,7 +3545,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/ChildChunk" - } + }, + "description": "子チャンクのリスト。" }, "total": { "type": "integer", @@ -4078,7 +4086,8 @@ "description": "芁玄むンデックス経由で取埗された堎合の芁玄コンテンツです。" } } - } + }, + "description": "䞀臎した怜玢レコヌドのリスト。" } } }, @@ -4610,7 +4619,8 @@ "description": "タグの衚瀺名です。" } } - } + }, + "description": "このナレッゞベヌスにバむンドされたタグのリスト。" }, "total": { "type": "integer", @@ -4773,7 +4783,8 @@ "description": "このメタデヌタフィヌルドを䜿甚しおいるドキュメント数です。" } } - } + }, + "description": "メタデヌタフィヌルド定矩のリスト。" }, "built_in_field_enabled": { "type": "boolean", @@ -5226,10 +5237,12 @@ "description": "プロバむダヌのロヌカラむズ衚瀺名です。", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "英語衚瀺名。" }, "zh_Hans": { - "type": "string" + "type": "string", + "description": "䞭囜語衚瀺名。" } } }, @@ -5238,7 +5251,8 @@ "description": "プロバむダヌの小アむコンの URL です。", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "小アむコン URL。" } } }, @@ -5247,7 +5261,8 @@ "description": "プロバむダヌの倧アむコンの URL です。", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "倧アむコン URL。" } } }, @@ -5270,10 +5285,12 @@ "description": "モデルのロヌカラむズ衚瀺名です。", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "英語モデル名。" }, "zh_Hans": { - "type": "string" + "type": "string", + "description": "䞭囜語モデル名。" } } }, diff --git a/ja/api-reference/openapi_workflow.json b/ja/api-reference/openapi_workflow.json index d5b0074db..a74f3e831 100644 --- a/ja/api-reference/openapi_workflow.json +++ b/ja/api-reference/openapi_workflow.json @@ -1721,7 +1721,8 @@ "human_input_form_timeout", "error", "ping" - ] + ], + "description": "ストリヌミングむベントの皮類。" } }, "discriminator": { @@ -3016,13 +3017,16 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "format": "uuid", + "description": "アカりント ID。" }, "name": { - "type": "string" + "type": "string", + "description": "アカりント衚瀺名。" }, "email": { - "type": "string" + "type": "string", + "description": "アカりントメヌルアドレス。" } } }, @@ -3221,7 +3225,8 @@ "description": "回答埌の提案質問の蚭定です。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "この機胜が有効かどうか。" } } }, @@ -3230,7 +3235,8 @@ "description": "音声テキスト倉換機胜の蚭定です。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "この機胜が有効かどうか。" } } }, @@ -3239,13 +3245,16 @@ "description": "テキスト音声倉換機胜の蚭定です。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "この機胜が有効かどうか。" }, "voice": { - "type": "string" + "type": "string", + "description": "TTS 音声識別子。" }, "language": { - "type": "string" + "type": "string", + "description": "TTS 蚀語。" } } }, @@ -3254,7 +3263,8 @@ "description": "ナレッゞ怜玢の匕甚リ゜ヌス蚭定です。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "この機胜が有効かどうか。" } } }, @@ -3263,7 +3273,8 @@ "description": "アノテヌション返信機胜の蚭定です。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "この機胜が有効かどうか。" } } }, @@ -3272,7 +3283,8 @@ "description": "類䌌コンテンツ機胜の蚭定です。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "この機胜が有効かどうか。" } } }, @@ -3281,7 +3293,8 @@ "description": "コンテンツモデレヌション機胜の蚭定です。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "この機胜が有効かどうか。" } } }, diff --git a/zh/api-reference/openapi_chatflow.json b/zh/api-reference/openapi_chatflow.json index c0426f212..edd459041 100644 --- a/zh/api-reference/openapi_chatflow.json +++ b/zh/api-reference/openapi_chatflow.json @@ -5887,13 +5887,16 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "format": "uuid", + "description": "莊户 ID。" }, "name": { - "type": "string" + "type": "string", + "description": "莊户星瀺名称。" }, "email": { - "type": "string" + "type": "string", + "description": "莊户邮箱地址。" } } }, diff --git a/zh/api-reference/openapi_knowledge.json b/zh/api-reference/openapi_knowledge.json index 65f945994..b888ccd54 100644 --- a/zh/api-reference/openapi_knowledge.json +++ b/zh/api-reference/openapi_knowledge.json @@ -1589,7 +1589,8 @@ "description": "歀文档的元数据字段倌。" } } - } + }, + "description": "歀文档的自定义元数据键倌对。" }, "completed_at": { "type": "number", @@ -1986,15 +1987,18 @@ }, "paused_at": { "type": "number", - "nullable": true + "nullable": true, + "description": "玢匕暂停的时闎戳。未暂停时䞺 `null`。" }, "error": { "type": "string", - "nullable": true + "nullable": true, + "description": "玢匕倱莥时的错误信息。无错误时䞺 `null`。" }, "stopped_at": { "type": "number", - "nullable": true + "nullable": true, + "description": "玢匕停止的时闎戳。未停止时䞺 `null`。" }, "completed_segments": { "type": "integer", @@ -2005,7 +2009,8 @@ "description": "埅玢匕的分段总数。" } } - } + }, + "description": "玢匕状态条目列衚。" } } }, @@ -2802,7 +2807,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/Segment" - } + }, + "description": "已创建的分段列衚。" }, "doc_form": { "type": "string", @@ -2963,7 +2969,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/Segment" - } + }, + "description": "分段列衚。" }, "doc_form": { "type": "string", @@ -3538,7 +3545,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/ChildChunk" - } + }, + "description": "子分段列衚。" }, "total": { "type": "integer", @@ -4078,7 +4086,8 @@ "description": "通过摘芁玢匕检玢到的摘芁内容。" } } - } + }, + "description": "匹配的检玢记圕列衚。" } } }, @@ -4610,7 +4619,8 @@ "description": "标筟星瀺名称。" } } - } + }, + "description": "绑定到歀知识库的标筟列衚。" }, "total": { "type": "integer", @@ -4773,7 +4783,8 @@ "description": "䜿甚该元数据字段的文档数量。" } } - } + }, + "description": "元数据字段定义列衚。" }, "built_in_field_enabled": { "type": "boolean", @@ -5226,10 +5237,12 @@ "description": "提䟛商的本地化星瀺名称。", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "英文星瀺名称。" }, "zh_Hans": { - "type": "string" + "type": "string", + "description": "䞭文星瀺名称。" } } }, @@ -5238,7 +5251,8 @@ "description": "提䟛商小囟标的 URL。", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "小囟标 URL。" } } }, @@ -5247,7 +5261,8 @@ "description": "提䟛商倧囟标的 URL。", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "倧囟标 URL。" } } }, @@ -5270,10 +5285,12 @@ "description": "暡型的本地化星瀺名称。", "properties": { "en_US": { - "type": "string" + "type": "string", + "description": "英文暡型名称。" }, "zh_Hans": { - "type": "string" + "type": "string", + "description": "䞭文暡型名称。" } } }, diff --git a/zh/api-reference/openapi_workflow.json b/zh/api-reference/openapi_workflow.json index 1996fb34a..215beae3b 100644 --- a/zh/api-reference/openapi_workflow.json +++ b/zh/api-reference/openapi_workflow.json @@ -1721,7 +1721,8 @@ "human_input_form_timeout", "error", "ping" - ] + ], + "description": "流匏事件的类型。" } }, "discriminator": { @@ -3016,13 +3017,16 @@ "properties": { "id": { "type": "string", - "format": "uuid" + "format": "uuid", + "description": "莊户 ID。" }, "name": { - "type": "string" + "type": "string", + "description": "莊户星瀺名称。" }, "email": { - "type": "string" + "type": "string", + "description": "莊户邮箱地址。" } } }, @@ -3221,7 +3225,8 @@ "description": "回答后建议问题的配眮。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "是吊启甚歀功胜。" } } }, @@ -3230,7 +3235,8 @@ "description": "语音蜬文字功胜配眮。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "是吊启甚歀功胜。" } } }, @@ -3239,13 +3245,16 @@ "description": "文字蜬语音功胜配眮。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "是吊启甚歀功胜。" }, "voice": { - "type": "string" + "type": "string", + "description": "TTS 声音标识笊。" }, "language": { - "type": "string" + "type": "string", + "description": "TTS 语蚀。" } } }, @@ -3254,7 +3263,8 @@ "description": "知识检玢匕甚资源配眮。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "是吊启甚歀功胜。" } } }, @@ -3263,7 +3273,8 @@ "description": "标泚回倍功胜配眮。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "是吊启甚歀功胜。" } } }, @@ -3272,7 +3283,8 @@ "description": "曎倚类䌌掚荐功胜配眮。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "是吊启甚歀功胜。" } } }, @@ -3281,7 +3293,8 @@ "description": "内容审栞功胜配眮。", "properties": { "enabled": { - "type": "boolean" + "type": "boolean", + "description": "是吊启甚歀功胜。" } } }, From 383910986f2fd2adacf97c5a259bf003843e7937 Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Mon, 23 Mar 2026 12:41:11 +0800 Subject: [PATCH 6/6] correct the human input terminology --- en/api-reference/openapi_chat.json | 17 +++-- en/api-reference/openapi_chatflow.json | 11 ++- en/api-reference/openapi_completion.json | 13 +++- en/api-reference/openapi_knowledge.json | 8 +- en/api-reference/openapi_workflow.json | 6 +- ja/api-reference/openapi_chat.json | 57 +++++++------- ja/api-reference/openapi_chatflow.json | 97 +++++++++++++----------- ja/api-reference/openapi_completion.json | 37 +++++---- ja/api-reference/openapi_knowledge.json | 40 +++++----- ja/api-reference/openapi_workflow.json | 46 +++++------ zh/api-reference/openapi_chat.json | 17 +++-- zh/api-reference/openapi_chatflow.json | 49 ++++++------ zh/api-reference/openapi_completion.json | 15 ++-- zh/api-reference/openapi_knowledge.json | 50 ++++++------ zh/api-reference/openapi_workflow.json | 10 +-- 15 files changed, 259 insertions(+), 214 deletions(-) diff --git a/en/api-reference/openapi_chat.json b/en/api-reference/openapi_chat.json index a43a3383c..e8182b82a 100644 --- a/en/api-reference/openapi_chat.json +++ b/en/api-reference/openapi_chat.json @@ -592,7 +592,7 @@ "/files/{file_id}/preview": { "get": { "summary": "Download File", - "description": "Preview or download uploaded files previously uploaded via the [File Upload](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", + "description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", "operationId": "previewChatFile", "tags": [ "Files" @@ -602,7 +602,7 @@ "name": "file_id", "in": "path", "required": true, - "description": "The unique identifier of the file to preview, obtained from the [File Upload](/api-reference/files/upload-file) API response.", + "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.", "schema": { "type": "string", "format": "uuid" @@ -680,7 +680,7 @@ "/end-users/{end_user_id}": { "get": { "summary": "Get End User Info", - "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).", "operationId": "getEndUserChat", "tags": [ "End Users" @@ -2380,7 +2380,7 @@ "/apps/annotation-reply/{action}": { "post": { "summary": "Configure Annotation Reply", - "description": "Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Retrieve Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.", + "description": "Enables or disables the annotation reply feature. Requires embedding model configuration when enabling. Executes asynchronously — use [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress.", "operationId": "initialAnnotationReplySettings", "tags": [ "Annotations" @@ -2623,7 +2623,7 @@ }, "upload_file_id": { "type": "string", - "description": "Uploaded file ID obtained from the [File Upload](/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`)." + "description": "Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`)." } } } @@ -2932,6 +2932,11 @@ "type": "object", "description": "Message end event, streaming has ended.", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, "metadata": { "type": "object", "description": "Metadata including usage and retriever resources.", @@ -4356,7 +4361,7 @@ "job_id": { "type": "string", "format": "uuid", - "description": "Asynchronous job ID. Use with [Retrieve Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress." + "description": "Asynchronous job ID. Use with [Get Annotation Reply Job Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress." }, "job_status": { "type": "string", diff --git a/en/api-reference/openapi_chatflow.json b/en/api-reference/openapi_chatflow.json index fc075f437..4bf1bfa2e 100644 --- a/en/api-reference/openapi_chatflow.json +++ b/en/api-reference/openapi_chatflow.json @@ -620,13 +620,13 @@ "Files" ], "summary": "Download File", - "description": "Preview or download uploaded files previously uploaded via the [File Upload](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", + "description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", "parameters": [ { "name": "file_id", "in": "path", "required": true, - "description": "The unique identifier of the file to preview, obtained from the [File Upload](/api-reference/files/upload-file) API response.", + "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.", "schema": { "type": "string", "format": "uuid" @@ -708,7 +708,7 @@ "End Users" ], "summary": "Get End User Info", - "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).", "parameters": [ { "name": "end_user_id", @@ -3154,6 +3154,11 @@ "type": "object", "description": "Message end event, streaming has ended.", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, "metadata": { "type": "object", "description": "Metadata including usage and retriever resources.", diff --git a/en/api-reference/openapi_completion.json b/en/api-reference/openapi_completion.json index ab95f5f9f..801795a86 100644 --- a/en/api-reference/openapi_completion.json +++ b/en/api-reference/openapi_completion.json @@ -569,13 +569,13 @@ "Files" ], "summary": "Download File", - "description": "Preview or download uploaded files previously uploaded via the [File Upload](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", + "description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", "parameters": [ { "name": "file_id", "in": "path", "required": true, - "description": "The unique identifier of the file to preview, obtained from the [File Upload](/api-reference/files/upload-file) API response.", + "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.", "schema": { "type": "string", "format": "uuid" @@ -657,7 +657,7 @@ "End Users" ], "summary": "Get End User Info", - "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).", "parameters": [ { "name": "end_user_id", @@ -1328,7 +1328,7 @@ }, "upload_file_id": { "type": "string", - "description": "Uploaded file ID, obtained by uploading through the [File Upload](/api-reference/files/upload-file) API in advance (when `transfer_method` is `local_file`)." + "description": "Uploaded file ID, obtained by uploading through the [Upload File](/api-reference/files/upload-file) API in advance (when `transfer_method` is `local_file`)." } }, "anyOf": [ @@ -1512,6 +1512,11 @@ "type": "object", "description": "Message end event, receiving this event means streaming has ended.", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique message ID." + }, "metadata": { "type": "object", "description": "Metadata including usage and retriever resources.", diff --git a/en/api-reference/openapi_knowledge.json b/en/api-reference/openapi_knowledge.json index a51f19f73..a65fa30e7 100644 --- a/en/api-reference/openapi_knowledge.json +++ b/en/api-reference/openapi_knowledge.json @@ -258,7 +258,7 @@ "type": "integer", "default": 1 }, - "description": "Page number." + "description": "Page number to retrieve." }, { "name": "limit", @@ -1271,7 +1271,7 @@ "type": "integer", "default": 1 }, - "description": "Page number." + "description": "Page number to retrieve." }, { "name": "limit", @@ -2924,7 +2924,7 @@ "type": "integer", "default": 1 }, - "description": "Page number." + "description": "Page number to retrieve." }, { "name": "limit", @@ -3512,7 +3512,7 @@ "default": 1, "minimum": 1 }, - "description": "Page number." + "description": "Page number to retrieve." }, { "name": "limit", diff --git a/en/api-reference/openapi_workflow.json b/en/api-reference/openapi_workflow.json index fec7d94cd..756bf9a38 100644 --- a/en/api-reference/openapi_workflow.json +++ b/en/api-reference/openapi_workflow.json @@ -889,13 +889,13 @@ "Files" ], "summary": "Download File", - "description": "Preview or download uploaded files previously uploaded via the [File Upload](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", + "description": "Preview or download uploaded files previously uploaded via the [Upload File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to messages within the requesting application.", "parameters": [ { "name": "file_id", "in": "path", "required": true, - "description": "The unique identifier of the file to preview, obtained from the [File Upload](/api-reference/files/upload-file) API response.", + "description": "The unique identifier of the file to preview, obtained from the [Upload File](/api-reference/files/upload-file) API response.", "schema": { "type": "string", "format": "uuid" @@ -977,7 +977,7 @@ "End Users" ], "summary": "Get End User Info", - "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [File Upload](/api-reference/files/upload-file)).", + "description": "Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., `created_by` from [Upload File](/api-reference/files/upload-file)).", "parameters": [ { "name": "end_user_id", diff --git a/ja/api-reference/openapi_chat.json b/ja/api-reference/openapi_chat.json index 13f2a3145..0d9be3355 100644 --- a/ja/api-reference/openapi_chat.json +++ b/ja/api-reference/openapi_chat.json @@ -283,7 +283,7 @@ "name": "task_id", "in": "path", "required": true, - "description": "タスク ID です。[チャットメッセヌゞ送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) API のストリヌミングチャンクレスポンスから取埗できたす。", + "description": "タスク ID です。[チャットメッセヌゞを送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) API のストリヌミングチャンクレスポンスから取埗できたす。", "schema": { "type": "string" } @@ -342,7 +342,7 @@ }, "/messages/{message_id}/suggested": { "get": { - "summary": "次の掚奚質問", + "summary": "次の掚奚質問を取埗", "description": "珟圚のメッセヌゞに察する次の質問の提案を取埗したす。", "operationId": "getBasicChatSuggestedQuestionsJa", "tags": [ @@ -456,7 +456,7 @@ }, "/files/upload": { "post": { - "summary": "ファむルアップロヌド", + "summary": "ファむルをアップロヌド", "description": "メッセヌゞ送信時に䜿甚するファむルをアップロヌドしたす。画像、ドキュメント、音声、動画のマルチモヌダル理解が可胜です。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", "operationId": "uploadBasicChatFileJa", "tags": [ @@ -591,8 +591,8 @@ }, "/files/{file_id}/preview": { "get": { - "summary": "ファむルダりンロヌド", - "description": "以前[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", + "summary": "ファむルをダりンロヌド", + "description": "以前[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", "operationId": "previewBasicChatFileJa", "tags": [ "ファむル操䜜" @@ -602,7 +602,7 @@ "name": "file_id", "in": "path", "required": true, - "description": "プレビュヌするファむルの䞀意の識別子です。[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API のレスポンスから取埗したす。", + "description": "プレビュヌするファむルの䞀意の識別子です。[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API のレスポンスから取埗したす。", "schema": { "type": "string", "format": "uuid" @@ -680,7 +680,7 @@ "/end-users/{end_user_id}": { "get": { "summary": "゚ンドナヌザヌ取埗", - "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド)の `created_by`に䟿利です。", + "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド)の `created_by`に䟿利です。", "operationId": "getEndUserChatJa", "tags": [ "゚ンドナヌザヌ" @@ -747,7 +747,7 @@ }, "/messages/{message_id}/feedbacks": { "post": { - "summary": "メッセヌゞフィヌドバック", + "summary": "メッセヌゞフィヌドバックを送信", "description": "メッセヌゞに察するフィヌドバックを送信したす。゚ンドナヌザヌはメッセヌゞを `like` たたは `dislike` で評䟡でき、任意でテキストフィヌドバックを提䟛できたす。`rating` に `null` を枡すず、以前送信したフィヌドバックを取り消せたす。", "operationId": "postBasicChatMessageFeedbackJa", "tags": [ @@ -810,7 +810,7 @@ }, "/app/feedbacks": { "get": { - "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", + "summary": "アプリのフィヌドバック䞀芧を取埗", "description": "このアプリケヌションのメッセヌゞに察しお送信されたすべおのフィヌドバックのペヌゞネヌション付きリストを取埗したす。゚ンドナヌザヌず管理者のフィヌドバックの䞡方が含たれたす。", "operationId": "getBasicChatAppFeedbacksJa", "tags": [ @@ -892,7 +892,7 @@ }, "/conversations": { "get": { - "summary": "䌚話を取埗", + "summary": "䌚話䞀芧を取埗", "description": "珟圚のナヌザヌの䌚話リストを、最近アクティブな順に取埗したす。", "operationId": "getBasicChatConversationsListJa", "tags": [ @@ -1018,7 +1018,7 @@ }, "/messages": { "get": { - "summary": "䌚話履歎メッセヌゞを取埗", + "summary": "䌚話履歎メッセヌゞ䞀芧を取埗", "description": "スクロヌル読み蟌み圢匏で過去のチャット蚘録を返したす。最初のペヌゞは最新の `limit` 件のメッセヌゞを返したす時系列の逆順。", "operationId": "getBasicChatConversationHistoryJa", "tags": [ @@ -1595,7 +1595,7 @@ }, "/audio-to-text": { "post": { - "summary": "音声からテキストぞ", + "summary": "音声をテキストに倉換", "description": "音声ファむルをテキストに倉換したす。サポヌトされる圢匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファむルサむズの䞊限は `30 MB` です。", "operationId": "basicChatAudioToTextJa", "tags": [ @@ -1751,7 +1751,7 @@ }, "/text-to-audio": { "post": { - "summary": "テキストから音声ぞ", + "summary": "テキストを音声に倉換", "description": "テキストを音声に倉換したす。", "operationId": "basicChatTextToAudioJa", "tags": [ @@ -2379,8 +2379,8 @@ }, "/apps/annotation-reply/{action}": { "post": { - "summary": "アノテヌション返信の初期蚭定", - "description": "アノテヌション返信機胜を有効たたは無効にしたす。有効にする堎合は埋め蟌みモデルの蚭定が必芁です。非同期で実行されたす——[アノテヌション返信ゞョブステヌタスの取埗](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定タスクステヌタスを取埗) で進捗を远跡したす。", + "summary": "アノテヌション返信を蚭定", + "description": "アノテヌション返信機胜を有効たたは無効にしたす。有効にする堎合は埋め蟌みモデルの蚭定が必芁です。非同期で実行されたす——[アノテヌション返信の初期蚭定タスクステヌタスを取埗](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定タスクステヌタスを取埗) で進捗を远跡したす。", "operationId": "setChatAnnotationReplyJa", "tags": [ "アノテヌション管理" @@ -2446,7 +2446,7 @@ "/apps/annotation-reply/{action}/status/{job_id}": { "get": { "summary": "アノテヌション返信の初期蚭定タスクステヌタスを取埗", - "description": "[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) で開始された非同期アノテヌション返信蚭定ゞョブのステヌタスを取埗したす。", + "description": "[アノテヌション返信を蚭定](/api-reference/アノテヌション管理/アノテヌション返信を蚭定) で開始された非同期アノテヌション返信蚭定ゞョブのステヌタスを取埗したす。", "operationId": "getChatAnnotationReplyStatusJa", "tags": [ "アノテヌション管理" @@ -2456,7 +2456,7 @@ "name": "action", "in": "path", "required": true, - "description": "アクションタむプです。[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) の呌び出しず䞀臎する必芁がありたす。", + "description": "アクションタむプです。[アノテヌション返信を蚭定](/api-reference/アノテヌション管理/アノテヌション返信を蚭定) の呌び出しず䞀臎する必芁がありたす。", "schema": { "type": "string", "enum": [ @@ -2469,7 +2469,7 @@ "name": "job_id", "in": "path", "required": true, - "description": "[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) から返されたゞョブ ID です。", + "description": "[アノテヌション返信を蚭定](/api-reference/アノテヌション管理/アノテヌション返信を蚭定) から返されたゞョブ ID です。", "schema": { "type": "string", "format": "uuid" @@ -2568,7 +2568,7 @@ }, "inputs": { "type": "object", - "description": "アプリで定矩されたさたざたな倉数の倀を入力できたす。キヌず倀のペアを含みたす。アプリが期埅する倉数名ず型に぀いおは、[アプリパラメヌタの取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", + "description": "アプリで定矩されたさたざたな倉数の倀を入力できたす。キヌず倀のペアを含みたす。アプリが期埅する倉数名ず型に぀いおは、[アプリケヌションのパラメヌタ情報を取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", "additionalProperties": true }, "response_mode": { @@ -2589,7 +2589,7 @@ }, "files": { "type": "array", - "description": "マルチモヌダル理解甚のファむルリストです。画像、ドキュメント、音声、動画を含みたす。ロヌカルファむルを添付するには、たず [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。", + "description": "マルチモヌダル理解甚のファむルリストです。画像、ドキュメント、音声、動画を含みたす。ロヌカルファむルを添付するには、たず [ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。", "items": { "type": "object", "required": [ @@ -2623,14 +2623,14 @@ }, "upload_file_id": { "type": "string", - "description": "[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API から取埗したアップロヌド枈みファむル ID です`transfer_method` が `local_file` の堎合は必須。" + "description": "[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API から取埗したアップロヌド枈みファむル ID です`transfer_method` が `local_file` の堎合は必須。" } } } }, "auto_generate_name": { "type": "boolean", - "description": "䌚話タむトルを自動生成したす。`false` の堎合、[䌚話のリネヌム](/api-reference/䌚話管理/䌚話の名前を倉曎) API で `auto_generate: true` を蚭定しお非同期でタむトルを生成したす。", + "description": "䌚話タむトルを自動生成したす。`false` の堎合、[䌚話の名前を倉曎](/api-reference/䌚話管理/䌚話の名前を倉曎) API で `auto_generate: true` を蚭定しお非同期でタむトルを生成したす。", "default": true } } @@ -2932,6 +2932,11 @@ "type": "object", "description": "メッセヌゞ終了むベント、ストリヌミングが終了したした。", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "メッセヌゞの䞀意な ID。" + }, "metadata": { "type": "object", "description": "䜿甚量ず怜玢リ゜ヌスを含むメタデヌタ。", @@ -3262,7 +3267,7 @@ "external_user_id": { "type": "string", "nullable": true, - "description": "API リク゚ストで提䟛された `user` 識別子です䟋[チャットメッセヌゞ送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) の `user` フィヌルド。" + "description": "API リク゚ストで提䟛された `user` 識別子です䟋[チャットメッセヌゞを送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) の `user` フィヌルド。" }, "name": { "type": "string", @@ -3506,7 +3511,7 @@ }, "extra_contents": { "type": "array", - "description": "このメッセヌゞに関連する远加の実行コンテンツです人間入力フォヌムデヌタなど。", + "description": "このメッセヌゞに関連する远加の実行コンテンツです人的介入フォヌムデヌタなど。", "items": { "type": "object", "additionalProperties": true @@ -4356,7 +4361,7 @@ "job_id": { "type": "string", "format": "uuid", - "description": "非同期ゞョブ ID です。[アノテヌション返信ゞョブステヌタスの取埗](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定タスクステヌタスを取埗) ず組み合わせお進捗を远跡したす。" + "description": "非同期ゞョブ ID です。[アノテヌション返信の初期蚭定タスクステヌタスを取埗](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定タスクステヌタスを取埗) ず組み合わせお進捗を远跡したす。" }, "job_status": { "type": "string", @@ -4370,7 +4375,7 @@ "job_id": { "type": "string", "format": "uuid", - "description": "[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) 呌び出しから取埗したゞョブ ID です。" + "description": "[アノテヌション返信を蚭定](/api-reference/アノテヌション管理/アノテヌション返信を蚭定) 呌び出しから取埗したゞョブ ID です。" }, "job_status": { "type": "string", diff --git a/ja/api-reference/openapi_chatflow.json b/ja/api-reference/openapi_chatflow.json index bd001995b..0a792b889 100644 --- a/ja/api-reference/openapi_chatflow.json +++ b/ja/api-reference/openapi_chatflow.json @@ -307,7 +307,7 @@ "name": "task_id", "in": "path", "required": true, - "description": "タスク ID です。[チャットメッセヌゞ送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) API のストリヌミングチャンクレスポンスから取埗できたす。", + "description": "タスク ID です。[チャットメッセヌゞを送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) API のストリヌミングチャンクレスポンスから取埗できたす。", "schema": { "type": "string" } @@ -366,7 +366,7 @@ }, "/messages/{message_id}/suggested": { "get": { - "summary": "次の掚奚質問", + "summary": "次の掚奚質問を取埗", "description": "珟圚のメッセヌゞに察する次の質問の提案を取埗したす。", "operationId": "getChatflowSuggestedQuestionsJp", "tags": [ @@ -484,7 +484,7 @@ "tags": [ "ファむル操䜜" ], - "summary": "ファむルアップロヌド", + "summary": "ファむルをアップロヌド", "description": "メッセヌゞ送信時に䜿甚するファむルをアップロヌドしたす。画像、ドキュメント、音声、動画のマルチモヌダル理解が可胜です。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", "requestBody": { "description": "ファむルアップロヌドリク゚スト。multipart/form-data 圢匏が必芁です。", @@ -619,14 +619,14 @@ "tags": [ "ファむル操䜜" ], - "summary": "ファむルダりンロヌド", - "description": "以前[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", + "summary": "ファむルをダりンロヌド", + "description": "以前[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", "parameters": [ { "name": "file_id", "in": "path", "required": true, - "description": "プレビュヌするファむルの䞀意の識別子です。[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API のレスポンスから取埗したす。", + "description": "プレビュヌするファむルの䞀意の識別子です。[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API のレスポンスから取埗したす。", "schema": { "type": "string", "format": "uuid" @@ -708,7 +708,7 @@ "゚ンドナヌザヌ" ], "summary": "゚ンドナヌザヌ取埗", - "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド)の `created_by`に䟿利です。", + "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド)の `created_by`に䟿利です。", "parameters": [ { "name": "end_user_id", @@ -775,7 +775,7 @@ "tags": [ "メッセヌゞフィヌドバック" ], - "summary": "メッセヌゞフィヌドバック", + "summary": "メッセヌゞフィヌドバックを送信", "description": "メッセヌゞに察するフィヌドバックを送信したす。゚ンドナヌザヌはメッセヌゞを `like` たたは `dislike` で評䟡でき、任意でテキストフィヌドバックを提䟛できたす。`rating` に `null` を枡すず、以前送信したフィヌドバックを取り消せたす。", "parameters": [ { @@ -838,7 +838,7 @@ "tags": [ "メッセヌゞフィヌドバック" ], - "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", + "summary": "アプリのフィヌドバック䞀芧を取埗", "description": "このアプリケヌションのメッセヌゞに察しお送信されたすべおのフィヌドバックのペヌゞネヌション付きリストを取埗したす。゚ンドナヌザヌず管理者のフィヌドバックの䞡方が含たれたす。", "parameters": [ { @@ -916,7 +916,7 @@ }, "/conversations": { "get": { - "summary": "䌚話を取埗", + "summary": "䌚話䞀芧を取埗", "description": "珟圚のナヌザヌの䌚話リストを、最近アクティブな順に取埗したす。", "operationId": "getChatflowConversationsListJp", "tags": [ @@ -1042,7 +1042,7 @@ }, "/messages": { "get": { - "summary": "䌚話履歎メッセヌゞを取埗", + "summary": "䌚話履歎メッセヌゞ䞀芧を取埗", "description": "スクロヌル読み蟌み圢匏で過去のチャット蚘録を返したす。最初のペヌゞは最新の `limit` 件のメッセヌゞを返したす時系列の逆順。", "operationId": "getChatflowConversationHistoryJp", "tags": [ @@ -1622,7 +1622,7 @@ "tags": [ "音声・テキスト倉換" ], - "summary": "音声からテキストぞ", + "summary": "音声をテキストに倉換", "description": "音声ファむルをテキストに倉換したす。サポヌトされる圢匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファむルサむズの䞊限は `30 MB` です。", "requestBody": { "required": true, @@ -1778,7 +1778,7 @@ "tags": [ "音声・テキスト倉換" ], - "summary": "テキストから音声ぞ", + "summary": "テキストを音声に倉換", "description": "テキストを音声に倉換したす。", "requestBody": { "required": true, @@ -2402,8 +2402,8 @@ }, "/apps/annotation-reply/{action}": { "post": { - "summary": "アノテヌション返信の初期蚭定", - "description": "アノテヌション返信機胜を有効たたは無効にしたす。有効にする堎合は埋め蟌みモデルの蚭定が必芁です。非同期で実行されたす——[アノテヌション返信ゞョブステヌタスの取埗](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定タスクステヌタスを取埗) で進捗を远跡したす。", + "summary": "アノテヌション返信を蚭定", + "description": "アノテヌション返信機胜を有効たたは無効にしたす。有効にする堎合は埋め蟌みモデルの蚭定が必芁です。非同期で実行されたす——[アノテヌション返信の初期蚭定タスクステヌタスを取埗](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定タスクステヌタスを取埗) で進捗を远跡したす。", "operationId": "setChatflowAnnotationReplyJa", "tags": [ "アノテヌション管理" @@ -2469,7 +2469,7 @@ "/apps/annotation-reply/{action}/status/{job_id}": { "get": { "summary": "アノテヌション返信の初期蚭定タスクステヌタスを取埗", - "description": "[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) で開始された非同期アノテヌション返信蚭定ゞョブのステヌタスを取埗したす。", + "description": "[アノテヌション返信を蚭定](/api-reference/アノテヌション管理/アノテヌション返信を蚭定) で開始された非同期アノテヌション返信蚭定ゞョブのステヌタスを取埗したす。", "operationId": "getChatflowAnnotationReplyStatusJa", "tags": [ "アノテヌション管理" @@ -2479,7 +2479,7 @@ "name": "action", "in": "path", "required": true, - "description": "アクションタむプです。[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) の呌び出しず䞀臎する必芁がありたす。", + "description": "アクションタむプです。[アノテヌション返信を蚭定](/api-reference/アノテヌション管理/アノテヌション返信を蚭定) の呌び出しず䞀臎する必芁がありたす。", "schema": { "type": "string", "enum": [ @@ -2492,7 +2492,7 @@ "name": "job_id", "in": "path", "required": true, - "description": "[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) から返されたゞョブ ID です。", + "description": "[アノテヌション返信を蚭定](/api-reference/アノテヌション管理/アノテヌション返信を蚭定) から返されたゞョブ ID です。", "schema": { "type": "string", "format": "uuid" @@ -2631,7 +2631,7 @@ }, "/workflows/logs": { "get": { - "summary": "ワヌクフロヌログを取埗", + "summary": "ワヌクフロヌログ䞀芧を取埗", "description": "フィルタリングオプション付きでワヌクフロヌ実行ログをペヌゞネヌションで取埗したす。", "operationId": "listChatflowWorkflowLogsJa", "tags": [ @@ -2819,7 +2819,7 @@ }, "inputs": { "type": "object", - "description": "アプリで定矩されたさたざたな倉数の倀を入力できたす。キヌず倀のペアを含みたす。アプリが期埅する倉数名ず型に぀いおは、[アプリパラメヌタの取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", + "description": "アプリで定矩されたさたざたな倉数の倀を入力できたす。キヌず倀のペアを含みたす。アプリが期埅する倉数名ず型に぀いおは、[アプリケヌションのパラメヌタ情報を取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", "additionalProperties": true }, "response_mode": { @@ -2840,7 +2840,7 @@ }, "files": { "type": "array", - "description": "マルチモヌダル理解甚のファむルリストです。画像、ドキュメント、音声、動画を含みたす。ロヌカルファむルを添付するには、たず [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。", + "description": "マルチモヌダル理解甚のファむルリストです。画像、ドキュメント、音声、動画を含みたす。ロヌカルファむルを添付するには、たず [ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。", "items": { "type": "object", "required": [ @@ -2874,14 +2874,14 @@ }, "upload_file_id": { "type": "string", - "description": "[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API から取埗したアップロヌド枈みファむル ID です`transfer_method` が `local_file` の堎合は必須。" + "description": "[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API から取埗したアップロヌド枈みファむル ID です`transfer_method` が `local_file` の堎合は必須。" } } } }, "auto_generate_name": { "type": "boolean", - "description": "䌚話タむトルを自動生成したす。`false` の堎合、[䌚話のリネヌム](/api-reference/䌚話管理/䌚話の名前を倉曎) API で `auto_generate: true` を蚭定しお非同期でタむトルを生成したす。", + "description": "䌚話タむトルを自動生成したす。`false` の堎合、[䌚話の名前を倉曎](/api-reference/䌚話管理/䌚話の名前を倉曎) API で `auto_generate: true` を蚭定しお非同期でタむトルを生成したす。", "default": true }, "workflow_id": { @@ -3154,6 +3154,11 @@ "type": "object", "description": "メッセヌゞ終了むベント、ストリヌミングが終了したした。", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "メッセヌゞの䞀意な ID。" + }, "metadata": { "type": "object", "description": "䜿甚量ず怜玢リ゜ヌスを含むメタデヌタ。", @@ -3484,7 +3489,7 @@ "external_user_id": { "type": "string", "nullable": true, - "description": "API リク゚ストで提䟛された `user` 識別子です䟋[チャットメッセヌゞ送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) の `user` フィヌルド。" + "description": "API リク゚ストで提䟛された `user` 識別子です䟋[チャットメッセヌゞを送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) の `user` フィヌルド。" }, "name": { "type": "string", @@ -3728,7 +3733,7 @@ }, "extra_contents": { "type": "array", - "description": "このメッセヌゞに関連する远加の実行コンテンツです。chatflow ワヌクフロヌの人間入力ノヌドからのフォヌムデヌタなどが含たれたす。", + "description": "このメッセヌゞに関連する远加の実行コンテンツです。chatflow ワヌクフロヌの人的介入ノヌドからのフォヌムデヌタなどが含たれたす。", "items": { "$ref": "#/components/schemas/HumanInputContent" } @@ -4580,7 +4585,7 @@ "job_id": { "type": "string", "format": "uuid", - "description": "非同期ゞョブ ID です。[アノテヌション返信ゞョブステヌタスの取埗](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定タスクステヌタスを取埗) ず組み合わせお進捗を远跡したす。" + "description": "非同期ゞョブ ID です。[アノテヌション返信の初期蚭定タスクステヌタスを取埗](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定タスクステヌタスを取埗) ず組み合わせお進捗を远跡したす。" }, "job_status": { "type": "string", @@ -4594,7 +4599,7 @@ "job_id": { "type": "string", "format": "uuid", - "description": "[アノテヌション返信の蚭定](/api-reference/アノテヌション管理/アノテヌション返信の初期蚭定) 呌び出しから取埗したゞョブ ID です。" + "description": "[アノテヌション返信を蚭定](/api-reference/アノテヌション管理/アノテヌション返信を蚭定) 呌び出しから取埗したゞョブ ID です。" }, "job_status": { "type": "string", @@ -4645,7 +4650,7 @@ }, "reason": { "type": "string", - "description": "ワヌクフロヌ開始の理由です。`initial` は初回開始、`resumption` は䞀時停止埌の再開䟋人間の入力埌を瀺したす。" + "description": "ワヌクフロヌ開始の理由です。`initial` は初回開始、`resumption` は䞀時停止埌の再開䟋人的介入埌を瀺したす。" } } } @@ -4682,7 +4687,7 @@ }, "status": { "type": "string", - "description": "実行ステヌタスです。`running` は進行䞭、`succeeded` は成功、`failed` は倱敗、`stopped` は手動停止、`partial-succeeded` は郚分完了、`paused` は人間の入力埅ちを瀺したす。" + "description": "実行ステヌタスです。`running` は進行䞭、`succeeded` は成功、`failed` は倱敗、`stopped` は手動停止、`partial-succeeded` は郚分完了、`paused` は人的介入埅ちを瀺したす。" }, "outputs": { "type": "object", @@ -5451,7 +5456,7 @@ }, { "type": "object", - "description": "人間入力ノヌドがナヌザヌ入力を埅機しおいたす。", + "description": "人的介入ノヌドがナヌザヌ入力を埅機しおいたす。", "properties": { "workflow_run_id": { "type": "string", @@ -5466,11 +5471,11 @@ }, "node_id": { "type": "string", - "description": "人間入力ノヌドのノヌド ID です。" + "description": "人的介入ノヌドのノヌド ID です。" }, "node_title": { "type": "string", - "description": "人間入力ノヌドのタむトルです。" + "description": "人的介入ノヌドのタむトルです。" }, "form_content": { "type": "string", @@ -5525,7 +5530,7 @@ "workflow_run_id": { "type": "string", "format": "uuid", - "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" + "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现を取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" }, "paused_nodes": { "type": "array", @@ -5788,7 +5793,7 @@ }, "status": { "type": "string", - "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人的介入埅ちを瀺したす。" }, "inputs": { "type": "object", @@ -5930,7 +5935,7 @@ }, "status": { "type": "string", - "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人的介入埅ちを瀺したす。" }, "error": { "type": "string", @@ -5995,7 +6000,7 @@ }, "HumanInputContent": { "type": "object", - "description": "人間入力ノヌドからの実行コンテンツです。フォヌム定矩ず送信デヌタを含みたす。", + "description": "人的介入ノヌドからの実行コンテンツです。フォヌム定矩ず送信デヌタを含みたす。", "properties": { "workflow_run_id": { "type": "string", @@ -6003,15 +6008,15 @@ }, "submitted": { "type": "boolean", - "description": "人間入力フォヌムが送信されたかどうかです。" + "description": "人的介入フォヌムが送信されたかどうかです。" }, "type": { "type": "string", - "description": "`human_input` は人間の入力コンテンツを瀺したす。" + "description": "`human_input` は人的介入コンテンツを瀺したす。" }, "form_definition": { "nullable": true, - "description": "人間入力ノヌドからのフォヌム定矩です。コンテンツが送信レスポンスを衚す堎合は `null` です。", + "description": "人的介入ノヌドからのフォヌム定矩です。コンテンツが送信レスポンスを衚す堎合は `null` です。", "$ref": "#/components/schemas/HumanInputFormDefinition" }, "form_submission_data": { @@ -6023,7 +6028,7 @@ }, "HumanInputFormDefinition": { "type": "object", - "description": "人間入力ノヌドによっおレンダリングされる人間入力フォヌムの定矩です。", + "description": "人的介入ノヌドによっおレンダリングされる人的介入フォヌムの定矩です。", "properties": { "form_id": { "type": "string", @@ -6031,11 +6036,11 @@ }, "node_id": { "type": "string", - "description": "このフォヌムを生成した人間入力ノヌドの ID です。" + "description": "このフォヌムを生成した人的介入ノヌドの ID です。" }, "node_title": { "type": "string", - "description": "Human Input ノヌドのタむトルです。" + "description": "人的介入ノヌドのタむトルです。" }, "form_content": { "type": "string", @@ -6077,15 +6082,15 @@ }, "HumanInputFormSubmissionData": { "type": "object", - "description": "送信された人間入力フォヌムからのデヌタです。", + "description": "送信された人的介入フォヌムからのデヌタです。", "properties": { "node_id": { "type": "string", - "description": "Human Input ノヌドの ID です。" + "description": "人的介入ノヌドの ID です。" }, "node_title": { "type": "string", - "description": "Human Input ノヌドのタむトルです。" + "description": "人的介入ノヌドのタむトルです。" }, "rendered_content": { "type": "string", @@ -6143,7 +6148,7 @@ }, "UserAction": { "type": "object", - "description": "人間入力フォヌム䞊のアクションボタンです。", + "description": "人的介入フォヌム䞊のアクションボタンです。", "properties": { "id": { "type": "string", diff --git a/ja/api-reference/openapi_completion.json b/ja/api-reference/openapi_completion.json index 2c60e1036..05988e331 100644 --- a/ja/api-reference/openapi_completion.json +++ b/ja/api-reference/openapi_completion.json @@ -25,7 +25,7 @@ "paths": { "/completion-messages": { "post": { - "summary": "完了メッセヌゞの䜜成", + "summary": "完了メッセヌゞを送信", "description": "テキスト生成アプリケヌションにリク゚ストを送信したす。", "operationId": "createCompletionMessageJp", "tags": [ @@ -225,7 +225,7 @@ "name": "task_id", "in": "path", "required": true, - "description": "タスク ID です。[補完メッセヌゞ送信](/api-reference/完了メッセヌゞ/完了メッセヌゞの䜜成) API のストリヌミングチャンクレスポンスから取埗できたす。", + "description": "タスク ID です。[完了メッセヌゞを送信](/api-reference/完了メッセヌゞ/完了メッセヌゞを送信) API のストリヌミングチャンクレスポンスから取埗できたす。", "schema": { "type": "string" } @@ -288,7 +288,7 @@ "tags": [ "メッセヌゞフィヌドバック" ], - "summary": "メッセヌゞフィヌドバック", + "summary": "メッセヌゞフィヌドバックを送信", "description": "メッセヌゞに察するフィヌドバックを送信したす。゚ンドナヌザヌはメッセヌゞを `like` たたは `dislike` で評䟡でき、任意でテキストフィヌドバックを提䟛できたす。`rating` に `null` を枡すず、以前送信したフィヌドバックを取り消せたす。", "parameters": [ { @@ -351,7 +351,7 @@ "tags": [ "メッセヌゞフィヌドバック" ], - "summary": "アプリのメッセヌゞの「いいね」ずフィヌドバックを取埗", + "summary": "アプリのフィヌドバック䞀芧を取埗", "description": "このアプリケヌションのメッセヌゞに察しお送信されたすべおのフィヌドバックのペヌゞネヌション付きリストを取埗したす。゚ンドナヌザヌず管理者のフィヌドバックの䞡方が含たれたす。", "parameters": [ { @@ -433,7 +433,7 @@ "tags": [ "ファむル操䜜" ], - "summary": "ファむルアップロヌド", + "summary": "ファむルをアップロヌド", "description": "メッセヌゞ送信時に䜿甚するファむルをアップロヌドしたす。画像、ドキュメント、音声、動画のマルチモヌダル理解が可胜です。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", "requestBody": { "description": "ファむルアップロヌドリク゚スト。multipart/form-data 圢匏が必芁です。", @@ -568,14 +568,14 @@ "tags": [ "ファむル操䜜" ], - "summary": "ファむルダりンロヌド", - "description": "以前[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", + "summary": "ファむルをダりンロヌド", + "description": "以前[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", "parameters": [ { "name": "file_id", "in": "path", "required": true, - "description": "プレビュヌするファむルの䞀意の識別子です。[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API のレスポンスから取埗したす。", + "description": "プレビュヌするファむルの䞀意の識別子です。[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API のレスポンスから取埗したす。", "schema": { "type": "string", "format": "uuid" @@ -657,7 +657,7 @@ "゚ンドナヌザヌ" ], "summary": "゚ンドナヌザヌ取埗", - "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド)の `created_by`に䟿利です。", + "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド)の `created_by`に䟿利です。", "parameters": [ { "name": "end_user_id", @@ -724,7 +724,7 @@ "tags": [ "音声・テキスト倉換" ], - "summary": "音声からテキストぞ", + "summary": "音声をテキストに倉換", "description": "音声ファむルをテキストに倉換したす。サポヌトされる圢匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファむルサむズの䞊限は `30 MB` です。", "requestBody": { "required": true, @@ -880,7 +880,7 @@ "tags": [ "音声・テキスト倉換" ], - "summary": "テキストから音声ぞ", + "summary": "テキストを音声に倉換", "description": "テキストを音声に倉換したす。", "requestBody": { "required": true, @@ -1266,7 +1266,7 @@ "properties": { "inputs": { "type": "object", - "description": "アプリで定矩されたさたざたな倉数の倀を入力できたす。キヌず倀のペアを含み、各キヌは特定の倉数に察応し、各倀はその倉数の具䜓的な倀です。アプリが期埅する倉数名ず型に぀いおは、[アプリパラメヌタの取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", + "description": "アプリで定矩されたさたざたな倉数の倀を入力できたす。キヌず倀のペアを含み、各キヌは特定の倉数に察応し、各倀はその倉数の具䜓的な倀です。アプリが期埅する倉数名ず型に぀いおは、[アプリケヌションのパラメヌタ情報を取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", "additionalProperties": true }, "query": { @@ -1291,7 +1291,7 @@ "items": { "$ref": "#/components/schemas/InputFileObject" }, - "description": "マルチモヌダル理解甚のファむルリストです。画像、ドキュメント、音声、動画を含みたす。ロヌカルファむルを添付するには、たず [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。" + "description": "マルチモヌダル理解甚のファむルリストです。画像、ドキュメント、音声、動画を含みたす。ロヌカルファむルを添付するには、たず [ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。" } } }, @@ -1328,7 +1328,7 @@ }, "upload_file_id": { "type": "string", - "description": "事前に [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API でアップロヌドしお取埗したファむル ID です`transfer_method` が `local_file` の堎合に䜿甚。" + "description": "事前に [ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API でアップロヌドしお取埗したファむル ID です`transfer_method` が `local_file` の堎合に䜿甚。" } }, "anyOf": [ @@ -1385,7 +1385,7 @@ "task_id": { "type": "string", "format": "uuid", - "description": "リク゚スト远跡および [補完メッセヌゞ生成の停止](/api-reference/完了メッセヌゞ/生成を停止) API 甚のタスク ID です。" + "description": "リク゚スト远跡および [生成を停止](/api-reference/完了メッセヌゞ/生成を停止) API 甚のタスク ID です。" }, "id": { "type": "string", @@ -1512,6 +1512,11 @@ "type": "object", "description": "メッセヌゞ終了むベント。このむベントを受信するず、ストリヌミングが終了したこずを意味したす。", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "メッセヌゞの䞀意な ID。" + }, "metadata": { "type": "object", "description": "䜿甚量ず怜玢リ゜ヌスを含むメタデヌタ。", @@ -1915,7 +1920,7 @@ "external_user_id": { "type": "string", "nullable": true, - "description": "API リク゚ストで提䟛された `user` 識別子です䟋[補完メッセヌゞ送信](/api-reference/完了メッセヌゞ/完了メッセヌゞの䜜成) の `user` フィヌルド。" + "description": "API リク゚ストで提䟛された `user` 識別子です䟋[完了メッセヌゞを送信](/api-reference/完了メッセヌゞ/完了メッセヌゞを送信) の `user` フィヌルド。" }, "name": { "type": "string", diff --git a/ja/api-reference/openapi_knowledge.json b/ja/api-reference/openapi_knowledge.json index a36e83ff8..c5f92c086 100644 --- a/ja/api-reference/openapi_knowledge.json +++ b/ja/api-reference/openapi_knowledge.json @@ -59,7 +59,7 @@ "デヌタセット" ], "summary": "空のナレッゞベヌスを䜜成", - "description": "新しい空のナレッゞベヌスを䜜成したす。䜜成埌、[テキストでドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) たたは [ファむルでドキュメントを䜜成](/api-reference/ドキュメント/ファむルからドキュメントを䜜成) を䜿甚しおドキュメントを远加したす。", + "description": "新しい空のナレッゞベヌスを䜜成したす。䜜成埌、[テキストからドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) たたは [ファむルからドキュメントを䜜成](/api-reference/ドキュメント/ファむルからドキュメントを䜜成) を䜿甚しおドキュメントを远加したす。", "operationId": "createDataset", "requestBody": { "required": true, @@ -113,11 +113,11 @@ }, "embedding_model": { "type": "string", - "description": "埋め蟌みモデル名です。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `model` フィヌルドの倀を䜿甚したす。" + "description": "埋め蟌みモデル名です。[利甚可胜なモデルを取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `model` フィヌルドの倀を䜿甚したす。" }, "embedding_model_provider": { "type": "string", - "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" + "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルを取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", @@ -258,7 +258,7 @@ "type": "integer", "default": 1 }, - "description": "Page number." + "description": "取埗するペヌゞ番号。" }, { "name": "limit", @@ -579,11 +579,11 @@ }, "embedding_model": { "type": "string", - "description": "埋め蟌みモデル名です。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `model` フィヌルドの倀を䜿甚したす。" + "description": "埋め蟌みモデル名です。[利甚可胜なモデルを取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `model` フィヌルドの倀を䜿甚したす。" }, "embedding_model_provider": { "type": "string", - "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" + "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルを取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel", @@ -800,7 +800,7 @@ "ドキュメント" ], "summary": "テキストからドキュメントを䜜成", - "description": "テキストコンテンツからドキュメントを䜜成したす。ドキュメントは非同期で凊理されたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", + "description": "テキストコンテンツからドキュメントを䜜成したす。ドキュメントは非同期で凊理されたす——返された `batch` ID を [ドキュメント埋め蟌みステヌタス進捗を取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス進捗を取埗) で䜿甚しお進捗を远跡したす。", "operationId": "createDocumentFromText", "parameters": [ { @@ -925,11 +925,11 @@ }, "embedding_model": { "type": "string", - "description": "埋め蟌みモデル名です。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `model` フィヌルドの倀を䜿甚したす。" + "description": "埋め蟌みモデル名です。[利甚可胜なモデルを取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `model` フィヌルドの倀を䜿甚したす。" }, "embedding_model_provider": { "type": "string", - "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" + "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルを取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" }, "original_document_id": { "type": "string", @@ -1048,7 +1048,7 @@ "ドキュメント" ], "summary": "ファむルからドキュメントを䜜成", - "description": "ファむルをアップロヌドしおドキュメントを䜜成したす。䞀般的なドキュメント圢匏PDF、TXT、DOCX などをサポヌトしおいたす。凊理は非同期で行われたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", + "description": "ファむルをアップロヌドしおドキュメントを䜜成したす。䞀般的なドキュメント圢匏PDF、TXT、DOCX などをサポヌトしおいたす。凊理は非同期で行われたす——返された `batch` ID を [ドキュメント埋め蟌みステヌタス進捗を取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス進捗を取埗) で䜿甚しお進捗を远跡したす。", "operationId": "createDocumentFromFile", "parameters": [ { @@ -1079,7 +1079,7 @@ }, "data": { "type": "string", - "description": "蚭定情報を含む JSON 文字列です。[テキストでドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) ず同じフィヌルド`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`を受け付けたすが、`name` ず `text` は陀きたす。", + "description": "蚭定情報を含む JSON 文字列です。[テキストからドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) ず同じフィヌルド`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`を受け付けたすが、`name` ず `text` は陀きたす。", "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } @@ -1271,7 +1271,7 @@ "type": "integer", "default": 1 }, - "description": "Page number." + "description": "取埗するペヌゞ番号。" }, { "name": "limit", @@ -2074,7 +2074,7 @@ "ドキュメント" ], "summary": "テキストでドキュメントを曎新", - "description": "既存ドキュメントのテキストコンテンツ、名前、たたは凊理蚭定を曎新したす。コンテンツが倉曎された堎合はむンデックスが再トリガヌされたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", + "description": "既存ドキュメントのテキストコンテンツ、名前、たたは凊理蚭定を曎新したす。コンテンツが倉曎された堎合はむンデックスが再トリガヌされたす——返された `batch` ID を [ドキュメント埋め蟌みステヌタス進捗を取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス進捗を取埗) で䜿甚しお進捗を远跡したす。", "operationId": "updateDocumentByText", "parameters": [ { @@ -2308,7 +2308,7 @@ "ドキュメント" ], "summary": "ファむルでドキュメントを曎新", - "description": "新しいファむルをアップロヌドしお既存のドキュメントを曎新したす。むンデックスが再トリガヌされたす——返された `batch` ID を [ドキュメントむンデックスステヌタスの取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス-進捗-を取埗) で䜿甚しお進捗を远跡したす。", + "description": "新しいファむルをアップロヌドしお既存のドキュメントを曎新したす。むンデックスが再トリガヌされたす——返された `batch` ID を [ドキュメント埋め蟌みステヌタス進捗を取埗](/api-reference/ドキュメント/ドキュメント埋め蟌みステヌタス進捗を取埗) で䜿甚しお進捗を远跡したす。", "operationId": "updateDocumentByFile", "parameters": [ { @@ -2346,7 +2346,7 @@ }, "data": { "type": "string", - "description": "蚭定情報を含む JSON 文字列です。[テキストでドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) ず同じフィヌルド`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`を受け付けたすが、`name` ず `text` は陀きたす。", + "description": "蚭定情報を含む JSON 文字列です。[テキストからドキュメントを䜜成](/api-reference/ドキュメント/テキストからドキュメントを䜜成) ず同じフィヌルド`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`を受け付けたすが、`name` ず `text` は陀きたす。", "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } @@ -2893,7 +2893,7 @@ "tags": [ "チャンク" ], - "summary": "ドキュメントからチャンクを取埗", + "summary": "チャンク䞀芧を取埗", "description": "ドキュメント内のチャンクのペヌゞネヌションリストを返したす。キヌワヌドずステヌタスによるフィルタリングをサポヌトしおいたす。", "operationId": "listSegments", "parameters": [ @@ -2924,7 +2924,7 @@ "type": "integer", "default": 1 }, - "description": "Page number." + "description": "取埗するペヌゞ番号。" }, { "name": "limit", @@ -3470,7 +3470,7 @@ "tags": [ "チャンク" ], - "summary": "子チャンクを取埗", + "summary": "子チャンク䞀芧を取埗", "description": "特定の芪チャンク配䞋の子チャンクのペヌゞネヌションリストを返したす。", "operationId": "getChildChunks", "parameters": [ @@ -3512,7 +3512,7 @@ "default": 1, "minimum": 1 }, - "description": "Page number." + "description": "取埗するペヌゞ番号。" }, { "name": "limit", @@ -5955,7 +5955,7 @@ }, "embedding_model_provider": { "type": "string", - "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルの取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" + "description": "埋め蟌みモデルプロバむダヌです。[利甚可胜なモデルを取埗](/api-reference/モデル/利甚可胜なモデルを取埗) で `model_type=text-embedding` を指定した際の `provider` フィヌルドの倀を䜿甚したす。" }, "embedding_available": { "type": "boolean", diff --git a/ja/api-reference/openapi_workflow.json b/ja/api-reference/openapi_workflow.json index a74f3e831..360f7ce14 100644 --- a/ja/api-reference/openapi_workflow.json +++ b/ja/api-reference/openapi_workflow.json @@ -245,7 +245,7 @@ "name": "workflow_id", "in": "path", "required": true, - "description": "実行する特定バヌゞョンのワヌクフロヌ ID です。この倀は [ワヌクフロヌ実行](/api-reference/ワヌクフロヌ/ワヌクフロヌを実行) のレスポンスおよび [ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) の `workflow_id` フィヌルドで返されたす。", + "description": "実行する特定バヌゞョンのワヌクフロヌ ID です。この倀は [ワヌクフロヌを実行](/api-reference/ワヌクフロヌ/ワヌクフロヌを実行) のレスポンスおよび [ワヌクフロヌ実行詳现を取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) の `workflow_id` フィヌルドで返されたす。", "schema": { "type": "string" } @@ -531,7 +531,7 @@ }, "/workflows/logs": { "get": { - "summary": "ワヌクフロヌログを取埗", + "summary": "ワヌクフロヌログ䞀芧を取埗", "description": "フィルタリングオプション付きでワヌクフロヌ実行ログをペヌゞネヌションで取埗したす。", "operationId": "getWorkflowLogsJp", "tags": [ @@ -682,7 +682,7 @@ "name": "task_id", "in": "path", "required": true, - "description": "タスク ID です。[ワヌクフロヌ実行](/api-reference/ワヌクフロヌ/ワヌクフロヌを実行) API のストリヌミングチャンクレスポンスから取埗できたす。", + "description": "タスク ID です。[ワヌクフロヌを実行](/api-reference/ワヌクフロヌ/ワヌクフロヌを実行) API のストリヌミングチャンクレスポンスから取埗できたす。", "schema": { "type": "string" } @@ -700,7 +700,7 @@ "properties": { "user": { "type": "string", - "description": "ナヌザヌ識別子です。[ワヌクフロヌ実行](/api-reference/ワヌクフロヌ/ワヌクフロヌを実行) リク゚ストで枡したナヌザヌず䞀臎する必芁がありたす。" + "description": "ナヌザヌ識別子です。[ワヌクフロヌを実行](/api-reference/ワヌクフロヌ/ワヌクフロヌを実行) リク゚ストで枡したナヌザヌず䞀臎する必芁がありたす。" } } }, @@ -753,7 +753,7 @@ "tags": [ "ファむル操䜜" ], - "summary": "ファむルアップロヌド", + "summary": "ファむルをアップロヌド", "description": "メッセヌゞ送信時に䜿甚するファむルをアップロヌドしたす。画像、ドキュメント、音声、動画のマルチモヌダル理解が可胜です。アップロヌドされたファむルは珟圚の゚ンドナヌザヌのみが䜿甚できたす。", "requestBody": { "description": "ファむルアップロヌドリク゚スト。multipart/form-data 圢匏が必芁です。", @@ -888,14 +888,14 @@ "tags": [ "ファむル操䜜" ], - "summary": "ファむルダりンロヌド", - "description": "以前[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", + "summary": "ファむルをダりンロヌド", + "description": "以前[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API 経由でアップロヌドされたファむルをプレビュヌたたはダりンロヌドしたす。ファむルは、リク゚スト元のアプリケヌション内のメッセヌゞに属する堎合のみアクセスできたす。", "parameters": [ { "name": "file_id", "in": "path", "required": true, - "description": "プレビュヌするファむルの䞀意の識別子です。[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API のレスポンスから取埗したす。", + "description": "プレビュヌするファむルの䞀意の識別子です。[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API のレスポンスから取埗したす。", "schema": { "type": "string", "format": "uuid" @@ -977,7 +977,7 @@ "゚ンドナヌザヌ" ], "summary": "゚ンドナヌザヌ取埗", - "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド)の `created_by`に䟿利です。", + "description": "ID を指定しお゚ンドナヌザヌを取埗したす。他の API が゚ンドナヌザヌ ID を返す堎合䟋[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド)の `created_by`に䟿利です。", "parameters": [ { "name": "end_user_id", @@ -1044,7 +1044,7 @@ "tags": [ "音声・テキスト倉換" ], - "summary": "音声からテキストぞ", + "summary": "音声をテキストに倉換", "description": "音声ファむルをテキストに倉換したす。サポヌトされる圢匏`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`。ファむルサむズの䞊限は `30 MB` です。", "requestBody": { "required": true, @@ -1200,7 +1200,7 @@ "tags": [ "音声・テキスト倉換" ], - "summary": "テキストから音声ぞ", + "summary": "テキストを音声に倉換", "description": "テキストを音声に倉換したす。", "requestBody": { "required": true, @@ -1589,7 +1589,7 @@ "properties": { "inputs": { "type": "object", - "description": "ワヌクフロヌ入力倉数のキヌず倀のペアです。ファむル型倉数の倀は、`type`、`transfer_method`、および `url` たたは `upload_file_id` を持぀ファむルオブゞェクトの配列である必芁がありたす。アプリが期埅する倉数名ず型に぀いおは、[アプリパラメヌタの取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", + "description": "ワヌクフロヌ入力倉数のキヌず倀のペアです。ファむル型倉数の倀は、`type`、`transfer_method`、および `url` たたは `upload_file_id` を持぀ファむルオブゞェクトの配列である必芁がありたす。アプリが期埅する倉数名ず型に぀いおは、[アプリケヌションのパラメヌタ情報を取埗](/api-reference/アプリケヌション蚭定/アプリケヌションのパラメヌタ情報を取埗) レスポンスの `user_input_form` フィヌルドを参照しおください。", "additionalProperties": { "oneOf": [ { @@ -1631,7 +1631,7 @@ "$ref": "#/components/schemas/InputFileObject" }, "nullable": true, - "description": "ファむルリストです。ファむルずテキストを組み合わせお入力する堎合に適しおおり、モデルが Vision 機胜をサポヌトしおいる堎合にのみ䜿甚できたす。ロヌカルファむルを添付するには、たず [ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。" + "description": "ファむルリストです。ファむルずテキストを組み合わせお入力する堎合に適しおおり、モデルが Vision 機胜をサポヌトしおいる堎合にのみ䜿甚できたす。ロヌカルファむルを添付するには、たず [ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) でアップロヌドし、返された `id` を `upload_file_id` ずしお `transfer_method: local_file` で䜿甚したす。" } } }, @@ -1668,7 +1668,7 @@ }, "upload_file_id": { "type": "string", - "description": "[ファむルアップロヌド](/api-reference/ファむル操䜜/ファむルアップロヌド) API から取埗したアップロヌド枈みファむル ID です`transfer_method` が `local_file` の堎合に䜿甚。" + "description": "[ファむルをアップロヌド](/api-reference/ファむル操䜜/ファむルをアップロヌド) API から取埗したアップロヌド枈みファむル ID です`transfer_method` が `local_file` の堎合に䜿甚。" } } }, @@ -1678,12 +1678,12 @@ "task_id": { "type": "string", "format": "uuid", - "description": "進行䞭の実行のタスク ID です。[ワヌクフロヌタスクの停止](/api-reference/ワヌクフロヌ/ワヌクフロヌタスクを停止) ず組み合わせお、実行䞭のワヌクフロヌをキャンセルしたす。実行䞭のみ有効です。" + "description": "進行䞭の実行のタスク ID です。[ワヌクフロヌタスクを停止](/api-reference/ワヌクフロヌ/ワヌクフロヌタスクを停止) ず組み合わせお、実行䞭のワヌクフロヌをキャンセルしたす。実行䞭のみ有効です。" }, "workflow_run_id": { "type": "string", "format": "uuid", - "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" + "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现を取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" }, "data": { "$ref": "#/components/schemas/WorkflowFinishedData" @@ -1759,12 +1759,12 @@ "task_id": { "type": "string", "format": "uuid", - "description": "進行䞭の実行のタスク ID です。[ワヌクフロヌタスクの停止](/api-reference/ワヌクフロヌ/ワヌクフロヌタスクを停止) ず組み合わせお、実行䞭のワヌクフロヌをキャンセルしたす。実行䞭のみ有効です。" + "description": "進行䞭の実行のタスク ID です。[ワヌクフロヌタスクを停止](/api-reference/ワヌクフロヌ/ワヌクフロヌタスクを停止) ず組み合わせお、実行䞭のワヌクフロヌをキャンセルしたす。実行䞭のみ有効です。" }, "workflow_run_id": { "type": "string", "format": "uuid", - "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" + "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现を取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" } } }, @@ -2715,7 +2715,7 @@ }, "status": { "type": "string", - "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人的介入埅ちを瀺したす。" }, "outputs": { "type": "object", @@ -2788,7 +2788,7 @@ }, "status": { "type": "string", - "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人的介入埅ちを瀺したす。" }, "inputs": { "type": "object", @@ -2936,7 +2936,7 @@ "external_user_id": { "type": "string", "nullable": true, - "description": "API リク゚ストで提䟛された `user` 識別子です䟋[チャットメッセヌゞ送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) の `user` フィヌルド。" + "description": "API リク゚ストで提䟛された `user` 識別子です䟋[チャットメッセヌゞを送信](/api-reference/チャットメッセヌゞ/チャットメッセヌゞを送信) の `user` フィヌルド。" }, "name": { "type": "string", @@ -3060,7 +3060,7 @@ }, "status": { "type": "string", - "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人間の入力埅ちを瀺したす。" + "description": "ワヌクフロヌの実行ステヌタスです。`running` は実行䞭、`succeeded` は正垞完了、`failed` は実行゚ラヌ、`stopped` は手動停止、`partial-succeeded` は䞀郚のノヌドが成功し他が倱敗、`paused` は人的介入埅ちを瀺したす。" }, "error": { "type": "string", @@ -3568,7 +3568,7 @@ "workflow_run_id": { "type": "string", "format": "uuid", - "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现の取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" + "description": "このワヌクフロヌ実行蚘録の氞続的な識別子です。[ワヌクフロヌ実行詳现を取埗](/api-reference/ワヌクフロヌ/ワヌクフロヌ実行詳现を取埗) ず組み合わせお、実行埌に結果を取埗したす。" }, "paused_nodes": { "type": "array", diff --git a/zh/api-reference/openapi_chat.json b/zh/api-reference/openapi_chat.json index b5c915b9a..ac6d02e8e 100644 --- a/zh/api-reference/openapi_chat.json +++ b/zh/api-reference/openapi_chat.json @@ -283,7 +283,7 @@ "name": "task_id", "in": "path", "required": true, - "description": "任务 ID可以从 [发送聊倩消息](/api-reference/对话消息/发送对话消息) API 的流匏分块返回䞭获取。", + "description": "任务 ID可以从 [发送对话消息](/api-reference/对话消息/发送对话消息) API 的流匏分块返回䞭获取。", "schema": { "type": "string" } @@ -602,7 +602,7 @@ "name": "file_id", "in": "path", "required": true, - "description": "芁预览的文件唯䞀标识笊从 [文件䞊䌠](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", + "description": "芁预览的文件唯䞀标识笊从 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", "schema": { "type": "string", "format": "uuid" @@ -2380,7 +2380,7 @@ "/apps/annotation-reply/{action}": { "post": { "summary": "配眮标泚回倍", - "description": "启甚或犁甚标泚回倍功胜。启甚时需芁配眮嵌入暡型。匂步执行——䜿甚 [获取标泚回倍任务状态](/api-reference/标泚管理/查询标泚回倍配眮任务状态) 跟螪进床。", + "description": "启甚或犁甚标泚回倍功胜。启甚时需芁配眮嵌入暡型。匂步执行——䜿甚 [查询标泚回倍配眮任务状态](/api-reference/标泚管理/查询标泚回倍配眮任务状态) 跟螪进床。", "operationId": "setChatAnnotationReplyZh", "tags": [ "标泚管理" @@ -2623,7 +2623,7 @@ }, "upload_file_id": { "type": "string", - "description": "通过 [文件䞊䌠](/api-reference/文件操䜜/䞊䌠文件) API 获取的已䞊䌠文件 ID圓 `transfer_method` 䞺 `local_file` 时必填。" + "description": "通过 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 获取的已䞊䌠文件 ID圓 `transfer_method` 䞺 `local_file` 时必填。" } } } @@ -2932,6 +2932,11 @@ "type": "object", "description": "消息结束事件流匏䌠蟓已结束。", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "消息的唯䞀 ID。" + }, "metadata": { "type": "object", "description": "包含甚量和检玢资源的元数据。", @@ -3262,7 +3267,7 @@ "external_user_id": { "type": "string", "nullable": true, - "description": "API 请求䞭提䟛的 `user` 标识笊䟋劂 [发送聊倩消息](/api-reference/对话消息/发送对话消息) 侭的 `user` 字段。" + "description": "API 请求䞭提䟛的 `user` 标识笊䟋劂 [发送对话消息](/api-reference/对话消息/发送对话消息) 侭的 `user` 字段。" }, "name": { "type": "string", @@ -3506,7 +3511,7 @@ }, "extra_contents": { "type": "array", - "description": "䞎该消息关联的附加执行内容䟋劂人工蟓入衚单数据。", + "description": "䞎该消息关联的附加执行内容䟋劂人工介入衚单数据。", "items": { "type": "object", "additionalProperties": true diff --git a/zh/api-reference/openapi_chatflow.json b/zh/api-reference/openapi_chatflow.json index edd459041..35bd21558 100644 --- a/zh/api-reference/openapi_chatflow.json +++ b/zh/api-reference/openapi_chatflow.json @@ -307,7 +307,7 @@ "name": "task_id", "in": "path", "required": true, - "description": "任务 ID可以从 [发送聊倩消息](/api-reference/对话消息/发送对话消息) API 的流匏分块返回䞭获取。", + "description": "任务 ID可以从 [发送对话消息](/api-reference/对话消息/发送对话消息) API 的流匏分块返回䞭获取。", "schema": { "type": "string" } @@ -626,7 +626,7 @@ "name": "file_id", "in": "path", "required": true, - "description": "芁预览的文件唯䞀标识笊从 [文件䞊䌠](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", + "description": "芁预览的文件唯䞀标识笊从 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", "schema": { "type": "string", "format": "uuid" @@ -3154,6 +3154,11 @@ "type": "object", "description": "消息结束事件流匏䌠蟓已结束。", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "消息的唯䞀 ID。" + }, "metadata": { "type": "object", "description": "包含甚量和检玢资源的元数据。", @@ -3484,7 +3489,7 @@ "external_user_id": { "type": "string", "nullable": true, - "description": "API 请求䞭提䟛的 `user` 标识笊䟋劂 [发送聊倩消息](/api-reference/对话消息/发送对话消息) 侭的 `user` 字段。" + "description": "API 请求䞭提䟛的 `user` 标识笊䟋劂 [发送对话消息](/api-reference/对话消息/发送对话消息) 侭的 `user` 字段。" }, "name": { "type": "string", @@ -3728,7 +3733,7 @@ }, "extra_contents": { "type": "array", - "description": "䞎歀消息关联的附加执行内容䟋劂对话流工䜜流䞭人工蟓入节点的衚单数据。", + "description": "䞎歀消息关联的附加执行内容䟋劂对话流工䜜流䞭人工介入节点的衚单数据。", "items": { "$ref": "#/components/schemas/HumanInputContent" } @@ -4645,7 +4650,7 @@ }, "reason": { "type": "string", - "description": "工䜜流启劚原因。`initial` 衚瀺銖次启劚`resumption` 衚瀺暂停后恢倍䟋劂人工蟓入后。" + "description": "工䜜流启劚原因。`initial` 衚瀺銖次启劚`resumption` 衚瀺暂停后恢倍䟋劂人工介入后。" } } } @@ -4682,7 +4687,7 @@ }, "status": { "type": "string", - "description": "执行状态。`running` 衚瀺进行䞭`succeeded` 衚瀺成功`failed` 衚瀺倱莥`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分完成`paused` 衚瀺等埅人工蟓入。" + "description": "执行状态。`running` 衚瀺进行䞭`succeeded` 衚瀺成功`failed` 衚瀺倱莥`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分完成`paused` 衚瀺等埅人工介入。" }, "outputs": { "type": "object", @@ -5451,7 +5456,7 @@ }, { "type": "object", - "description": "人工蟓入节点正圚等埅甚户蟓入。", + "description": "人工介入节点正圚等埅甚户蟓入。", "properties": { "workflow_run_id": { "type": "string", @@ -5466,11 +5471,11 @@ }, "node_id": { "type": "string", - "description": "人工蟓入节点的节点 ID。" + "description": "人工介入节点的节点 ID。" }, "node_title": { "type": "string", - "description": "人工蟓入节点的标题。" + "description": "人工介入节点的标题。" }, "form_content": { "type": "string", @@ -5788,7 +5793,7 @@ }, "status": { "type": "string", - "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工介入。" }, "inputs": { "type": "object", @@ -5930,7 +5935,7 @@ }, "status": { "type": "string", - "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工介入。" }, "error": { "type": "string", @@ -5995,7 +6000,7 @@ }, "HumanInputContent": { "type": "object", - "description": "人工蟓入节点的执行内容包括衚单定义和提亀数据。", + "description": "人工介入节点的执行内容包括衚单定义和提亀数据。", "properties": { "workflow_run_id": { "type": "string", @@ -6003,15 +6008,15 @@ }, "submitted": { "type": "boolean", - "description": "人工蟓入衚单是吊已提亀。" + "description": "人工介入衚单是吊已提亀。" }, "type": { "type": "string", - "description": "`human_input` 衚瀺人工蟓入内容。" + "description": "`human_input` 衚瀺人工介入内容。" }, "form_definition": { "nullable": true, - "description": "人工蟓入节点的衚单定义。圓内容衚瀺提亀响应时䞺 `null`。", + "description": "人工介入节点的衚单定义。圓内容衚瀺提亀响应时䞺 `null`。", "$ref": "#/components/schemas/HumanInputFormDefinition" }, "form_submission_data": { @@ -6023,7 +6028,7 @@ }, "HumanInputFormDefinition": { "type": "object", - "description": "由人工蟓入节点枲染的人工蟓入衚单定义。", + "description": "由人工介入节点枲染的人工介入衚单定义。", "properties": { "form_id": { "type": "string", @@ -6031,11 +6036,11 @@ }, "node_id": { "type": "string", - "description": "生成该衚单的人工蟓入节点 ID。" + "description": "生成该衚单的人工介入节点 ID。" }, "node_title": { "type": "string", - "description": "Human Input 节点的标题。" + "description": "人工介入节点的标题。" }, "form_content": { "type": "string", @@ -6077,15 +6082,15 @@ }, "HumanInputFormSubmissionData": { "type": "object", - "description": "来自已提亀的人工蟓入衚单的数据。", + "description": "来自已提亀的人工介入衚单的数据。", "properties": { "node_id": { "type": "string", - "description": "Human Input 节点的 ID。" + "description": "人工介入节点的 ID。" }, "node_title": { "type": "string", - "description": "Human Input 节点的标题。" + "description": "人工介入节点的标题。" }, "rendered_content": { "type": "string", @@ -6143,7 +6148,7 @@ }, "UserAction": { "type": "object", - "description": "人工蟓入衚单䞊的操䜜按钮。", + "description": "人工介入衚单䞊的操䜜按钮。", "properties": { "id": { "type": "string", diff --git a/zh/api-reference/openapi_completion.json b/zh/api-reference/openapi_completion.json index 2facc54c9..43bff9e05 100644 --- a/zh/api-reference/openapi_completion.json +++ b/zh/api-reference/openapi_completion.json @@ -225,7 +225,7 @@ "name": "task_id", "in": "path", "required": true, - "description": "任务 ID可以从 [发送补党消息](/api-reference/文本生成/发送消息) API 的流匏分块返回䞭获取。", + "description": "任务 ID可以从 [发送消息](/api-reference/文本生成/发送消息) API 的流匏分块返回䞭获取。", "schema": { "type": "string" } @@ -575,7 +575,7 @@ "name": "file_id", "in": "path", "required": true, - "description": "芁预览的文件唯䞀标识笊从 [文件䞊䌠](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", + "description": "芁预览的文件唯䞀标识笊从 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", "schema": { "type": "string", "format": "uuid" @@ -1328,7 +1328,7 @@ }, "upload_file_id": { "type": "string", - "description": "已䞊䌠文件 ID通过 [文件䞊䌠](/api-reference/文件操䜜/䞊䌠文件) API 预先䞊䌠获取圓 `transfer_method` 䞺 `local_file` 时䜿甚。" + "description": "已䞊䌠文件 ID通过 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 预先䞊䌠获取圓 `transfer_method` 䞺 `local_file` 时䜿甚。" } }, "anyOf": [ @@ -1385,7 +1385,7 @@ "task_id": { "type": "string", "format": "uuid", - "description": "甚于请求远螪和 [停止生成补党消息](/api-reference/文本生成/停止响应) API 的任务 ID。" + "description": "甚于请求远螪和 [停止响应](/api-reference/文本生成/停止响应) API 的任务 ID。" }, "id": { "type": "string", @@ -1512,6 +1512,11 @@ "type": "object", "description": "消息结束事件收到歀事件衚瀺流匏蟓出已结束。", "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "消息的唯䞀 ID。" + }, "metadata": { "type": "object", "description": "包含甚量和检玢资源的元数据。", @@ -1915,7 +1920,7 @@ "external_user_id": { "type": "string", "nullable": true, - "description": "API 请求䞭提䟛的 `user` 标识笊䟋劂 [发送补党消息](/api-reference/文本生成/发送消息) 侭的 `user` 字段。" + "description": "API 请求䞭提䟛的 `user` 标识笊䟋劂 [发送消息](/api-reference/文本生成/发送消息) 侭的 `user` 字段。" }, "name": { "type": "string", diff --git a/zh/api-reference/openapi_knowledge.json b/zh/api-reference/openapi_knowledge.json index b888ccd54..2473cdd63 100644 --- a/zh/api-reference/openapi_knowledge.json +++ b/zh/api-reference/openapi_knowledge.json @@ -59,7 +59,7 @@ "知识库" ], "summary": "创建空知识库", - "description": "创建新的空知识库。创建后䜿甚 [通过文本创建文档](/api-reference/文档/从文本创建文档) 或 [通过文件创建文档](/api-reference/文档/从文件创建文档) 添加文档。", + "description": "创建新的空知识库。创建后䜿甚 [从文本创建文档](/api-reference/文档/从文本创建文档) 或 [从文件创建文档](/api-reference/文档/从文件创建文档) 添加文档。", "operationId": "createDataset", "requestBody": { "required": true, @@ -258,7 +258,7 @@ "type": "integer", "default": 1 }, - "description": "Page number." + "description": "芁获取的页码。" }, { "name": "limit", @@ -800,7 +800,7 @@ "文档" ], "summary": "从文本创建文档", - "description": "通过纯文本内容创建文档。文档将匂步倄理——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", + "description": "通过纯文本内容创建文档。文档将匂步倄理——䜿甚返回的 `batch` ID 配合 [获取文档嵌入状态进床](/api-reference/文档/获取文档嵌入状态进床) 跟螪进床。", "operationId": "createDocumentFromText", "parameters": [ { @@ -1048,7 +1048,7 @@ "文档" ], "summary": "从文件创建文档", - "description": "通过䞊䌠文件创建文档。支持垞见文档栌匏PDF、TXT、DOCX 等。倄理过皋䞺匂步——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", + "description": "通过䞊䌠文件创建文档。支持垞见文档栌匏PDF、TXT、DOCX 等。倄理过皋䞺匂步——䜿甚返回的 `batch` ID 配合 [获取文档嵌入状态进床](/api-reference/文档/获取文档嵌入状态进床) 跟螪进床。", "operationId": "createDocumentFromFile", "parameters": [ { @@ -1079,7 +1079,7 @@ }, "data": { "type": "string", - "description": "包含配眮信息的 JSON 字笊䞲。接受䞎 [通过文本创建文档](/api-reference/文档/从文本创建文档) 盞同的字段`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`䜆䞍包括 `name` 和 `text`。", + "description": "包含配眮信息的 JSON 字笊䞲。接受䞎 [从文本创建文档](/api-reference/文档/从文本创建文档) 盞同的字段`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`䜆䞍包括 `name` 和 `text`。", "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } @@ -1271,7 +1271,7 @@ "type": "integer", "default": 1 }, - "description": "Page number." + "description": "芁获取的页码。" }, { "name": "limit", @@ -1442,7 +1442,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." }, { "name": "metadata", @@ -1762,7 +1762,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." } ], "responses": { @@ -1850,7 +1850,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." } ], "responses": { @@ -2074,7 +2074,7 @@ "文档" ], "summary": "甚文本曎新文档", - "description": "曎新现有文档的文本内容、名称或倄理配眮。内容变曎时将重新觊发玢匕——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", + "description": "曎新现有文档的文本内容、名称或倄理配眮。内容变曎时将重新觊发玢匕——䜿甚返回的 `batch` ID 配合 [获取文档嵌入状态进床](/api-reference/文档/获取文档嵌入状态进床) 跟螪进床。", "operationId": "updateDocumentByText", "parameters": [ { @@ -2095,7 +2095,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." } ], "requestBody": { @@ -2308,7 +2308,7 @@ "文档" ], "summary": "甚文件曎新文档", - "description": "通过䞊䌠新文件曎新现有文档。将重新觊发玢匕——䜿甚返回的 `batch` ID 配合 [获取文档玢匕状态](/api-reference/文档/获取文档嵌入状态-进床) 跟螪进床。", + "description": "通过䞊䌠新文件曎新现有文档。将重新觊发玢匕——䜿甚返回的 `batch` ID 配合 [获取文档嵌入状态进床](/api-reference/文档/获取文档嵌入状态进床) 跟螪进床。", "operationId": "updateDocumentByFile", "parameters": [ { @@ -2329,7 +2329,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." } ], "requestBody": { @@ -2346,7 +2346,7 @@ }, "data": { "type": "string", - "description": "包含配眮信息的 JSON 字笊䞲。接受䞎 [通过文本创建文档](/api-reference/文档/从文本创建文档) 盞同的字段`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`䜆䞍包括 `name` 和 `text`。", + "description": "包含配眮信息的 JSON 字笊䞲。接受䞎 [从文本创建文档](/api-reference/文档/从文本创建文档) 盞同的字段`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`䜆䞍包括 `name` 和 `text`。", "example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}" } } @@ -2746,7 +2746,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." } ], "requestBody": { @@ -2915,7 +2915,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." }, { "name": "page", @@ -2924,7 +2924,7 @@ "type": "integer", "default": 1 }, - "description": "Page number." + "description": "芁获取的页码。" }, { "name": "limit", @@ -3074,7 +3074,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." }, { "name": "segment_id", @@ -3176,7 +3176,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." }, { "name": "segment_id", @@ -3335,7 +3335,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." }, { "name": "segment_id", @@ -3382,7 +3382,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." }, { "name": "segment_id", @@ -3492,7 +3492,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." }, { "name": "segment_id", @@ -3512,7 +3512,7 @@ "default": 1, "minimum": 1 }, - "description": "Page number." + "description": "芁获取的页码。" }, { "name": "limit", @@ -3622,7 +3622,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." }, { "name": "segment_id", @@ -3742,7 +3742,7 @@ "type": "string", "format": "uuid" }, - "description": "Document ID." + "description": "文档 ID." }, { "name": "segment_id", diff --git a/zh/api-reference/openapi_workflow.json b/zh/api-reference/openapi_workflow.json index 215beae3b..17f6ca3c3 100644 --- a/zh/api-reference/openapi_workflow.json +++ b/zh/api-reference/openapi_workflow.json @@ -895,7 +895,7 @@ "name": "file_id", "in": "path", "required": true, - "description": "芁预览的文件唯䞀标识笊从 [文件䞊䌠](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", + "description": "芁预览的文件唯䞀标识笊从 [䞊䌠文件](/api-reference/文件操䜜/䞊䌠文件) API 响应䞭获取。", "schema": { "type": "string", "format": "uuid" @@ -2715,7 +2715,7 @@ }, "status": { "type": "string", - "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工介入。" }, "outputs": { "type": "object", @@ -2788,7 +2788,7 @@ }, "status": { "type": "string", - "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工介入。" }, "inputs": { "type": "object", @@ -2936,7 +2936,7 @@ "external_user_id": { "type": "string", "nullable": true, - "description": "API 请求䞭提䟛的 `user` 标识笊䟋劂 [发送聊倩消息](/api-reference/对话消息/发送对话消息) 侭的 `user` 字段。" + "description": "API 请求䞭提䟛的 `user` 标识笊䟋劂 [发送对话消息](/api-reference/对话消息/发送对话消息) 侭的 `user` 字段。" }, "name": { "type": "string", @@ -3060,7 +3060,7 @@ }, "status": { "type": "string", - "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工蟓入。" + "description": "工䜜流执行状态。`running` 衚瀺执行䞭`succeeded` 衚瀺成功完成`failed` 衚瀺执行出错`stopped` 衚瀺手劚停止`partial-succeeded` 衚瀺郚分节点成功䜆其他倱莥`paused` 衚瀺等埅人工介入。" }, "error": { "type": "string",