不容错过的实战指南！Dify工作流API全景揭秘，掌握高效开发秘籍！

关注

原创最新推荐文章于 2026-06-16 12:19:11 发布 1.8k 阅读 AI 写同款· GEO 优化 ›

AGI 之【Dify】之 Dify 在 Windows 端本地部署调用 Ollama 本地下载的大模型， API 形式 Python 调用进行简单聊天接口测试 AGI，即通用人工智能（Artificial General Intelligence），是一种具备人类智能水平的人工智能系统。它不仅能够执行特定的任务，而且能够理解、学习和应用知识于广泛的问题解决中，具有较高的自主性和适应性。AGI的能力包括但不限于自我学习、自我改进、自我调整，并能在没有人为干预的情况下解决各种复杂问题。本节将介绍如何使用 Dify 平台调用 Ollama 部署的本地模型来创建一个聊天应用。通过 API 的方式发起聊天，可以让前端自由布置所需的聊天形式。阅读详情

你是否想过，让你现有的业务流程与强大的AI模型无缝对接？

你是否希望，能够一键处理成百上千的任务，自动生成内容，甚至打造一个完全属于你自己的AI应用前端？

如果这些正是你所想的，那么Dify的API接口，就是你实现这一切的魔法棒。

或许你会问，Dify的网页界面已经很好用了，为什么我们还需要API？

来看一下三个无法在网页上完成，但通过API接口却能轻松实现的典型场景：

1. 自动化与批量处理：告别千次点击的灾难

我们都喜欢Dify工作流带来的智能。比如，用它来识别一张发票，既新奇又高效。但如果这项任务需要重复1000次呢？手动上传1000份文件，再点击1000次运行，那不是乐趣，而是一场灾难。现在可以调用API接口编写一个脚本，让它自动处理成千上万的文件，而你要做的，仅仅是下达一次指令。

2. 无缝嵌入系统：让AI成为流程的一部分，而不是一个独立的工具

你的业务或许已经运行在一套成熟的系统上。API能让你将Dify的AI能力，像一个智能插件一样，无缝嵌入到你现有的业务流程中。

3. 功能拓展：实现Dify本身没有的定时任务

可以设置定时任务自动调用Dify的API接口，不过后续这个功能Dify应该会实现。比如自动分析前一天的数据。

总而言之，当你追求效率的极致、流程的融合、功能的自由时，API就是你的不二之选。

理解了为什么要用API，接下来，怎么用就变得水到渠成。

在本系列的第一篇，我们就从最核心、用途最广的工作流API入手，开启你的实践之旅。

下面是官方手册里的8个API接口。

序号	分类	功能	接口
1	工作流执行	执行 workflow	POST /workflows/run
2		获取workflow执行情况	GET /workflows/run/:workflow_run_id
3		停止响应	POST /workflows/tasks/:task_id/stop
4		获取 workflow 日志	GET /workflows/logs
5	文件操作	上传文件	POST /files/upload
6	应用配置	获取应用基本信息	GET /info
7		获取应用参数	GET /parameters
8		获取应用 WebApp 设置	GET /site

本文都用apifox做接口测试，不用安装客户端，在线测试，比较方便，当然不建议测试隐私信息。

也有很多其他的接口测试工具，可以按需选择。

1 接口详解

接口说明的示例就用之前文章搭建的发票识别工作流来举例。

输入是一个文件类型的参数，参数名称：upload。输出是一个JSON变量，参数名称：result。

我们调用工作流的时候都需要用到API KEY，先要获取一下。

点击左侧菜单的【访问API】，点击右上角【API秘钥】，创建密钥。

这个密钥是访问工作流的关键，需要保存好，不要轻易泄露。

我这里都是本地搭建的Dify环境，为了演示方便，实际工作中不要轻易泄露。

无论是哪种接口调用，都是需要API KEY的。

1.1 工作流执行

1.1.1 执行 workflow

