Dify API Base URL 填到 /v1 后 404先拆开 /v1/chat-messages调用 Dify 应用 API 时如果返回404 Not Found很多人会先换 API Key、模型甚至重启整套 Docker。对于路径配置错误最快的检查其实只有一个Base URL 已经包含/v1时具体接口只再拼/chat-messages不要把/v1拼第二次。本文只解决一个问题调用 Dify 应用的chat-messages接口时因为 Base URL 和 endpoint 都包含/v1最终请求变成/v1/v1/chat-messages并返回 404。Dify 官方文档把 Service API 的 Base URL 示例写成https://api.dify.ai/v1聊天操作路径写成/chat-messages自托管实例则把域名和端口换成自己的地址。先跑通配置位置、最小请求和成功信号适用环境Dify Cloud或者 Docker Compose 自托管的 Dify 实例。调用方使用curl、Python 或自己的后端服务。你已经在 Dify 应用中创建了 App API Key下面的示例 Key 是占位符不要替换成文章或截图中的真实凭据。配置放在哪里调用方可以先在当前 shell 或项目.env中放两个变量export DIFY_API_BASE_URLhttps://your-dify-host/v1 export DIFY_API_KEYYOUR_DIFY_APP_API_KEYDIFY_API_BASE_URL只负责协议、主机、端口和版本前缀。接口路径由每个 API 操作自己补上。如果是自托管 Docker服务端的配置文件通常是仓库docker/.env。官方 Compose 配置默认把宿主机的EXPOSE_NGINX_PORT映射到容器内的NGINX_PORT若宿主机端口改为8080调用方的基址应类似export DIFY_API_BASE_URLhttp://127.0.0.1:8080/v1调用方不要把 Compose 内部服务名api:5001当成浏览器或宿主机可访问的 Base URL。官方 Compose 的http://localhost:5001/health是 API 容器内部的健康检查地址容器外部通常应通过 Nginx 映射出的宿主机端口访问。第一步用/v1/info做预检Dify 官方入门文档给出的低成本首个请求是GET /v1/info。先执行curl --fail-with-body --silent --show-error \ $DIFY_API_BASE_URL/info \ -H Authorization: Bearer $DIFY_API_KEY成功信号不是“curl 没有报错”而是收到 HTTP200并看到包含应用信息的 JSON例如{ name: My Chat App, mode: chat }如果这一步请求的是$DIFY_API_BASE_URL/v1/info而变量本身已经以/v1结尾实际地址就是/v1/v1/info。先把这一处改正确再进入聊天请求。第二步调用chat-messagesDify 的聊天操作路径是/chat-messages所以调用代码应该把它接在已包含/v1的 Base URL 后面curl --fail-with-body --silent --show-error \ -X POST $DIFY_API_BASE_URL/chat-messages \ -H Authorization: Bearer $DIFY_API_KEY \ -H Content-Type: application/json \ -d { inputs: {}, query: reply with one short word, response_mode: blocking, conversation_id: , user: csdn-path-check }成功信号是 HTTP200并能在 JSON 中读到answer。如果使用streaming成功的 HTTP 状态仍然是200后续内容会以 SSE 事件到达本文先用blocking验证路径避免把流式解析问题混进 Base URL 排错。404 的根因Base URL 和 endpoint 各自负责什么把最终请求拆成两段Base URL endpoint https://your-dify-host/v1 /chat-messages组合后的完整路径是https://your-dify-host/v1/chat-messages常见错误写法是Base URL endpoint https://your-dify-host/v1 /v1/chat-messages最终路径会变成https://your-dify-host/v1/v1/chat-messagesDify 没有这条重复版本前缀的路由时返回 404 是合理的。修复动作不是给服务端增加一个重复路由而是让调用方只保留一个/v1。代码中最容易出现的错误通常长这样base_url https://your-dify-host/v1 endpoint /v1/chat-messages # 错误重复了版本前缀 url base_url.rstrip(/) endpoint应该改成base_url https://your-dify-host/v1 endpoint /chat-messages url base_url.rstrip(/) endpoint如果项目中 endpoint 是由配置生成的可以在发送请求前打印脱敏后的最终方法和路径from urllib.parse import urlsplit url base_url.rstrip(/) /chat-messages parts urlsplit(url) print({method: POST, scheme: parts.scheme, host: parts.netloc, path: parts.path})不要打印Authorization头、完整 API Key、带查询参数的私密 URL 或完整请求体。排查 404 时真正有价值的是最终path应看到/v1/chat-messages而不是/v1/v1/chat-messages。本地复现正确路径 200重复路径 404为了验证路径组合我写了一个标准库 HTTP 夹具。它模拟 Dify 文档里最小的三个信号GET /v1/info返回200和mode。POST /v1/chat-messages返回200和answer。POST /v1/v1/chat-messages返回 Dify 风格的404错误对象。本次测试环境披露下面的输出来自 Python 3.9.6 和只绑定127.0.0.1的本地 fixture没有请求 Dify Cloud、自托管实例、第三方 provider 或线上中转服务域名、Key、用户和回答均为占位符。运行命令python3 06-evidence/probe_dify_base_url.py本次实际输出PYTHON_VERSION3.9.6 FIXTURE127.0.0.1 only INFO_STATUS200 MODEchat GOOD_CHAT_STATUS200 ANSWERfixture answer BAD_CHAT_STATUS404 CODEnot_found PATH/v1/v1/chat-messages SUMMARYpass info200 good_chat200 expected_bad404 ONLINE_PROVIDER_REQUESTNO REQUESTS[[GET, /v1/info], [POST, /v1/chat-messages], [POST, /v1/v1/chat-messages]]这里的200和404证明的是 URL 组合结果当 Base URL 停在/v1endpoint 使用/chat-messages时路径正确当两段都带/v1时路径重复。自托管 Dify 的端口和路径要分两层看如果你使用 Docker Compose404 可能来自两层不同位置宿主机入口层浏览器或调用程序访问http://127.0.0.1:宿主机端口端口由 Nginx 的映射决定。先检查docker ps的端口映射确认访问的是当前运行实例。Dify API 路径层在入口主机和端口确认后再检查是否只使用一个/v1并用/v1/info复核 API Key 与路径。不要把这两层混成“Dify API 不支持”。如果访问的是 Compose 内部服务名、旧端口或错误的反向代理前缀得到的 404 可能根本没有到达 Dify API。一个安全的核对顺序是docker compose ps docker compose logs --tail80 nginx api日志中只关注请求方法、路径、状态和服务是否健康不要把完整请求体、Authorization 头或环境文件内容复制到文章、工单或截图中。仍然 404 时按状态码分层Dify 官方错误文档使用code、message、status三个字段。先保留这三个字段再按下面的顺序判断现象优先检查不要直接得出的结论404路径是/v1/v1/chat-messagesBase URL 是否已经包含/v1不是“Key 一定失效”404路径是/v1/chat-messagesApp 类型、资源是否存在、user或自托管反代前缀不是“模型名一定错”401unauthorizedBearer Key 是否缺失、错误或属于别的应用不是先改路径403forbidden权限、访问范围或计划限制不是重试能解决429too_many_requests或rate_limit_error并发上限与配额含义不是继续快速重发HTTP 200 后流中出现error事件SSE 事件和应用/模型配置不是 HTTP 路由 404特别注意/v1/info能返回 200只能说明当前 Base URL、认证和应用信息预检通过它不证明每一种应用类型都能调用chat-messages。如果应用是 Workflow应改用官方 Workflow API 的对应 endpoint不要拿聊天路径硬试。最小排错清单在调用方打印脱敏后的最终 HTTP 方法和path。确认 Base URL 只包含一个/v1末尾不要带具体操作路径。用GET /v1/info做预检先排除主机、端口、版本前缀和 Key 的组合错误。Chat 应用使用/chat-messages不要把/v1再写进 endpoint。自托管时检查EXPOSE_NGINX_PORT与实际 Nginx 入口不要从容器外访问内部api:5001。看到 Dify 的404错误对象后再检查资源、App 类型、user和反向代理不要先换模型或增加重试。真实 Key 只通过环境变量或密钥管理器提供日志和截图统一脱敏。适用边界与安全说明真实项目中应通过环境变量或密钥管理器提供 Key并在日志、截图和异常上报中脱敏。Dify 的具体版本、反向代理前缀和应用类型可能改变可调用的 endpoint遇到差异时以当前版本的官方 API 文档和服务端访问日志为准。官方参考Dify API 入门Send Chat MessageDify 错误与限流Dify Docker Compose总结Dify API 返回 404 时先看最终路径不要先换 Key。官方组合方式是Base URL 负责https://主机/v1聊天操作负责/chat-messages最终请求应是/v1/chat-messages。先用/v1/info得到 200再调用聊天接口如果日志显示/v1/v1/chat-messages删除 endpoint 中多余的/v1即可把问题从“服务不可用”还原成一个可验证的字符串拼接错误。