dify

dify/api/controllers/service_api/app/annotation.py

@@ -0,0 +1,186 @@
+from typing import Literal
+
+from flask import request
+from flask_restx import Api, Namespace, Resource, fields, reqparse
+from flask_restx.api import HTTPStatus
+
+from controllers.console.wraps import edit_permission_required
+from controllers.service_api import service_api_ns
+from controllers.service_api.wraps import validate_app_token
+from extensions.ext_redis import redis_client
+from fields.annotation_fields import annotation_fields, build_annotation_model
+from models.model import App
+from services.annotation_service import AppAnnotationService
+
+# Define parsers for annotation API
+annotation_create_parser = (
+    reqparse.RequestParser()
+    .add_argument("question", required=True, type=str, location="json", help="Annotation question")
+    .add_argument("answer", required=True, type=str, location="json", help="Annotation answer")
+)
+
+annotation_reply_action_parser = (
+    reqparse.RequestParser()
+    .add_argument(
+        "score_threshold", required=True, type=float, location="json", help="Score threshold for annotation matching"
+    )
+    .add_argument("embedding_provider_name", required=True, type=str, location="json", help="Embedding provider name")
+    .add_argument("embedding_model_name", required=True, type=str, location="json", help="Embedding model name")
+)
+
+
+@service_api_ns.route("/apps/annotation-reply/<string:action>")
+class AnnotationReplyActionApi(Resource):
+    @service_api_ns.expect(annotation_reply_action_parser)
+    @service_api_ns.doc("annotation_reply_action")
+    @service_api_ns.doc(description="Enable or disable annotation reply feature")
+    @service_api_ns.doc(params={"action": "Action to perform: 'enable' or 'disable'"})
+    @service_api_ns.doc(
+        responses={
+            200: "Action completed successfully",
+            401: "Unauthorized - invalid API token",
+        }
+    )
+    @validate_app_token
+    def post(self, app_model: App, action: Literal["enable", "disable"]):
+        """Enable or disable annotation reply feature."""
+        args = annotation_reply_action_parser.parse_args()
+        if action == "enable":
+            result = AppAnnotationService.enable_app_annotation(args, app_model.id)
+        elif action == "disable":
+            result = AppAnnotationService.disable_app_annotation(app_model.id)
+        return result, 200
+
+
+@service_api_ns.route("/apps/annotation-reply/<string:action>/status/<uuid:job_id>")
+class AnnotationReplyActionStatusApi(Resource):
+    @service_api_ns.doc("get_annotation_reply_action_status")
+    @service_api_ns.doc(description="Get the status of an annotation reply action job")
+    @service_api_ns.doc(params={"action": "Action type", "job_id": "Job ID"})
+    @service_api_ns.doc(
+        responses={
+            200: "Job status retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Job not found",
+        }
+    )
+    @validate_app_token
+    def get(self, app_model: App, job_id, action):
+        """Get the status of an annotation reply action job."""
+        job_id = str(job_id)
+        app_annotation_job_key = f"{action}_app_annotation_job_{str(job_id)}"
+        cache_result = redis_client.get(app_annotation_job_key)
+        if cache_result is None:
+            raise ValueError("The job does not exist.")
+
+        job_status = cache_result.decode()
+        error_msg = ""
+        if job_status == "error":
+            app_annotation_error_key = f"{action}_app_annotation_error_{str(job_id)}"
+            error_msg = redis_client.get(app_annotation_error_key).decode()
+
+        return {"job_id": job_id, "job_status": job_status, "error_msg": error_msg}, 200
+
+
+# Define annotation list response model
+annotation_list_fields = {
+    "data": fields.List(fields.Nested(annotation_fields)),
+    "has_more": fields.Boolean,
+    "limit": fields.Integer,
+    "total": fields.Integer,
+    "page": fields.Integer,
+}
+
+
+def build_annotation_list_model(api_or_ns: Api | Namespace):
+    """Build the annotation list model for the API or Namespace."""
+    copied_annotation_list_fields = annotation_list_fields.copy()
+    copied_annotation_list_fields["data"] = fields.List(fields.Nested(build_annotation_model(api_or_ns)))
+    return api_or_ns.model("AnnotationList", copied_annotation_list_fields)
+
+
+@service_api_ns.route("/apps/annotations")
+class AnnotationListApi(Resource):
+    @service_api_ns.doc("list_annotations")
+    @service_api_ns.doc(description="List annotations for the application")
+    @service_api_ns.doc(
+        responses={
+            200: "Annotations retrieved successfully",
+            401: "Unauthorized - invalid API token",
+        }
+    )
+    @validate_app_token
+    @service_api_ns.marshal_with(build_annotation_list_model(service_api_ns))
+    def get(self, app_model: App):
+        """List annotations for the application."""
+        page = request.args.get("page", default=1, type=int)
+        limit = request.args.get("limit", default=20, type=int)
+        keyword = request.args.get("keyword", default="", type=str)
+
+        annotation_list, total = AppAnnotationService.get_annotation_list_by_app_id(app_model.id, page, limit, keyword)
+        return {
+            "data": annotation_list,
+            "has_more": len(annotation_list) == limit,
+            "limit": limit,
+            "total": total,
+            "page": page,
+        }
+
+    @service_api_ns.expect(annotation_create_parser)
+    @service_api_ns.doc("create_annotation")
+    @service_api_ns.doc(description="Create a new annotation")
+    @service_api_ns.doc(
+        responses={
+            201: "Annotation created successfully",
+            401: "Unauthorized - invalid API token",
+        }
+    )
+    @validate_app_token
+    @service_api_ns.marshal_with(build_annotation_model(service_api_ns), code=HTTPStatus.CREATED)
+    def post(self, app_model: App):
+        """Create a new annotation."""
+        args = annotation_create_parser.parse_args()
+        annotation = AppAnnotationService.insert_app_annotation_directly(args, app_model.id)
+        return annotation, 201
+
+
+@service_api_ns.route("/apps/annotations/<uuid:annotation_id>")
+class AnnotationUpdateDeleteApi(Resource):
+    @service_api_ns.expect(annotation_create_parser)
+    @service_api_ns.doc("update_annotation")
+    @service_api_ns.doc(description="Update an existing annotation")
+    @service_api_ns.doc(params={"annotation_id": "Annotation ID"})
+    @service_api_ns.doc(
+        responses={
+            200: "Annotation updated successfully",
+            401: "Unauthorized - invalid API token",
+            403: "Forbidden - insufficient permissions",
+            404: "Annotation not found",
+        }
+    )
+    @validate_app_token
+    @edit_permission_required
+    @service_api_ns.marshal_with(build_annotation_model(service_api_ns))
+    def put(self, app_model: App, annotation_id: str):
+        """Update an existing annotation."""
+        args = annotation_create_parser.parse_args()
+        annotation = AppAnnotationService.update_app_annotation_directly(args, app_model.id, annotation_id)
+        return annotation
+
+    @service_api_ns.doc("delete_annotation")
+    @service_api_ns.doc(description="Delete an annotation")
+    @service_api_ns.doc(params={"annotation_id": "Annotation ID"})
+    @service_api_ns.doc(
+        responses={
+            204: "Annotation deleted successfully",
+            401: "Unauthorized - invalid API token",
+            403: "Forbidden - insufficient permissions",
+            404: "Annotation not found",
+        }
+    )
+    @validate_app_token
+    @edit_permission_required
+    def delete(self, app_model: App, annotation_id: str):
+        """Delete an annotation."""
+        AppAnnotationService.delete_app_annotation(app_model.id, annotation_id)
+        return {"result": "success"}, 204

dify/api/controllers/service_api/app/app.py

