> 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. # Using BeatAPI in Dify > Configure BeatAPI as a model provider in Dify and use it across apps, agents, and workflows. # Using BeatAPI in Dify Dify is an LLMOps platform for building chat apps, agents, and workflows. BeatAPI is added as a model provider once and is then selectable on every app in the workspace. The model-provider setup below is separate from the [BeatAPI tool plugin in Dify Marketplace](https://marketplace.dify.ai/plugin/erickkkyt/beatapi). The Marketplace currently lists v0.1.0 with two music-video tools. The expanded v0.2.1 plugin has been [submitted for Marketplace review](https://github.com/langgenius/dify-plugins/pull/3164); submission does not establish that the Marketplace has upgraded or that every new tool has completed a Dify workspace execution. ## Prerequisites 1. **A Dify workspace** — the cloud service or a self-hosted deployment. 2. **A BeatAPI API key** — create one in [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys). ## Step 1: Open model settings Click your avatar at the top right, choose **Settings**, then **Model Provider** in the left menu. ## Step 2: Add BeatAPI Two routes reach the same result. The first is faster; the second keeps BeatAPI separate from any other provider you use. ### Option A: Reuse the OpenAI provider 1. Find the **OpenAI** provider and click **Configure**. 2. Fill in: | Field | Value | | ------------ | --------------------------- | | API Key | Your BeatAPI API key | | API Base URL | `https://api.beatapi.io/v1` | 3. Save, then enable the models you intend to use in the model list. > **Note** > > Dify's OpenAI model list is Dify's own; it is not read from the endpoint. Enabling a model that BeatAPI does not serve produces a `not_found` at run time, inside whatever app you built on it. Enable only IDs from the table below or from the [pricing page](https://beatapi.io/pricing). ### Option B: Add a custom model provider 1. Scroll to **Custom Model** and click **+ Add Model**. 2. Fill in: | Field | Value | | ------------------- | ------------------------------------------------- | | Model Name | `BeatAPI` or any label | | Model Type | `LLM` | | API Key | Your BeatAPI API key | | API endpoint URL | `https://api.beatapi.io/v1` | | Endpoint model name | The exact model ID, for example `claude-sonnet-5` | Repeat for each model you want available. This route is more typing but the list only ever contains models that actually work. ## Step 3: Models | Model ID | Context | Choose it for | | --------------------------- | --------- | ----------------------------------------------------------------- | | `claude-fable-5-1` | Long | The newest generation, for demanding apps | | `claude-sonnet-5` | Long | Balanced quality and cost | | `claude-haiku-4-5-20251001` | Long | Classification, routing, and other cheap steps | | `gpt-6-astra` | Long | The newest OpenAI generation; higher rate above 272K input tokens | | `gemini-3.7-flash` | Long | Fast and inexpensive | | `deepseek-v4-pro-0813` | Long | Strong reasoning at a low rate | | `minimax-m3` | Very long | Documents past the usual context ceiling | Full details are on the [Text API](/text-api) pages; rates on the [pricing page](https://beatapi.io/pricing). > **Note** > > A few models change rate with load or context length: the two DeepSeek HC (high-cache) models double on weekdays 09:00–12:00 and 14:00–18:00 Beijing time (the regular paid DeepSeek models bill one rate at all hours), Hunyuan `hy3` has its own daily peak window, GPT-6 Astra and the GPT-5.6 family have a higher tier above 272K input tokens, and Grok has a higher tier above 200K. A Dify workflow that runs on a schedule can sit entirely inside a peak window without anyone noticing. See the [pricing page](https://beatapi.io/pricing) footnotes. ## Step 4: Build and publish 1. Create an app — Chatbot, Text Generator, Agent, or Workflow. 2. In **Model Settings**, select the BeatAPI model. 3. Write the system prompt, using `{{variable}}` for user input and `{{context}}` for knowledge-base content. 4. Test in the preview panel, then **Publish** — as an API, an embed, or a shared link. ### Parameters worth setting | Parameter | Effect | Suggested | | ----------- | ----------------- | ----------------------------- | | Temperature | Output randomness | `0.7` creative, `0.3` precise | | Max Tokens | Output length cap | 2000–4000 | | Top P | Nucleus sampling | `0.9` | ## FAQ ### Dify cannot connect 1. Base URL must be `https://api.beatapi.io/v1` — with `/v1`, no trailing slash. 2. Confirm the key is active in [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys). 3. Self-hosted deployments: confirm the Dify **server** can reach `api.beatapi.io`, not just your browser. ### A model fails only at run time It was enabled in Dify's list but is not served by the account. Cross-check the ID against the [pricing page](https://beatapi.io/pricing). ### 402 insufficient_credits Insufficient balance: the balance is zero or below the price of the request. Top up from the dashboard. A published app fails for its users while the balance is empty, so this is worth alerting on. ### 429 rate_limit_exceeded The key exceeded its request rate — likely from a workflow fanning out. Reduce concurrency in the workflow, or raise the allowance; the per-minute rate rises with lifetime top-ups and is shown on the dashboard. ### Controlling spend * Give each app its own BeatAPI key so `by_api_key` in [`GET /v1/usage`](/quick-guide) attributes cost per app. * Route cheap steps — classification, routing, extraction — to a cheap model and reserve the strong model for the final answer. * Cap Max Tokens on every node; workflow nodes inherit generous defaults. ## Support Open a support ticket from the [dashboard](https://beatapi.io/dashboard) and include the `request_id` from the failing response.