工作流编排对话型应用 API

远程 URL 方式（transfer_method: remote_url）

不用真正上传文件，只要给 Dify 一个可访问的公网 URL。

files = [
    {
        "type": "image",                 # 文件类型：image / audio / video / document
        "transfer_method": "remote_url", # 表示文件是远程 URL
        "url": "<https://cloud.dify.ai/logo/logo-site.png>"  # 远程文件地址
    }
]

payload = {
    "inputs": {},
    "query": "请描述图片内容",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "abc-123",
    "files": files
}


import requests
import json

API_KEY  = "YOUR_DIFY_API_KEY"
BASE_URL = "<https://api.dify.ai/v1/chat-messages>"

# 请求体 JSON（不含文件）
payload = {
    "inputs": {},
    "query": "请分析这个文件",
    "response_mode": "blocking",  # 流式的话 streaming
    "conversation_id": "",
    "user": "abc-123",
    "files": [
        {
            "type": "document",             # 文件类型
            "transfer_method": "local_file" # 本地上传
            # url 字段不需要
        }
    ]
}

files = {
    "file": open("local/path/to/file.pdf", "rb")  # 文件对象
}

resp = requests.post(
    BASE_URL,
    headers={"Authorization": f"Bearer {API_KEY}"},
    data={"payload": json.dumps(payload)},  # JSON 作为表单字段
    # 在这里上传files，和data的请求体分开
    files=files
)

print(resp.json())

这个文件还不在“消息上下文（message context）”里，或者不属于当前应用（API Key 对应的 app）

上传只是把文件存起来；

只有当文件被挂到一条消息上（比如通过 /chat-messages 发送一次并引用这个 upload_file_id）后，这个文件才“属于消息范围”，此时 /files/{id}/preview 才能访问。

你的对话应用使用的模型不支持图像输入或未启用 Vision，导致服务端忽略 files，虽然 /chat-messages 200，但附件不会进入“消息上下文”。

image.png