curl -X POST 'http://127.0.0.1/v1/workflows/run' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "inputs": {},
    "response_mode": "streaming",
    "user": "abc-123"
}'

执行工作流是我们用的最多的API接口，Headers里面需要添加两个参数：Authorization和Content-Type。

Content-Type为json类型，我们请求体构造的就是json类型的数据。

然后就是请求体的构造了，也是很多人不太明白的地方。

请求体主要分为三大块：

{
    "inputs":{
        "upload":{
            "type":"document",
            "transfer_method":"local_file",
            "upload_file_id":"fdc58b65-72e4-442a-af26-1af05e61e09e"
        }
    },
    "response_mode":"blocking",
    "user":"rongjie"
}

1、inputs：对象类型，必填，允许传入 App 定义的各变量值，就是我们在工作流中开始节点增加的参数。

本示例的传入工作流的参数我只增加了一个，为upload，文件类型。

2、response_mode：字符串类型，必填，返回的响应模式，支持流式模式（streaming）和阻塞模式（blocking）。

3、user：字符串类型，必填，用户标识，用于定义终端用户的身份，方便检索、统计。

返回的响应模式和用户标识表示都非常好理解， inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。

比如我们这次的示例，变量只有一个，upload，变量字段类型是单文件，文件类型选择的是文档，因为我们上传的发票是PDF文件，所以type类型是document 。文件类型一共是5种，如下所示：

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 具体类型包含：其他文件类型

如果你上传的是图片文件，那么这个type值应该填写image。

transfer_method为传递方式，local_file为本地上传，remote_url为url地址。

upload_file_id为上传的文件ID，这个是我执行完【1.4节上传文件】获取的值。

返回的信息包括任务ID、工作流ID、详细的数据信息。

这份完整版的大模型 AI 学习和面试资料已经上传优快云，朋友们如果需要可以微信扫描下方优快云官方认证二维码免费领取【保证100%免费】

我这里上传的文件类型是PDF，所以type为文档类型。

响应信息。其中outputs是输出的数据结构，result是我在工作流中定义的输出变量，输出的是一个JSON结构的数据。其他还有工作流的错误信息、耗时、总tokens、总步数、开始时间、结束时间等。

{
    "task_id":"f717c097-d965-4198-b9a9-8e8b4e1c626d",
    "workflow_run_id":"40293a05-c790-4061-a5cd-fa3b7c973ed4",
    "data":{
        "id":"40293a05-c790-4061-a5cd-fa3b7c973ed4",
        "workflow_id":"ae15d15b-cfe2-4381-9899-e95fd9d7b8d2",
        "status":"succeeded",
        "outputs":{
            "result":{
                "invoice_title":"电子发票(普通发票)",
                "invoice_code":"25XXXX1359",
                "issue_date":"2025-03-23",
                "buyer_name":"北京XXXX有限公司",
                "buyer_tax_id":"911XXXX57T",
                "seller_name":"深圳XXXX有限公司",
                "seller_tax_id":"914XXXX399Q",
                "items":"[{\"name\": \"*电子元件*线对板针座\", \"model\": \"XH-4A-L\", \"unit\": \"个\", \"quantity\": 200, \"unit_price\": 0.0862831858407, \"amount\": 17.26, \"tax_rate\": \"13%\", \"tax_amount\": 2.24}, {\"name\": \"*电子元件*线对板针座\", \"model\": \"\", \"unit\": \"\", \"quantity\": null, \"unit_price\": null, \"amount\": -14.13, \"tax_rate\": \"13%\", \"tax_amount\": -1.84}]",
                "total_amount":3.13,
                "total_tax":0.4,
                "total_with_tax":3.53,
                "total_with_tax_in_words":"叁圆伍角叁分",
                "remarks":"",
                "issuer":"XX"
            }
        },
        "error":null,
        "elapsed_time":19.725127106999935,
        "total_tokens":2138,
        "total_steps":5,
        "created_at":1752820513,
        "finished_at":1752820533
    }
}