@@ -0,0 +1,95 @@
+from flask_restx import Resource
+
+from controllers.common.fields import build_parameters_model
+from controllers.service_api import service_api_ns
+from controllers.service_api.app.error import AppUnavailableError
+from controllers.service_api.wraps import validate_app_token
+from core.app.app_config.common.parameters_mapping import get_parameters_from_feature_dict
+from models.model import App, AppMode
+from services.app_service import AppService
+
+
+@service_api_ns.route("/parameters")
+class AppParameterApi(Resource):
+    """Resource for app variables."""
+
+    @service_api_ns.doc("get_app_parameters")
+    @service_api_ns.doc(description="Retrieve application input parameters and configuration")
+    @service_api_ns.doc(
+        responses={
+            200: "Parameters retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Application not found",
+        }
+    )
+    @validate_app_token
+    @service_api_ns.marshal_with(build_parameters_model(service_api_ns))
+    def get(self, app_model: App):
+        """Retrieve app parameters.
+
+        Returns the input form parameters and configuration for the application.
+        """
+        if app_model.mode in {AppMode.ADVANCED_CHAT, AppMode.WORKFLOW}:
+            workflow = app_model.workflow
+            if workflow is None:
+                raise AppUnavailableError()
+
+            features_dict = workflow.features_dict
+            user_input_form = workflow.user_input_form(to_old_structure=True)
+        else:
+            app_model_config = app_model.app_model_config
+            if app_model_config is None:
+                raise AppUnavailableError()
+
+            features_dict = app_model_config.to_dict()
+
+            user_input_form = features_dict.get("user_input_form", [])
+
+        return get_parameters_from_feature_dict(features_dict=features_dict, user_input_form=user_input_form)
+
+
+@service_api_ns.route("/meta")
+class AppMetaApi(Resource):
+    @service_api_ns.doc("get_app_meta")
+    @service_api_ns.doc(description="Get application metadata")
+    @service_api_ns.doc(
+        responses={
+            200: "Metadata retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Application not found",
+        }
+    )
+    @validate_app_token
+    def get(self, app_model: App):
+        """Get app metadata.
+
+        Returns metadata about the application including configuration and settings.
+        """
+        return AppService().get_app_meta(app_model)
+
+
+@service_api_ns.route("/info")
+class AppInfoApi(Resource):
+    @service_api_ns.doc("get_app_info")
+    @service_api_ns.doc(description="Get basic application information")
+    @service_api_ns.doc(
+        responses={
+            200: "Application info retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Application not found",
+        }
+    )
+    @validate_app_token
+    def get(self, app_model: App):
+        """Get app information.
+
+        Returns basic information about the application including name, description, tags, and mode.
+        """
+        tags = [tag.name for tag in app_model.tags]
+        return {
+            "name": app_model.name,
+            "description": app_model.description,
+            "tags": tags,
+            "mode": app_model.mode,
+            "author_name": app_model.author_name,
+        }

dify/api/controllers/service_api/app/audio.py

