> 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 を使う

> Dify のモデル接続先に BeatAPI を設定し、アプリ、エージェント、ワークフローで利用します。

# Dify で BeatAPI を使う

Dify はチャットアプリ、エージェント、ワークフローを構築する LLMOps プラットフォームです。BeatAPI をモデル接続先として一度登録すると、ワークスペースの各アプリで選択できます。

以下のモデル設定は、[Dify Marketplace の BeatAPI ツールプラグイン](https://marketplace.dify.ai/plugin/erickkkyt/beatapi)とは別です。Marketplace には現在、ミュージックビデオ用ツール 2 つを含む v0.1.0 が掲載されています。拡張版の v0.2.1 は[Marketplace の審査に提出済み](https://github.com/langgenius/dify-plugins/pull/3164)ですが、提出しただけでは Marketplace が更新されたことや、すべての新しいツールが Dify ワークスペースで実行を完了したことを意味しません。

## 前提条件

1. **Dify ワークスペース。** クラウド版またはセルフホスト版を使います。
2. **BeatAPI API キー。** [ダッシュボード → API キー](https://beatapi.io/dashboard/apikeys)で作成します。

## ステップ 1：モデル設定を開く

右上のアバターから **Settings** を開き、左メニューの **Model Provider** を選択します。

## ステップ 2：BeatAPI を追加する

2 つの設定方法で同じ結果を得られます。方法 A は手早く、方法 B はほかの接続先と分けて管理できます。

### 方法 A：OpenAI 接続を利用する

1. **OpenAI** の **Configure** を押します。
2. 次を入力します。

| 項目           | 値                           |
| ------------ | --------------------------- |
| API Key      | BeatAPI API キー              |
| API Base URL | `https://api.beatapi.io/v1` |

3. 保存し、モデル一覧で利用するモデルを有効にします。

> **Note**
>
> OpenAI モデル一覧は Dify 独自のもので、エンドポイントから取得する一覧ではありません。BeatAPI が提供しないモデルを有効にすると、そのモデルを使うアプリの実行時に `not_found` が発生します。下の表か[料金ページ](https://beatapi.io/pricing)にある ID だけを有効にしてください。

### 方法 B：カスタムモデルを追加する

1. **Custom Model** まで移動し **+ Add Model** を押します。
2. 次を入力します。

| 項目                  | 値                             |
| ------------------- | ----------------------------- |
| Model Name          | `BeatAPI` または任意の名前            |
| Model Type          | `LLM`                         |
| API Key             | BeatAPI API キー                |
| API endpoint URL    | `https://api.beatapi.io/v1`   |
| Endpoint model name | 正確なモデル ID。例 `claude-sonnet-5` |

モデルごとに追加します。入力は増えますが、実際に動くモデルだけを一覧に置けます。

## ステップ 3：モデルを選ぶ

| モデル ID                      | コンテキスト | 用途                                    |
| --------------------------- | ------ | ------------------------------------- |
| `claude-fable-5-1`          | 長い     | 最新世代。要求水準の高いアプリ                       |
| `claude-sonnet-5`           | 長い     | 品質とコストのバランス                           |
| `claude-haiku-4-5-20251001` | 長い     | 分類、ルーティングなどの低コストな処理                   |
| `gpt-6-astra`               | 長い     | 最新世代の OpenAI。入力トークンが 272K を超えると単価が上がる |
| `gemini-3.7-flash`          | 長い     | 高速、低価格                                |
| `deepseek-v4-pro-0813`      | 長い     | 低価格で高い推論性能                            |
| `minimax-m3`                | 非常に長い  | 通常のコンテキスト上限を超える文書                     |

詳細は [Text API](/text-api)、料金は[料金ページ](https://beatapi.io/pricing)を参照してください。

> **Note**
>
> 一部のモデルは負荷やコンテキスト長に応じて単価が変わります。2 つの DeepSeek HC（高キャッシュ）モデルは平日の北京時間 09:00–12:00 と 14:00–18:00 に 2 倍になります。通常の有料 DeepSeek モデルは時間帯を問わず同じ料金です。Hunyuan `hy3` には毎日の独自のピーク時間帯があります。GPT-6 Astra と GPT-5.6 シリーズは入力トークンが 272K、Grok は 200K を超えると高い単価になります。定期実行する Dify ワークフローが、気付かないままピーク時間帯だけで動いている場合もあります。[料金ページ](https://beatapi.io/pricing)の注記を確認してください。

## ステップ 4：構築して公開する

1. Chatbot、Text Generator、Agent、Workflow のいずれかのアプリを作成します。
2. **Model Settings** で BeatAPI のモデルを選びます。
3. ユーザー入力に `{{variable}}`、ナレッジベースの内容に `{{context}}` を使ってシステムプロンプトを記述します。
4. プレビューパネルでテストし、**Publish** から API、埋め込み、共有リンクとして公開します。

### 設定を推奨するパラメーター

| パラメーター      | 効果       | 推奨値                    |
| ----------- | -------- | ---------------------- |
| Temperature | 出力のランダム性 | 創作は `0.7`、正確さ重視は `0.3` |
| Max Tokens  | 出力の長さの上限 | 2000–4000              |
| Top P       | 核サンプリング  | `0.9`                  |

## よくある質問

### Dify が接続できません

1. Base URL は `/v1` を含み、末尾スラッシュのない `https://api.beatapi.io/v1` を指定します。
2. [ダッシュボード → API キー](https://beatapi.io/dashboard/apikeys)でキーが有効か確認します。
3. セルフホストでは、ブラウザーだけでなく Dify の**サーバー**が `api.beatapi.io` に到達できるか確認します。

### 実行時にだけモデルが失敗します

Dify の一覧で有効になっていても、アカウントでは提供していない可能性があります。[料金ページ](https://beatapi.io/pricing)と ID を照合してください。

### 402 insufficient\_credits

残高が 0、またはリクエストの料金に不足しています。ダッシュボードからチャージしてください。残高が空の間は公開アプリの利用者にも影響するため、監視を推奨します。

### 429 rate\_limit\_exceeded

キーのリクエスト数が上限を超えています。ワークフローの並列呼び出しが原因になりがちです。同時実行数を減らすか、上限を増やしてください。毎分の上限はチャージ累計額に応じて増え、ダッシュボードに表示されます。

### コストを管理するには

* アプリごとに BeatAPI キーを分け、[`GET /v1/usage`](/quick-guide) の `by_api_key` でアプリ別の料金を確認します。
* 分類、ルーティング、抽出などは安いモデルに振り分け、最終回答に高性能モデルを使います。
* 各ノードの Max Tokens に上限を設けます。ワークフローノードの初期値は大きめです。

## サポート

[ダッシュボード](https://beatapi.io/dashboard)からチケットを作成し、失敗したレスポンスの `request_id` を添えてください。