1.1.2 获取workflow执行情况

curl -X GET 'http://127.0.0.1/v1/workflows/run/:workflow_run_id' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json'

根据 workflow 执行 ID 获取 workflow 任务当前执行结果。

workflow_run_id是从上面执行workflow中获取的，Headers中要填写授权信息和Content-Type。

返回工作流的执行状态，status 执行状态有四种： running / succeeded / failed / stopped。

1.1.3 停止响应

curl -X POST 'http://127.0.0.1/v1/workflows/tasks/:task_id/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{"user": "abc-123"}'

执行工作流的时候会返回task_id。仅支持流式模式。

我们使用流式模式执行一下发票识别的工作流，然后执行停止响应的请求。

下面是流式响应执行工作流，在开始的时候获取task_id，在执行停止响应命令后可以看到断开连接，状态是stopped，error为被用户停止。

停止响应需要填写任务的task_id。还有授权信息和Content-Type。

返回一个固定信息，result为success。

1.1.4 获取 workflow 日志

curl -X GET 'http://127.0.0.1/v1/workflows/logs'\
 --header 'Authorization: Bearer {api_key}'

倒序返回workflow日志。之前执行了两次，一次正常执行工作流，一次被我停止响应了，返回了两条记录。

参数填写授权信息即可。

1.2 上传文件

curl -X POST 'http://127.0.0.1/v1/files/upload' \
--header 'Authorization: Bearer {api_key}' \
--form 'file=@localfile;type=image/[png|jpeg|jpg|webp|gif] \
--form 'user=abc-123'

Headers还是需要填写授权，form-data中要增加file参数，参数类型为文件，点击Upload按钮可以上传本地文件。

返回文件的ID、名称、大小、后缀、mime-type、上传人ID、上传时间（时间戳格式）。

{
    "id":"fdc58b65-72e4-442a-af26-1af05e61e09e",
    "name":"立创电子发票SO25032025405.pdf",
    "size":56981,
    "extension":"pdf",
    "mime_type":"application/pdf",
    "created_by":"4d63e97d-c836-4d16-bcc0-5628b863e2e0",
    "created_at":1752819363,
    "preview_url":null
}

1.3 应用配置

1.3.1 获取应用基本信息

curl -X GET 'http://127.0.0.1/v1/info' \
-H 'Authorization: Bearer {api_key}'

填写授权信息，返回应用名称、应用描述、应用标签。

1.3.2 获取应用参数

 curl -X GET 'http://127.0.0.1/v1/parameters'

填写授权信息，返回开场白、开场白推荐问题、启用回答后给出推荐问题、语音转文本、文本转语音、引用和归属、标记回复、用户输入表单配置、文件上传配置、系统参数。

完整输出：

{
    "opening_statement":"",
    "suggested_questions":[],
    "suggested_questions_after_answer":{
        "enabled":false
    },
    "speech_to_text":{
        "enabled":false
    },
    "text_to_speech":{
        "enabled":false,
        "language":"",
        "voice":""
    },
    "retriever_resource":{
        "enabled":true
    },
    "annotation_reply":{
        "enabled":false
    },
    "more_like_this":{
        "enabled":false
    },
    "user_input_form":[
        {
            "file":{
                "allowed_file_extensions":[],
                "allowed_file_types":[
                    "document"
                ],
                "allowed_file_upload_methods":[
                    "local_file"
                ],
                "label":"发票文件",
                "max_length":48,
                "options":[],
                "required":true,
                "type":"file",
                "variable":"upload"
            }
        }
    ],
    "sensitive_word_avoidance":{
        "enabled":false
    },
    "file_upload":{
        "image":{
            "enabled":false,
            "number_limits":3,
            "transfer_methods":[
                "local_file",
                "remote_url"
            ]
        },
        "enabled":false,
        "allowed_file_types":[
            "image"
        ],
        "allowed_file_extensions":[
            ".JPG",
            ".JPEG",
            ".PNG",
            ".GIF",
            ".WEBP",
            ".SVG"
        ],
        "allowed_file_upload_methods":[
            "local_file",
            "remote_url"
        ],
        "number_limits":3,
        "fileUploadConfig":{
            "file_size_limit":15,
            "batch_count_limit":5,
            "image_file_size_limit":10,
            "video_file_size_limit":100,
            "audio_file_size_limit":50,
            "workflow_file_upload_limit":10
        }
    },
    "system_parameters":{
        "image_file_size_limit":10,
        "video_file_size_limit":100,
        "audio_file_size_limit":50,
        "file_size_limit":15,
        "workflow_file_upload_limit":10
    }
}

