# Connect Dify to Tokens

> Add Tokens models to Dify with the OpenAI-API-compatible provider plugin: the form fields, model IDs with a slash, the Function Call Type setting for agents, and Dify Cloud versus self-hosted.

Dify is an open-source platform for building LLM apps, chatbots, agents and workflows. Model providers in Dify are plugins. Its OpenAI-API-compatible provider sends OpenAI Chat Completions requests to any base URL, which for Tokens is `https://tokens.bd/v1`. You add each Tokens model to Dify by hand, as a custom model.

This guide was checked against Dify 1.17.1 (released 10 September 2026) and version 0.0.68 of the OpenAI-API-compatible plugin, using Dify's documentation and the plugin's source in the langgenius/dify-official-plugins repository, in October 2026. It was checked against the documentation and source, not run end to end against a live Tokens key.

## What you need

- A Tokens key. [API keys](/docs/api-keys) covers creating one with a spend cap.
- A model ID from the [model catalog](/models). This guide uses `deepseek/deepseek-v4.1-flash`.
- The model's context window and maximum output from its catalog page. `GET /v1/models` does not return them ([Models and usage](/docs/models-and-usage)), and Dify asks for both.
- A Dify workspace where you are the owner or an admin. Dify allows only those roles to manage model providers.

## Install the provider plugin

In Dify, open **Integrations** and then **Model Provider**, and install **OpenAI-API-compatible** from the Marketplace. Dify's documentation lists three plugin sources: the Marketplace, a public GitHub repository, and a local `.zip` upload.

## Add a Tokens model

Open the OpenAI-API-compatible provider card and click **Add Model**. Dify's documentation describes Add Model as the way to add a model that is not in a provider's list. If a model with the same name and type already exists, Dify attaches the new key to it instead of creating a duplicate.

Fill in the form. The labels below come from the plugin's source at version 0.0.68, and your Dify version may word them differently.

| Field                                  | Value                                                                  |
| -------------------------------------- | ---------------------------------------------------------------------- |
| Model Type                             | `LLM`                                                                  |
| Model Name                             | `deepseek/deepseek-v4.1-flash`                                                    |
| Model display name (optional)          | Any label you want to see in Dify, such as `DeepSeek V4.1 Flash`       |
| API Key                                | Your Tokens key                                                        |
| API Base URL                           | `https://tokens.bd/v1`                                                  |
| model name for API endpoint (optional) | Leave empty (see below)                                                |
| Completion mode                        | `Chat`                                                                 |
| Model context size                     | The context window from the model's catalog page                       |
| Upper bound for max tokens             | The maximum output from the model's catalog page                       |
| Function Call Type                     | `Tool Call` for a model that supports tools (see Tool calling below)   |
| Stream function calling                | `Support` if you want streamed tool calls, when the model supports it  |
| Vision Support                         | `Support` only for a model that accepts images                         |

Save the form. Dify checks the credentials when you save, and the plugin does this by sending a short chat request to the endpoint. If the form saves, the key, address and model name are accepted.

A few notes on the form:

- **API Base URL.** The plugin's placeholder is `https://api.openai.com/v1`, so the address ends in `/v1`. The plugin adds `chat/completions` itself. Do not add it. Some third-party guides call this field "API endpoint URL".
- **The key is optional in the form**, but Tokens always needs one. Without it you get 401 `missing_api_key`.
- **Model context size and Upper bound for max tokens both default to 4096.** If you leave the defaults, Dify limits long prompts and outputs on its side, whatever the model can do. Set both from the catalog page.
- **Include Usage in Stream** is on by default in the plugin. Keep it on: it makes Dify ask for token counts in the stream. Tokens supports this ([Streaming](/docs/streaming)).
- **Add each model separately.** The plugin does not fetch a model list from the endpoint. Repeat Add Model for every Tokens model you want to pick in Dify.

### Model IDs with a slash

Tokens IDs look like `provider/model`. Dify's documentation does not say whether a slash is allowed in a model name, and the plugin's Model Name placeholder says "Enter full model name". The plugin sends the model name to the endpoint as is, unless **model name for API endpoint** is filled in, in which case it sends that value instead.

1. First try the full ID in **Model Name**.
2. If Dify rejects the name, put a short name in Model Name, for example `tokens-flash`, and the full Tokens ID in **model name for API endpoint**. This second field exists for that case: the name Dify shows can differ from the name the endpoint expects.

Whichever you choose, the value that reaches Tokens must be the full ID, or you get 404 `model_not_found`.

## Check that it works

Test the key and model with curl first.

```bash
export TOKENS_API_KEY=tok_live_your_key
curl -s https://tokens.bd/v1/chat/completions \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4.1-flash", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'
```

Then in Dify create an app, pick the model you added, and send a message in the preview. The request appears in your Tokens dashboard usage analytics.

## Tool calling

Dify's Agent node and agent apps work with tools. Dify offers two agent strategies:

- **Function Calling** uses the model's native tool calling and passes tool definitions through the `tools` parameter. Dify says to make sure the model supports function calling when you use it.
- **ReAct** guides the model with structured prompts instead. Dify recommends it for models without native tool calling.

