#发布与 API

预览只给开发者用。对外有三条主路：Web App（浏览器对话页）、Service API（REST，带应用级 API Key）、以及把应用暴露为 MCP Server（给 Cursor 等客户端，见本站 MCP）。官方 CLI difyctl 可在终端跑同一批应用，见 安装。

#发布 Web App

在 Studio 点 Publish / 发布，打开 Web App。典型能力：独立链接、嵌入 iframe / 聊天气泡、基础品牌与访问控制（具体开关以当前版本文档的 Web App Settings 为准）。

适合：给同事试用、官网挂一个助手。不适合：把 API Key 写进前端 再冒充「集成」。浏览器用户走 Web App；你的后端走下一节的 Service API。

隔离： Service API 产生的会话与 Web App 不共享。同一业务用户在两边是两套 conversation_id。

#创建 API Key

在应用里打开 API Access / 访问 API（侧栏名称可能是「API」或「开发」）：

1. 阅读该应用自动生成的接口说明（Chat 类与 Workflow 类路径不同）
2. 创建 API Key，按环境拆分（dev / prod），不要共用一把
3. Key 只放在服务器环境变量，轮换时先加新再删旧

Cloud 的 Service API 基址官方示例为 https://api.dify.ai/v1。自托管则是你的站点根路径加上 /v1（经 nginx），例如 http://localhost/v1。鉴权头统一为：

Authorization: Bearer {YOUR_API_KEY}

#官方路径：POST /v1/chat-messages

对话类应用（官方写明适用于 Chatflow、Chatbot、Agent 以及文档中的 New Agent）发送消息的路径是 /chat-messages，完整 URL 即 {API_BASE}/chat-messages，也就是大家常写的 /v1/chat-messages。

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {},
    "query": "用一句话介绍你自己",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "user-42"
  }'

自托管把 URL 换成 http://localhost/v1/chat-messages（或 https://your-host/v1/chat-messages）。

工作流型应用（单次跑完、无对话外壳）走另一条 workflow run 类接口（在该应用的 API 文档页查看），不要误用 chat-messages。

#最小 Python 调用

import os
import requests

BASE = os.environ.get("DIFY_API_BASE", "http://localhost/v1")
KEY = os.environ["DIFY_API_KEY"]

r = requests.post(
    f"{BASE}/chat-messages",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "inputs": {},
        "query": "What is Dify?",
        "response_mode": "blocking",
        "user": "backend-demo",
    },
    timeout=60,
)
r.raise_for_status()
data = r.json()
print(data.get("answer") or data)
# 续聊：把 data["conversation_id"] 放进下一请求

生产请加超时、重试与日志（不要打印完整 Key）。更完整的封装见 实战案例。

#安全清单

• Key 视为密码；泄露后立刻吊销
• 按应用、按环境拆 Key，便于停掉被滥用的那一把
• 前端只打你自己的 BFF，由 BFF 持有 Dify Key
• 注意平台日志保留策略与合规（Cloud 与自托管不同）

#下一步

• 接入 Ollama
• 实战案例
• 官方：Send Chat Message