Connect Dify to Tokens

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 covers creating one with a spend cap.
• A model ID from the model catalog. 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), 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.

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).
• 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.

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 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 and see 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). 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), 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).
• 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. 402 insufficient_credits: top up in billing.

Every code is listed in Errors. When you contact support, include the x-tokens-request-id header from a curl run of the same call.

Sources: Dify Model Providers, Integrations and the self-hosted Integrations page, Agent node, the OpenAI-API-compatible plugin source and README (version 0.0.68) and the Dify plugin SDK's OpenAI-compatible model class, checked October 2026.