1.3.3 获取应用 WebApp 设置

curl -X GET 'http://127.0.0.1/v1/site' \
-H 'Authorization: Bearer {api_key}'

填写授权信息，返回应用的 WebApp 设置，包括WebApp 名称、聊天颜色主题、聊天颜色主题是否反转、图标类型、图标、背景色、图标 URL、描述、版权信息、隐私政策链接、自定义免责声明、默认语言、是否显示工作流详情、是否使用 WebApp 图标替换聊天中的机器人图标。

2 Python代码调用示例

接口搞明白后，Python代码就是顺理成章的事情，没有什么难度了。

我们还是以这个发票识别的举例。

这个工作流用到了两个接口，上传文件和执行工作流。

当上传文件成功的时候再执行工作流，这里需要注意的是上传文件的时候还是要给出文件的mime类型。

MIME（Multipurpose Internet Mail Extensions）类型，也叫“媒体类型”，用来标识文件的内容类型。

它的格式通常是主类型/子类型，比如：

application/pdf —— PDF 文件
image/jpeg —— JPEG 图片
text/plain —— 纯文本文件

这里用了mimetypes.guess_type(file_path) 会根据文件扩展名自动推断出合适的 MIME 类型。

下面的Python脚本封装了两个核心函数：upload_file_to_dify() 和 run_dify_workflow()。

脚本的执行逻辑：首先调用文件上传接口，成功获取file_id后，再将其作为参数调用工作流执行接口。

import requests
import os
import mimetypes
import json

defupload_file_to_dify(api_key, file_path, user_id, dify_base_url="http://127.0.0.1"):
    """
    上传文件到Dify的工作流接口。
    :param api_key: Dify API密钥。
    :param file_path: 需要上传的文件的本地路径。
    :param user_id: 用户标识字符串。
    :param dify_base_url: Dify服务地址。
    :return: 成功返回服务器JSON响应，失败返回None。
    """
    ifnot os.path.exists(file_path):
        print(f"[错误] 文件未找到: {file_path}")
        returnNone

    url = f"{dify_base_url}/v1/files/upload"
    headers = {
        'Authorization': f'Bearer {api_key}'
    }
    data = {
        'user': user_id
    }

    # 自动推断MIME类型，支持多种常见类型
    mime_type, _ = mimetypes.guess_type(file_path)
    ifnot mime_type:
        mime_type = 'application/octet-stream'# 默认二进制流

    print(f"准备上传文件 '{os.path.basename(file_path)}' (类型: {mime_type}) 至 {url}...")

    try:
        withopen(file_path, 'rb') as f:
            files = {
                'file': (os.path.basename(file_path), f, mime_type)
            }
            response = requests.post(url, headers=headers, data=data, files=files)
            if response.status_code in (200, 201):
                print("[成功] 文件上传成功!")
                print("服务器返回:", response.json())
                return response.json()
            else:
                print(f"[失败] 文件上传失败，状态码: {response.status_code}")
                print("错误详情:", response.text)
                returnNone
    except Exception as e:
        print(f"[错误] 请求过程中发生异常: {e}")
        returnNone