@@ -0,0 +1,150 @@
+import logging
+
+from flask import request
+from flask_restx import Resource, reqparse
+from werkzeug.exceptions import InternalServerError
+
+import services
+from controllers.service_api import service_api_ns
+from controllers.service_api.app.error import (
+    AppUnavailableError,
+    AudioTooLargeError,
+    CompletionRequestError,
+    NoAudioUploadedError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderNotSupportSpeechToTextError,
+    ProviderQuotaExceededError,
+    UnsupportedAudioTypeError,
+)
+from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
+from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
+from core.model_runtime.errors.invoke import InvokeError
+from models.model import App, EndUser
+from services.audio_service import AudioService
+from services.errors.audio import (
+    AudioTooLargeServiceError,
+    NoAudioUploadedServiceError,
+    ProviderNotSupportSpeechToTextServiceError,
+    UnsupportedAudioTypeServiceError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@service_api_ns.route("/audio-to-text")
+class AudioApi(Resource):
+    @service_api_ns.doc("audio_to_text")
+    @service_api_ns.doc(description="Convert audio to text using speech-to-text")
+    @service_api_ns.doc(
+        responses={
+            200: "Audio successfully transcribed",
+            400: "Bad request - no audio or invalid audio",
+            401: "Unauthorized - invalid API token",
+            413: "Audio file too large",
+            415: "Unsupported audio type",
+            500: "Internal server error",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.FORM))
+    def post(self, app_model: App, end_user: EndUser):
+        """Convert audio to text using speech-to-text.
+
+        Accepts an audio file upload and returns the transcribed text.
+        """
+        file = request.files["file"]
+
+        try:
+            response = AudioService.transcript_asr(app_model=app_model, file=file, end_user=end_user.id)
+
+            return response
+        except services.errors.app_model_config.AppModelConfigBrokenError:
+            logger.exception("App model config broken.")
+            raise AppUnavailableError()
+        except NoAudioUploadedServiceError:
+            raise NoAudioUploadedError()
+        except AudioTooLargeServiceError as e:
+            raise AudioTooLargeError(str(e))
+        except UnsupportedAudioTypeServiceError:
+            raise UnsupportedAudioTypeError()
+        except ProviderNotSupportSpeechToTextServiceError:
+            raise ProviderNotSupportSpeechToTextError()
+        except ProviderTokenNotInitError as ex:
+            raise ProviderNotInitializeError(ex.description)
+        except QuotaExceededError:
+            raise ProviderQuotaExceededError()
+        except ModelCurrentlyNotSupportError:
+            raise ProviderModelCurrentlyNotSupportError()
+        except InvokeError as e:
+            raise CompletionRequestError(e.description)
+        except ValueError as e:
+            raise e
+        except Exception as e:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+# Define parser for text-to-audio API
+text_to_audio_parser = (
+    reqparse.RequestParser()
+    .add_argument("message_id", type=str, required=False, location="json", help="Message ID")
+    .add_argument("voice", type=str, location="json", help="Voice to use for TTS")
+    .add_argument("text", type=str, location="json", help="Text to convert to audio")
+    .add_argument("streaming", type=bool, location="json", help="Enable streaming response")
+)
+
+
+@service_api_ns.route("/text-to-audio")
+class TextApi(Resource):
+    @service_api_ns.expect(text_to_audio_parser)
+    @service_api_ns.doc("text_to_audio")
+    @service_api_ns.doc(description="Convert text to audio using text-to-speech")
+    @service_api_ns.doc(
+        responses={
+            200: "Text successfully converted to audio",
+            400: "Bad request - invalid parameters",
+            401: "Unauthorized - invalid API token",
+            500: "Internal server error",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON))
+    def post(self, app_model: App, end_user: EndUser):
+        """Convert text to audio using text-to-speech.
+
+        Converts the provided text to audio using the specified voice.
+        """
+        try:
+            args = text_to_audio_parser.parse_args()
+
+            message_id = args.get("message_id", None)
+            text = args.get("text", None)
+            voice = args.get("voice", None)
+            response = AudioService.transcript_tts(
+                app_model=app_model, text=text, voice=voice, end_user=end_user.external_user_id, message_id=message_id
+            )
+
+            return response
+        except services.errors.app_model_config.AppModelConfigBrokenError:
+            logger.exception("App model config broken.")
+            raise AppUnavailableError()
+        except NoAudioUploadedServiceError:
+            raise NoAudioUploadedError()
+        except AudioTooLargeServiceError as e:
+            raise AudioTooLargeError(str(e))
+        except UnsupportedAudioTypeServiceError:
+            raise UnsupportedAudioTypeError()
+        except ProviderNotSupportSpeechToTextServiceError:
+            raise ProviderNotSupportSpeechToTextError()
+        except ProviderTokenNotInitError as ex:
+            raise ProviderNotInitializeError(ex.description)
+        except QuotaExceededError:
+            raise ProviderQuotaExceededError()
+        except ModelCurrentlyNotSupportError:
+            raise ProviderModelCurrentlyNotSupportError()
+        except InvokeError as e:
+            raise CompletionRequestError(e.description)
+        except ValueError as e:
+            raise e
+        except Exception as e:
+            logger.exception("internal server error.")
+            raise InternalServerError()

dify/api/controllers/service_api/app/completion.py

@@ -0,0 +1,259 @@
+import logging
+
+from flask import request
+from flask_restx import Resource, reqparse
+from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
+
+import services
+from controllers.service_api import service_api_ns
+from controllers.service_api.app.error import (
+    AppUnavailableError,
+    CompletionRequestError,
+    ConversationCompletedError,
+    NotChatAppError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderQuotaExceededError,
+)
+from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
+from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
+from core.app.entities.app_invoke_entities import InvokeFrom
+from core.errors.error import (
+    ModelCurrentlyNotSupportError,
+    ProviderTokenNotInitError,
+    QuotaExceededError,
+)
+from core.helper.trace_id_helper import get_external_trace_id
+from core.model_runtime.errors.invoke import InvokeError
+from libs import helper
+from libs.helper import uuid_value
+from models.model import App, AppMode, EndUser
+from services.app_generate_service import AppGenerateService
+from services.app_task_service import AppTaskService
+from services.errors.app import IsDraftWorkflowError, WorkflowIdFormatError, WorkflowNotFoundError
+from services.errors.llm import InvokeRateLimitError
+
+logger = logging.getLogger(__name__)
+
+
+# Define parser for completion API
+completion_parser = (
+    reqparse.RequestParser()
+    .add_argument("inputs", type=dict, required=True, location="json", help="Input parameters for completion")
+    .add_argument("query", type=str, location="json", default="", help="The query string")
+    .add_argument("files", type=list, required=False, location="json", help="List of file attachments")
+    .add_argument("response_mode", type=str, choices=["blocking", "streaming"], location="json", help="Response mode")
+    .add_argument("retriever_from", type=str, required=False, default="dev", location="json", help="Retriever source")
+)
+
+# Define parser for chat API
+chat_parser = (
+    reqparse.RequestParser()
+    .add_argument("inputs", type=dict, required=True, location="json", help="Input parameters for chat")
+    .add_argument("query", type=str, required=True, location="json", help="The chat query")
+    .add_argument("files", type=list, required=False, location="json", help="List of file attachments")
+    .add_argument("response_mode", type=str, choices=["blocking", "streaming"], location="json", help="Response mode")
+    .add_argument("conversation_id", type=uuid_value, location="json", help="Existing conversation ID")
+    .add_argument("retriever_from", type=str, required=False, default="dev", location="json", help="Retriever source")
+    .add_argument(
+        "auto_generate_name",
+        type=bool,
+        required=False,
+        default=True,
+        location="json",
+        help="Auto generate conversation name",
+    )
+    .add_argument("workflow_id", type=str, required=False, location="json", help="Workflow ID for advanced chat")
+)
+
+
+@service_api_ns.route("/completion-messages")
+class CompletionApi(Resource):
+    @service_api_ns.expect(completion_parser)
+    @service_api_ns.doc("create_completion")
+    @service_api_ns.doc(description="Create a completion for the given prompt")
+    @service_api_ns.doc(
+        responses={
+            200: "Completion created successfully",
+            400: "Bad request - invalid parameters",
+            401: "Unauthorized - invalid API token",
+            404: "Conversation not found",
+            500: "Internal server error",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser):
+        """Create a completion for the given prompt.
+
+        This endpoint generates a completion based on the provided inputs and query.
+        Supports both blocking and streaming response modes.
+        """
+        if app_model.mode != AppMode.COMPLETION:
+            raise AppUnavailableError()
+
+        args = completion_parser.parse_args()
+        external_trace_id = get_external_trace_id(request)
+        if external_trace_id:
+            args["external_trace_id"] = external_trace_id
+
+        streaming = args["response_mode"] == "streaming"
+
+        args["auto_generate_name"] = False
+
+        try:
+            response = AppGenerateService.generate(
+                app_model=app_model,
+                user=end_user,
+                args=args,
+                invoke_from=InvokeFrom.SERVICE_API,
+                streaming=streaming,
+            )
+
+            return helper.compact_generate_response(response)
+        except services.errors.conversation.ConversationNotExistsError:
+            raise NotFound("Conversation Not Exists.")
+        except services.errors.conversation.ConversationCompletedError:
+            raise ConversationCompletedError()
+        except services.errors.app_model_config.AppModelConfigBrokenError:
+            logger.exception("App model config broken.")
+            raise AppUnavailableError()
+        except ProviderTokenNotInitError as ex:
+            raise ProviderNotInitializeError(ex.description)
+        except QuotaExceededError:
+            raise ProviderQuotaExceededError()
+        except ModelCurrentlyNotSupportError:
+            raise ProviderModelCurrentlyNotSupportError()
+        except InvokeError as e:
+            raise CompletionRequestError(e.description)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@service_api_ns.route("/completion-messages/<string:task_id>/stop")
+class CompletionStopApi(Resource):
+    @service_api_ns.doc("stop_completion")
+    @service_api_ns.doc(description="Stop a running completion task")
+    @service_api_ns.doc(params={"task_id": "The ID of the task to stop"})
+    @service_api_ns.doc(
+        responses={
+            200: "Task stopped successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Task not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser, task_id: str):
+        """Stop a running completion task."""
+        if app_model.mode != AppMode.COMPLETION:
+            raise AppUnavailableError()
+
+        AppTaskService.stop_task(
+            task_id=task_id,
+            invoke_from=InvokeFrom.SERVICE_API,
+            user_id=end_user.id,
+            app_mode=AppMode.value_of(app_model.mode),
+        )
+
+        return {"result": "success"}, 200
+
+
+@service_api_ns.route("/chat-messages")
+class ChatApi(Resource):
+    @service_api_ns.expect(chat_parser)
+    @service_api_ns.doc("create_chat_message")
+    @service_api_ns.doc(description="Send a message in a chat conversation")
+    @service_api_ns.doc(
+        responses={
+            200: "Message sent successfully",
+            400: "Bad request - invalid parameters or workflow issues",
+            401: "Unauthorized - invalid API token",
+            404: "Conversation or workflow not found",
+            429: "Rate limit exceeded",
+            500: "Internal server error",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser):
+        """Send a message in a chat conversation.
+
+        This endpoint handles chat messages for chat, agent chat, and advanced chat applications.
+        Supports conversation management and both blocking and streaming response modes.
+        """
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+            raise NotChatAppError()
+
+        args = chat_parser.parse_args()
+
+        external_trace_id = get_external_trace_id(request)
+        if external_trace_id:
+            args["external_trace_id"] = external_trace_id
+
+        streaming = args["response_mode"] == "streaming"
+
+        try:
+            response = AppGenerateService.generate(
+                app_model=app_model, user=end_user, args=args, invoke_from=InvokeFrom.SERVICE_API, streaming=streaming
+            )
+
+            return helper.compact_generate_response(response)
+        except WorkflowNotFoundError as ex:
+            raise NotFound(str(ex))
+        except IsDraftWorkflowError as ex:
+            raise BadRequest(str(ex))
+        except WorkflowIdFormatError as ex:
+            raise BadRequest(str(ex))
+        except services.errors.conversation.ConversationNotExistsError:
+            raise NotFound("Conversation Not Exists.")
+        except services.errors.conversation.ConversationCompletedError:
+            raise ConversationCompletedError()
+        except services.errors.app_model_config.AppModelConfigBrokenError:
+            logger.exception("App model config broken.")
+            raise AppUnavailableError()
+        except ProviderTokenNotInitError as ex:
+            raise ProviderNotInitializeError(ex.description)
+        except QuotaExceededError:
+            raise ProviderQuotaExceededError()
+        except ModelCurrentlyNotSupportError:
+            raise ProviderModelCurrentlyNotSupportError()
+        except InvokeRateLimitError as ex:
+            raise InvokeRateLimitHttpError(ex.description)
+        except InvokeError as e:
+            raise CompletionRequestError(e.description)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@service_api_ns.route("/chat-messages/<string:task_id>/stop")
+class ChatStopApi(Resource):
+    @service_api_ns.doc("stop_chat_message")
+    @service_api_ns.doc(description="Stop a running chat message generation")
+    @service_api_ns.doc(params={"task_id": "The ID of the task to stop"})
+    @service_api_ns.doc(
+        responses={
+            200: "Task stopped successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Task not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser, task_id: str):
+        """Stop a running chat message generation."""
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+            raise NotChatAppError()
+
+        AppTaskService.stop_task(
+            task_id=task_id,
+            invoke_from=InvokeFrom.SERVICE_API,
+            user_id=end_user.id,
+            app_mode=app_mode,
+        )
+
+        return {"result": "success"}, 200

dify/api/controllers/service_api/app/conversation.py

@@ -0,0 +1,264 @@
+from flask_restx import Resource, reqparse
+from flask_restx._http import HTTPStatus
+from flask_restx.inputs import int_range
+from sqlalchemy.orm import Session
+from werkzeug.exceptions import BadRequest, NotFound
+
+import services
+from controllers.service_api import service_api_ns
+from controllers.service_api.app.error import NotChatAppError
+from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
+from core.app.entities.app_invoke_entities import InvokeFrom
+from extensions.ext_database import db
+from fields.conversation_fields import (
+    build_conversation_delete_model,
+    build_conversation_infinite_scroll_pagination_model,
+    build_simple_conversation_model,
+)
+from fields.conversation_variable_fields import (
+    build_conversation_variable_infinite_scroll_pagination_model,
+    build_conversation_variable_model,
+)
+from libs.helper import uuid_value
+from models.model import App, AppMode, EndUser
+from services.conversation_service import ConversationService
+
+# Define parsers for conversation APIs
+conversation_list_parser = (
+    reqparse.RequestParser()
+    .add_argument("last_id", type=uuid_value, location="args", help="Last conversation ID for pagination")
+    .add_argument(
+        "limit",
+        type=int_range(1, 100),
+        required=False,
+        default=20,
+        location="args",
+        help="Number of conversations to return",
+    )
+    .add_argument(
+        "sort_by",
+        type=str,
+        choices=["created_at", "-created_at", "updated_at", "-updated_at"],
+        required=False,
+        default="-updated_at",
+        location="args",
+        help="Sort order for conversations",
+    )
+)
+
+conversation_rename_parser = (
+    reqparse.RequestParser()
+    .add_argument("name", type=str, required=False, location="json", help="New conversation name")
+    .add_argument(
+        "auto_generate",
+        type=bool,
+        required=False,
+        default=False,
+        location="json",
+        help="Auto-generate conversation name",
+    )
+)
+
+conversation_variables_parser = (
+    reqparse.RequestParser()
+    .add_argument("last_id", type=uuid_value, location="args", help="Last variable ID for pagination")
+    .add_argument(
+        "limit",
+        type=int_range(1, 100),
+        required=False,
+        default=20,
+        location="args",
+        help="Number of variables to return",
+    )
+)
+
+conversation_variable_update_parser = reqparse.RequestParser().add_argument(
+    # using lambda is for passing the already-typed value without modification
+    # if no lambda, it will be converted to string
+    # the string cannot be converted using json.loads
+    "value",
+    required=True,
+    location="json",
+    type=lambda x: x,
+    help="New value for the conversation variable",
+)
+
+
+@service_api_ns.route("/conversations")
+class ConversationApi(Resource):
+    @service_api_ns.expect(conversation_list_parser)
+    @service_api_ns.doc("list_conversations")
+    @service_api_ns.doc(description="List all conversations for the current user")
+    @service_api_ns.doc(
+        responses={
+            200: "Conversations retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Last conversation not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY))
+    @service_api_ns.marshal_with(build_conversation_infinite_scroll_pagination_model(service_api_ns))
+    def get(self, app_model: App, end_user: EndUser):
+        """List all conversations for the current user.
+
+        Supports pagination using last_id and limit parameters.
+        """
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+            raise NotChatAppError()
+
+        args = conversation_list_parser.parse_args()
+
+        try:
+            with Session(db.engine) as session:
+                return ConversationService.pagination_by_last_id(
+                    session=session,
+                    app_model=app_model,
+                    user=end_user,
+                    last_id=args["last_id"],
+                    limit=args["limit"],
+                    invoke_from=InvokeFrom.SERVICE_API,
+                    sort_by=args["sort_by"],
+                )
+        except services.errors.conversation.LastConversationNotExistsError:
+            raise NotFound("Last Conversation Not Exists.")
+
+
+@service_api_ns.route("/conversations/<uuid:c_id>")
+class ConversationDetailApi(Resource):
+    @service_api_ns.doc("delete_conversation")
+    @service_api_ns.doc(description="Delete a specific conversation")
+    @service_api_ns.doc(params={"c_id": "Conversation ID"})
+    @service_api_ns.doc(
+        responses={
+            204: "Conversation deleted successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Conversation not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON))
+    @service_api_ns.marshal_with(build_conversation_delete_model(service_api_ns), code=HTTPStatus.NO_CONTENT)
+    def delete(self, app_model: App, end_user: EndUser, c_id):
+        """Delete a specific conversation."""
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+            raise NotChatAppError()
+
+        conversation_id = str(c_id)
+
+        try:
+            ConversationService.delete(app_model, conversation_id, end_user)
+        except services.errors.conversation.ConversationNotExistsError:
+            raise NotFound("Conversation Not Exists.")
+        return {"result": "success"}, 204
+
+
+@service_api_ns.route("/conversations/<uuid:c_id>/name")
+class ConversationRenameApi(Resource):
+    @service_api_ns.expect(conversation_rename_parser)
+    @service_api_ns.doc("rename_conversation")
+    @service_api_ns.doc(description="Rename a conversation or auto-generate a name")
+    @service_api_ns.doc(params={"c_id": "Conversation ID"})
+    @service_api_ns.doc(
+        responses={
+            200: "Conversation renamed successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Conversation not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON))
+    @service_api_ns.marshal_with(build_simple_conversation_model(service_api_ns))
+    def post(self, app_model: App, end_user: EndUser, c_id):
+        """Rename a conversation or auto-generate a name."""
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+            raise NotChatAppError()
+
+        conversation_id = str(c_id)
+
+        args = conversation_rename_parser.parse_args()
+
+        try:
+            return ConversationService.rename(app_model, conversation_id, end_user, args["name"], args["auto_generate"])
+        except services.errors.conversation.ConversationNotExistsError:
+            raise NotFound("Conversation Not Exists.")
+
+
+@service_api_ns.route("/conversations/<uuid:c_id>/variables")
+class ConversationVariablesApi(Resource):
+    @service_api_ns.expect(conversation_variables_parser)
+    @service_api_ns.doc("list_conversation_variables")
+    @service_api_ns.doc(description="List all variables for a conversation")
+    @service_api_ns.doc(params={"c_id": "Conversation ID"})
+    @service_api_ns.doc(
+        responses={
+            200: "Variables retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Conversation not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY))
+    @service_api_ns.marshal_with(build_conversation_variable_infinite_scroll_pagination_model(service_api_ns))
+    def get(self, app_model: App, end_user: EndUser, c_id):
+        """List all variables for a conversation.
+
+        Conversational variables are only available for chat applications.
+        """
+        # conversational variable only for chat app
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+            raise NotChatAppError()
+
+        conversation_id = str(c_id)
+
+        args = conversation_variables_parser.parse_args()
+
+        try:
+            return ConversationService.get_conversational_variable(
+                app_model, conversation_id, end_user, args["limit"], args["last_id"]
+            )
+        except services.errors.conversation.ConversationNotExistsError:
+            raise NotFound("Conversation Not Exists.")
+
+
+@service_api_ns.route("/conversations/<uuid:c_id>/variables/<uuid:variable_id>")
+class ConversationVariableDetailApi(Resource):
+    @service_api_ns.expect(conversation_variable_update_parser)
+    @service_api_ns.doc("update_conversation_variable")
+    @service_api_ns.doc(description="Update a conversation variable's value")
+    @service_api_ns.doc(params={"c_id": "Conversation ID", "variable_id": "Variable ID"})
+    @service_api_ns.doc(
+        responses={
+            200: "Variable updated successfully",
+            400: "Bad request - type mismatch",
+            401: "Unauthorized - invalid API token",
+            404: "Conversation or variable not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON))
+    @service_api_ns.marshal_with(build_conversation_variable_model(service_api_ns))
+    def put(self, app_model: App, end_user: EndUser, c_id, variable_id):
+        """Update a conversation variable's value.
+
+        Allows updating the value of a specific conversation variable.
+        The value must match the variable's expected type.
+        """
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+            raise NotChatAppError()
+
+        conversation_id = str(c_id)
+        variable_id = str(variable_id)
+
+        args = conversation_variable_update_parser.parse_args()
+
+        try:
+            return ConversationService.update_conversation_variable(
+                app_model, conversation_id, variable_id, end_user, args["value"]
+            )
+        except services.errors.conversation.ConversationNotExistsError:
+            raise NotFound("Conversation Not Exists.")
+        except services.errors.conversation.ConversationVariableNotExistsError:
+            raise NotFound("Conversation Variable Not Exists.")
+        except services.errors.conversation.ConversationVariableTypeMismatchError as e:
+            raise BadRequest(str(e))

dify/api/controllers/service_api/app/error.py

@@ -0,0 +1,97 @@
+from libs.exception import BaseHTTPException
+
+
+class AppUnavailableError(BaseHTTPException):
+    error_code = "app_unavailable"
+    description = "App unavailable, please check your app configurations."
+    code = 400
+
+
+class NotCompletionAppError(BaseHTTPException):
+    error_code = "not_completion_app"
+    description = "Please check if your Completion app mode matches the right API route."
+    code = 400
+
+
+class NotChatAppError(BaseHTTPException):
+    error_code = "not_chat_app"
+    description = "Please check if your app mode matches the right API route."
+    code = 400
+
+
+class NotWorkflowAppError(BaseHTTPException):
+    error_code = "not_workflow_app"
+    description = "Please check if your app mode matches the right API route."
+    code = 400
+
+
+class ConversationCompletedError(BaseHTTPException):
+    error_code = "conversation_completed"
+    description = "The conversation has ended. Please start a new conversation."
+    code = 400
+
+
+class ProviderNotInitializeError(BaseHTTPException):
+    error_code = "provider_not_initialize"
+    description = (
+        "No valid model provider credentials found. "
+        "Please go to Settings -> Model Provider to complete your provider credentials."
+    )
+    code = 400
+
+
+class ProviderQuotaExceededError(BaseHTTPException):
+    error_code = "provider_quota_exceeded"
+    description = (
+        "Your quota for Dify Hosted OpenAI has been exhausted. "
+        "Please go to Settings -> Model Provider to complete your own provider credentials."
+    )
+    code = 400
+
+
+class ProviderModelCurrentlyNotSupportError(BaseHTTPException):
+    error_code = "model_currently_not_support"
+    description = "Dify Hosted OpenAI trial currently not support the GPT-4 model."
+    code = 400
+
+
+class CompletionRequestError(BaseHTTPException):
+    error_code = "completion_request_error"
+    description = "Completion request failed."
+    code = 400
+
+
+class NoAudioUploadedError(BaseHTTPException):
+    error_code = "no_audio_uploaded"
+    description = "Please upload your audio."
+    code = 400
+
+
+class AudioTooLargeError(BaseHTTPException):
+    error_code = "audio_too_large"
+    description = "Audio size exceeded. {message}"
+    code = 413
+
+
+class UnsupportedAudioTypeError(BaseHTTPException):
+    error_code = "unsupported_audio_type"
+    description = "Audio type not allowed."
+    code = 415
+
+
+class ProviderNotSupportSpeechToTextError(BaseHTTPException):
+    error_code = "provider_not_support_speech_to_text"
+    description = "Provider not support speech to text."
+    code = 400
+
+
+class FileNotFoundError(BaseHTTPException):
+    error_code = "file_not_found"
+    description = "The requested file was not found."
+    code = 404
+
+
+class FileAccessDeniedError(BaseHTTPException):
+    error_code = "file_access_denied"
+    description = "Access to the requested file is denied."
+    code = 403

dify/api/controllers/service_api/app/file.py

@@ -0,0 +1,67 @@
+from flask import request
+from flask_restx import Resource
+from flask_restx.api import HTTPStatus
+
+import services
+from controllers.common.errors import (
+    FilenameNotExistsError,
+    FileTooLargeError,
+    NoFileUploadedError,
+    TooManyFilesError,
+    UnsupportedFileTypeError,
+)
+from controllers.service_api import service_api_ns
+from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
+from extensions.ext_database import db
+from fields.file_fields import build_file_model
+from models import App, EndUser
+from services.file_service import FileService
+
+
+@service_api_ns.route("/files/upload")
+class FileApi(Resource):
+    @service_api_ns.doc("upload_file")
+    @service_api_ns.doc(description="Upload a file for use in conversations")
+    @service_api_ns.doc(
+        responses={
+            201: "File uploaded successfully",
+            400: "Bad request - no file or invalid file",
+            401: "Unauthorized - invalid API token",
+            413: "File too large",
+            415: "Unsupported file type",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.FORM))
+    @service_api_ns.marshal_with(build_file_model(service_api_ns), code=HTTPStatus.CREATED)
+    def post(self, app_model: App, end_user: EndUser):
+        """Upload a file for use in conversations.
+
+        Accepts a single file upload via multipart/form-data.
+        """
+        # check file
+        if "file" not in request.files:
+            raise NoFileUploadedError()
+
+        if len(request.files) > 1:
+            raise TooManyFilesError()
+
+        file = request.files["file"]
+        if not file.mimetype:
+            raise UnsupportedFileTypeError()
+
+        if not file.filename:
+            raise FilenameNotExistsError
+
+        try:
+            upload_file = FileService(db.engine).upload_file(
+                filename=file.filename,
+                content=file.read(),
+                mimetype=file.mimetype,
+                user=end_user,
+            )
+        except services.errors.file.FileTooLargeError as file_too_large_error:
+            raise FileTooLargeError(file_too_large_error.description)
+        except services.errors.file.UnsupportedFileTypeError:
+            raise UnsupportedFileTypeError()
+
+        return upload_file, 201

dify/api/controllers/service_api/app/file_preview.py

@@ -0,0 +1,186 @@
+import logging
+from urllib.parse import quote
+
+from flask import Response
+from flask_restx import Resource, reqparse
+
+from controllers.service_api import service_api_ns
+from controllers.service_api.app.error import (
+    FileAccessDeniedError,
+    FileNotFoundError,
+)
+from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
+from extensions.ext_database import db
+from extensions.ext_storage import storage
+from models.model import App, EndUser, Message, MessageFile, UploadFile
+
+logger = logging.getLogger(__name__)
+
+
+# Define parser for file preview API
+file_preview_parser = reqparse.RequestParser().add_argument(
+    "as_attachment", type=bool, required=False, default=False, location="args", help="Download as attachment"
+)
+
+
+@service_api_ns.route("/files/<uuid:file_id>/preview")
+class FilePreviewApi(Resource):
+    """
+    Service API File Preview endpoint
+
+    Provides secure file preview/download functionality for external API users.
+    Files can only be accessed if they belong to messages within the requesting app's context.
+    """
+
+    @service_api_ns.expect(file_preview_parser)
+    @service_api_ns.doc("preview_file")
+    @service_api_ns.doc(description="Preview or download a file uploaded via Service API")
+    @service_api_ns.doc(params={"file_id": "UUID of the file to preview"})
+    @service_api_ns.doc(
+        responses={
+            200: "File retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            403: "Forbidden - file access denied",
+            404: "File not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY))
+    def get(self, app_model: App, end_user: EndUser, file_id: str):
+        """
+        Preview/Download a file that was uploaded via Service API.
+
+        Provides secure file preview/download functionality.
+        Files can only be accessed if they belong to messages within the requesting app's context.
+        """
+        file_id = str(file_id)
+
+        # Parse query parameters
+        args = file_preview_parser.parse_args()
+
+        # Validate file ownership and get file objects
+        _, upload_file = self._validate_file_ownership(file_id, app_model.id)
+
+        # Get file content generator
+        try:
+            generator = storage.load(upload_file.key, stream=True)
+        except Exception as e:
+            raise FileNotFoundError(f"Failed to load file content: {str(e)}")
+
+        # Build response with appropriate headers
+        response = self._build_file_response(generator, upload_file, args["as_attachment"])
+
+        return response
+
+    def _validate_file_ownership(self, file_id: str, app_id: str) -> tuple[MessageFile, UploadFile]:
+        """
+        Validate that the file belongs to a message within the requesting app's context
+
+        Security validations performed:
+        1. File exists in MessageFile table (was used in a conversation)
+        2. Message belongs to the requesting app
+        3. UploadFile record exists and is accessible
+        4. File tenant matches app tenant (additional security layer)
+
+        Args:
+            file_id: UUID of the file to validate
+            app_id: UUID of the requesting app
+
+        Returns:
+            Tuple of (MessageFile, UploadFile) if validation passes
+
+        Raises:
+            FileNotFoundError: File or related records not found
+            FileAccessDeniedError: File does not belong to the app's context
+        """
+        try:
+            # Input validation
+            if not file_id or not app_id:
+                raise FileAccessDeniedError("Invalid file or app identifier")
+
+            # First, find the MessageFile that references this upload file
+            message_file = db.session.query(MessageFile).where(MessageFile.upload_file_id == file_id).first()
+
+            if not message_file:
+                raise FileNotFoundError("File not found in message context")
+
+            # Get the message and verify it belongs to the requesting app
+            message = (
+                db.session.query(Message).where(Message.id == message_file.message_id, Message.app_id == app_id).first()
+            )
+
+            if not message:
+                raise FileAccessDeniedError("File access denied: not owned by requesting app")
+
+            # Get the actual upload file record
+            upload_file = db.session.query(UploadFile).where(UploadFile.id == file_id).first()
+
+            if not upload_file:
+                raise FileNotFoundError("Upload file record not found")
+
+            # Additional security: verify tenant isolation
+            app = db.session.query(App).where(App.id == app_id).first()
+            if app and upload_file.tenant_id != app.tenant_id:
+                raise FileAccessDeniedError("File access denied: tenant mismatch")
+
+            return message_file, upload_file
+
+        except (FileNotFoundError, FileAccessDeniedError):
+            # Re-raise our custom exceptions
+            raise
+        except Exception as e:
+            # Log unexpected errors for debugging
+            logger.exception(
+                "Unexpected error during file ownership validation",
+                extra={"file_id": file_id, "app_id": app_id, "error": str(e)},
+            )
+            raise FileAccessDeniedError("File access validation failed")
+
+    def _build_file_response(self, generator, upload_file: UploadFile, as_attachment: bool = False) -> Response:
+        """
+        Build Flask Response object with appropriate headers for file streaming
+
+        Args:
+            generator: File content generator from storage
+            upload_file: UploadFile database record
+            as_attachment: Whether to set Content-Disposition as attachment
+
+        Returns:
+            Flask Response object with streaming file content
+        """
+        response = Response(
+            generator,
+            mimetype=upload_file.mime_type,
+            direct_passthrough=True,
+            headers={},
+        )
+
+        # Add Content-Length if known
+        if upload_file.size and upload_file.size > 0:
+            response.headers["Content-Length"] = str(upload_file.size)
+
+        # Add Accept-Ranges header for audio/video files to support seeking
+        if upload_file.mime_type in [
+            "audio/mpeg",
+            "audio/wav",
+            "audio/mp4",
+            "audio/ogg",
+            "audio/flac",
+            "audio/aac",
+            "video/mp4",
+            "video/webm",
+            "video/quicktime",
+            "audio/x-m4a",
+        ]:
+            response.headers["Accept-Ranges"] = "bytes"
+
+        # Set Content-Disposition for downloads
+        if as_attachment and upload_file.name:
+            encoded_filename = quote(upload_file.name)
+            response.headers["Content-Disposition"] = f"attachment; filename*=UTF-8''{encoded_filename}"
+            # Override content-type for downloads to force download
+            response.headers["Content-Type"] = "application/octet-stream"
+
+        # Add caching headers for performance
+        response.headers["Cache-Control"] = "public, max-age=3600"  # Cache for 1 hour
+
+        return response

dify/api/controllers/service_api/app/message.py

@@ -0,0 +1,237 @@
+import json
+import logging
+
+from flask_restx import Api, Namespace, Resource, fields, reqparse
+from flask_restx.inputs import int_range
+from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
+
+import services
+from controllers.service_api import service_api_ns
+from controllers.service_api.app.error import NotChatAppError
+from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
+from core.app.entities.app_invoke_entities import InvokeFrom
+from fields.conversation_fields import build_message_file_model
+from fields.message_fields import build_agent_thought_model, build_feedback_model
+from fields.raws import FilesContainedField
+from libs.helper import TimestampField, uuid_value
+from models.model import App, AppMode, EndUser
+from services.errors.message import (
+    FirstMessageNotExistsError,
+    MessageNotExistsError,
+    SuggestedQuestionsAfterAnswerDisabledError,
+)
+from services.message_service import MessageService
+
+logger = logging.getLogger(__name__)
+
+
+# Define parsers for message APIs
+message_list_parser = (
+    reqparse.RequestParser()
+    .add_argument("conversation_id", required=True, type=uuid_value, location="args", help="Conversation ID")
+    .add_argument("first_id", type=uuid_value, location="args", help="First message ID for pagination")
+    .add_argument(
+        "limit",
+        type=int_range(1, 100),
+        required=False,
+        default=20,
+        location="args",
+        help="Number of messages to return",
+    )
+)
+
+message_feedback_parser = (
+    reqparse.RequestParser()
+    .add_argument("rating", type=str, choices=["like", "dislike", None], location="json", help="Feedback rating")
+    .add_argument("content", type=str, location="json", help="Feedback content")
+)
+
+feedback_list_parser = (
+    reqparse.RequestParser()
+    .add_argument("page", type=int, default=1, location="args", help="Page number")
+    .add_argument(
+        "limit",
+        type=int_range(1, 101),
+        required=False,
+        default=20,
+        location="args",
+        help="Number of feedbacks per page",
+    )
+)
+
+
+def build_message_model(api_or_ns: Api | Namespace):
+    """Build the message model for the API or Namespace."""
+    # First build the nested models
+    feedback_model = build_feedback_model(api_or_ns)
+    agent_thought_model = build_agent_thought_model(api_or_ns)
+    message_file_model = build_message_file_model(api_or_ns)
+
+    # Then build the message fields with nested models
+    message_fields = {
+        "id": fields.String,
+        "conversation_id": fields.String,
+        "parent_message_id": fields.String,
+        "inputs": FilesContainedField,
+        "query": fields.String,
+        "answer": fields.String(attribute="re_sign_file_url_answer"),
+        "message_files": fields.List(fields.Nested(message_file_model)),
+        "feedback": fields.Nested(feedback_model, attribute="user_feedback", allow_null=True),
+        "retriever_resources": fields.Raw(
+            attribute=lambda obj: json.loads(obj.message_metadata).get("retriever_resources", [])
+            if obj.message_metadata
+            else []
+        ),
+        "created_at": TimestampField,
+        "agent_thoughts": fields.List(fields.Nested(agent_thought_model)),
+        "status": fields.String,
+        "error": fields.String,
+    }
+    return api_or_ns.model("Message", message_fields)
+
+
+def build_message_infinite_scroll_pagination_model(api_or_ns: Api | Namespace):
+    """Build the message infinite scroll pagination model for the API or Namespace."""
+    # Build the nested message model first
+    message_model = build_message_model(api_or_ns)
+
+    message_infinite_scroll_pagination_fields = {
+        "limit": fields.Integer,
+        "has_more": fields.Boolean,
+        "data": fields.List(fields.Nested(message_model)),
+    }
+    return api_or_ns.model("MessageInfiniteScrollPagination", message_infinite_scroll_pagination_fields)
+
+
+@service_api_ns.route("/messages")
+class MessageListApi(Resource):
+    @service_api_ns.expect(message_list_parser)
+    @service_api_ns.doc("list_messages")
+    @service_api_ns.doc(description="List messages in a conversation")
+    @service_api_ns.doc(
+        responses={
+            200: "Messages retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Conversation or first message not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY))
+    @service_api_ns.marshal_with(build_message_infinite_scroll_pagination_model(service_api_ns))
+    def get(self, app_model: App, end_user: EndUser):
+        """List messages in a conversation.
+
+        Retrieves messages with pagination support using first_id.
+        """
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+            raise NotChatAppError()
+
+        args = message_list_parser.parse_args()
+
+        try:
+            return MessageService.pagination_by_first_id(
+                app_model, end_user, args["conversation_id"], args["first_id"], args["limit"]
+            )
+        except services.errors.conversation.ConversationNotExistsError:
+            raise NotFound("Conversation Not Exists.")
+        except FirstMessageNotExistsError:
+            raise NotFound("First Message Not Exists.")
+
+
+@service_api_ns.route("/messages/<uuid:message_id>/feedbacks")
+class MessageFeedbackApi(Resource):
+    @service_api_ns.expect(message_feedback_parser)
+    @service_api_ns.doc("create_message_feedback")
+    @service_api_ns.doc(description="Submit feedback for a message")
+    @service_api_ns.doc(params={"message_id": "Message ID"})
+    @service_api_ns.doc(
+        responses={
+            200: "Feedback submitted successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Message not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser, message_id):
+        """Submit feedback for a message.
+
+        Allows users to rate messages as like/dislike and provide optional feedback content.
+        """
+        message_id = str(message_id)
+
+        args = message_feedback_parser.parse_args()
+
+        try:
+            MessageService.create_feedback(
+                app_model=app_model,
+                message_id=message_id,
+                user=end_user,
+                rating=args.get("rating"),
+                content=args.get("content"),
+            )
+        except MessageNotExistsError:
+            raise NotFound("Message Not Exists.")
+
+        return {"result": "success"}
+
+
+@service_api_ns.route("/app/feedbacks")
+class AppGetFeedbacksApi(Resource):
+    @service_api_ns.expect(feedback_list_parser)
+    @service_api_ns.doc("get_app_feedbacks")
+    @service_api_ns.doc(description="Get all feedbacks for the application")
+    @service_api_ns.doc(
+        responses={
+            200: "Feedbacks retrieved successfully",
+            401: "Unauthorized - invalid API token",
+        }
+    )
+    @validate_app_token
+    def get(self, app_model: App):
+        """Get all feedbacks for the application.
+
+        Returns paginated list of all feedback submitted for messages in this app.
+        """
+        args = feedback_list_parser.parse_args()
+        feedbacks = MessageService.get_all_messages_feedbacks(app_model, page=args["page"], limit=args["limit"])
+        return {"data": feedbacks}
+
+
+@service_api_ns.route("/messages/<uuid:message_id>/suggested")
+class MessageSuggestedApi(Resource):
+    @service_api_ns.doc("get_suggested_questions")
+    @service_api_ns.doc(description="Get suggested follow-up questions for a message")
+    @service_api_ns.doc(params={"message_id": "Message ID"})
+    @service_api_ns.doc(
+        responses={
+            200: "Suggested questions retrieved successfully",
+            400: "Suggested questions feature is disabled",
+            401: "Unauthorized - invalid API token",
+            404: "Message not found",
+            500: "Internal server error",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY, required=True))
+    def get(self, app_model: App, end_user: EndUser, message_id):
+        """Get suggested follow-up questions for a message.
+
+        Returns AI-generated follow-up questions based on the message content.
+        """
+        message_id = str(message_id)
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
+            raise NotChatAppError()
+
+        try:
+            questions = MessageService.get_suggested_questions_after_answer(
+                app_model=app_model, user=end_user, message_id=message_id, invoke_from=InvokeFrom.SERVICE_API
+            )
+        except MessageNotExistsError:
+            raise NotFound("Message Not Exists.")
+        except SuggestedQuestionsAfterAnswerDisabledError:
+            raise BadRequest("Suggested Questions Is Disabled.")
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+        return {"result": "success", "data": questions}

dify/api/controllers/service_api/app/site.py

@@ -0,0 +1,41 @@
+from flask_restx import Resource
+from werkzeug.exceptions import Forbidden
+
+from controllers.common.fields import build_site_model
+from controllers.service_api import service_api_ns
+from controllers.service_api.wraps import validate_app_token
+from extensions.ext_database import db
+from models.account import TenantStatus
+from models.model import App, Site
+
+
+@service_api_ns.route("/site")
+class AppSiteApi(Resource):
+    """Resource for app sites."""
+
+    @service_api_ns.doc("get_app_site")
+    @service_api_ns.doc(description="Get application site configuration")
+    @service_api_ns.doc(
+        responses={
+            200: "Site configuration retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            403: "Forbidden - site not found or tenant archived",
+        }
+    )
+    @validate_app_token
+    @service_api_ns.marshal_with(build_site_model(service_api_ns))
+    def get(self, app_model: App):
+        """Retrieve app site info.
+
+        Returns the site configuration for the application including theme, icons, and text.
+        """
+        site = db.session.query(Site).where(Site.app_id == app_model.id).first()
+
+        if not site:
+            raise Forbidden()
+
+        assert app_model.tenant
+        if app_model.tenant.status == TenantStatus.ARCHIVE:
+            raise Forbidden()
+
+        return site

dify/api/controllers/service_api/app/workflow.py

@@ -0,0 +1,323 @@
+import logging
+
+from dateutil.parser import isoparse
+from flask import request
+from flask_restx import Api, Namespace, Resource, fields, reqparse
+from flask_restx.inputs import int_range
+from sqlalchemy.orm import Session, sessionmaker
+from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
+
+from controllers.service_api import service_api_ns
+from controllers.service_api.app.error import (
+    CompletionRequestError,
+    NotWorkflowAppError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderQuotaExceededError,
+)
+from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
+from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
+from core.app.apps.base_app_queue_manager import AppQueueManager
+from core.app.entities.app_invoke_entities import InvokeFrom
+from core.errors.error import (
+    ModelCurrentlyNotSupportError,
+    ProviderTokenNotInitError,
+    QuotaExceededError,
+)
+from core.helper.trace_id_helper import get_external_trace_id
+from core.model_runtime.errors.invoke import InvokeError
+from core.workflow.enums import WorkflowExecutionStatus
+from core.workflow.graph_engine.manager import GraphEngineManager
+from extensions.ext_database import db
+from fields.workflow_app_log_fields import build_workflow_app_log_pagination_model
+from libs import helper
+from libs.helper import TimestampField
+from models.model import App, AppMode, EndUser
+from repositories.factory import DifyAPIRepositoryFactory
+from services.app_generate_service import AppGenerateService
+from services.errors.app import IsDraftWorkflowError, WorkflowIdFormatError, WorkflowNotFoundError
+from services.errors.llm import InvokeRateLimitError
+from services.workflow_app_service import WorkflowAppService
+
+logger = logging.getLogger(__name__)
+
+# Define parsers for workflow APIs
+workflow_run_parser = (
+    reqparse.RequestParser()
+    .add_argument("inputs", type=dict, required=True, nullable=False, location="json")
+    .add_argument("files", type=list, required=False, location="json")
+    .add_argument("response_mode", type=str, choices=["blocking", "streaming"], location="json")
+)
+
+workflow_log_parser = (
+    reqparse.RequestParser()
+    .add_argument("keyword", type=str, location="args")
+    .add_argument("status", type=str, choices=["succeeded", "failed", "stopped"], location="args")
+    .add_argument("created_at__before", type=str, location="args")
+    .add_argument("created_at__after", type=str, location="args")
+    .add_argument(
+        "created_by_end_user_session_id",
+        type=str,
+        location="args",
+        required=False,
+        default=None,
+    )
+    .add_argument(
+        "created_by_account",
+        type=str,
+        location="args",
+        required=False,
+        default=None,
+    )
+    .add_argument("page", type=int_range(1, 99999), default=1, location="args")
+    .add_argument("limit", type=int_range(1, 100), default=20, location="args")
+)
+
+workflow_run_fields = {
+    "id": fields.String,
+    "workflow_id": fields.String,
+    "status": fields.String,
+    "inputs": fields.Raw,
+    "outputs": fields.Raw,
+    "error": fields.String,
+    "total_steps": fields.Integer,
+    "total_tokens": fields.Integer,
+    "created_at": TimestampField,
+    "finished_at": TimestampField,
+    "elapsed_time": fields.Float,
+}
+
+
+def build_workflow_run_model(api_or_ns: Api | Namespace):
+    """Build the workflow run model for the API or Namespace."""
+    return api_or_ns.model("WorkflowRun", workflow_run_fields)
+
+
+@service_api_ns.route("/workflows/run/<string:workflow_run_id>")
+class WorkflowRunDetailApi(Resource):
+    @service_api_ns.doc("get_workflow_run_detail")
+    @service_api_ns.doc(description="Get workflow run details")
+    @service_api_ns.doc(params={"workflow_run_id": "Workflow run ID"})
+    @service_api_ns.doc(
+        responses={
+            200: "Workflow run details retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Workflow run not found",
+        }
+    )
+    @validate_app_token
+    @service_api_ns.marshal_with(build_workflow_run_model(service_api_ns))
+    def get(self, app_model: App, workflow_run_id: str):
+        """Get a workflow task running detail.
+
+        Returns detailed information about a specific workflow run.
+        """
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in [AppMode.WORKFLOW, AppMode.ADVANCED_CHAT]:
+            raise NotWorkflowAppError()
+
+        # Use repository to get workflow run
+        session_maker = sessionmaker(bind=db.engine, expire_on_commit=False)
+        workflow_run_repo = DifyAPIRepositoryFactory.create_api_workflow_run_repository(session_maker)
+
+        workflow_run = workflow_run_repo.get_workflow_run_by_id(
+            tenant_id=app_model.tenant_id,
+            app_id=app_model.id,
+            run_id=workflow_run_id,
+        )
+        return workflow_run
+
+
+@service_api_ns.route("/workflows/run")
+class WorkflowRunApi(Resource):
+    @service_api_ns.expect(workflow_run_parser)
+    @service_api_ns.doc("run_workflow")
+    @service_api_ns.doc(description="Execute a workflow")
+    @service_api_ns.doc(
+        responses={
+            200: "Workflow executed successfully",
+            400: "Bad request - invalid parameters or workflow issues",
+            401: "Unauthorized - invalid API token",
+            404: "Workflow not found",
+            429: "Rate limit exceeded",
+            500: "Internal server error",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser):
+        """Execute a workflow.
+
+        Runs a workflow with the provided inputs and returns the results.
+        Supports both blocking and streaming response modes.
+        """
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode != AppMode.WORKFLOW:
+            raise NotWorkflowAppError()
+
+        args = workflow_run_parser.parse_args()
+        external_trace_id = get_external_trace_id(request)
+        if external_trace_id:
+            args["external_trace_id"] = external_trace_id
+        streaming = args.get("response_mode") == "streaming"
+
+        try:
+            response = AppGenerateService.generate(
+                app_model=app_model, user=end_user, args=args, invoke_from=InvokeFrom.SERVICE_API, streaming=streaming
+            )
+
+            return helper.compact_generate_response(response)
+        except ProviderTokenNotInitError as ex:
+            raise ProviderNotInitializeError(ex.description)
+        except QuotaExceededError:
+            raise ProviderQuotaExceededError()
+        except ModelCurrentlyNotSupportError:
+            raise ProviderModelCurrentlyNotSupportError()
+        except InvokeRateLimitError as ex:
+            raise InvokeRateLimitHttpError(ex.description)
+        except InvokeError as e:
+            raise CompletionRequestError(e.description)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@service_api_ns.route("/workflows/<string:workflow_id>/run")
+class WorkflowRunByIdApi(Resource):
+    @service_api_ns.expect(workflow_run_parser)
+    @service_api_ns.doc("run_workflow_by_id")
+    @service_api_ns.doc(description="Execute a specific workflow by ID")
+    @service_api_ns.doc(params={"workflow_id": "Workflow ID to execute"})
+    @service_api_ns.doc(
+        responses={
+            200: "Workflow executed successfully",
+            400: "Bad request - invalid parameters or workflow issues",
+            401: "Unauthorized - invalid API token",
+            404: "Workflow not found",
+            429: "Rate limit exceeded",
+            500: "Internal server error",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser, workflow_id: str):
+        """Run specific workflow by ID.
+
+        Executes a specific workflow version identified by its ID.
+        """
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode != AppMode.WORKFLOW:
+            raise NotWorkflowAppError()
+
+        args = workflow_run_parser.parse_args()
+
+        # Add workflow_id to args for AppGenerateService
+        args["workflow_id"] = workflow_id
+
+        external_trace_id = get_external_trace_id(request)
+        if external_trace_id:
+            args["external_trace_id"] = external_trace_id
+        streaming = args.get("response_mode") == "streaming"
+
+        try:
+            response = AppGenerateService.generate(
+                app_model=app_model, user=end_user, args=args, invoke_from=InvokeFrom.SERVICE_API, streaming=streaming
+            )
+
+            return helper.compact_generate_response(response)
+        except WorkflowNotFoundError as ex:
+            raise NotFound(str(ex))
+        except IsDraftWorkflowError as ex:
+            raise BadRequest(str(ex))
+        except WorkflowIdFormatError as ex:
+            raise BadRequest(str(ex))
+        except ProviderTokenNotInitError as ex:
+            raise ProviderNotInitializeError(ex.description)
+        except QuotaExceededError:
+            raise ProviderQuotaExceededError()
+        except ModelCurrentlyNotSupportError:
+            raise ProviderModelCurrentlyNotSupportError()
+        except InvokeRateLimitError as ex:
+            raise InvokeRateLimitHttpError(ex.description)
+        except InvokeError as e:
+            raise CompletionRequestError(e.description)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@service_api_ns.route("/workflows/tasks/<string:task_id>/stop")
+class WorkflowTaskStopApi(Resource):
+    @service_api_ns.doc("stop_workflow_task")
+    @service_api_ns.doc(description="Stop a running workflow task")
+    @service_api_ns.doc(params={"task_id": "Task ID to stop"})
+    @service_api_ns.doc(
+        responses={
+            200: "Task stopped successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Task not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser, task_id: str):
+        """Stop a running workflow task."""
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode != AppMode.WORKFLOW:
+            raise NotWorkflowAppError()
+
+        # Stop using both mechanisms for backward compatibility
+        # Legacy stop flag mechanism (without user check)
+        AppQueueManager.set_stop_flag_no_user_check(task_id)
+
+        # New graph engine command channel mechanism
+        GraphEngineManager.send_stop_command(task_id)
+
+        return {"result": "success"}
+
+
+@service_api_ns.route("/workflows/logs")
+class WorkflowAppLogApi(Resource):
+    @service_api_ns.expect(workflow_log_parser)
+    @service_api_ns.doc("get_workflow_logs")
+    @service_api_ns.doc(description="Get workflow execution logs")
+    @service_api_ns.doc(
+        responses={
+            200: "Logs retrieved successfully",
+            401: "Unauthorized - invalid API token",
+        }
+    )
+    @validate_app_token
+    @service_api_ns.marshal_with(build_workflow_app_log_pagination_model(service_api_ns))
+    def get(self, app_model: App):
+        """Get workflow app logs.
+
+        Returns paginated workflow execution logs with filtering options.
+        """
+        args = workflow_log_parser.parse_args()
+
+        args.status = WorkflowExecutionStatus(args.status) if args.status else None
+        if args.created_at__before:
+            args.created_at__before = isoparse(args.created_at__before)
+
+        if args.created_at__after:
+            args.created_at__after = isoparse(args.created_at__after)
+
+        # get paginate workflow app logs
+        workflow_app_service = WorkflowAppService()
+        with Session(db.engine) as session:
+            workflow_app_log_pagination = workflow_app_service.get_paginate_workflow_app_logs(
+                session=session,
+                app_model=app_model,
+                keyword=args.keyword,
+                status=args.status,
+                created_at_before=args.created_at__before,
+                created_at_after=args.created_at__after,
+                page=args.page,
+                limit=args.limit,
+                created_by_end_user_session_id=args.created_by_end_user_session_id,
+                created_by_account=args.created_by_account,
+            )
+
+            return workflow_app_log_pagination