For a custom model, the setting that tells Dify a model can call tools is **Function Call Type** in the Add Model form. Its default is `Not Support`. The plugin's source shows what the choices do.

- **Tool Call** sends the OpenAI `tools` format. This is the one that matches [Tool calling](/docs/tool-calling) on Tokens.
- **Function Call** sends the older `functions` format. Tokens' documentation does not cover it, so do not use it.
- **Not Support** sends no tool definitions, so the Function Calling strategy cannot work with that model.

Dify's documentation does not say what happens if you pick the Function Calling strategy for a model set to Not Support, so set it correctly rather than testing it.

Tool calling still needs a model that supports it. Check the model's page in the [model catalog](/models) and see [Choosing a model](/docs/choosing-a-model).

## Dify Cloud and self-hosted

The setup is the same in both. The difference is where the requests to Tokens come from: Dify's servers on Dify Cloud, your own deployment when self-hosted. Tokens is a public HTTPS address, so a self-hosted Dify needs outbound access to it, and nothing on the Tokens side needs to know which one you use.

- **Dify's AI credits** are Dify's own billing. They do not pay for a Tokens model. Tokens usage is billed to your Tokens account.
- On a self-hosted Dify, if you open the Marketplace outside Dify to install the plugin, set your deployment's URL under **Install Preference** first.

Not confirmed from Dify's documentation: the network requirements of a self-hosted plugin daemon, and whether any Dify Cloud plan limits custom model providers. Check Dify's self-hosting documentation and your plan.

## What costs credits in the background

Every request Dify sends to a Tokens model is billed to the key.

- Each LLM node in a workflow is one request per run. A workflow with several LLM nodes, or one inside an iteration or loop, makes one request per pass.
- An agent calls the model again after each tool result. Dify's documentation describes **Max Iterations** as a safety limit that prevents infinite loops, and suggests 3 to 5 for simple tasks and 10 to 15 for complex research. Keep it as low as the task allows.
- Each round sends the conversation again, so input tokens grow with every round.
- Dify's documentation does not list other features that call a model automatically. Check which of your app's features use a model, and which model they use, in the app and workspace settings.

Use a dedicated key for Dify with a monthly spend cap and an allowed-models list ([API keys](/docs/api-keys)). When the cap is reached, requests fail with 403 `monthly_spend_cap_exceeded` instead of running up a bill.

## Limits and what is not covered

- This page covers LLM models only. The plugin also offers text embedding, rerank, speech and text-to-speech types. Tokens' embeddings endpoint works only for embedding models, and Tokens has no audio endpoints ([Models and usage](/docs/models-and-usage)), so the others are not covered here.
- The plugin has an **API Type** setting with a Responses API choice. Leave it on Chat Completions. Responses works on Tokens only when the upstream supports it ([Responses API](/docs/responses)).
- Dify's built-in model providers, such as its OpenAI provider, are not used here.

## Troubleshooting

**Saving the model fails with a credentials error.** The message contains the status code and response body from Tokens, so read it. 401 `invalid_api_key` means a wrong or revoked key. 404 means the API Base URL or the model name is wrong. Compare with the curl test above.

**404 on every request.** Check that API Base URL is `https://tokens.bd/v1`. It needs `/v1`, and `/chat/completions` must not be added.

**404 `model_not_found`.** The model name that reaches Tokens is not the full ID. Check Model Name and "model name for API endpoint" against `GET /v1/models`.

**403 `model_not_allowed_on_key`.** The key's allowed-models list does not include this model. Use an allowed model or another key.

**The Agent node refuses the model, or never calls tools.** Set Function Call Type to `Tool Call` on the model, or switch the agent to the ReAct strategy. If it still fails to call tools, the model is probably a poor fit for tool use.

**400 `invalid_request` mentioning the `user` field.** The plugin has a **User Identity Support** setting, described as whether the endpoint accepts the optional top-level `user` parameter. Set it to Not Support to leave the field out.

**Long prompts are cut short or outputs stop early.** Check Model context size and Upper bound for max tokens. Both default to 4096.

**429 `rate_limited`, `concurrency_limit` or `window_exhausted`.** Wait for `Retry-After` seconds, or see [Rate limits](/docs/rate-limits). **402 `insufficient_credits`**: top up in [billing](/dashboard/billing).

Every code is listed in [Errors](/docs/errors). When you contact [support](/docs/support), include the `x-tokens-request-id` header from a curl run of the same call.

Sources: [Dify Model Providers](https://docs.dify.ai/en/use-dify/workspace/model-providers), [Integrations](https://docs.dify.ai/en/use-dify/workspace/plugins) and the [self-hosted Integrations page](https://docs.dify.ai/en/self-host/use-dify/workspace/plugins), [Agent node](https://docs.dify.ai/en/use-dify/nodes/agent), the [OpenAI-API-compatible plugin source and README](https://github.com/langgenius/dify-official-plugins/tree/main/models/openai_api_compatible) (version 0.0.68) and the [Dify plugin SDK's OpenAI-compatible model class](https://github.com/langgenius/dify-plugin-sdks/blob/main/src/dify_plugin/interfaces/model/openai_compatible/llm.py), checked October 2026.

---
Page: https://tokens.bd/docs/dify