defrun_dify_workflow(api_key, file_id, user_id, dify_base_url="http://127.0.0.1"):
    """
    执行Dify工作流
    :param api_key: Dify API密钥
    :param file_id: 上传文件返回的id
    :param user_id: 用户ID
    :param dify_base_url: Dify服务地址
    :return: 服务器返回的JSON响应
    """
    url = f"{dify_base_url}/v1/workflows/run"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    data = {
        "inputs": {
            "upload": {
                "type": "document",
                "transfer_method": "local_file",
                "upload_file_id": file_id
            }
        },
        "response_mode": "blocking",
        "user": user_id
    }
    print(f"准备执行工作流，文件ID: {file_id}")
    try:
        response = requests.post(url, headers=headers, data=json.dumps(data))
        if response.status_code in (200, 201):
            print("[成功] 工作流执行成功!")
            print("服务器返回:", response.json())
            return response.json()
        else:
            print(f"[失败] 工作流执行失败，状态码: {response.status_code}")
            print("错误详情:", response.text)
            returnNone
    except Exception as e:
        print(f"[错误] 请求过程中发生异常: {e}")
        returnNone

if __name__ == "__main__":
    DIFY_API_KEY = "app-2HhXFkGAploInzSfAc8S9ZL4"
    DIFY_BASE_URL = "http://127.0.0.1"
    USER_ID = "rongjie"
    # 文件路径：当前目录下的upload_file/立创电子发票SO25032025405.pdf
    LOCAL_FILE_PATH = os.path.join(os.path.dirname(__file__), "upload_file", "立创电子发票SO25032025405.pdf")

    # 上传文件
    upload_result = upload_file_to_dify(
        api_key=DIFY_API_KEY,
        file_path=LOCAL_FILE_PATH,
        user_id=USER_ID,
        dify_base_url=DIFY_BASE_URL
    )

    # 如果上传成功，执行工作流
    if upload_result and'id'in upload_result:
        FILE_ID = upload_result['id']
        run_dify_workflow(
            api_key=DIFY_API_KEY,
            file_id=FILE_ID,
            user_id=USER_ID,
            dify_base_url=DIFY_BASE_URL
        )
    else:
        print("[错误] 未获取到文件ID，无法执行工作流。")

代码中加了很多调试信息，是为了测试方便，实际应用可以去掉。

拿到工作流返回的结果，就可以根据实际情况进行分析了，比如发票识别这个例子，之前的文章就是把结果写到了本地的Excel表格中了。

如果你没有代码基础，需要调用工作流的API接口，把DIFY_API_KEY 、DIFY_BASE_URL 、USER_ID更改为你本地的实际值。工作流中的输入参数改为你本地工作流的值，我这里是工作流开始节点增加的参数是upload，参数类型等也要更改为你实际的值。

"inputs": {
    "upload": {
        "type": "document",
        "transfer_method": "local_file",
        "upload_file_id": file_id
    }
},

上传文件的工作流参数，只需要修改上传文件的路径就行了。当然，DIFY_API_KEY 、DIFY_BASE_URL 、USER_ID更改为你本地的实际值。

其他的接口其实都是类似的，就不在此一一赘述了。

本文档详细介绍了Dify工作流API的核心接口与调用方法，并提供了一个覆盖文件上传到执行的全流程Python示例。

从开发者角度来看，掌握API调用，核心是实现一种视角的转变：即将Dify从一个独立的AI应用，视为一个可被任意业务系统集成的智能化组件。

在这种视角下，Dify的Web界面更多承担了工作流设计与调试的职责，而API则是在生产环境中实现自动化、批量化和深度集成任务的必要手段。将二者结合使用，才能发挥出Dify在实际工程项目中的全部潜力。

3 如何学习AI大模型？

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑，所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限，很多互联网行业朋友无法获得正确的资料得到学习提升，故此将并将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

这份完整版的大模型 AI 学习和面试资料已经上传优快云，朋友们如果需要可以微信扫描下方优快云官方认证二维码免费领取【保证100%免费】