> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API 集成

> 通过强大的后端即服务 API 将 Dify AI 能力直接嵌入到你的应用程序中

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/cloud/use-dify/publish/developing-with-apis)。

Dify 的 API 让你将 AI 能力集成到现有应用程序中，而无需从零开始构建 AI 基础设施。你既能用上大语言模型的全部能力，又能自由打造定制化的用户体验。

## 为什么使用 Dify API

<CardGroup cols={2}>
  <Card title="跳过后端复杂性" icon="server">
    直接从前端应用访问大型语言模型能力，无需管理 AI 基础设施
  </Card>

  <Card title="可视化应用管理" icon="eye">
    可视化设计和更新 AI 行为，更改会立即同步到所有 API 消费者
  </Card>

  <Card title="提供商灵活性" icon="shuffle">
    在 AI 提供商之间切换并集中管理 API 密钥，无需更改代码
  </Card>

  <Card title="内置监控" icon="chart-line">
    开箱即用的日志、分析和用户活动跟踪
  </Card>
</CardGroup>

## API 集成的工作原理

1. **构建应用**：在 Dify Studio 中构建具有所需 AI 能力的应用
2. **生成 API 凭据**：安全访问应用功能
3. **调用 API**：从你的应用程序调用 API 获取 AI 驱动的响应
4. **用户交互**：用户在你的自定义界面中操作，AI 推理则交由 Dify 完成

<Info>
  你的 API 会自动继承 Dify 应用的所有功能：提示词、知识库、工具和模型配置。
</Info>

## 开始使用

<Steps>
  <Step title="访问 API 设置">
    在你的应用中，导航至左侧边栏的 **访问 API**。
  </Step>

  <Step title="创建 API 凭据">
    为你的集成生成新凭据。你可以为不同环境或用户创建多个密钥。
  </Step>

  <Step title="查看文档">
    Dify 会生成针对你应用配置的完整 API 文档。
  </Step>

  <Step title="在应用中实现">
    使用提供的示例将 API 调用集成到你的应用程序中。
  </Step>
</Steps>

<Warning>
  永远不要在前端代码或客户端请求中暴露 API 密钥。始终从后端调用 Dify API 以防止滥用并维护安全性。
</Warning>

## API 安全

**凭据管理**：

* 为开发、测试和生产环境创建独立的 API 密钥
* 定期轮换密钥并撤销未使用的凭据
* 监控 API 使用情况以检测异常活动

**最佳实践**：

* 在后端将 API 密钥存储为环境变量
* 在你这边实施速率限制以防止过度使用
* 在转发到 Dify API 之前添加请求验证
* 记录 API 调用以便调试和监控

### 文本生成应用

这些应用程序用于生成高质量文本，如传入用户输入来获得生成的文本结果。用于生成文本的模型参数和提示词模板取决于开发者在 Dify 提示词编排页面中的设置。

你可以在 **应用 -> 访问 API** 中找到此应用程序的 API 文档和示例请求。

例如，这里是一个调用文本生成 API 的示例：

<Tabs>
  <Tab title="cURL">
    ```
    curl --location --request POST 'https://api.dify.ai/v1/completion-messages' \
    --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "inputs": {},
    "response_mode": "streaming",
    "user": "abc-123"
    }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import json

    url = "https://api.dify.ai/v1/completion-messages"

    headers = {
    'Authorization': 'Bearer ENTER-YOUR-SECRET-KEY',
    'Content-Type': 'application/json',
    }

    data = {
    "inputs": {"text": 'Hello, how are you?'},
    "response_mode": "streaming",
    "user": "abc-123"
    }

    response = requests.post(url, headers=headers, data=json.dumps(data))

    print(response.text)
    ```
  </Tab>
</Tabs>

### 对话应用

对话应用通过问答格式促进与用户的持续对话。要启动对话，你需要调用 `chat-messages` API。每个会话都会生成一个 `conversation_id`，必须在后续 API 调用中包含此 ID 以维持对话流。

> **重要说明**：服务 API 不会共享 WebApp 创建的对话。通过 API 创建的对话与在 WebApp 界面中创建的对话是隔离的。

#### `conversation_id` 的关键注意事项：

* **生成 `conversation_id`**：开始新对话时，将 `conversation_id` 字段留空。系统将生成并返回新的 `conversation_id`，你将在未来的交互中使用此 ID 继续对话。
* **在现有会话中处理 `conversation_id`**：一旦生成 `conversation_id`，对 API 的后续调用应包含此 `conversation_id` 以确保与 Dify 机器人的对话连续性。当传递之前的 `conversation_id` 时，任何新的 `inputs` 将被忽略。只有 `query` 会为正在进行的对话进行处理。
* **管理动态变量**：如果需要在会话期间修改逻辑或变量，你可以使用会话变量（特定于会话的变量）来调整机器人的行为或响应。

你可以在 **应用 -> 访问 API** 中访问此应用程序的 API 文档和示例请求。

这里是一个调用 `chat-messages` API 的示例：

<Tabs>
  <Tab title="cURL">
    ```
    curl --location --request POST 'https://api.dify.ai/v1/chat-messages' \
    --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "inputs": {},
    "query": "eh",
    "response_mode": "streaming",
    "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276",
    "user": "abc-123"
    }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import json

    url = 'https://api.dify.ai/v1/chat-messages'
    headers = {
    'Authorization': 'Bearer ENTER-YOUR-SECRET-KEY',
    'Content-Type': 'application/json',
    }
    data = {
    "inputs": {},
    "query": "eh",
    "response_mode": "streaming",
    "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276",
    "user": "abc-123"
    }

    response = requests.post(url, headers=headers, data=json.dumps(data))

    print(response.text())
    ```
  </Tab>
</Tabs>