Dify API Guide: Connect OpenAI-Compatible Models and Control Costs

Dify separates two jobs that are often confused: configuring the model provider inside Dify, and calling a published Dify application through its API. Configure the provider first, publish a Chat or Completion app, then call the app with its Dify application key. Your caller does not normally send the upstream model key.

For an OpenAI-compatible provider such as LinkModel, use Dify's compatible provider/plugin path and enter the provider base URL, API key, and model ID required by your Dify deployment. LinkModel documents https://api.linkmodel.ai/v1 as its API root and POST /chat/completions as its bearer-authenticated OpenAI-compatible chat endpoint. Confirm the current model ID and capabilities in the LinkModel model reference.

For media branches, Dify's chat API is not a substitute for an image or video generation task endpoint. Use n8n workflow templates for AI media for orchestration patterns, or LinkModel CLI for explicit terminal workflows.

Dify's model-provider documentation distinguishes provider credentials from the models and capabilities exposed to an app. Use it to confirm the provider/plugin flow for the Dify version you operate.

Dify API versus the upstream model API

The request path looks like this:

Your app → Dify application API → Dify workflow/model layer → compatible model provider

The Dify API key identifies the published application. The provider credential is stored in Dify's model configuration. This lets you change a model or provider without changing every client, but it also means Dify is now part of your latency, logging, and security boundary.

If you only need a direct OpenAI-compatible chat request, call LinkModel directly. If you need prompts, variables, knowledge retrieval, workflow nodes, conversation handling, or a visual app layer, Dify may be the better boundary.

Step 1: Configure an OpenAI-compatible model provider

In Dify's model provider settings, install or select the OpenAI API-compatible provider available in your version. The exact plugin name and fields can vary between Dify releases, so use the provider's own credential form rather than assuming that the native OpenAI provider accepts every custom endpoint.

Enter values conceptually like these:

API base URL: https://api.linkmodel.ai/v1
API key:      your LinkModel API key
Model name:   gpt-5.4-mini

The current LinkModel reference lists gpt-5.4-mini as a chat model. Treat the model ID as configuration data: check the live catalog, confirm that it supports the features used by your Dify app, and keep a documented fallback.

Dify's model-provider documentation distinguishes predefined models from customizable models. An OpenAI-compatible integration may require you to enter the model name and, depending on the plugin, a custom base URL. If the provider test fails, check whether Dify is appending /v1 or another path twice.

Step 2: Build and publish a Dify app

Create a Chat application for conversational requests or a Completion/Workflow application for a defined input and output. Keep the first prompt simple:

You classify support tickets.
Return a concise answer with:
- category: billing, technical, account, or other
- priority: low, medium, or high
- next_action: one sentence
If the input does not contain enough evidence, use category=other.

Add a knowledge base or workflow node only after the base model call works. This isolates provider errors from retrieval and orchestration errors. Publish the app and create an application API key. Keep it server-side; do not expose it in browser JavaScript.

Step 3: Call the Dify chat API

Dify's published chat interface uses the Dify API host and a bearer application key. A typical blocking request is:

export DIFY_API_KEY="app_api_key"
export DIFY_BASE_URL="https://api.dify.ai/v1"
 
curl -X POST "$DIFY_BASE_URL/chat-messages" \
  -H "Authorization: Bearer $DIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {},
    "query": "Classify: the customer was charged twice for order 1842.",
    "response_mode": "blocking",
    "user": "customer-1842"
  }'

Use the streaming response mode only when your server and client are prepared to parse the event stream. Save the returned conversation identifier when you want to continue a conversation, and treat it as application state rather than authorization.

The exact response fields depend on the Dify interface and mode. Read the answer or workflow output documented for your app, validate its shape, and handle an error object before passing the result to another system.

Control Dify and model costs

Your monthly cost is a combination of Dify execution, provider usage, and downstream work:

effective monthly cost
= Dify hosting or plan cost
+ model input/output usage
+ retrieval, storage, and embedding usage
+ retries and failed workflow runs
+ human review or downstream API work

The provider model is only one line item. Long conversation history, repeated retrieval, large documents, and workflow retries can dominate a small chatbot's bill. Limit input size, cap conversation history, and avoid rerunning expensive nodes after a validation-only failure.

If you need a separate gateway for budgets, virtual keys, or routing, compare the LiteLLM Proxy guide. If the same model should be reachable from a self-hosted chat UI, use the Open WebUI API setup as the adjacent integration path.

Use a routing policy when the app supports it:

Measure accepted answers and completed business tasks, not just provider requests. A retry that creates duplicate downstream work is a reliability problem as well as a cost problem.

Security and production checklist

• Store the Dify application key and provider key in server-side secrets.
• Give each app or environment its own key when possible.
• Use a stable but non-sensitive user identifier.
• Validate variables before starting a workflow.
• Limit file types, file size, and retrieval scope.
• Add timeouts and a safe fallback message.
• Log request IDs, model IDs, latency, and error classes; redact prompts by default.
• Require approval for emails, refunds, deletion, or other side effects.
• Keep a provider fallback only if its prompt and output behavior are tested.

Provider compatibility can be partial. Plain chat may work while tools, structured output, multimodal input, or streaming differs. Test each capability in the Dify app you plan to ship.

Troubleshooting Dify API integrations

Provider test fails: verify the custom base URL, API key, and model name. Check for duplicate path segments.

Dify app returns an upstream error: call the provider directly with the same model ID and a minimal prompt, then add Dify nodes one at a time.

Conversation responses grow expensive: cap history, summarize old turns, and avoid sending retrieved documents that cannot affect the answer.

The client cannot parse the result: confirm whether the app is blocking or streaming and validate the actual response shape before destructuring fields.

Next step

Use Dify as the application layer when you need visual workflows, knowledge, and published app APIs. Keep the upstream model configuration explicit and test the exact feature set before promising compatibility. For media automation, follow n8n workflow templates for AI media; for agent-driven terminal generation, see LinkModel CLI.

Sources: Dify model provider plugin documentation, Dify model API interface, LinkModel's first API call, and LinkModel's model reference.