> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 在 Dify 中使用 BeatAPI

> 把 BeatAPI 配置为 Dify 的模型提供方，供应用、智能体与工作流统一调用。

# 在 Dify 中使用 BeatAPI

Dify 是一个用来搭建对话应用、智能体与工作流的大模型平台。BeatAPI 添加一次之后，工作区内所有应用都能选到它。

下文的模型提供方配置与 [Dify Marketplace 的 BeatAPI 工具插件](https://marketplace.dify.ai/plugin/erickkkyt/beatapi)是两条接入路径。Marketplace 当前展示 v0.1.0，包含两个音乐视频工具。扩展后的 v0.2.1 插件已[提交 Marketplace 审核](https://github.com/langgenius/dify-plugins/pull/3164)；提交不等于 Marketplace 已升级，也不证明每个新工具都在 Dify 工作区完整执行过。

## 准备工作

1. **一个 Dify 工作区** —— 云端版或自部署版。
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：打开模型设置

点右上角头像，选择**设置**，再在左侧菜单选择**模型供应商**。

## 第二步：添加 BeatAPI

两条路径结果相同。第一条更快，第二条能把 BeatAPI 与其他供应商分开管理。

### 方案一：复用 OpenAI 供应商

1. 找到 **OpenAI** 供应商，点**配置**。
2. 填写：

| 字段           | 值                           |
| ------------ | --------------------------- |
| API Key      | 你的 BeatAPI 密钥               |
| API Base URL | `https://api.beatapi.io/v1` |

3. 保存后，在模型列表里启用你打算使用的模型。

> **Note**
>
> Dify 的 OpenAI 模型列表是 Dify 自己维护的，**不是**从接口读回来的。启用一个 BeatAPI 不提供的模型，会在运行时才返回 `not_found` —— 而那时它已经在你搭好的应用里了。请只启用下表或[价目页](https://beatapi.io/pricing)中的编号。

### 方案二：添加自定义模型供应商

1. 滚动到**自定义模型**区域，点 **+ 添加模型**。
2. 填写：

| 字段       | 值                            |
| -------- | ---------------------------- |
| 模型名称     | `BeatAPI` 或任意标签              |
| 模型类型     | `LLM`                        |
| API Key  | 你的 BeatAPI 密钥                |
| API 端点地址 | `https://api.beatapi.io/v1`  |
| 端点模型名称   | 准确的模型编号，例如 `claude-sonnet-5` |

每个要用的模型重复一次。这条路要多打点字，但列表里永远只有真正能用的模型。

## 第三步：模型

| 模型编号                        | 上下文 | 适用场景                          |
| --------------------------- | --- | ----------------------------- |
| `claude-fable-5-1`          | 长   | 最新一代，适合高要求应用                  |
| `claude-sonnet-5`           | 长   | 质量与成本均衡                       |
| `claude-haiku-4-5-20251001` | 长   | 分类、路由等廉价步骤                    |
| `gpt-6-astra`               | 长   | 最新一代 GPT，输入超过 272K 后按长上下文档位计费 |
| `gemini-3.7-flash`          | 长   | 快速便宜                          |
| `deepseek-v4-pro-0813`      | 长   | 低价强推理                         |
| `minimax-m3`                | 超长  | 超出常规上下文上限的文档                  |

详情见[文本 API](/text-api) 各页，价格见[价目页](https://beatapi.io/pricing)。

> **Note**
>
> 少数模型的价格会随负载或上下文长度变化：DeepSeek 的两个高缓存版（HC）模型在工作日北京时间 09:00–12:00、14:00–18:00 翻倍（常规付费 DeepSeek 模型全天同一价），混元 `hy3` 有自己的每日高峰窗口，GPT-5.6 与 Grok 系列在上下文超过阈值后按更高档位计费。**定时运行的 Dify 工作流可能整个落在高峰窗口里而无人察觉。** 具体时段见[价目页](https://beatapi.io/pricing)脚注。

## 第四步：搭建与发布

1. 创建应用 —— 聊天助手、文本生成、Agent 或工作流。
2. 在**模型设置**中选择 BeatAPI 的模型。
3. 编写系统提示词，用 `{{变量名}}` 表示用户输入、`{{context}}` 表示知识库内容。
4. 在右侧预览面板测试，然后**发布** —— 可作为 API、嵌入网页或分享链接。

### 值得设置的参数

| 参数          | 作用     | 建议值                   |
| ----------- | ------ | --------------------- |
| Temperature | 输出随机性  | `0.7` 偏创意 / `0.3` 偏精确 |
| Max Tokens  | 输出长度上限 | 2000–4000             |
| Top P       | 核采样    | `0.9`                 |

## 常见问题

### Dify 连不上

1. Base URL 必须是 `https://api.beatapi.io/v1` —— 带 `/v1`，结尾不加斜杠。
2. 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认密钥仍然可用。
3. 自部署版：要确认 Dify **服务端**能访问 `api.beatapi.io`，而不只是你的浏览器能访问。

### 某个模型只在运行时失败

说明它在 Dify 列表里被启用了，但账户并不提供。对照[价目页](https://beatapi.io/pricing)核对编号。

### 402 insufficient_credits

余额不足：余额为零或低于本次请求的价格，在控制台充值。余额为空期间，已发布的应用对它的用户来说是坏的 —— 这一项值得配告警。

### 429 rate_limit_exceeded

该密钥超出请求频率上限，通常是工作流并发扇出造成的。降低工作流并发度，或提升额度；每分钟额度随累计充值提升，当前值在控制台可见。

### 怎么控制花费

* 每个应用发一把独立密钥，[`GET /v1/usage`](/quick-guide) 的 `by_api_key` 就能按应用归集成本。
* 分类、路由、抽取这类廉价步骤走便宜模型，只把最终作答留给强模型。
* 给每个节点都设 Max Tokens；工作流节点的默认上限相当宽松。

## 获取支持

在[控制台](https://beatapi.io/dashboard)提交工单，并附上失败响应里的 `request_id`。