diff --git a/api/controllers/service_api/app/message.py b/api/controllers/service_api/app/message.py index b516e8afae..53476139d4 100644 --- a/api/controllers/service_api/app/message.py +++ b/api/controllers/service_api/app/message.py @@ -131,4 +131,4 @@ class MessageSuggestedApi(Resource): api.add_resource(MessageListApi, "/messages") api.add_resource(MessageFeedbackApi, "/messages//feedbacks") api.add_resource(MessageSuggestedApi, "/messages//suggested") -api.add_resource(AppGetFeedbacksApi, "/feedbacks") +api.add_resource(AppGetFeedbacksApi, "/app/feedbacks") diff --git a/web/app/components/develop/template/template.en.mdx b/web/app/components/develop/template/template.en.mdx index 75f044f780..c1ed213793 100755 --- a/web/app/components/develop/template/template.en.mdx +++ b/web/app/components/develop/template/template.en.mdx @@ -1,586 +1,649 @@ -import { CodeGroup } from '../code.tsx' -import { Row, Col, Properties, Property, Heading, SubProperty, Paragraph } from '../md.tsx' - -# Completion App API - -The text generation application offers non-session support and is ideal for translation, article writing, summarization AI, and more. - -
- ### Base URL - - ```javascript - ``` - - - ### Authentication - - The Service API uses `API-Key` authentication. - **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.** - - For all API requests, include your API Key in the `Authorization` HTTP Header, as shown below: - - - ```javascript - Authorization: Bearer {API_KEY} - - ``` - -
- ---- - - - - - Send a request to the text generation application. - - ### Request Body - - - - - 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. - - `query` (string) Required - The input text, the content to be processed. - - - The mode of response return, supporting: - - `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)). - - `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. - - - 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. - - - File list, suitable for inputting files (images) combined with text understanding and answering questions, available only when the model supports Vision capability. - - `type` (string) Supported type: `image` (currently only supports image type) - - `transfer_method` (string) Transfer method, `remote_url` for image URL / `local_file` for file upload - - `url` (string) Image URL (when the transfer method is `remote_url`) - - `upload_file_id` (string) Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`) - - - - ### Response - When `response_mode` is `blocking`, return a CompletionResponse object. - When `response_mode` is `streaming`, return a ChunkCompletionResponse stream. - - ### ChatCompletionResponse - Returns the complete App result, `Content-Type` is `application/json`. - - `message_id` (string) Unique message ID - - `mode` (string) App mode, fixed as `chat` - - `answer` (string) Complete response content - - `metadata` (object) Metadata - - `usage` (Usage) Model usage information - - `retriever_resources` (array[RetrieverResource]) Citation and Attribution List - - `created_at` (int) Message creation timestamp, e.g., 1705395332 - - ### ChunkChatCompletionResponse - Returns the stream chunks outputted by the App, `Content-Type` is `text/event-stream`. - Each streaming chunk starts with `data:`, separated by two newline characters `\n\n`, as shown below: - - ```streaming {{ title: 'Response' }} - data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n - ``` - - The structure of the streaming chunks varies depending on the `event`: - - `event: message` LLM returns text chunk event, i.e., the complete text is output in a chunked fashion. - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `message_id` (string) Unique message ID - - `answer` (string) LLM returned text chunk content - - `created_at` (int) Creation timestamp, e.g., 1705395332 - - `event: message_end` Message end event, receiving this event means streaming has ended. - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `message_id` (string) Unique message ID - - `metadata` (object) Metadata - - `usage` (Usage) Model usage information - - `retriever_resources` (array[RetrieverResource]) Citation and Attribution List - - `event: tts_message` TTS audio stream event, that is, speech synthesis output. The content is an audio block in Mp3 format, encoded as a base64 string. When playing, simply decode the base64 and feed it into the player. (This message is available only when auto-play is enabled) - - `task_id` (string) Task ID, used for request tracking and the stop response interface below - - `message_id` (string) Unique message ID - - `audio` (string) The audio after speech synthesis, encoded in base64 text content, when playing, simply decode the base64 and feed it into the player - - `created_at` (int) Creation timestamp, e.g.: 1705395332 - - `event: tts_message_end` TTS audio stream end event, receiving this event indicates the end of the audio stream. - - `task_id` (string) Task ID, used for request tracking and the stop response interface below - - `message_id` (string) Unique message ID - - `audio` (string) The end event has no audio, so this is an empty string - - `created_at` (int) Creation timestamp, e.g.: 1705395332 - - `event: message_replace` 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. - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `message_id` (string) Unique message ID - - `answer` (string) Replacement content (directly replaces all LLM reply text) - - `created_at` (int) Creation timestamp, e.g., 1705395332 - - `event: error` - 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. - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `message_id` (string) Unique message ID - - `status` (int) HTTP status code - - `code` (string) Error code - - `message` (string) Error message - - `event: ping` Ping event every 10 seconds to keep the connection alive. - - ### Errors - - 404, Conversation does not exists - - 400, `invalid_param`, abnormal parameter input - - 400, `app_unavailable`, App configuration unavailable - - 400, `provider_not_initialize`, no available model credential configuration - - 400, `provider_quota_exceeded`, model invocation quota insufficient - - 400, `model_currently_not_support`, current model unavailable - - 400, `completion_request_error`, text generation failed - - 500, internal server error - - - - - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/completion-messages' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "inputs": { - "query": "Hello, world!" - }, - "response_mode": "streaming", - "user": "abc-123" - }' - ``` - - - ### Blocking Mode - - ```json {{ title: 'Response' }} - { - "event": "message", - "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 - } - ``` - - ### Streaming Mode - - ```streaming {{ title: 'Response' }} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": "'m", "created_at": 1679586595} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " glad", "created_at": 1679586595} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " to", "created_at": 1679586595} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " meet", "created_at": 1679586595} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " you", "created_at": 1679586595} - data: {"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}}} - data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"} - data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""} - ``` - - - - ---- - - - - 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. - - ### Request Body - This interface requires a `multipart/form-data` request. - - `file` (File) Required - The file to be uploaded. - - `user` (string) Required - User identifier, defined by the developer's rules, must be unique within the application. - - ### Response - After a successful upload, the server will return the file's ID and related information. - - `id` (uuid) ID - - `name` (string) File name - - `size` (int) File size (bytes) - - `extension` (string) File extension - - `mime_type` (string) File mime-type - - `created_by` (uuid) End-user ID - - `created_at` (timestamp) Creation timestamp, e.g., 1705395332 - - ### Errors - - 400, `no_file_uploaded`, a file must be provided - - 400, `too_many_files`, currently only one file is accepted - - 400, `unsupported_preview`, the file does not support preview - - 400, `unsupported_estimate`, the file does not support estimation - - 413, `file_too_large`, the file is too large - - 415, `unsupported_file_type`, unsupported extension, currently only document files are accepted - - 503, `s3_connection_failed`, unable to connect to S3 service - - 503, `s3_permission_denied`, no permission to upload files to S3 - - 503, `s3_file_too_large`, file exceeds S3 size limit - - 500, internal server error - - - - - ### Request Example - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/files/upload' \ - --header 'Authorization: Bearer {api_key}' \ - --form 'file=@"/path/to/file"' - ``` - - - - - ### Response Example - - ```json {{ title: 'Response' }} - { - "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, - } - ``` - - - ---- - - - - - Only supported in streaming mode. - ### Path - - `task_id` (string) Task ID, can be obtained from the streaming chunk return - Request Body - - `user` (string) Required - User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface. - ### Response - - `result` (string) Always returns "success" - - - ### Request Example - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/completion-messages/:task_id/stop' \ - -H 'Authorization: Bearer {api_key}' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "user": "abc-123" - }' - ``` - - - ### Response Example - - ```json {{ title: 'Response' }} - { - "result": "success" - } - ``` - - - - ---- - - - - - End-users can provide feedback messages, facilitating application developers to optimize expected outputs. - - ### Path - - - Message ID - - - - ### Request Body - - - - Upvote as `like`, downvote as `dislike`, revoke upvote as `null` - - - User identifier, defined by the developer's rules, must be unique within the application. - - - The specific content of message feedback. - - - - ### Response - - `result` (string) Always returns "success" - - - - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "rating": "like", - "user": "abc-123", - "content": "message feedback information" - }' - ``` - - - - - ```json {{ title: 'Response' }} - { - "result": "success" - } - ``` - - - - ---- - - - - - Text to speech. - - ### Request Body - - - - 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. - - - Speech generated content. - - - The user identifier, defined by the developer, must ensure uniqueness within the app. - - - - - - - - ```bash {{ title: 'cURL' }} - curl -o text-to-audio.mp3 -X POST '${props.appDetail.api_base_url}/text-to-audio' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", - "text": "Hello Dify", - "user": "abc-123" - }' - ``` - - - - - ```json {{ title: 'headers' }} - { - "Content-Type": "audio/wav" - } - ``` - - - ---- - - - - - Used to get basic information about this application - - ### Response - - `name` (string) application name - - `description` (string) application description - - `tags` (array[string]) application tags - - - - ```bash {{ title: 'cURL' }} - curl -X GET '${props.appDetail.api_base_url}/info' \ - -H 'Authorization: Bearer {api_key}' - ``` - - - ```json {{ title: 'Response' }} - { - "name": "My App", - "description": "This is my app.", - "tags": [ - "tag1", - "tag2" - ] - } - ``` - - - - ---- - - - - - Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values. - - ### Response - - `opening_statement` (string) Opening statement - - `suggested_questions` (array[string]) List of suggested questions for the opening - - `suggested_questions_after_answer` (object) Suggest questions after enabling the answer. - - `enabled` (bool) Whether it is enabled - - `speech_to_text` (object) Speech to text - - `enabled` (bool) Whether it is enabled - - `retriever_resource` (object) Citation and Attribution - - `enabled` (bool) Whether it is enabled - - `annotation_reply` (object) Annotation reply - - `enabled` (bool) Whether it is enabled - - `user_input_form` (array[object]) User input form configuration - - `text-input` (object) Text input control - - `label` (string) Variable display label name - - `variable` (string) Variable ID - - `required` (bool) Whether it is required - - `default` (string) Default value - - `paragraph` (object) Paragraph text input control - - `label` (string) Variable display label name - - `variable` (string) Variable ID - - `required` (bool) Whether it is required - - `default` (string) Default value - - `select` (object) Dropdown control - - `label` (string) Variable display label name - - `variable` (string) Variable ID - - `required` (bool) Whether it is required - - `default` (string) Default value - - `options` (array[string]) Option values - - `file_upload` (object) File upload configuration - - `image` (object) Image settings - Currently only supports image types: `png`, `jpg`, `jpeg`, `webp`, `gif` - - `enabled` (bool) Whether it is enabled - - `number_limits` (int) Image number limit, default is 3 - - `transfer_methods` (array[string]) List of transfer methods, remote_url, local_file, must choose one - - `system_parameters` (object) System parameters - - `file_size_limit` (int) Document upload size limit (MB) - - `image_file_size_limit` (int) Image file upload size limit (MB) - - `audio_file_size_limit` (int) Audio file upload size limit (MB) - - `video_file_size_limit` (int) Video file upload size limit (MB) - - - - - - - ```bash {{ title: 'cURL' }} - curl -X GET '${props.appDetail.api_base_url}/parameters' \ - --header 'Authorization: Bearer {api_key}' - ``` - - - - - ```json {{ title: 'Response' }} - { - "opening_statement": "Hello!", - "suggested_questions_after_answer": { - "enabled": true - }, - "speech_to_text": { - "enabled": true - }, - "retriever_resource": { - "enabled": true - }, - "annotation_reply": { - "enabled": true - }, - "user_input_form": [ - { - "paragraph": { - "label": "Query", - "variable": "query", - "required": true, - "default": "" - } - } - ], - "file_upload": { - "image": { - "enabled": false, - "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 - } - } - ``` - - - +import { CodeGroup } from '../code.tsx' +import { Row, Col, Properties, Property, Heading, SubProperty, Paragraph } from '../md.tsx' + +# Completion App API + +The text generation application offers non-session support and is ideal for translation, article writing, summarization AI, and more. + +
+ ### Base URL + + ```javascript + ``` + + + ### Authentication + + The Service API uses `API-Key` authentication. + **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.** + + For all API requests, include your API Key in the `Authorization` HTTP Header, as shown below: + + + ```javascript + Authorization: Bearer {API_KEY} + + ``` + +
+ +--- + + + + + Send a request to the text generation application. + + ### Request Body + + + + + 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. + - `query` (string) Required + The input text, the content to be processed. + + + The mode of response return, supporting: + - `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)). + - `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. + + + 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. + + + File list, suitable for inputting files (images) combined with text understanding and answering questions, available only when the model supports Vision capability. + - `type` (string) Supported type: `image` (currently only supports image type) + - `transfer_method` (string) Transfer method, `remote_url` for image URL / `local_file` for file upload + - `url` (string) Image URL (when the transfer method is `remote_url`) + - `upload_file_id` (string) Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`) + + + + ### Response + When `response_mode` is `blocking`, return a CompletionResponse object. + When `response_mode` is `streaming`, return a ChunkCompletionResponse stream. + + ### ChatCompletionResponse + Returns the complete App result, `Content-Type` is `application/json`. + - `message_id` (string) Unique message ID + - `mode` (string) App mode, fixed as `chat` + - `answer` (string) Complete response content + - `metadata` (object) Metadata + - `usage` (Usage) Model usage information + - `retriever_resources` (array[RetrieverResource]) Citation and Attribution List + - `created_at` (int) Message creation timestamp, e.g., 1705395332 + + ### ChunkChatCompletionResponse + Returns the stream chunks outputted by the App, `Content-Type` is `text/event-stream`. + Each streaming chunk starts with `data:`, separated by two newline characters `\n\n`, as shown below: + + ```streaming {{ title: 'Response' }} + data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n + ``` + + The structure of the streaming chunks varies depending on the `event`: + - `event: message` LLM returns text chunk event, i.e., the complete text is output in a chunked fashion. + - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API + - `message_id` (string) Unique message ID + - `answer` (string) LLM returned text chunk content + - `created_at` (int) Creation timestamp, e.g., 1705395332 + - `event: message_end` Message end event, receiving this event means streaming has ended. + - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API + - `message_id` (string) Unique message ID + - `metadata` (object) Metadata + - `usage` (Usage) Model usage information + - `retriever_resources` (array[RetrieverResource]) Citation and Attribution List + - `event: tts_message` TTS audio stream event, that is, speech synthesis output. The content is an audio block in Mp3 format, encoded as a base64 string. When playing, simply decode the base64 and feed it into the player. (This message is available only when auto-play is enabled) + - `task_id` (string) Task ID, used for request tracking and the stop response interface below + - `message_id` (string) Unique message ID + - `audio` (string) The audio after speech synthesis, encoded in base64 text content, when playing, simply decode the base64 and feed it into the player + - `created_at` (int) Creation timestamp, e.g.: 1705395332 + - `event: tts_message_end` TTS audio stream end event, receiving this event indicates the end of the audio stream. + - `task_id` (string) Task ID, used for request tracking and the stop response interface below + - `message_id` (string) Unique message ID + - `audio` (string) The end event has no audio, so this is an empty string + - `created_at` (int) Creation timestamp, e.g.: 1705395332 + - `event: message_replace` 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. + - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API + - `message_id` (string) Unique message ID + - `answer` (string) Replacement content (directly replaces all LLM reply text) + - `created_at` (int) Creation timestamp, e.g., 1705395332 + - `event: error` + 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. + - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API + - `message_id` (string) Unique message ID + - `status` (int) HTTP status code + - `code` (string) Error code + - `message` (string) Error message + - `event: ping` Ping event every 10 seconds to keep the connection alive. + + ### Errors + - 404, Conversation does not exists + - 400, `invalid_param`, abnormal parameter input + - 400, `app_unavailable`, App configuration unavailable + - 400, `provider_not_initialize`, no available model credential configuration + - 400, `provider_quota_exceeded`, model invocation quota insufficient + - 400, `model_currently_not_support`, current model unavailable + - 400, `completion_request_error`, text generation failed + - 500, internal server error + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/completion-messages' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "inputs": { + "query": "Hello, world!" + }, + "response_mode": "streaming", + "user": "abc-123" + }' + ``` + + + ### Blocking Mode + + ```json {{ title: 'Response' }} + { + "event": "message", + "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 + } + ``` + + ### Streaming Mode + + ```streaming {{ title: 'Response' }} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": "'m", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " glad", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " to", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " meet", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " you", "created_at": 1679586595} + data: {"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}}} + data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"} + data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""} + ``` + + + + +--- + + + + 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. + + ### Request Body + This interface requires a `multipart/form-data` request. + - `file` (File) Required + The file to be uploaded. + - `user` (string) Required + User identifier, defined by the developer's rules, must be unique within the application. + + ### Response + After a successful upload, the server will return the file's ID and related information. + - `id` (uuid) ID + - `name` (string) File name + - `size` (int) File size (bytes) + - `extension` (string) File extension + - `mime_type` (string) File mime-type + - `created_by` (uuid) End-user ID + - `created_at` (timestamp) Creation timestamp, e.g., 1705395332 + + ### Errors + - 400, `no_file_uploaded`, a file must be provided + - 400, `too_many_files`, currently only one file is accepted + - 400, `unsupported_preview`, the file does not support preview + - 400, `unsupported_estimate`, the file does not support estimation + - 413, `file_too_large`, the file is too large + - 415, `unsupported_file_type`, unsupported extension, currently only document files are accepted + - 503, `s3_connection_failed`, unable to connect to S3 service + - 503, `s3_permission_denied`, no permission to upload files to S3 + - 503, `s3_file_too_large`, file exceeds S3 size limit + - 500, internal server error + + + + + ### Request Example + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/files/upload' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@"/path/to/file"' + ``` + + + + + ### Response Example + + ```json {{ title: 'Response' }} + { + "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, + } + ``` + + + +--- + + + + + Only supported in streaming mode. + ### Path + - `task_id` (string) Task ID, can be obtained from the streaming chunk return + Request Body + - `user` (string) Required + User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface. + ### Response + - `result` (string) Always returns "success" + + + ### Request Example + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/completion-messages/:task_id/stop' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "user": "abc-123" + }' + ``` + + + ### Response Example + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + End-users can provide feedback messages, facilitating application developers to optimize expected outputs. + + ### Path + + + Message ID + + + + ### Request Body + + + + Upvote as `like`, downvote as `dislike`, revoke upvote as `null` + + + User identifier, defined by the developer's rules, must be unique within the application. + + + The specific content of message feedback. + + + + ### Response + - `result` (string) Always returns "success" + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "rating": "like", + "user": "abc-123", + "content": "message feedback information" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + Get application's feedbacks. + + ### Query + + + （optional）pagination，default：1 + + + + + + （optional） records per page default：20 + + + + ### Response + - `data` (List) return apps feedback list. + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + ``` + + + +--- + + + + + Text to speech. + + ### Request Body + + + + 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. + + + Speech generated content. + + + The user identifier, defined by the developer, must ensure uniqueness within the app. + + + + + + + + ```bash {{ title: 'cURL' }} + curl -o text-to-audio.mp3 -X POST '${props.appDetail.api_base_url}/text-to-audio' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", + "text": "Hello Dify", + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'headers' }} + { + "Content-Type": "audio/wav" + } + ``` + + + +--- + + + + + Used to get basic information about this application + + ### Response + - `name` (string) application name + - `description` (string) application description + - `tags` (array[string]) application tags + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/info' \ + -H 'Authorization: Bearer {api_key}' + ``` + + + ```json {{ title: 'Response' }} + { + "name": "My App", + "description": "This is my app.", + "tags": [ + "tag1", + "tag2" + ] + } + ``` + + + + +--- + + + + + Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values. + + ### Response + - `opening_statement` (string) Opening statement + - `suggested_questions` (array[string]) List of suggested questions for the opening + - `suggested_questions_after_answer` (object) Suggest questions after enabling the answer. + - `enabled` (bool) Whether it is enabled + - `speech_to_text` (object) Speech to text + - `enabled` (bool) Whether it is enabled + - `retriever_resource` (object) Citation and Attribution + - `enabled` (bool) Whether it is enabled + - `annotation_reply` (object) Annotation reply + - `enabled` (bool) Whether it is enabled + - `user_input_form` (array[object]) User input form configuration + - `text-input` (object) Text input control + - `label` (string) Variable display label name + - `variable` (string) Variable ID + - `required` (bool) Whether it is required + - `default` (string) Default value + - `paragraph` (object) Paragraph text input control + - `label` (string) Variable display label name + - `variable` (string) Variable ID + - `required` (bool) Whether it is required + - `default` (string) Default value + - `select` (object) Dropdown control + - `label` (string) Variable display label name + - `variable` (string) Variable ID + - `required` (bool) Whether it is required + - `default` (string) Default value + - `options` (array[string]) Option values + - `file_upload` (object) File upload configuration + - `image` (object) Image settings + Currently only supports image types: `png`, `jpg`, `jpeg`, `webp`, `gif` + - `enabled` (bool) Whether it is enabled + - `number_limits` (int) Image number limit, default is 3 + - `transfer_methods` (array[string]) List of transfer methods, remote_url, local_file, must choose one + - `system_parameters` (object) System parameters + - `file_size_limit` (int) Document upload size limit (MB) + - `image_file_size_limit` (int) Image file upload size limit (MB) + - `audio_file_size_limit` (int) Audio file upload size limit (MB) + - `video_file_size_limit` (int) Video file upload size limit (MB) + + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/parameters' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "opening_statement": "Hello!", + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": true + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": true + }, + "user_input_form": [ + { + "paragraph": { + "label": "Query", + "variable": "query", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": false, + "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 + } + } + ``` + + + diff --git a/web/app/components/develop/template/template.ja.mdx b/web/app/components/develop/template/template.ja.mdx index 50bf1e234b..1711ee97cb 100755 --- a/web/app/components/develop/template/template.ja.mdx +++ b/web/app/components/develop/template/template.ja.mdx @@ -1,584 +1,647 @@ -import { CodeGroup } from '../code.tsx' -import { Row, Col, Properties, Property, Heading, SubProperty, Paragraph } from '../md.tsx' - -# Completion アプリ API - -テキスト生成アプリケーションはセッションレスをサポートし、翻訳、記事作成、要約AI等に最適です。 - -
- ### ベースURL - - ```javascript - ``` - - - ### 認証 - - サービスAPIは`API-Key`認証を使用します。 - **APIキーの漏洩による重大な結果を避けるため、APIキーはサーバーサイドに保存し、クライアントサイドでは共有や保存しないことを強く推奨します。** - - すべてのAPIリクエストで、以下のように`Authorization` HTTPヘッダーにAPIキーを含めてください： - - - ```javascript - Authorization: Bearer {API_KEY} - - ``` - -
- ---- - - - - - テキスト生成アプリケーションにリクエストを送信します。 - - ### リクエストボディ - - - - - アプリで定義された各種変数値を入力できます。 - `inputs`パラメータには複数のキー/値ペアが含まれ、各キーは特定の変数に対応し、各値はその変数の具体的な値となります。 - テキスト生成アプリケーションでは、少なくとも1つのキー/値ペアの入力が必要です。 - - `query` (string) 必須 - 入力テキスト、処理される内容。 - - - レスポンス返却モード、以下をサポート： - - `streaming` ストリーミングモード（推奨）、SSE（[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)）によるタイプライター風の出力を実装。 - - `blocking` ブロッキングモード、実行完了後に結果を返却。（処理が長い場合はリクエストが中断される可能性があります） - Cloudflareの制限により、100秒後に返却なしで中断されます。 - - - ユーザー識別子、エンドユーザーの身元を定義し、取得や統計に使用します。 - アプリケーション内で開発者が一意に定義する必要があります。 - - - ファイルリスト、モデルがVision機能をサポートしている場合のみ、テキスト理解と質問応答を組み合わせたファイル（画像）の入力に適しています。 - - `type` (string) サポートされるタイプ：`image`（現在は画像タイプのみサポート） - - `transfer_method` (string) 転送方法、画像URLの場合は`remote_url` / ファイルアップロードの場合は`local_file` - - `url` (string) 画像URL（転送方法が`remote_url`の場合） - - `upload_file_id` (string) アップロードされたファイルID、事前にファイルアップロードAPIを通じてアップロードする必要があります（転送方法が`local_file`の場合） - - - - ### レスポンス - `response_mode`が`blocking`の場合、CompletionResponseオブジェクトを返却します。 - `response_mode`が`streaming`の場合、ChunkCompletionResponseストリームを返却します。 - - ### ChatCompletionResponse - アプリの完全な結果を返却、`Content-Type`は`application/json`です。 - - `message_id` (string) 一意のメッセージID - - `mode` (string) アプリモード、固定で`chat` - - `answer` (string) 完全な応答内容 - - `metadata` (object) メタデータ - - `usage` (Usage) モデル使用情報 - - `retriever_resources` (array[RetrieverResource]) 引用と帰属のリスト - - `created_at` (int) メッセージ作成タイムスタンプ、例：1705395332 - - ### ChunkChatCompletionResponse - アプリが出力するストリームチャンクを返却、`Content-Type`は`text/event-stream`です。 - 各ストリーミングチャンクは`data:`で始まり、2つの改行文字`\n\n`で区切られます： - - ```streaming {{ title: 'Response' }} - data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n - ``` - - ストリーミングチャンクの構造は`event`によって異なります： - - `event: message` LLMがテキストチャンクを返すイベント、つまり完全なテキストがチャンク形式で出力されます。 - - `task_id` (string) タスクID、リクエストの追跡と以下の生成停止APIに使用 - - `message_id` (string) 一意のメッセージID - - `answer` (string) LLMが返したテキストチャンクの内容 - - `created_at` (int) 作成タイムスタンプ、例：1705395332 - - `event: message_end` メッセージ終了イベント、このイベントを受信するとストリーミングが終了したことを意味します。 - - `task_id` (string) タスクID、リクエストの追跡と以下の生成停止APIに使用 - - `message_id` (string) 一意のメッセージID - - `metadata` (object) メタデータ - - `usage` (Usage) モデル使用情報 - - `retriever_resources` (array[RetrieverResource]) 引用と帰属のリスト - - `event: tts_message` TTS音声ストリームイベント、つまり音声合成出力。内容はMp3形式の音声ブロックで、base64文字列としてエンコードされています。再生時は単にbase64をデコードしてプレーヤーに供給するだけです。（このメッセージは自動再生が有効な場合のみ利用可能） - - `task_id` (string) タスクID、リクエストの追跡と以下の応答停止インターフェースに使用 - - `message_id` (string) 一意のメッセージID - - `audio` (string) 音声合成後の音声、base64テキストコンテンツとしてエンコード、再生時は単にbase64をデコードしてプレーヤーに供給 - - `created_at` (int) 作成タイムスタンプ、例：1705395332 - - `event: tts_message_end` TTS音声ストリーム終了イベント、このイベントを受信すると音声ストリームが終了したことを示します。 - - `task_id` (string) タスクID、リクエストの追跡と以下の応答停止インターフェースに使用 - - `message_id` (string) 一意のメッセージID - - `audio` (string) 終了イベントには音声がないため、空文字列 - - `created_at` (int) 作成タイムスタンプ、例：1705395332 - - `event: message_replace` メッセージ内容置換イベント。 - 出力内容のモデレーションが有効な場合、コンテンツがフラグ付けされると、このイベントを通じてメッセージ内容が事前設定された返信に置き換えられます。 - - `task_id` (string) タスクID、リクエストの追跡と以下の生成停止APIに使用 - - `message_id` (string) 一意のメッセージID - - `answer` (string) 置換内容（LLMの返信テキストすべてを直接置換） - - `created_at` (int) 作成タイムスタンプ、例：1705395332 - - `event: error` - ストリーミング処理中に発生した例外は、ストリームイベントの形式で出力され、エラーイベントを受信するとストリームが終了します。 - - `task_id` (string) タスクID、リクエストの追跡と以下の生成停止APIに使用 - - `message_id` (string) 一意のメッセージID - - `status` (int) HTTPステータスコード - - `code` (string) エラーコード - - `message` (string) エラーメッセージ - - `event: ping` 接続を維持するため10秒ごとのPingイベント。 - - ### エラー - - 404, 会話が存在しません - - 400, `invalid_param`, パラメータ入力異常 - - 400, `app_unavailable`, アプリ設定が利用できません - - 400, `provider_not_initialize`, 利用可能なモデル認証情報設定がありません - - 400, `provider_quota_exceeded`, モデル呼び出しクォータ不足 - - 400, `model_currently_not_support`, 現在のモデルは利用できません - - 400, `completion_request_error`, テキスト生成に失敗しました - - 500, 内部サーバーエラー - - - - - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/completion-messages' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "inputs": { - "query": "Hello, world!" - }, - "response_mode": "streaming", - "user": "abc-123" - }' - ``` - - - ### ブロッキングモード - - ```json {{ title: 'Response' }} - { - "event": "message", - "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 - } - ``` - - ### ストリーミングモード - - ```streaming {{ title: 'Response' }} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": "'m", "created_at": 1679586595} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " glad", "created_at": 1679586595} - data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " to", "created_at": 1679586595} - data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " meet", "created_at": 1679586595} - data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " you", "created_at": 1679586595} - data: {"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}}} - data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"} - data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""} - ``` - - - - ---- - - - - メッセージ送信時に使用するファイル（現在は画像のみ対応）をアップロードし、画像とテキストのマルチモーダルな理解を可能にします。 - png、jpg、jpeg、webp、gif形式に対応しています。 - アップロードされたファイルは、現在のエンドユーザーのみが使用できます。 - - ### リクエストボディ - このインターフェースは`multipart/form-data`リクエストが必要です。 - - `file` (File) 必須 - アップロードするファイル。 - - `user` (string) 必須 - 開発者のルールで定義されたユーザー識別子。アプリケーション内で一意である必要があります。 - - ### レスポンス - アップロードが成功すると、サーバーはファイルのIDと関連情報を返します。 - - `id` (uuid) ID - - `name` (string) ファイル名 - - `size` (int) ファイルサイズ（バイト） - - `extension` (string) ファイル拡張子 - - `mime_type` (string) ファイルのMIMEタイプ - - `created_by` (uuid) エンドユーザーID - - `created_at` (timestamp) 作成タイムスタンプ、例：1705395332 - - ### エラー - - 400, `no_file_uploaded`, ファイルを提供する必要があります - - 400, `too_many_files`, 現在は1つのファイルのみ受け付けています - - 400, `unsupported_preview`, ファイルがプレビューに対応していません - - 400, `unsupported_estimate`, ファイルが推定に対応していません - - 413, `file_too_large`, ファイルが大きすぎます - - 415, `unsupported_file_type`, サポートされていない拡張子です。現在はドキュメントファイルのみ受け付けています - - 503, `s3_connection_failed`, S3サービスに接続できません - - 503, `s3_permission_denied`, S3へのファイルアップロード権限がありません - - 503, `s3_file_too_large`, ファイルがS3のサイズ制限を超えています - - 500, 内部サーバーエラー - - - - ### リクエスト例 - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/files/upload' \ - --header 'Authorization: Bearer {api_key}' \ - --form 'file=@"/path/to/file"' - ``` - - - - - ### レスポンス例 - - ```json {{ title: 'Response' }} - { - "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, - } - ``` - - - ---- - - - - - ストリーミングモードでのみサポートされています。 - ### パス - - `task_id` (string) タスクID、ストリーミングチャンクの返信から取得可能 - リクエストボディ - - `user` (string) 必須 - ユーザー識別子。エンドユーザーの身元を定義するために使用され、メッセージ送信インターフェースで渡されたユーザーと一致する必要があります。 - ### レスポンス - - `result` (string) 常に"success"を返します - - - ### リクエスト例 - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/completion-messages/:task_id/stop' \ - -H 'Authorization: Bearer {api_key}' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "user": "abc-123" - }' - ``` - - - ### レスポンス例 - - ```json {{ title: 'Response' }} - { - "result": "success" - } - ``` - - - - ---- - - - - - エンドユーザーはフィードバックメッセージを提供でき、アプリケーション開発者が期待される出力を最適化するのに役立ちます。 - - ### パス - - - メッセージID - - - - ### リクエストボディ - - - - 高評価は`like`、低評価は`dislike`、高評価の取り消しは`null` - - - 開発者のルールで定義されたユーザー識別子。アプリケーション内で一意である必要があります。 - - - メッセージのフィードバックです。 - - - - ### レスポンス - - `result` (string) 常に"success"を返します - - - - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "rating": "like", - "user": "abc-123", - "content": "message feedback information" - }' - ``` - - - - - ```json {{ title: 'Response' }} - { - "result": "success" - } - ``` - - - ---- - - - - - テキストを音声に変換します。 - - ### リクエストボディ - - - - Difyが生成したテキストメッセージの場合、生成されたmessage-idを直接渡すだけです。バックエンドはmessage-idを使用して対応するコンテンツを検索し、音声情報を直接合成します。message_idとtextの両方が同時に提供された場合、message_idが優先されます。 - - - 音声生成コンテンツ。 - - - 開発者が定義したユーザー識別子。アプリ内で一意性を確保する必要があります。 - - - - - - - - ```bash {{ title: 'cURL' }} - curl -o text-to-audio.mp3 -X POST '${props.appDetail.api_base_url}/text-to-audio' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", - "text": "Hello Dify", - "user": "abc-123" - }' - ``` - - - - - ```json {{ title: 'headers' }} - { - "Content-Type": "audio/wav" - } - ``` - - - ---- - - - - - このアプリケーションの基本情報を取得するために使用されます - - ### Response - - `name` (string) アプリケーションの名前 - - `description` (string) アプリケーションの説明 - - `tags` (array[string]) アプリケーションのタグ - - - - ```bash {{ title: 'cURL' }} - curl -X GET '${props.appDetail.api_base_url}/info' \ - -H 'Authorization: Bearer {api_key}' - ``` - - - ```json {{ title: 'Response' }} - { - "name": "My App", - "description": "This is my app.", - "tags": [ - "tag1", - "tag2" - ] - } - ``` - - - - ---- - - - - - ページ開始時に、機能、入力パラメータ名、タイプ、デフォルト値などの情報を取得するために使用されます。 - - ### レスポンス - - `opening_statement` (string) 開始文 - - `suggested_questions` (array[string]) 開始時の提案質問リスト - - `suggested_questions_after_answer` (object) 回答後の提案質問を有効にします。 - - `enabled` (bool) 有効かどうか - - `speech_to_text` (object) 音声からテキスト - - `enabled` (bool) 有効かどうか - - `retriever_resource` (object) 引用と帰属 - - `enabled` (bool) 有効かどうか - - `annotation_reply` (object) 注釈付き返信 - - `enabled` (bool) 有効かどうか - - `user_input_form` (array[object]) ユーザー入力フォーム設定 - - `text-input` (object) テキスト入力コントロール - - `label` (string) 変数表示ラベル名 - - `variable` (string) 変数ID - - `required` (bool) 必須かどうか - - `default` (string) デフォルト値 - - `paragraph` (object) 段落テキスト入力コントロール - - `label` (string) 変数表示ラベル名 - - `variable` (string) 変数ID - - `required` (bool) 必須かどうか - - `default` (string) デフォルト値 - - `select` (object) ドロップダウンコントロール - - `label` (string) 変数表示ラベル名 - - `variable` (string) 変数ID - - `required` (bool) 必須かどうか - - `default` (string) デフォルト値 - - `options` (array[string]) オプション値 - - `file_upload` (object) ファイルアップロード設定 - - `image` (object) 画像設定 - 現在は画像タイプのみ対応：`png`、`jpg`、`jpeg`、`webp`、`gif` - - `enabled` (bool) 有効かどうか - - `number_limits` (int) 画像数制限、デフォルトは3 - - `transfer_methods` (array[string]) 転送方法リスト、remote_url、local_file、いずれかを選択 - - `system_parameters` (object) システムパラメータ - - `file_size_limit` (int) ドキュメントアップロードサイズ制限（MB） - - `image_file_size_limit` (int) 画像ファイルアップロードサイズ制限（MB） - - `audio_file_size_limit` (int) 音声ファイルアップロードサイズ制限（MB） - - `video_file_size_limit` (int) 動画ファイルアップロードサイズ制限（MB） - - - - - - - ```bash {{ title: 'cURL' }} - curl -X GET '${props.appDetail.api_base_url}/parameters' \ - --header 'Authorization: Bearer {api_key}' - ``` - - - - - ```json {{ title: 'Response' }} - { - "opening_statement": "Hello!", - "suggested_questions_after_answer": { - "enabled": true - }, - "speech_to_text": { - "enabled": true - }, - "retriever_resource": { - "enabled": true - }, - "annotation_reply": { - "enabled": true - }, - "user_input_form": [ - { - "paragraph": { - "label": "Query", - "variable": "query", - "required": true, - "default": "" - } - } - ], - "file_upload": { - "image": { - "enabled": false, - "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 - } - } - ``` - - - +import { CodeGroup } from '../code.tsx' +import { Row, Col, Properties, Property, Heading, SubProperty, Paragraph } from '../md.tsx' + +# Completion アプリ API + +テキスト生成アプリケーションはセッションレスをサポートし、翻訳、記事作成、要約AI等に最適です。 + +
+ ### ベースURL + + ```javascript + ``` + + + ### 認証 + + サービスAPIは`API-Key`認証を使用します。 + **APIキーの漏洩による重大な結果を避けるため、APIキーはサーバーサイドに保存し、クライアントサイドでは共有や保存しないことを強く推奨します。** + + すべてのAPIリクエストで、以下のように`Authorization` HTTPヘッダーにAPIキーを含めてください： + + + ```javascript + Authorization: Bearer {API_KEY} + + ``` + +
+ +--- + + + + + テキスト生成アプリケーションにリクエストを送信します。 + + ### リクエストボディ + + + + + アプリで定義された各種変数値を入力できます。 + `inputs`パラメータには複数のキー/値ペアが含まれ、各キーは特定の変数に対応し、各値はその変数の具体的な値となります。 + テキスト生成アプリケーションでは、少なくとも1つのキー/値ペアの入力が必要です。 + - `query` (string) 必須 + 入力テキスト、処理される内容。 + + + レスポンス返却モード、以下をサポート： + - `streaming` ストリーミングモード（推奨）、SSE（[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)）によるタイプライター風の出力を実装。 + - `blocking` ブロッキングモード、実行完了後に結果を返却。（処理が長い場合はリクエストが中断される可能性があります） + Cloudflareの制限により、100秒後に返却なしで中断されます。 + + + ユーザー識別子、エンドユーザーの身元を定義し、取得や統計に使用します。 + アプリケーション内で開発者が一意に定義する必要があります。 + + + ファイルリスト、モデルがVision機能をサポートしている場合のみ、テキスト理解と質問応答を組み合わせたファイル（画像）の入力に適しています。 + - `type` (string) サポートされるタイプ：`image`（現在は画像タイプのみサポート） + - `transfer_method` (string) 転送方法、画像URLの場合は`remote_url` / ファイルアップロードの場合は`local_file` + - `url` (string) 画像URL（転送方法が`remote_url`の場合） + - `upload_file_id` (string) アップロードされたファイルID、事前にファイルアップロードAPIを通じてアップロードする必要があります（転送方法が`local_file`の場合） + + + + ### レスポンス + `response_mode`が`blocking`の場合、CompletionResponseオブジェクトを返却します。 + `response_mode`が`streaming`の場合、ChunkCompletionResponseストリームを返却します。 + + ### ChatCompletionResponse + アプリの完全な結果を返却、`Content-Type`は`application/json`です。 + - `message_id` (string) 一意のメッセージID + - `mode` (string) アプリモード、固定で`chat` + - `answer` (string) 完全な応答内容 + - `metadata` (object) メタデータ + - `usage` (Usage) モデル使用情報 + - `retriever_resources` (array[RetrieverResource]) 引用と帰属のリスト + - `created_at` (int) メッセージ作成タイムスタンプ、例：1705395332 + + ### ChunkChatCompletionResponse + アプリが出力するストリームチャンクを返却、`Content-Type`は`text/event-stream`です。 + 各ストリーミングチャンクは`data:`で始まり、2つの改行文字`\n\n`で区切られます： + + ```streaming {{ title: 'Response' }} + data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n + ``` + + ストリーミングチャンクの構造は`event`によって異なります： + - `event: message` LLMがテキストチャンクを返すイベント、つまり完全なテキストがチャンク形式で出力されます。 + - `task_id` (string) タスクID、リクエストの追跡と以下の生成停止APIに使用 + - `message_id` (string) 一意のメッセージID + - `answer` (string) LLMが返したテキストチャンクの内容 + - `created_at` (int) 作成タイムスタンプ、例：1705395332 + - `event: message_end` メッセージ終了イベント、このイベントを受信するとストリーミングが終了したことを意味します。 + - `task_id` (string) タスクID、リクエストの追跡と以下の生成停止APIに使用 + - `message_id` (string) 一意のメッセージID + - `metadata` (object) メタデータ + - `usage` (Usage) モデル使用情報 + - `retriever_resources` (array[RetrieverResource]) 引用と帰属のリスト + - `event: tts_message` TTS音声ストリームイベント、つまり音声合成出力。内容はMp3形式の音声ブロックで、base64文字列としてエンコードされています。再生時は単にbase64をデコードしてプレーヤーに供給するだけです。（このメッセージは自動再生が有効な場合のみ利用可能） + - `task_id` (string) タスクID、リクエストの追跡と以下の応答停止インターフェースに使用 + - `message_id` (string) 一意のメッセージID + - `audio` (string) 音声合成後の音声、base64テキストコンテンツとしてエンコード、再生時は単にbase64をデコードしてプレーヤーに供給 + - `created_at` (int) 作成タイムスタンプ、例：1705395332 + - `event: tts_message_end` TTS音声ストリーム終了イベント、このイベントを受信すると音声ストリームが終了したことを示します。 + - `task_id` (string) タスクID、リクエストの追跡と以下の応答停止インターフェースに使用 + - `message_id` (string) 一意のメッセージID + - `audio` (string) 終了イベントには音声がないため、空文字列 + - `created_at` (int) 作成タイムスタンプ、例：1705395332 + - `event: message_replace` メッセージ内容置換イベント。 + 出力内容のモデレーションが有効な場合、コンテンツがフラグ付けされると、このイベントを通じてメッセージ内容が事前設定された返信に置き換えられます。 + - `task_id` (string) タスクID、リクエストの追跡と以下の生成停止APIに使用 + - `message_id` (string) 一意のメッセージID + - `answer` (string) 置換内容（LLMの返信テキストすべてを直接置換） + - `created_at` (int) 作成タイムスタンプ、例：1705395332 + - `event: error` + ストリーミング処理中に発生した例外は、ストリームイベントの形式で出力され、エラーイベントを受信するとストリームが終了します。 + - `task_id` (string) タスクID、リクエストの追跡と以下の生成停止APIに使用 + - `message_id` (string) 一意のメッセージID + - `status` (int) HTTPステータスコード + - `code` (string) エラーコード + - `message` (string) エラーメッセージ + - `event: ping` 接続を維持するため10秒ごとのPingイベント。 + + ### エラー + - 404, 会話が存在しません + - 400, `invalid_param`, パラメータ入力異常 + - 400, `app_unavailable`, アプリ設定が利用できません + - 400, `provider_not_initialize`, 利用可能なモデル認証情報設定がありません + - 400, `provider_quota_exceeded`, モデル呼び出しクォータ不足 + - 400, `model_currently_not_support`, 現在のモデルは利用できません + - 400, `completion_request_error`, テキスト生成に失敗しました + - 500, 内部サーバーエラー + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/completion-messages' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "inputs": { + "query": "Hello, world!" + }, + "response_mode": "streaming", + "user": "abc-123" + }' + ``` + + + ### ブロッキングモード + + ```json {{ title: 'Response' }} + { + "event": "message", + "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 + } + ``` + + ### ストリーミングモード + + ```streaming {{ title: 'Response' }} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": "'m", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " glad", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " to", "created_at": 1679586595} + data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " meet", "created_at": 1679586595} + data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " you", "created_at": 1679586595} + data: {"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}}} + data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"} + data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""} + ``` + + + + +--- + + + + メッセージ送信時に使用するファイル（現在は画像のみ対応）をアップロードし、画像とテキストのマルチモーダルな理解を可能にします。 + png、jpg、jpeg、webp、gif形式に対応しています。 + アップロードされたファイルは、現在のエンドユーザーのみが使用できます。 + + ### リクエストボディ + このインターフェースは`multipart/form-data`リクエストが必要です。 + - `file` (File) 必須 + アップロードするファイル。 + - `user` (string) 必須 + 開発者のルールで定義されたユーザー識別子。アプリケーション内で一意である必要があります。 + + ### レスポンス + アップロードが成功すると、サーバーはファイルのIDと関連情報を返します。 + - `id` (uuid) ID + - `name` (string) ファイル名 + - `size` (int) ファイルサイズ（バイト） + - `extension` (string) ファイル拡張子 + - `mime_type` (string) ファイルのMIMEタイプ + - `created_by` (uuid) エンドユーザーID + - `created_at` (timestamp) 作成タイムスタンプ、例：1705395332 + + ### エラー + - 400, `no_file_uploaded`, ファイルを提供する必要があります + - 400, `too_many_files`, 現在は1つのファイルのみ受け付けています + - 400, `unsupported_preview`, ファイルがプレビューに対応していません + - 400, `unsupported_estimate`, ファイルが推定に対応していません + - 413, `file_too_large`, ファイルが大きすぎます + - 415, `unsupported_file_type`, サポートされていない拡張子です。現在はドキュメントファイルのみ受け付けています + - 503, `s3_connection_failed`, S3サービスに接続できません + - 503, `s3_permission_denied`, S3へのファイルアップロード権限がありません + - 503, `s3_file_too_large`, ファイルがS3のサイズ制限を超えています + - 500, 内部サーバーエラー + + + + ### リクエスト例 + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/files/upload' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@"/path/to/file"' + ``` + + + + + ### レスポンス例 + + ```json {{ title: 'Response' }} + { + "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, + } + ``` + + + +--- + + + + + ストリーミングモードでのみサポートされています。 + ### パス + - `task_id` (string) タスクID、ストリーミングチャンクの返信から取得可能 + リクエストボディ + - `user` (string) 必須 + ユーザー識別子。エンドユーザーの身元を定義するために使用され、メッセージ送信インターフェースで渡されたユーザーと一致する必要があります。 + ### レスポンス + - `result` (string) 常に"success"を返します + + + ### リクエスト例 + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/completion-messages/:task_id/stop' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "user": "abc-123" + }' + ``` + + + ### レスポンス例 + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + エンドユーザーはフィードバックメッセージを提供でき、アプリケーション開発者が期待される出力を最適化するのに役立ちます。 + + ### パス + + + メッセージID + + + + ### リクエストボディ + + + + 高評価は`like`、低評価は`dislike`、高評価の取り消しは`null` + + + 開発者のルールで定義されたユーザー識別子。アプリケーション内で一意である必要があります。 + + + メッセージのフィードバックです。 + + + + ### レスポンス + - `result` (string) 常に"success"を返します + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "rating": "like", + "user": "abc-123", + "content": "message feedback information" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + +--- + + + + + アプリのエンドユーザーからのフィードバックや「いいね」を取得します。 + + ### クエリ + + + （任意）ページ番号。デフォルト値：1 + + + + + + （任意）1ページあたりの件数。デフォルト値：20 + + + + ### レスポンス + - `data` (リスト) このアプリの「いいね」とフィードバックの一覧を返します。 + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + ``` + + + +--- + + + + + テキストを音声に変換します。 + + ### リクエストボディ + + + + Difyが生成したテキストメッセージの場合、生成されたmessage-idを直接渡すだけです。バックエンドはmessage-idを使用して対応するコンテンツを検索し、音声情報を直接合成します。message_idとtextの両方が同時に提供された場合、message_idが優先されます。 + + + 音声生成コンテンツ。 + + + 開発者が定義したユーザー識別子。アプリ内で一意性を確保する必要があります。 + + + + + + + + ```bash {{ title: 'cURL' }} + curl -o text-to-audio.mp3 -X POST '${props.appDetail.api_base_url}/text-to-audio' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", + "text": "Hello Dify", + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'headers' }} + { + "Content-Type": "audio/wav" + } + ``` + + + +--- + + + + + このアプリケーションの基本情報を取得するために使用されます + + ### Response + - `name` (string) アプリケーションの名前 + - `description` (string) アプリケーションの説明 + - `tags` (array[string]) アプリケーションのタグ + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/info' \ + -H 'Authorization: Bearer {api_key}' + ``` + + + ```json {{ title: 'Response' }} + { + "name": "My App", + "description": "This is my app.", + "tags": [ + "tag1", + "tag2" + ] + } + ``` + + + + +--- + + + + + ページ開始時に、機能、入力パラメータ名、タイプ、デフォルト値などの情報を取得するために使用されます。 + + ### レスポンス + - `opening_statement` (string) 開始文 + - `suggested_questions` (array[string]) 開始時の提案質問リスト + - `suggested_questions_after_answer` (object) 回答後の提案質問を有効にします。 + - `enabled` (bool) 有効かどうか + - `speech_to_text` (object) 音声からテキスト + - `enabled` (bool) 有効かどうか + - `retriever_resource` (object) 引用と帰属 + - `enabled` (bool) 有効かどうか + - `annotation_reply` (object) 注釈付き返信 + - `enabled` (bool) 有効かどうか + - `user_input_form` (array[object]) ユーザー入力フォーム設定 + - `text-input` (object) テキスト入力コントロール + - `label` (string) 変数表示ラベル名 + - `variable` (string) 変数ID + - `required` (bool) 必須かどうか + - `default` (string) デフォルト値 + - `paragraph` (object) 段落テキスト入力コントロール + - `label` (string) 変数表示ラベル名 + - `variable` (string) 変数ID + - `required` (bool) 必須かどうか + - `default` (string) デフォルト値 + - `select` (object) ドロップダウンコントロール + - `label` (string) 変数表示ラベル名 + - `variable` (string) 変数ID + - `required` (bool) 必須かどうか + - `default` (string) デフォルト値 + - `options` (array[string]) オプション値 + - `file_upload` (object) ファイルアップロード設定 + - `image` (object) 画像設定 + 現在は画像タイプのみ対応：`png`、`jpg`、`jpeg`、`webp`、`gif` + - `enabled` (bool) 有効かどうか + - `number_limits` (int) 画像数制限、デフォルトは3 + - `transfer_methods` (array[string]) 転送方法リスト、remote_url、local_file、いずれかを選択 + - `system_parameters` (object) システムパラメータ + - `file_size_limit` (int) ドキュメントアップロードサイズ制限（MB） + - `image_file_size_limit` (int) 画像ファイルアップロードサイズ制限（MB） + - `audio_file_size_limit` (int) 音声ファイルアップロードサイズ制限（MB） + - `video_file_size_limit` (int) 動画ファイルアップロードサイズ制限（MB） + + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/parameters' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "opening_statement": "Hello!", + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": true + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": true + }, + "user_input_form": [ + { + "paragraph": { + "label": "Query", + "variable": "query", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": false, + "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 + } + } + ``` + + + diff --git a/web/app/components/develop/template/template.zh.mdx b/web/app/components/develop/template/template.zh.mdx index 24abb481e3..9194c6c13c 100755 --- a/web/app/components/develop/template/template.zh.mdx +++ b/web/app/components/develop/template/template.zh.mdx @@ -1,852 +1,915 @@ -import { CodeGroup } from '../code.tsx' -import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx' - -# 文本生成型应用 API - -文本生成应用无会话支持，适合用于翻译/文章写作/总结 AI 等等。 - -
- ### 基础 URL - - ```javascript - ``` - - - ### 鉴权 - - - Dify Service API 使用 `API-Key` 进行鉴权。 - **强烈建议开发者把 `API-Key` 放在后端存储，而非分享或者放在客户端存储，以免 `API-Key` 泄露，导致财产损失。** - 所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`，如下所示： - - - ```javascript - Authorization: Bearer {API_KEY} - ``` - -
- ---- - - - - - 发送请求给文本生成型应用。 - - ### Request Body - - - - (选填)允许传入 App 定义的各变量值。 - inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。 - 文本生成型应用要求至少传入一组键值对。 - - `query` (string) 必填 - 用户输入的文本内容。 - - - - `streaming` 流式模式（推荐）。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现类似打字机输出方式的流式返回。 - - `blocking` 阻塞模式，等待执行完毕后返回结果。（请求若流程较长可能会被中断）。 - 由于 Cloudflare 限制，请求会在 100 秒超时无返回后中断。 - - - 用户标识，用于定义终端用户的身份，方便检索、统计。 - 由开发者定义规则，需保证用户标识在应用内唯一。 - - - 上传的文件。 - - `type` (string) 支持类型：图片 `image`（目前仅支持图片格式） 。 - - `transfer_method` (string) 传递方式: - - `remote_url`: 图片地址。 - - `local_file`: 上传文件。 - - `url` 图片地址。（仅当传递方式为 `remote_url` 时）。 - - `upload_file_id` 上传文件 ID。（仅当传递方式为 `local_file `时）。 - - - - ### Response - - 当 `response_mode` 为 `blocking` 时，返回 ChatCompletionResponse object。 - 当 `response_mode` 为 `streaming`时，返回 ChunkChatCompletionResponse object 流式序列。 - - ### ChatCompletionResponse - 返回完整的 App 结果，`Content-Type` 为 `application/json`。 - - `message_id` (string) 消息唯一 ID - - `mode` (string) App 模式，固定为 chat - - `answer` (string) 完整回复内容 - - `metadata` (object) 元数据 - - `usage` (Usage) 模型用量信息 - - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 - - `created_at` (int) 消息创建时间戳，如：1705395332 - - ### ChunkChatCompletionResponse - 返回 App 输出的流式块，`Content-Type` 为 `text/event-stream`。 - 每个流式块均为 data: 开头，块之间以 `\n\n` 即两个换行符分隔，如下所示： - - ```streaming {{ title: 'Response' }} - data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n - ``` - - 流式块中根据 `event` 不同，结构也不同： - - `event: message` LLM 返回文本块事件，即：完整的文本以分块的方式输出。 - - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 - - `message_id` (string) 消息唯一 ID - - `answer` (string) LLM 返回文本块内容 - - `created_at` (int) 创建时间戳，如：1705395332 - - `event: message_end` 消息结束事件，收到此事件则代表文本流式返回结束。 - - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 - - `message_id` (string) 消息唯一 ID - - `metadata` (object) 元数据 - - `usage` (Usage) 模型用量信息 - - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 - - `event: tts_message` TTS 音频流事件，即：语音合成输出。内容是Mp3格式的音频块，使用 base64 编码后的字符串，播放的时候直接解码即可。(开启自动播放才有此消息) - - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 - - `message_id` (string) 消息唯一 ID - - `audio` (string) 语音合成之后的音频块使用 Base64 编码之后的文本内容，播放的时候直接 base64 解码送入播放器即可 - - `created_at` (int) 创建时间戳，如：1705395332 - - `event: tts_message_end` TTS 音频流结束事件，收到这个事件表示音频流返回结束。 - - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 - - `message_id` (string) 消息唯一 ID - - `audio` (string) 结束事件是没有音频的，所以这里是空字符串 - - `created_at` (int) 创建时间戳，如：1705395332 - - `event: message_replace` 消息内容替换事件。 - 开启内容审查和审查输出内容时，若命中了审查条件，则会通过此事件替换消息内容为预设回复。 - - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 - - `message_id` (string) 消息唯一 ID - - `answer` (string) 替换内容（直接替换 LLM 所有回复文本） - - `created_at` (int) 创建时间戳，如：1705395332 - - `event: error` - 流式输出过程中出现的异常会以 stream event 形式输出，收到异常事件后即结束。 - - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 - - `message_id` (string) 消息唯一 ID - - `status` (int) HTTP 状态码 - - `code` (string) 错误码 - - `message` (string) 错误消息 - - `event: ping` 每 10s 一次的 ping 事件，保持连接存活。 - - ### Errors - - 404，对话不存在 - - 400，`invalid_param`，传入参数异常 - - 400，`app_unavailable`，App 配置不可用 - - 400，`provider_not_initialize`，无可用模型凭据配置 - - 400，`provider_quota_exceeded`，模型调用额度不足 - - 400，`model_currently_not_support`，当前模型不可用 - - 400，`completion_request_error`，文本生成失败 - - 500，服务内部异常 - - - - - - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/completion-messages' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "inputs": { - "query": "Hello, world!" - }, - "response_mode": "streaming", - "user": "abc-123" - }' - ``` - - ### blocking - - ```json {{ title: 'Response' }} - { - "id": "0b089b9a-24d9-48cc-94f8-762677276261", - "answer": "how are you?", - "created_at": 1679586667 - } - ``` - - ### streaming - - ```streaming {{ title: 'Response' }} - data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595} - data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595} - data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"} - data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""} - ``` - - - - ---- - - - - 上传文件（目前仅支持图片）并在发送消息时使用，可实现图文多模态理解。 - 支持 png, jpg, jpeg, webp, gif 格式。 - 上传的文件仅供当前终端用户使用。 - - ### Request Body - 该接口需使用 `multipart/form-data` 进行请求。 - - - 要上传的文件。 - - - 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 - - - - ### Response - 成功上传后，服务器会返回文件的 ID 和相关信息。 - - `id` (uuid) ID - - `name` (string) 文件名 - - `size` (int) 文件大小（byte） - - `extension` (string) 文件后缀 - - `mime_type` (string) 文件 mime-type - - `created_by` (uuid) 上传人 ID - - `created_at` (timestamp) 上传时间 - - ### Errors - - 400，`no_file_uploaded`，必须提供文件 - - 400，`too_many_files`，目前只接受一个文件 - - 400，`unsupported_preview`，该文件不支持预览 - - 400，`unsupported_estimate`，该文件不支持估算 - - 413，`file_too_large`，文件太大 - - 415，`unsupported_file_type`，不支持的扩展名，当前只接受文档类文件 - - 503，`s3_connection_failed`，无法连接到 S3 服务 - - 503，`s3_permission_denied`，无权限上传文件到 S3 - - 503，`s3_file_too_large`，文件超出 S3 大小限制 - - - - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/files/upload' \ - --header 'Authorization: Bearer {api_key}' \ - --form 'file=@"/path/to/file"' - ``` - - - - - ```json {{ title: 'Response' }} - { - "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67", - "name": "example.png", - "size": 1024, - "extension": "png", - "mime_type": "image/png", - "created_by": 123, - "created_at": 1577836800, - } - ``` - - - ---- - - - - 仅支持流式模式。 - ### Path - - `task_id` (string) 任务 ID，可在流式返回 Chunk 中获取 - - ### Request Body - - `user` (string) Required - 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 - ### Response - - `result` (string) 固定返回 success - - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/completion-messages/:task_id/stop' \ - -H 'Authorization: Bearer {api_key}' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "user": "abc-123" - }' - ``` - - - - - ```json {{ title: 'Response' }} - { - "result": "success" - } - ``` - - - ---- - - - - - 消息终端用户反馈、点赞，方便应用开发者优化输出预期。 - - ### Path Params - - - 消息 ID - - - - ### Request Body - - - - 点赞 like, 点踩 dislike, 撤销点赞 null - - - 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 - - - 消息反馈的具体信息。 - - - - ### Response - - `result` (string) 固定返回 success - - - - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "rating": "like", - "user": "abc-123", - "content": "message feedback information" - }' - ``` - - - - - ```json {{ title: 'Response' }} - { - "result": "success" - } - ``` - - - - ---- - - - - - 文字转语音。 - - ### Request Body - - - - Dify 生成的文本消息，那么直接传递生成的message-id 即可，后台会通过 message_id 查找相应的内容直接合成语音信息。如果同时传 message_id 和 text，优先使用 message_id。 - - - 语音生成内容。如果没有传 message-id的话，则会使用这个字段的内容 - - - 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 - - - - - - - - ```bash {{ title: 'cURL' }} - curl -o text-to-audio.mp3 -X POST '${props.appDetail.api_base_url}/text-to-audio' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", - "text": "你好Dify", - "user": "abc-123", - "streaming": false - }' - ``` - - - - - ```json {{ title: 'headers' }} - { - "Content-Type": "audio/wav" - } - ``` - - - ---- - - - - - 用于获取应用的基本信息 - ### Response - - `name` (string) 应用名称 - - `description` (string) 应用描述 - - `tags` (array[string]) 应用标签 - - - - ```bash {{ title: 'cURL' }} - curl -X GET '${props.appDetail.api_base_url}/info' \ - -H 'Authorization: Bearer {api_key}' - ``` - - - ```json {{ title: 'Response' }} - { - "name": "My App", - "description": "This is my app.", - "tags": [ - "tag1", - "tag2" - ] - } - ``` - - - - ---- - - - - - 用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。 - - ### Response - - `opening_statement` (string) 开场白 - - `suggested_questions` (array[string]) 开场推荐问题列表 - - `suggested_questions_after_answer` (object) 启用回答后给出推荐问题。 - - `enabled` (bool) 是否开启 - - `speech_to_text` (object) 语音转文本 - - `enabled` (bool) 是否开启 - - `retriever_resource` (object) 引用和归属 - - `enabled` (bool) 是否开启 - - `annotation_reply` (object) 标记回复 - - `enabled` (bool) 是否开启 - - `user_input_form` (array[object]) 用户输入表单配置 - - `text-input` (object) 文本输入控件 - - `label` (string) 控件展示标签名 - - `variable` (string) 控件 ID - - `required` (bool) 是否必填 - - `default` (string) 默认值 - - `paragraph` (object) 段落文本输入控件 - - `label` (string) 控件展示标签名 - - `variable` (string) 控件 ID - - `required` (bool) 是否必填 - - `default` (string) 默认值 - - `select` (object) 下拉控件 - - `label` (string) 控件展示标签名 - - `variable` (string) 控件 ID - - `required` (bool) 是否必填 - - `default` (string) 默认值 - - `options` (array[string]) 选项值 - - `file_upload` (object) 文件上传配置 - - `image` (object) 图片设置 - 当前仅支持图片类型：`png`, `jpg`, `jpeg`, `webp`, `gif` - - `enabled` (bool) 是否开启 - - `number_limits` (int) 图片数量限制，默认 3 - - `transfer_methods` (array[string]) 传递方式列表，remote_url , local_file，必选一个 - - `system_parameters` (object) 系统参数 - - `file_size_limit` (int) 文档上传大小限制 (MB) - - `image_file_size_limit` (int) 图片文件上传大小限制（MB） - - `audio_file_size_limit` (int) 音频文件上传大小限制 (MB) - - `video_file_size_limit` (int) 视频文件上传大小限制 (MB) - - - - - - ```bash {{ title: 'cURL' }} - curl -X GET '${props.appDetail.api_base_url}/parameters' \ - --header 'Authorization: Bearer {api_key}' - ``` - - - - - ```json {{ title: 'Response' }} - { - "introduction": "nice to meet you", - "user_input_form": [ - { - "text-input": { - "label": "a", - "variable": "a", - "required": true, - "max_length": 48, - "default": "" - } - }, - { - // ... - } - ], - "file_upload": { - "image": { - "enabled": true, - "number_limits": 3, - "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 - } - } - ``` - - - ---- - - - - - ### Query - - - 页码 - - - 每页数量 - - - - - - ```bash {{ title: 'cURL' }} - curl --location --request GET '${props.apiBaseUrl}/apps/annotations?page=1&limit=20' \ - --header 'Authorization: Bearer {api_key}' - ``` - - - - ```json {{ title: 'Response' }} - { - "data": [ - { - "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", - "question": "What is your name?", - "answer": "I am Dify.", - "hit_count": 0, - "created_at": 1735625869 - } - ], - "has_more": false, - "limit": 20, - "total": 1, - "page": 1 - } - ``` - - - ---- - - - - - ### Query - - - 问题 - - - 答案内容 - - - - - - ```bash {{ title: 'cURL' }} - curl --location --request POST '${props.apiBaseUrl}/apps/annotations' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "question": "What is your name?", - "answer": "I am Dify." - }' - ``` - - - - ```json {{ title: 'Response' }} - { - { - "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", - "question": "What is your name?", - "answer": "I am Dify.", - "hit_count": 0, - "created_at": 1735625869 - } - } - ``` - - - ---- - - - - - ### Query - - - 标注 ID - - - 问题 - - - 答案内容 - - - - - - ```bash {{ title: 'cURL' }} - curl --location --request POST '${props.apiBaseUrl}/apps/annotations/{annotation_id}' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "question": "What is your name?", - "answer": "I am Dify." - }' - ``` - - - - ```json {{ title: 'Response' }} - { - { - "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", - "question": "What is your name?", - "answer": "I am Dify.", - "hit_count": 0, - "created_at": 1735625869 - } - } - ``` - - - ---- - - - - - ### Query - - - 标注 ID - - - - - - ```bash {{ title: 'cURL' }} - curl --location --request DELETE '${props.apiBaseUrl}/apps/annotations/{annotation_id}' \ - --header 'Authorization: Bearer {api_key}' - ``` - - - - ```json {{ title: 'Response' }} - {"result": "success"} - ``` - - - ---- - - - - - ### Query - - - 动作，只能是 'enable' 或 'disable' - - - 指定的嵌入模型提供商, 必须先在系统内设定好接入的模型，对应的是provider字段 - - - 指定的嵌入模型，对应的是model字段 - - - 相似度阈值，当相似度大于该阈值时，系统会自动回复，否则不回复 - - - - - 嵌入模型的提供商和模型名称可以通过以下接口获取：v1/workspaces/current/models/model-types/text-embedding， 具体见：通过 API 维护知识库。 使用的Authorization是Dataset的API Token。 - 该接口是异步执行，所以会返回一个job_id，通过查询job状态接口可以获取到最终的执行结果。 - - ```bash {{ title: 'cURL' }} - curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/{action}' \ - --header 'Authorization: Bearer {api_key}' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "score_threshold": 0.9, - "embedding_provider_name": "zhipu", - "embedding_model_name": "embedding_3" - }' - ``` - - - - ```json {{ title: 'Response' }} - { - "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", - "job_status": "waiting" - } - ``` - - - - ---- - - - - - ### Query - - - 动作，只能是 'enable' 或 'disable'，并且必须和标注回复初始设置接口的动作一致 - - - 任务 ID，从标注回复初始设置接口返回的 job_id - - - - - - ```bash {{ title: 'cURL' }} - curl --location --request GET '${props.apiBaseUrl}/apps/annotation-reply/{action}/status/{job_id}' \ - --header 'Authorization: Bearer {api_key}' - ``` - - - - ```json {{ title: 'Response' }} - { - "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", - "job_status": "waiting", - "error_msg": "" - } - ``` - - - +import { CodeGroup } from '../code.tsx' +import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx' + +# 文本生成型应用 API + +文本生成应用无会话支持，适合用于翻译/文章写作/总结 AI 等等。 + +
+ ### 基础 URL + + ```javascript + ``` + + + ### 鉴权 + + + Dify Service API 使用 `API-Key` 进行鉴权。 + **强烈建议开发者把 `API-Key` 放在后端存储，而非分享或者放在客户端存储，以免 `API-Key` 泄露，导致财产损失。** + 所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`，如下所示： + + + ```javascript + Authorization: Bearer {API_KEY} + ``` + +
+ +--- + + + + + 发送请求给文本生成型应用。 + + ### Request Body + + + + (选填)允许传入 App 定义的各变量值。 + inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。 + 文本生成型应用要求至少传入一组键值对。 + - `query` (string) 必填 + 用户输入的文本内容。 + + + - `streaming` 流式模式（推荐）。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现类似打字机输出方式的流式返回。 + - `blocking` 阻塞模式，等待执行完毕后返回结果。（请求若流程较长可能会被中断）。 + 由于 Cloudflare 限制，请求会在 100 秒超时无返回后中断。 + + + 用户标识，用于定义终端用户的身份，方便检索、统计。 + 由开发者定义规则，需保证用户标识在应用内唯一。 + + + 上传的文件。 + - `type` (string) 支持类型：图片 `image`（目前仅支持图片格式） 。 + - `transfer_method` (string) 传递方式: + - `remote_url`: 图片地址。 + - `local_file`: 上传文件。 + - `url` 图片地址。（仅当传递方式为 `remote_url` 时）。 + - `upload_file_id` 上传文件 ID。（仅当传递方式为 `local_file `时）。 + + + + ### Response + + 当 `response_mode` 为 `blocking` 时，返回 ChatCompletionResponse object。 + 当 `response_mode` 为 `streaming`时，返回 ChunkChatCompletionResponse object 流式序列。 + + ### ChatCompletionResponse + 返回完整的 App 结果，`Content-Type` 为 `application/json`。 + - `message_id` (string) 消息唯一 ID + - `mode` (string) App 模式，固定为 chat + - `answer` (string) 完整回复内容 + - `metadata` (object) 元数据 + - `usage` (Usage) 模型用量信息 + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `created_at` (int) 消息创建时间戳，如：1705395332 + + ### ChunkChatCompletionResponse + 返回 App 输出的流式块，`Content-Type` 为 `text/event-stream`。 + 每个流式块均为 data: 开头，块之间以 `\n\n` 即两个换行符分隔，如下所示： + + ```streaming {{ title: 'Response' }} + data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n + ``` + + 流式块中根据 `event` 不同，结构也不同： + - `event: message` LLM 返回文本块事件，即：完整的文本以分块的方式输出。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `answer` (string) LLM 返回文本块内容 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: message_end` 消息结束事件，收到此事件则代表文本流式返回结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `metadata` (object) 元数据 + - `usage` (Usage) 模型用量信息 + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `event: tts_message` TTS 音频流事件，即：语音合成输出。内容是Mp3格式的音频块，使用 base64 编码后的字符串，播放的时候直接解码即可。(开启自动播放才有此消息) + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `audio` (string) 语音合成之后的音频块使用 Base64 编码之后的文本内容，播放的时候直接 base64 解码送入播放器即可 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: tts_message_end` TTS 音频流结束事件，收到这个事件表示音频流返回结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `audio` (string) 结束事件是没有音频的，所以这里是空字符串 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: message_replace` 消息内容替换事件。 + 开启内容审查和审查输出内容时，若命中了审查条件，则会通过此事件替换消息内容为预设回复。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `answer` (string) 替换内容（直接替换 LLM 所有回复文本） + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: error` + 流式输出过程中出现的异常会以 stream event 形式输出，收到异常事件后即结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `status` (int) HTTP 状态码 + - `code` (string) 错误码 + - `message` (string) 错误消息 + - `event: ping` 每 10s 一次的 ping 事件，保持连接存活。 + + ### Errors + - 404，对话不存在 + - 400，`invalid_param`，传入参数异常 + - 400，`app_unavailable`，App 配置不可用 + - 400，`provider_not_initialize`，无可用模型凭据配置 + - 400，`provider_quota_exceeded`，模型调用额度不足 + - 400，`model_currently_not_support`，当前模型不可用 + - 400，`completion_request_error`，文本生成失败 + - 500，服务内部异常 + + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/completion-messages' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "inputs": { + "query": "Hello, world!" + }, + "response_mode": "streaming", + "user": "abc-123" + }' + ``` + + ### blocking + + ```json {{ title: 'Response' }} + { + "id": "0b089b9a-24d9-48cc-94f8-762677276261", + "answer": "how are you?", + "created_at": 1679586667 + } + ``` + + ### streaming + + ```streaming {{ title: 'Response' }} + data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595} + data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595} + data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"} + data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""} + ``` + + + + +--- + + + + 上传文件（目前仅支持图片）并在发送消息时使用，可实现图文多模态理解。 + 支持 png, jpg, jpeg, webp, gif 格式。 + 上传的文件仅供当前终端用户使用。 + + ### Request Body + 该接口需使用 `multipart/form-data` 进行请求。 + + + 要上传的文件。 + + + 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 + + + + ### Response + 成功上传后，服务器会返回文件的 ID 和相关信息。 + - `id` (uuid) ID + - `name` (string) 文件名 + - `size` (int) 文件大小（byte） + - `extension` (string) 文件后缀 + - `mime_type` (string) 文件 mime-type + - `created_by` (uuid) 上传人 ID + - `created_at` (timestamp) 上传时间 + + ### Errors + - 400，`no_file_uploaded`，必须提供文件 + - 400，`too_many_files`，目前只接受一个文件 + - 400，`unsupported_preview`，该文件不支持预览 + - 400，`unsupported_estimate`，该文件不支持估算 + - 413，`file_too_large`，文件太大 + - 415，`unsupported_file_type`，不支持的扩展名，当前只接受文档类文件 + - 503，`s3_connection_failed`，无法连接到 S3 服务 + - 503，`s3_permission_denied`，无权限上传文件到 S3 + - 503，`s3_file_too_large`，文件超出 S3 大小限制 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/files/upload' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@"/path/to/file"' + ``` + + + + + ```json {{ title: 'Response' }} + { + "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67", + "name": "example.png", + "size": 1024, + "extension": "png", + "mime_type": "image/png", + "created_by": 123, + "created_at": 1577836800, + } + ``` + + + +--- + + + + 仅支持流式模式。 + ### Path + - `task_id` (string) 任务 ID，可在流式返回 Chunk 中获取 + + ### Request Body + - `user` (string) Required + 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 + ### Response + - `result` (string) 固定返回 success + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/completion-messages/:task_id/stop' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + +--- + + + + + 消息终端用户反馈、点赞，方便应用开发者优化输出预期。 + + ### Path Params + + + 消息 ID + + + + ### Request Body + + + + 点赞 like, 点踩 dislike, 撤销点赞 null + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + 消息反馈的具体信息。 + + + + ### Response + - `result` (string) 固定返回 success + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "rating": "like", + "user": "abc-123", + "content": "message feedback information" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + 获取应用的终端用户反馈、点赞。 + + ### Query + + + （选填）分页，默认值：1 + + + + + + （选填）每页数量，默认值：20 + + + + ### Response + - `data` (List) 返回该APP的点赞、反馈列表。 + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + ``` + + + +--- + + + + + 文字转语音。 + + ### Request Body + + + + Dify 生成的文本消息，那么直接传递生成的message-id 即可，后台会通过 message_id 查找相应的内容直接合成语音信息。如果同时传 message_id 和 text，优先使用 message_id。 + + + 语音生成内容。如果没有传 message-id的话，则会使用这个字段的内容 + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + + + + + ```bash {{ title: 'cURL' }} + curl -o text-to-audio.mp3 -X POST '${props.appDetail.api_base_url}/text-to-audio' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", + "text": "你好Dify", + "user": "abc-123", + "streaming": false + }' + ``` + + + + + ```json {{ title: 'headers' }} + { + "Content-Type": "audio/wav" + } + ``` + + + +--- + + + + + 用于获取应用的基本信息 + ### Response + - `name` (string) 应用名称 + - `description` (string) 应用描述 + - `tags` (array[string]) 应用标签 + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/info' \ + -H 'Authorization: Bearer {api_key}' + ``` + + + ```json {{ title: 'Response' }} + { + "name": "My App", + "description": "This is my app.", + "tags": [ + "tag1", + "tag2" + ] + } + ``` + + + + +--- + + + + + 用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。 + + ### Response + - `opening_statement` (string) 开场白 + - `suggested_questions` (array[string]) 开场推荐问题列表 + - `suggested_questions_after_answer` (object) 启用回答后给出推荐问题。 + - `enabled` (bool) 是否开启 + - `speech_to_text` (object) 语音转文本 + - `enabled` (bool) 是否开启 + - `retriever_resource` (object) 引用和归属 + - `enabled` (bool) 是否开启 + - `annotation_reply` (object) 标记回复 + - `enabled` (bool) 是否开启 + - `user_input_form` (array[object]) 用户输入表单配置 + - `text-input` (object) 文本输入控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `paragraph` (object) 段落文本输入控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `select` (object) 下拉控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `options` (array[string]) 选项值 + - `file_upload` (object) 文件上传配置 + - `image` (object) 图片设置 + 当前仅支持图片类型：`png`, `jpg`, `jpeg`, `webp`, `gif` + - `enabled` (bool) 是否开启 + - `number_limits` (int) 图片数量限制，默认 3 + - `transfer_methods` (array[string]) 传递方式列表，remote_url , local_file，必选一个 + - `system_parameters` (object) 系统参数 + - `file_size_limit` (int) 文档上传大小限制 (MB) + - `image_file_size_limit` (int) 图片文件上传大小限制（MB） + - `audio_file_size_limit` (int) 音频文件上传大小限制 (MB) + - `video_file_size_limit` (int) 视频文件上传大小限制 (MB) + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/parameters' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "introduction": "nice to meet you", + "user_input_form": [ + { + "text-input": { + "label": "a", + "variable": "a", + "required": true, + "max_length": 48, + "default": "" + } + }, + { + // ... + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "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 + } + } + ``` + + + +--- + + + + + ### Query + + + 页码 + + + 每页数量 + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.apiBaseUrl}/apps/annotations?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + { + "data": [ + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + ``` + + + +--- + + + + + ### Query + + + 问题 + + + 答案内容 + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST '${props.apiBaseUrl}/apps/annotations' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." + }' + ``` + + + + ```json {{ title: 'Response' }} + { + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + } + ``` + + + +--- + + + + + ### Query + + + 标注 ID + + + 问题 + + + 答案内容 + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST '${props.apiBaseUrl}/apps/annotations/{annotation_id}' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." + }' + ``` + + + + ```json {{ title: 'Response' }} + { + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + } + ``` + + + +--- + + + + + ### Query + + + 标注 ID + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request DELETE '${props.apiBaseUrl}/apps/annotations/{annotation_id}' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + {"result": "success"} + ``` + + + +--- + + + + + ### Query + + + 动作，只能是 'enable' 或 'disable' + + + 指定的嵌入模型提供商, 必须先在系统内设定好接入的模型，对应的是provider字段 + + + 指定的嵌入模型，对应的是model字段 + + + 相似度阈值，当相似度大于该阈值时，系统会自动回复，否则不回复 + + + + + 嵌入模型的提供商和模型名称可以通过以下接口获取：v1/workspaces/current/models/model-types/text-embedding， 具体见：通过 API 维护知识库。 使用的Authorization是Dataset的API Token。 + 该接口是异步执行，所以会返回一个job_id，通过查询job状态接口可以获取到最终的执行结果。 + + ```bash {{ title: 'cURL' }} + curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/{action}' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "score_threshold": 0.9, + "embedding_provider_name": "zhipu", + "embedding_model_name": "embedding_3" + }' + ``` + + + + ```json {{ title: 'Response' }} + { + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting" + } + ``` + + + + +--- + + + + + ### Query + + + 动作，只能是 'enable' 或 'disable'，并且必须和标注回复初始设置接口的动作一致 + + + 任务 ID，从标注回复初始设置接口返回的 job_id + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.apiBaseUrl}/apps/annotation-reply/{action}/status/{job_id}' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + { + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting", + "error_msg": "" + } + ``` + + + diff --git a/web/app/components/develop/template/template_advanced_chat.en.mdx b/web/app/components/develop/template/template_advanced_chat.en.mdx index f645133030..64c6f4d316 100644 --- a/web/app/components/develop/template/template_advanced_chat.en.mdx +++ b/web/app/components/develop/template/template_advanced_chat.en.mdx @@ -487,6 +487,69 @@ Chat applications support session persistence, allowing previous chat history to --- + + + + Get application's feedbacks. + + ### Query + + + （optional）pagination，default：1 + + + + + + （optional） records per page default：20 + + + + ### Response + - `data` (List) return apps feedback list. + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + ``` + + + +--- + + + + アプリのエンドユーザーからのフィードバックや「いいね」を取得します。 + + ### クエリ + + + （任意）ページ番号。デフォルト値：1 + + + + + + （任意）1ページあたりの件数。デフォルト値：20 + + + + ### レスポンス + - `data` (リスト) このアプリの「いいね」とフィードバックの一覧を返します。 + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + ``` + + + +--- + + + + + 获取应用的终端用户反馈、点赞。 + + ### Query + + + （选填）分页，默认值：1 + + + + + + （选填）每页数量，默认值：20 + + + + ### Response + - `data` (List) 返回该APP的点赞、反馈列表。 + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + + ``` + + + + +--- + + ### 基础 URL + + ```javascript + ``` + + + ### 鉴权 + + Service API 使用 `API-Key` 进行鉴权。 + **强烈建议开发者把 `API-Key` 放在后端存储，而非分享或者放在客户端存储，以免 `API-Key` 泄露，导致财产损失。** + 所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`，如下所示： + + + ```javascript + Authorization: Bearer {API_KEY} + ``` + + + +--- + + + + + 创建会话消息。 + + ### Request Body + + + + 用户输入/提问内容。 + + + 允许传入 App 定义的各变量值。 + inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。 + 如果变量是文件类型，请指定一个包含以下 `files` 中所述键的对象。 + 默认 `{}` + + + - `streaming` 流式模式（推荐）。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现类似打字机输出方式的流式返回。 + - `blocking` 阻塞模式，等待执行完毕后返回结果。（请求若流程较长可能会被中断）。 + 由于 Cloudflare 限制，请求会在 100 秒超时无返回后中断。 + + + 用户标识，用于定义终端用户的身份，方便检索、统计。 + 由开发者定义规则，需保证用户标识在应用内唯一。 + + + （选填）会话 ID，需要基于之前的聊天记录继续对话，必须传之前消息的 conversation_id。 + + + 文件列表，适用于传入文件结合文本理解并回答问题，仅当模型支持 Vision 能力时可用。 + - `type` (string) 支持类型： + - `document` 具体类型包含：'TXT', 'MD', 'MARKDOWN', 'PDF', 'HTML', 'XLSX', 'XLS', 'DOCX', 'CSV', 'EML', 'MSG', 'PPTX', 'PPT', 'XML', 'EPUB' + - `image` 具体类型包含：'JPG', 'JPEG', 'PNG', 'GIF', 'WEBP', 'SVG' + - `audio` 具体类型包含：'MP3', 'M4A', 'WAV', 'WEBM', 'AMR' + - `video` 具体类型包含：'MP4', 'MOV', 'MPEG', 'MPGA' + - `custom` 具体类型包含：其他文件类型 + - `transfer_method` (string) 传递方式: + - `remote_url`: 图片地址。 + - `local_file`: 上传文件。 + - `url` 图片地址。（仅当传递方式为 `remote_url` 时）。 + - `upload_file_id` 上传文件 ID。（仅当传递方式为 `local_file `时）。 + + + （选填）自动生成标题，默认 `true`。 若设置为 `false`，则可通过调用会话重命名接口并设置 `auto_generate` 为 `true` 实现异步生成标题。 + + + + ### Response + + 当 `response_mode` 为 `blocking` 时，返回 ChatCompletionResponse object。 + 当 `response_mode` 为 `streaming`时，返回 ChunkChatCompletionResponse object 流式序列。 + + ### ChatCompletionResponse + + 返回完整的 App 结果，`Content-Type` 为 `application/json`。 + - `event` (string) 事件类型，固定为 `message` + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `id` (string) 唯一ID + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `mode` (string) App 模式，固定为 chat + - `answer` (string) 完整回复内容 + - `metadata` (object) 元数据 + - `usage` (Usage) 模型用量信息 + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `created_at` (int) 消息创建时间戳，如：1705395332 + + ### ChunkChatCompletionResponse + 返回 App 输出的流式块，`Content-Type` 为 `text/event-stream`。 + 每个流式块均为 data: 开头，块之间以 \n\n 即两个换行符分隔，如下所示： + + ```streaming {{ title: 'Response' }} + data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n + ``` + + + 流式块中根据 event 不同，结构也不同： + - `event: message` LLM 返回文本块事件，即：完整的文本以分块的方式输出。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `answer` (string) LLM 返回文本块内容 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: message_file` 文件事件，表示有新文件需要展示 + - `id` (string) 文件唯一ID + - `type` (string) 文件类型，目前仅为image + - `belongs_to` (string) 文件归属，user或assistant，该接口返回仅为 `assistant` + - `url` (string) 文件访问地址 + - `conversation_id` (string) 会话ID + - `event: message_end` 消息结束事件，收到此事件则代表流式返回结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `metadata` (object) 元数据 + - `usage` (Usage) 模型用量信息 + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `event: tts_message` TTS 音频流事件，即：语音合成输出。内容是Mp3格式的音频块，使用 base64 编码后的字符串，播放的时候直接解码即可。(开启自动播放才有此消息) + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `audio` (string) 语音合成之后的音频块使用 Base64 编码之后的文本内容，播放的时候直接 base64 解码送入播放器即可 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: tts_message_end` TTS 音频流结束事件，收到这个事件表示音频流返回结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `audio` (string) 结束事件是没有音频的，所以这里是空字符串 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: message_replace` 消息内容替换事件。 + 开启内容审查和审查输出内容时，若命中了审查条件，则会通过此事件替换消息内容为预设回复。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `answer` (string) 替换内容（直接替换 LLM 所有回复文本） + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: workflow_started` workflow 开始执行 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `workflow_started` + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `workflow_id` (string) 关联 Workflow ID + - `sequence_number` (int) 自增序号，App 内自增，从 1 开始 + - `created_at` (timestamp) 开始时间 + - `event: node_started` node 开始执行 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `node_started` + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `node_id` (string) 节点 ID + - `node_type` (string) 节点类型 + - `title` (string) 节点名称 + - `index` (int) 执行序号，用于展示 Tracing Node 顺序 + - `predecessor_node_id` (string) 前置节点 ID，用于画布展示执行路径 + - `inputs` (object) 节点中所有使用到的前置节点变量内容 + - `created_at` (timestamp) 开始时间 + - `event: node_finished` node 执行结束，成功失败同一事件中不同状态 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `node_finished` + - `data` (object) 详细内容 + - `id` (string) node 执行 ID + - `node_id` (string) 节点 ID + - `index` (int) 执行序号，用于展示 Tracing Node 顺序 + - `predecessor_node_id` (string) optional 前置节点 ID，用于画布展示执行路径 + - `inputs` (object) 节点中所有使用到的前置节点变量内容 + - `process_data` (json) Optional 节点过程数据 + - `outputs` (json) Optional 输出内容 + - `status` (string) 执行状态 `running` / `succeeded` / `failed` / `stopped` + - `error` (string) Optional 错误原因 + - `elapsed_time` (float) Optional 耗时(s) + - `execution_metadata` (json) 元数据 + - `total_tokens` (int) optional 总使用 tokens + - `total_price` (decimal) optional 总费用 + - `currency` (string) optional 货币，如 `USD` / `RMB` + - `created_at` (timestamp) 开始时间 + - `event: workflow_finished` workflow 执行结束，成功失败同一事件中不同状态 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `workflow_finished` + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `workflow_id` (string) 关联 Workflow ID + - `status` (string) 执行状态 `running` / `succeeded` / `failed` / `stopped` + - `outputs` (json) Optional 输出内容 + - `error` (string) Optional 错误原因 + - `elapsed_time` (float) Optional 耗时(s) + - `total_tokens` (int) Optional 总使用 tokens + - `total_steps` (int) 总步数（冗余），默认 0 + - `created_at` (timestamp) 开始时间 + - `finished_at` (timestamp) 结束时间 + - `event: error` + 流式输出过程中出现的异常会以 stream event 形式输出，收到异常事件后即结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `status` (int) HTTP 状态码 + - `code` (string) 错误码 + - `message` (string) 错误消息 + - `event: ping` 每 10s 一次的 ping 事件，保持连接存活。 + + ### Errors + - 404，对话不存在 + - 400，`invalid_param`，传入参数异常 + - 400，`app_unavailable`，App 配置不可用 + - 400，`provider_not_initialize`，无可用模型凭据配置 + - 400，`provider_quota_exceeded`，模型调用额度不足 + - 400，`model_currently_not_support`，当前模型不可用 + - 400，`completion_request_error`，文本生成失败 + - 500，服务内部异常 + + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/chat-messages' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "inputs": { + "name": "dify" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "conversation_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "response_mode": "streaming", + "user": "abc-123", + "files": [ + { + "type": "image", + "transfer_method": "remote_url", + "url": "https://cloud.dify.ai/logo/logo-site.png" + } + ] + }' + ``` + + + ### 阻塞模式 + + ```json {{ title: 'Response' }} + { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "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\"\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\"" + } + ] + }, + "created_at": 1705407629 + } + ``` + + ### 流式模式 + + ```streaming {{ title: 'Response' }} + data: {"event": "workflow_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "sequence_number": 1, "created_at": 1679586595}} + data: {"event": "node_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "created_at": 1679586595}} + data: {"event": "node_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "execution_metadata": {"total_tokens": 63127864, "total_price": 2.378, "currency": "USD"}, "created_at": 1679586595}} + data: {"event": "workflow_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "total_tokens": 63127864, "total_steps": "1", "created_at": 1679586595, "finished_at": 1679976595}} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " I", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": "'m", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " glad", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " to", "created_at": 1679586595} + data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " meet", "created_at": 1679586595} + data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " you", "created_at": 1679586595} + data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "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}, "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\"\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\""}]}} + data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"} + data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""} + ``` + + + + +--- + + + + 上传文件并在发送消息时使用，可实现图文多模态理解。 + 支持您的应用程序所支持的所有格式。 + 上传的文件仅供当前终端用户使用。 + + ### Request Body + 该接口需使用 `multipart/form-data` 进行请求。 + + + 要上传的文件。 + + + 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 + + + + ### Response + 成功上传后，服务器会返回文件的 ID 和相关信息。 + - `id` (uuid) ID + - `name` (string) 文件名 + - `size` (int) 文件大小（byte） + - `extension` (string) 文件后缀 + - `mime_type` (string) 文件 mime-type + - `created_by` (uuid) 上传人 ID + - `created_at` (timestamp) 上传时间 + + ### Errors + - 400，`no_file_uploaded`，必须提供文件 + - 400，`too_many_files`，目前只接受一个文件 + - 400，`unsupported_preview`，该文件不支持预览 + - 400，`unsupported_estimate`，该文件不支持估算 + - 413，`file_too_large`，文件太大 + - 415，`unsupported_file_type`，不支持的扩展名，当前只接受文档类文件 + - 503，`s3_connection_failed`，无法连接到 S3 服务 + - 503，`s3_permission_denied`，无权限上传文件到 S3 + - 503，`s3_file_too_large`，文件超出 S3 大小限制 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/files/upload' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@"/path/to/file"' + ``` + + + + + ```json {{ title: 'Response' }} + { + "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67", + "name": "example.png", + "size": 1024, + "extension": "png", + "mime_type": "image/png", + "created_by": 123, + "created_at": 1577836800, + } + ``` + + + +--- + + + + 仅支持流式模式。 + ### Path + - `task_id` (string) 任务 ID，可在流式返回 Chunk 中获取 + + ### Request Body + - `user` (string) Required + 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 + ### Response + - `result` (string) 固定返回 success + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/chat-messages/:task_id/stop' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + +--- + + + + + 消息终端用户反馈、点赞，方便应用开发者优化输出预期。 + + ### Path Params + + + 消息 ID + + + + ### Request Body + + + + 点赞 like, 点踩 dislike, 撤销点赞 null + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + 消息反馈的具体信息。 + + + + ### Response + - `result` (string) 固定返回 success + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "rating": "like", + "user": "abc-123", + "content": "message feedback information" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + 获取下一轮建议问题列表。 + + ### Path Params + + + + Message ID + + + + ### Query + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.appDetail.api_base_url}/messages/{message_id}/suggested?user=abc-123' \ + --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \ + --header 'Content-Type: application/json' \ + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success", + "data": [ + "a", + "b", + "c" + ] + } + ``` + + + + +--- + +--- + + + + + 滚动加载形式返回历史聊天记录，第一页返回最新 `limit` 条，即：倒序返回。 + + ### Query + + + + 会话 ID + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + 当前页第一条聊天记录的 ID，默认 null + + + 一次请求返回多少条聊天记录，默认 20 条。 + + + + ### Response + - `data` (array[object]) 消息列表 + - `id` (string) 消息 ID + - `conversation_id` (string) 会话 ID + - `inputs` (object) 用户输入参数。 + - `query` (string) 用户输入 / 提问内容。 + - `message_files` (array[object]) 消息文件 + - `id` (string) ID + - `type` (string) 文件类型，image 图片 + - `url` (string) 预览图片地址 + - `belongs_to` (string) 文件归属方，user 或 assistant + - `answer` (string) 回答消息内容 + - `created_at` (timestamp) 创建时间 + - `feedback` (object) 反馈信息 + - `rating` (string) 点赞 like / 点踩 dislike + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `has_more` (bool) 是否存在下一页 + - `limit` (int) 返回条数，若传入超过系统限制，返回系统限制数量 + + + ### Request Example + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/messages?user=abc-123&conversation_id=' + --header 'Authorization: Bearer {api_key}' + ``` + + + + ### Response Example + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a076a87f-31e5-48dc-b452-0061adbbc922", + "conversation_id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce", + "inputs": { + "name": "dify" + }, + "query": "iphone 13 pro", + "answer": "The iPhone 13 Pro, released on September 24, 2021, features a 6.1-inch display with a resolution of 1170 x 2532. It is equipped with a Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard) processor, 6 GB of RAM, and offers storage options of 128 GB, 256 GB, 512 GB, and 1 TB. The camera is 12 MP, the battery capacity is 3095 mAh, and it runs on iOS 15.", + "message_files": [], + "feedback": null, + "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\"\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\"" + } + ], + "created_at": 1705569239 + } + ] + } + ``` + + + ### Response Example(智能助手) + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "d35e006c-7c4d-458f-9142-be4930abdf94", + "conversation_id": "957c068b-f258-4f89-ba10-6e8a0361c457", + "inputs": {}, + "query": "draw a cat", + "answer": "I have generated an image of a cat for you. Please check your messages to view the image.", + "message_files": [ + { + "id": "976990d2-5294-47e6-8f14-7356ba9d2d76", + "type": "image", + "url": "http://127.0.0.1:5001/files/tools/976990d2-5294-47e6-8f14-7356ba9d2d76.png?timestamp=1705988524&nonce=55df3f9f7311a9acd91bf074cd524092&sign=z43nMSO1L2HBvoqADLkRxr7Biz0fkjeDstnJiCK1zh8=", + "belongs_to": "assistant" + } + ], + "feedback": null, + "retriever_resources": [], + "created_at": 1705988187 + } + ] + } + ``` + + + + +--- + + + + + 获取当前用户的会话列表，默认返回最近的 20 条。 + + ### Query + + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + （选填）当前页最后面一条记录的 ID，默认 null + + + （选填）一次请求返回多少条记录，默认 20 条，最大 100 条，最小 1 条。 + + + （选填）排序字段，默认 -updated_at(按更新时间倒序排列) + - 可选值：created_at, -created_at, updated_at, -updated_at + - 字段前面的符号代表顺序或倒序，-代表倒序 + + + + ### Response + - `data` (array[object]) 会话列表 + - `id` (string) 会话 ID + - `name` (string) 会话名称，默认由大语言模型生成。 + - `inputs` (object) 用户输入参数。 + - `status` (string) 会话状态 + - `introduction` (string) 开场白 + - `created_at` (timestamp) 创建时间 + - `updated_at` (timestamp) 更新时间 + - `has_more` (bool) + - `limit` (int) 返回条数，若传入超过系统限制，返回系统限制数量 + + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/conversations?user=abc-123&last_id=&limit=20' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "10799fb8-64f7-4296-bbf7-b42bfbe0ae54", + "name": "New chat", + "inputs": { + "book": "book", + "myName": "Lucy" + }, + "status": "normal", + "created_at": 1679667915, + "updated_at": 1679667915 + }, + { + "id": "hSIhXBhNe8X1d8Et" + // ... + } + ] + } + ``` + + + + +--- + + + + 删除会话。 + + ### Path + - `conversation_id` (string) 会话 ID + + ### Request Body + + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `result` (string) 固定返回 success + + + + + + ```bash {{ title: 'cURL' }} + curl -X DELETE '${props.appDetail.api_base_url}/conversations/{conversation_id}' \ + --header 'Content-Type: application/json' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer {api_key}' \ + --data '{ + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + 对会话进行重命名，会话名称用于显示在支持多会话的客户端上。 + + ### Path + - `conversation_id` (string) 会话 ID + + ### Request Body + + + + （选填）名称，若 `auto_generate` 为 `true` 时，该参数可不传。 + + + （选填）自动生成标题，默认 false。 + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `id` (string) 会话 ID + - `name` (string) 会话名称 + - `inputs` (object) 用户输入参数 + - `status` (string) 会话状态 + - `introduction` (string) 开场白 + - `created_at` (timestamp) 创建时间 + - `updated_at` (timestamp) 更新时间 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/conversations/{conversation_id}/name' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "name": "", + "auto_generate": true, + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "id": "34d511d5-56de-4f16-a997-57b379508443", + "name": "hello", + "inputs": {}, + "status": "normal", + "introduction": "", + "created_at": 1732731141, + "updated_at": 1732734510 + } + ``` + + + + +--- + + + + + 从特定对话中检索变量。此端点对于提取对话过程中捕获的结构化数据非常有用。 + + ### 路径参数 + + + + 要从中检索变量的对话ID。 + + + + ### 查询参数 + + + + 用户标识符，由开发人员定义的规则，在应用程序内必须唯一。 + + + （选填）当前页最后面一条记录的 ID，默认 null + + + （选填）一次请求返回多少条记录，默认 20 条，最大 100 条，最小 1 条。 + + + + ### 响应 + + - `limit` (int) 每页项目数 + - `has_more` (bool) 是否有更多项目 + - `data` (array[object]) 变量列表 + - `id` (string) 变量ID + - `name` (string) 变量名称 + - `value_type` (string) 变量类型（字符串、数字、布尔等） + - `value` (string) 变量值 + - `description` (string) 变量描述 + - `created_at` (int) 创建时间戳 + - `updated_at` (int) 最后更新时间戳 + + ### 错误 + - 404, `conversation_not_exists`, 对话不存在 + + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/conversations/{conversation_id}/variables?user=abc-123' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/conversations/{conversation_id}/variables?user=abc-123&variable_name=customer_name' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + { + "limit": 100, + "has_more": false, + "data": [ + { + "id": "variable-uuid-1", + "name": "customer_name", + "value_type": "string", + "value": "John Doe", + "description": "客户名称（从对话中提取）", + "created_at": 1650000000000, + "updated_at": 1650000000000 + }, + { + "id": "variable-uuid-2", + "name": "order_details", + "value_type": "json", + "value": "{\"product\":\"Widget\",\"quantity\":5,\"price\":19.99}", + "description": "客户的订单详情", + "created_at": 1650000000000, + "updated_at": 1650000000000 + } + ] + } + ``` + + + + +--- + + + + + ### Request Body + 该接口需使用 `multipart/form-data` 进行请求。 + + + 语音文件。 + 支持格式：`['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']` + 文件大小限制：15MB + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `text` (string) 输出文字 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/conversations/name' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@localfile;type=audio/mp3' + ``` + + + + + ```json {{ title: 'Response' }} + { + "text": "hello" + } + ``` + + + + +--- + + + + + 文字转语音。 + + ### Request Body + + + + Dify 生成的文本消息，那么直接传递生成的message-id 即可，后台会通过 message_id 查找相应的内容直接合成语音信息。如果同时传 message_id 和 text，优先使用 message_id。 + + + 语音生成内容。如果没有传 message-id的话，则会使用这个字段的内容 + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + + + + + ```bash {{ title: 'cURL' }} + curl -o text-to-audio.mp3 -X POST '${props.appDetail.api_base_url}/text-to-audio' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", + "text": "你好Dify", + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'headers' }} + { + "Content-Type": "audio/wav" + } + ``` + + + +--- + + + + + 用于获取应用的基本信息 + ### Response + - `name` (string) 应用名称 + - `description` (string) 应用描述 + - `tags` (array[string]) 应用标签 + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/info' \ + -H 'Authorization: Bearer {api_key}' + ``` + + + ```json {{ title: 'Response' }} + { + "name": "My App", + "description": "This is my app.", + "tags": [ + "tag1", + "tag2" + ] + } + ``` + + + + +--- + + + + + 用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。 + + ### Response + - `opening_statement` (string) 开场白 + - `suggested_questions` (array[string]) 开场推荐问题列表 + - `suggested_questions_after_answer` (object) 启用回答后给出推荐问题。 + - `enabled` (bool) 是否开启 + - `speech_to_text` (object) 语音转文本 + - `enabled` (bool) 是否开启 + - `retriever_resource` (object) 引用和归属 + - `enabled` (bool) 是否开启 + - `annotation_reply` (object) 标记回复 + - `enabled` (bool) 是否开启 + - `user_input_form` (array[object]) 用户输入表单配置 + - `text-input` (object) 文本输入控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `paragraph` (object) 段落文本输入控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `select` (object) 下拉控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `options` (array[string]) 选项值 + - `file_upload` (object) 文件上传配置 + - `image` (object) 图片设置 + 当前仅支持图片类型：`png`, `jpg`, `jpeg`, `webp`, `gif` + - `enabled` (bool) 是否开启 + - `number_limits` (int) 图片数量限制，默认 3 + - `transfer_methods` (array[string]) 传递方式列表，remote_url , local_file，必选一个 + - `system_parameters` (object) 系统参数 + - `file_size_limit` (int) Document upload size limit (MB) + - `image_file_size_limit` (int) Image file upload size limit (MB) + - `audio_file_size_limit` (int) Audio file upload size limit (MB) + - `video_file_size_limit` (int) Video file upload size limit (MB) + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/parameters' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "introduction": "nice to meet you", + "user_input_form": [ + { + "text-input": { + "label": "a", + "variable": "a", + "required": true, + "max_length": 48, + "default": "" + } + }, + { + // ... + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "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 + } + } + ``` + + + + +--- + + + + + 用于获取工具icon + ### Response + - `tool_icons`(object[string]) 工具图标 + - `工具名称` (string) + - `icon` (object|string) + - (object) 图标 + - `background` (string) hex格式的背景色 + - `content`(string) emoji + - (string) 图标URL + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/meta' \ + -H 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "tool_icons": { + "dalle2": "https://cloud.dify.ai/console/api/workspaces/current/tool-provider/builtin/dalle/icon", + "api_tool": { + "background": "#252525", + "content": "\ud83d\ude01" + } + } + } + ``` + + + +--- + +--- + + + + + ### Query + + + 页码 + + + 每页数量 + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.appDetail.api_base_url}/apps/annotations?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + { + "data": [ + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + ``` + + + +--- + + + + + ### Query + + + 问题 + + + 答案内容 + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST '${props.appDetail.api_base_url}/apps/annotations' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." + }' + ``` + + + + ```json {{ title: 'Response' }} + { + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + } + ``` + + + +--- + + + + + ### Query + + + 标注 ID + + + 问题 + + + 答案内容 + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST '${props.appDetail.api_base_url}/apps/annotations/{annotation_id}' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." + }' + ``` + + + + ```json {{ title: 'Response' }} + { + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + } + ``` + + + +--- + + + + + ### Query + + + 标注 ID + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request DELETE '${props.appDetail.api_base_url}/apps/annotations/{annotation_id}' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + {"result": "success"} + ``` + + + +--- + + + + + ### Query + + + 动作，只能是 'enable' 或 'disable' + + + 指定的嵌入模型提供商, 必须先在系统内设定好接入的模型，对应的是provider字段 + + + 指定的嵌入模型，对应的是model字段 + + + 相似度阈值，当相似度大于该阈值时，系统会自动回复，否则不回复 + + + + + 嵌入模型的提供商和模型名称可以通过以下接口获取：v1/workspaces/current/models/model-types/text-embedding， 具体见：通过 API 维护知识库。 使用的Authorization是Dataset的API Token。 + + ```bash {{ title: 'cURL' }} + curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/{action}' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "score_threshold": 0.9, + "embedding_provider_name": "zhipu", + "embedding_model_name": "embedding_3" + }' + ``` + + + + ```json {{ title: 'Response' }} + { + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting" + } + ``` + + 该接口是异步执行，所以会返回一个job_id，通过查询job状态接口可以获取到最终的执行结果。 + + +--- + + + + + ### Query + + + 动作，只能是 'enable' 或 'disable'，并且必须和标注回复初始设置接口的动作一致 + + + 任务 ID，从标注回复初始设置接口返回的 job_id + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.appDetail.api_base_url}/apps/annotation-reply/{action}/status/{job_id}' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + { + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting", + "error_msg": "" + } + ``` + + + +======= +import { CodeGroup } from '../code.tsx' +import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx' + +# 工作流编排对话型应用 API + +对话应用支持会话持久化，可将之前的聊天记录作为上下文进行回答，可适用于聊天/客服 AI 等。 + +
+ ### 基础 URL + + ```javascript + ``` + + + ### 鉴权 + + Service API 使用 `API-Key` 进行鉴权。 + **强烈建议开发者把 `API-Key` 放在后端存储，而非分享或者放在客户端存储，以免 `API-Key` 泄露，导致财产损失。** + 所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`，如下所示： + + + ```javascript + Authorization: Bearer {API_KEY} + ``` + +
+ +--- + + + + + 创建会话消息。 + + ### Request Body + + + + 用户输入/提问内容。 + + + 允许传入 App 定义的各变量值。 + inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。 + 如果变量是文件类型，请指定一个包含以下 `files` 中所述键的对象。 + 默认 `{}` + + + - `streaming` 流式模式（推荐）。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现类似打字机输出方式的流式返回。 + - `blocking` 阻塞模式，等待执行完毕后返回结果。（请求若流程较长可能会被中断）。 + 由于 Cloudflare 限制，请求会在 100 秒超时无返回后中断。 + + + 用户标识，用于定义终端用户的身份，方便检索、统计。 + 由开发者定义规则，需保证用户标识在应用内唯一。 + + + （选填）会话 ID，需要基于之前的聊天记录继续对话，必须传之前消息的 conversation_id。 + + + 文件列表，适用于传入文件结合文本理解并回答问题，仅当模型支持 Vision 能力时可用。 + - `type` (string) 支持类型： + - `document` 具体类型包含：'TXT', 'MD', 'MARKDOWN', 'PDF', 'HTML', 'XLSX', 'XLS', 'DOCX', 'CSV', 'EML', 'MSG', 'PPTX', 'PPT', 'XML', 'EPUB' + - `image` 具体类型包含：'JPG', 'JPEG', 'PNG', 'GIF', 'WEBP', 'SVG' + - `audio` 具体类型包含：'MP3', 'M4A', 'WAV', 'WEBM', 'AMR' + - `video` 具体类型包含：'MP4', 'MOV', 'MPEG', 'MPGA' + - `custom` 具体类型包含：其他文件类型 + - `transfer_method` (string) 传递方式: + - `remote_url`: 图片地址。 + - `local_file`: 上传文件。 + - `url` 图片地址。（仅当传递方式为 `remote_url` 时）。 + - `upload_file_id` 上传文件 ID。（仅当传递方式为 `local_file `时）。 + + + （选填）自动生成标题，默认 `true`。 若设置为 `false`，则可通过调用会话重命名接口并设置 `auto_generate` 为 `true` 实现异步生成标题。 + + + + ### Response + + 当 `response_mode` 为 `blocking` 时，返回 ChatCompletionResponse object。 + 当 `response_mode` 为 `streaming`时，返回 ChunkChatCompletionResponse object 流式序列。 + + ### ChatCompletionResponse + + 返回完整的 App 结果，`Content-Type` 为 `application/json`。 + - `event` (string) 事件类型，固定为 `message` + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `id` (string) 唯一ID + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `mode` (string) App 模式，固定为 chat + - `answer` (string) 完整回复内容 + - `metadata` (object) 元数据 + - `usage` (Usage) 模型用量信息 + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `created_at` (int) 消息创建时间戳，如：1705395332 + + ### ChunkChatCompletionResponse + 返回 App 输出的流式块，`Content-Type` 为 `text/event-stream`。 + 每个流式块均为 data: 开头，块之间以 \n\n 即两个换行符分隔，如下所示： + + ```streaming {{ title: 'Response' }} + data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n + ``` + + + 流式块中根据 event 不同，结构也不同： + - `event: message` LLM 返回文本块事件，即：完整的文本以分块的方式输出。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `answer` (string) LLM 返回文本块内容 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: message_file` 文件事件，表示有新文件需要展示 + - `id` (string) 文件唯一ID + - `type` (string) 文件类型，目前仅为image + - `belongs_to` (string) 文件归属，user或assistant，该接口返回仅为 `assistant` + - `url` (string) 文件访问地址 + - `conversation_id` (string) 会话ID + - `event: message_end` 消息结束事件，收到此事件则代表流式返回结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `metadata` (object) 元数据 + - `usage` (Usage) 模型用量信息 + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `event: tts_message` TTS 音频流事件，即：语音合成输出。内容是Mp3格式的音频块，使用 base64 编码后的字符串，播放的时候直接解码即可。(开启自动播放才有此消息) + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `audio` (string) 语音合成之后的音频块使用 Base64 编码之后的文本内容，播放的时候直接 base64 解码送入播放器即可 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: tts_message_end` TTS 音频流结束事件，收到这个事件表示音频流返回结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `audio` (string) 结束事件是没有音频的，所以这里是空字符串 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: message_replace` 消息内容替换事件。 + 开启内容审查和审查输出内容时，若命中了审查条件，则会通过此事件替换消息内容为预设回复。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `answer` (string) 替换内容（直接替换 LLM 所有回复文本） + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: workflow_started` workflow 开始执行 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `workflow_started` + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `workflow_id` (string) 关联 Workflow ID + - `sequence_number` (int) 自增序号，App 内自增，从 1 开始 + - `created_at` (timestamp) 开始时间 + - `event: node_started` node 开始执行 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `node_started` + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `node_id` (string) 节点 ID + - `node_type` (string) 节点类型 + - `title` (string) 节点名称 + - `index` (int) 执行序号，用于展示 Tracing Node 顺序 + - `predecessor_node_id` (string) 前置节点 ID，用于画布展示执行路径 + - `inputs` (object) 节点中所有使用到的前置节点变量内容 + - `created_at` (timestamp) 开始时间 + - `event: node_finished` node 执行结束，成功失败同一事件中不同状态 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `node_finished` + - `data` (object) 详细内容 + - `id` (string) node 执行 ID + - `node_id` (string) 节点 ID + - `index` (int) 执行序号，用于展示 Tracing Node 顺序 + - `predecessor_node_id` (string) optional 前置节点 ID，用于画布展示执行路径 + - `inputs` (object) 节点中所有使用到的前置节点变量内容 + - `process_data` (json) Optional 节点过程数据 + - `outputs` (json) Optional 输出内容 + - `status` (string) 执行状态 `running` / `succeeded` / `failed` / `stopped` + - `error` (string) Optional 错误原因 + - `elapsed_time` (float) Optional 耗时(s) + - `execution_metadata` (json) 元数据 + - `total_tokens` (int) optional 总使用 tokens + - `total_price` (decimal) optional 总费用 + - `currency` (string) optional 货币，如 `USD` / `RMB` + - `created_at` (timestamp) 开始时间 + - `event: workflow_finished` workflow 执行结束，成功失败同一事件中不同状态 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `workflow_finished` + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `workflow_id` (string) 关联 Workflow ID + - `status` (string) 执行状态 `running` / `succeeded` / `failed` / `stopped` + - `outputs` (json) Optional 输出内容 + - `error` (string) Optional 错误原因 + - `elapsed_time` (float) Optional 耗时(s) + - `total_tokens` (int) Optional 总使用 tokens + - `total_steps` (int) 总步数（冗余），默认 0 + - `created_at` (timestamp) 开始时间 + - `finished_at` (timestamp) 结束时间 + - `event: error` + 流式输出过程中出现的异常会以 stream event 形式输出，收到异常事件后即结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `status` (int) HTTP 状态码 + - `code` (string) 错误码 + - `message` (string) 错误消息 + - `event: ping` 每 10s 一次的 ping 事件，保持连接存活。 + + ### Errors + - 404，对话不存在 + - 400，`invalid_param`，传入参数异常 + - 400，`app_unavailable`，App 配置不可用 + - 400，`provider_not_initialize`，无可用模型凭据配置 + - 400，`provider_quota_exceeded`，模型调用额度不足 + - 400，`model_currently_not_support`，当前模型不可用 + - 400，`completion_request_error`，文本生成失败 + - 500，服务内部异常 + + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/chat-messages' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "inputs": { + "name": "dify" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "conversation_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "response_mode": "streaming", + "user": "abc-123", + "files": [ + { + "type": "image", + "transfer_method": "remote_url", + "url": "https://cloud.dify.ai/logo/logo-site.png" + } + ] + }' + ``` + + + ### 阻塞模式 + + ```json {{ title: 'Response' }} + { + "event": "message", + "task_id": "c3800678-a077-43df-a102-53f23ed20b88", + "id": "9da23599-e713-473b-982c-4328d4f5c78a", + "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\"\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\"" + } + ] + }, + "created_at": 1705407629 + } + ``` + + ### 流式模式 + + ```streaming {{ title: 'Response' }} + data: {"event": "workflow_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "sequence_number": 1, "created_at": 1679586595}} + data: {"event": "node_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "created_at": 1679586595}} + data: {"event": "node_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "execution_metadata": {"total_tokens": 63127864, "total_price": 2.378, "currency": "USD"}, "created_at": 1679586595}} + data: {"event": "workflow_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "total_tokens": 63127864, "total_steps": "1", "created_at": 1679586595, "finished_at": 1679976595}} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " I", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": "'m", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " glad", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " to", "created_at": 1679586595} + data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " meet", "created_at": 1679586595} + data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " you", "created_at": 1679586595} + data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "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}, "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\"\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\""}]}} + data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"} + data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""} + ``` + + + + +--- + + + + 上传文件并在发送消息时使用，可实现图文多模态理解。 + 支持您的应用程序所支持的所有格式。 + 上传的文件仅供当前终端用户使用。 + + ### Request Body + 该接口需使用 `multipart/form-data` 进行请求。 + + + 要上传的文件。 + + + 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 + + + + ### Response + 成功上传后，服务器会返回文件的 ID 和相关信息。 + - `id` (uuid) ID + - `name` (string) 文件名 + - `size` (int) 文件大小（byte） + - `extension` (string) 文件后缀 + - `mime_type` (string) 文件 mime-type + - `created_by` (uuid) 上传人 ID + - `created_at` (timestamp) 上传时间 + + ### Errors + - 400，`no_file_uploaded`，必须提供文件 + - 400，`too_many_files`，目前只接受一个文件 + - 400，`unsupported_preview`，该文件不支持预览 + - 400，`unsupported_estimate`，该文件不支持估算 + - 413，`file_too_large`，文件太大 + - 415，`unsupported_file_type`，不支持的扩展名，当前只接受文档类文件 + - 503，`s3_connection_failed`，无法连接到 S3 服务 + - 503，`s3_permission_denied`，无权限上传文件到 S3 + - 503，`s3_file_too_large`，文件超出 S3 大小限制 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/files/upload' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@"/path/to/file"' + ``` + + + + + ```json {{ title: 'Response' }} + { + "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67", + "name": "example.png", + "size": 1024, + "extension": "png", + "mime_type": "image/png", + "created_by": 123, + "created_at": 1577836800, + } + ``` + + + +--- + + + + 仅支持流式模式。 + ### Path + - `task_id` (string) 任务 ID，可在流式返回 Chunk 中获取 + + ### Request Body + - `user` (string) Required + 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 + ### Response + - `result` (string) 固定返回 success + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/chat-messages/:task_id/stop' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + +--- + + + + + 消息终端用户反馈、点赞，方便应用开发者优化输出预期。 + + ### Path Params + + + 消息 ID + + + + ### Request Body + + + + 点赞 like, 点踩 dislike, 撤销点赞 null + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + 消息反馈的具体信息。 + + + + ### Response + - `result` (string) 固定返回 success + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "rating": "like", + "user": "abc-123", + "content": "message feedback information" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + 获取应用的终端用户反馈、点赞。 + + ### Query + + + （选填）分页，默认值：1 + + + + + + （选填）每页数量，默认值：20 + + + + ### Response + - `data` (List) 返回该APP的点赞、反馈列表。 + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + + ``` + + + + +--- + + + + + 获取下一轮建议问题列表。 + + ### Path Params + + + + Message ID + + + + ### Query + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.appDetail.api_base_url}/messages/{message_id}/suggested?user=abc-123' \ + --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \ + --header 'Content-Type: application/json' \ + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success", + "data": [ + "a", + "b", + "c" + ] + } + ``` + + + + +--- + +--- + + + + + 滚动加载形式返回历史聊天记录，第一页返回最新 `limit` 条，即：倒序返回。 + + ### Query + + + + 会话 ID + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + 当前页第一条聊天记录的 ID，默认 null + + + 一次请求返回多少条聊天记录，默认 20 条。 + + + + ### Response + - `data` (array[object]) 消息列表 + - `id` (string) 消息 ID + - `conversation_id` (string) 会话 ID + - `inputs` (object) 用户输入参数。 + - `query` (string) 用户输入 / 提问内容。 + - `message_files` (array[object]) 消息文件 + - `id` (string) ID + - `type` (string) 文件类型，image 图片 + - `url` (string) 预览图片地址 + - `belongs_to` (string) 文件归属方，user 或 assistant + - `answer` (string) 回答消息内容 + - `created_at` (timestamp) 创建时间 + - `feedback` (object) 反馈信息 + - `rating` (string) 点赞 like / 点踩 dislike + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `has_more` (bool) 是否存在下一页 + - `limit` (int) 返回条数，若传入超过系统限制，返回系统限制数量 + + + ### Request Example + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/messages?user=abc-123&conversation_id=' + --header 'Authorization: Bearer {api_key}' + ``` + + + + ### Response Example + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a076a87f-31e5-48dc-b452-0061adbbc922", + "conversation_id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce", + "inputs": { + "name": "dify" + }, + "query": "iphone 13 pro", + "answer": "The iPhone 13 Pro, released on September 24, 2021, features a 6.1-inch display with a resolution of 1170 x 2532. It is equipped with a Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard) processor, 6 GB of RAM, and offers storage options of 128 GB, 256 GB, 512 GB, and 1 TB. The camera is 12 MP, the battery capacity is 3095 mAh, and it runs on iOS 15.", + "message_files": [], + "feedback": null, + "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\"\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\"" + } + ], + "created_at": 1705569239 + } + ] + } + ``` + + + ### Response Example(智能助手) + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "d35e006c-7c4d-458f-9142-be4930abdf94", + "conversation_id": "957c068b-f258-4f89-ba10-6e8a0361c457", + "inputs": {}, + "query": "draw a cat", + "answer": "I have generated an image of a cat for you. Please check your messages to view the image.", + "message_files": [ + { + "id": "976990d2-5294-47e6-8f14-7356ba9d2d76", + "type": "image", + "url": "http://127.0.0.1:5001/files/tools/976990d2-5294-47e6-8f14-7356ba9d2d76.png?timestamp=1705988524&nonce=55df3f9f7311a9acd91bf074cd524092&sign=z43nMSO1L2HBvoqADLkRxr7Biz0fkjeDstnJiCK1zh8=", + "belongs_to": "assistant" + } + ], + "feedback": null, + "retriever_resources": [], + "created_at": 1705988187 + } + ] + } + ``` + + + + +--- + + + + + 获取当前用户的会话列表，默认返回最近的 20 条。 + + ### Query + + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + （选填）当前页最后面一条记录的 ID，默认 null + + + （选填）一次请求返回多少条记录，默认 20 条，最大 100 条，最小 1 条。 + + + （选填）排序字段，默认 -updated_at(按更新时间倒序排列) + - 可选值：created_at, -created_at, updated_at, -updated_at + - 字段前面的符号代表顺序或倒序，-代表倒序 + + + + ### Response + - `data` (array[object]) 会话列表 + - `id` (string) 会话 ID + - `name` (string) 会话名称，默认由大语言模型生成。 + - `inputs` (object) 用户输入参数。 + - `status` (string) 会话状态 + - `introduction` (string) 开场白 + - `created_at` (timestamp) 创建时间 + - `updated_at` (timestamp) 更新时间 + - `has_more` (bool) + - `limit` (int) 返回条数，若传入超过系统限制，返回系统限制数量 + + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/conversations?user=abc-123&last_id=&limit=20' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "10799fb8-64f7-4296-bbf7-b42bfbe0ae54", + "name": "New chat", + "inputs": { + "book": "book", + "myName": "Lucy" + }, + "status": "normal", + "created_at": 1679667915, + "updated_at": 1679667915 + }, + { + "id": "hSIhXBhNe8X1d8Et" + // ... + } + ] + } + ``` + + + + +--- + + + + 删除会话。 + + ### Path + - `conversation_id` (string) 会话 ID + + ### Request Body + + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `result` (string) 固定返回 success + + + + + + ```bash {{ title: 'cURL' }} + curl -X DELETE '${props.appDetail.api_base_url}/conversations/{conversation_id}' \ + --header 'Content-Type: application/json' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer {api_key}' \ + --data '{ + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + 对会话进行重命名，会话名称用于显示在支持多会话的客户端上。 + + ### Path + - `conversation_id` (string) 会话 ID + + ### Request Body + + + + （选填）名称，若 `auto_generate` 为 `true` 时，该参数可不传。 + + + （选填）自动生成标题，默认 false。 + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `id` (string) 会话 ID + - `name` (string) 会话名称 + - `inputs` (object) 用户输入参数 + - `status` (string) 会话状态 + - `introduction` (string) 开场白 + - `created_at` (timestamp) 创建时间 + - `updated_at` (timestamp) 更新时间 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/conversations/{conversation_id}/name' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "name": "", + "auto_generate": true, + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "id": "34d511d5-56de-4f16-a997-57b379508443", + "name": "hello", + "inputs": {}, + "status": "normal", + "introduction": "", + "created_at": 1732731141, + "updated_at": 1732734510 + } + ``` + + + + +--- + + + + + ### Request Body + 该接口需使用 `multipart/form-data` 进行请求。 + + + 语音文件。 + 支持格式：`['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']` + 文件大小限制：15MB + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `text` (string) 输出文字 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/conversations/name' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@localfile;type=audio/mp3' + ``` + + + + + ```json {{ title: 'Response' }} + { + "text": "hello" + } + ``` + + + + +--- + + + + + 文字转语音。 + + ### Request Body + + + + Dify 生成的文本消息，那么直接传递生成的message-id 即可，后台会通过 message_id 查找相应的内容直接合成语音信息。如果同时传 message_id 和 text，优先使用 message_id。 + + + 语音生成内容。如果没有传 message-id的话，则会使用这个字段的内容 + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + + + + + ```bash {{ title: 'cURL' }} + curl -o text-to-audio.mp3 -X POST '${props.appDetail.api_base_url}/text-to-audio' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", + "text": "你好Dify", + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'headers' }} + { + "Content-Type": "audio/wav" + } + ``` + + + +--- + + + + + 用于获取应用的基本信息 + ### Response + - `name` (string) 应用名称 + - `description` (string) 应用描述 + - `tags` (array[string]) 应用标签 + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/info' \ + -H 'Authorization: Bearer {api_key}' + ``` + + + ```json {{ title: 'Response' }} + { + "name": "My App", + "description": "This is my app.", + "tags": [ + "tag1", + "tag2" + ] + } + ``` + + + + +--- + + + + + 用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。 + + ### Response + - `opening_statement` (string) 开场白 + - `suggested_questions` (array[string]) 开场推荐问题列表 + - `suggested_questions_after_answer` (object) 启用回答后给出推荐问题。 + - `enabled` (bool) 是否开启 + - `speech_to_text` (object) 语音转文本 + - `enabled` (bool) 是否开启 + - `retriever_resource` (object) 引用和归属 + - `enabled` (bool) 是否开启 + - `annotation_reply` (object) 标记回复 + - `enabled` (bool) 是否开启 + - `user_input_form` (array[object]) 用户输入表单配置 + - `text-input` (object) 文本输入控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `paragraph` (object) 段落文本输入控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `select` (object) 下拉控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `options` (array[string]) 选项值 + - `file_upload` (object) 文件上传配置 + - `image` (object) 图片设置 + 当前仅支持图片类型：`png`, `jpg`, `jpeg`, `webp`, `gif` + - `enabled` (bool) 是否开启 + - `number_limits` (int) 图片数量限制，默认 3 + - `transfer_methods` (array[string]) 传递方式列表，remote_url , local_file，必选一个 + - `system_parameters` (object) 系统参数 + - `file_size_limit` (int) Document upload size limit (MB) + - `image_file_size_limit` (int) Image file upload size limit (MB) + - `audio_file_size_limit` (int) Audio file upload size limit (MB) + - `video_file_size_limit` (int) Video file upload size limit (MB) + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/parameters' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "introduction": "nice to meet you", + "user_input_form": [ + { + "text-input": { + "label": "a", + "variable": "a", + "required": true, + "max_length": 48, + "default": "" + } + }, + { + // ... + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "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 + } + } + ``` + + + + +--- + + + + + 用于获取工具icon + ### Response + - `tool_icons`(object[string]) 工具图标 + - `工具名称` (string) + - `icon` (object|string) + - (object) 图标 + - `background` (string) hex格式的背景色 + - `content`(string) emoji + - (string) 图标URL + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/meta' \ + -H 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "tool_icons": { + "dalle2": "https://cloud.dify.ai/console/api/workspaces/current/tool-provider/builtin/dalle/icon", + "api_tool": { + "background": "#252525", + "content": "\ud83d\ude01" + } + } + } + ``` + + + +--- + +--- + + + + + ### Query + + + 页码 + + + 每页数量 + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.appDetail.api_base_url}/apps/annotations?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + { + "data": [ + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 + } + ``` + + + +--- + + + + + ### Query + + + 问题 + + + 答案内容 + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST '${props.appDetail.api_base_url}/apps/annotations' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." + }' + ``` + + + + ```json {{ title: 'Response' }} + { + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + } + ``` + + + +--- + + + + + ### Query + + + 标注 ID + + + 问题 + + + 答案内容 + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST '${props.appDetail.api_base_url}/apps/annotations/{annotation_id}' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." + }' + ``` + + + + ```json {{ title: 'Response' }} + { + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + } + ``` + + + +--- + + + + + ### Query + + + 标注 ID + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request DELETE '${props.appDetail.api_base_url}/apps/annotations/{annotation_id}' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + {"result": "success"} + ``` + + + +--- + + + + + ### Query + + + 动作，只能是 'enable' 或 'disable' + + + 指定的嵌入模型提供商, 必须先在系统内设定好接入的模型，对应的是provider字段 + + + 指定的嵌入模型，对应的是model字段 + + + 相似度阈值，当相似度大于该阈值时，系统会自动回复，否则不回复 + + + + + 嵌入模型的提供商和模型名称可以通过以下接口获取：v1/workspaces/current/models/model-types/text-embedding， 具体见：通过 API 维护知识库。 使用的Authorization是Dataset的API Token。 + + ```bash {{ title: 'cURL' }} + curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/{action}' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "score_threshold": 0.9, + "embedding_provider_name": "zhipu", + "embedding_model_name": "embedding_3" + }' + ``` + + + + ```json {{ title: 'Response' }} + { + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting" + } + ``` + + 该接口是异步执行，所以会返回一个job_id，通过查询job状态接口可以获取到最终的执行结果。 + + +--- + + + + + ### Query + + + 动作，只能是 'enable' 或 'disable'，并且必须和标注回复初始设置接口的动作一致 + + + 任务 ID，从标注回复初始设置接口返回的 job_id + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.appDetail.api_base_url}/apps/annotation-reply/{action}/status/{job_id}' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + ```json {{ title: 'Response' }} + { + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting", + "error_msg": "" + } + ``` + + + +>>>>>>> add doc and modify endpoint path diff --git a/web/app/components/develop/template/template_chat.en.mdx b/web/app/components/develop/template/template_chat.en.mdx index aa3b9c62e5..c49cbca50a 100644 --- a/web/app/components/develop/template/template_chat.en.mdx +++ b/web/app/components/develop/template/template_chat.en.mdx @@ -450,6 +450,69 @@ Chat applications support session persistence, allowing previous chat history to --- + + + + Get application's feedbacks. + + ### Query + + + （optional）pagination，default：1 + + + + + + （optional） records per page default：20 + + + + ### Response + - `data` (List) return apps feedback list. + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + ``` + + + +--- + + + + アプリのエンドユーザーからのフィードバックや「いいね」を取得します。 + + ### クエリ + + + （任意）ページ番号。デフォルト値：1 + + + + + + （任意）1ページあたりの件数。デフォルト値：20 + + + + ### レスポンス + - `data` (リスト) このアプリの「いいね」とフィードバックの一覧を返します。 + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + ``` + + + +--- + + + + + 获取应用的终端用户反馈、点赞。 + + ### Query + + + （选填）分页，默认值：1 + + + + + + （选填）每页数量，默认值：20 + + + + ### Response + - `data` (List) 返回该APP的点赞、反馈列表。 + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/app/feedbacks?page=1&limit=20' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' + ``` + + + + + ```json {{ title: 'Response' }} + { + "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", + "rating": "like", + "content": "message feedback information-3", + "from_source": "user", + "from_end_user_id": "74286412-9a1a-42c1-929c-01edb1d381d5", + "from_account_id": null, + "created_at": "2025-04-24T09:24:38", + "updated_at": "2025-04-24T09:24:38" + } + ] + } + ``` + + + +--- +