Dokumentation

Dify

Dify erreicht einen externen Endpunkt über ein Plugin — OpenAI-API-compatible — und ein Pflichtfeld, API Base URL. Fülle es aus, und jeder LLM-Knoten in deinen Workflows kann Claude- und GPT-IDs mit einem einzigen Schlüssel ansprechen.

Ein Pflichtfeld — API Base URL im Add-Model-Formular des OpenAI-API-kompatiblen Plugins — richtet jeden LLM-Knoten eines Dify-Arbeitsbereichs auf Kunavo aus.

Model Provider → OpenAI-API-compatible → Add Model

# Integrations → Model Provider → OpenAI-API-compatible → Add Model
Type                          LLM
Model Name                    claude-sonnet-5
Model display name            Kunavo · Claude Sonnet 5
API Key                       sk-kn-...
API Base URL                  https://api.kunavo.com/v1
model name for API endpoint   (leave blank — Model Name is already the id)
Completion mode               Chat
Model context size            1000000
Upper bound for max tokens    (your own ceiling for one reply)
Function Call Type            Tool Call     # defaults to no_call
Vision Support                Support       # only if you will send images
Structured Output             Support       # defaults to not supported

# Model context size is per model, not per endpoint: 1000000 is
# claude-sonnet-5's. The table below carries the rest.

API Base URL enthält das /v1. Das Plugin deklariert endpoint_url unter der Bezeichnung API Base URL, kennzeichnet es neben dem Modellnamen als einziges Pflichtfeld und verwendet den Platzhalter „Base URL, e.g. https://api.openai.com/v1“ — dieser Platzhalter klärt die Frage zum Formular. Die README des Plugins erläutert die Ausnahme, statt ihr zu widersprechen: Bei Nicht-LLM-Modelltypen „fügt das Plugin die API-Version intern hinzu“. Für diese Typen wird der nackte Ursprung verwendet, damit kein doppeltes /v1/v1 entsteht. Kein Kunavo-Modell gehört zu diesen Typen. Du benötigst also nur das /v1-Formular.

Drei Schalter sind standardmäßig deaktiviert und verursachen häufig Probleme. Function Call Type ist standardmäßig auf no_call gesetzt, Structured Output und Vision Support auf „nicht unterstützt“. Ein mit den Standardwerten hinzugefügtes Modell beantwortet eine einfache Chat-Node einwandfrei und scheitert dann in einer Agent-Node oder einem Workflow mit Tool-Aufrufen – das wirkt wie ein Fehler am Endpunkt, ist aber keiner. Legen Sie die Werte fest, wenn Sie das Modell hinzufügen, bevor Sie etwas anderes debuggen.

Kunavo stellt weder ein Embedding-Modell noch ein Text-to-Speech- oder Speech-to-Text-Modell bereit und bietet auch kein Reranking an – dieser Providereintrag deckt also nur Dify's LLM-Slot ab. Eine Wissensdatenbank, die im Modus „High Quality“ indexiert wurde, eine Rerank-Endpoint-URL oder eine Voice-Node behält ihren bisherigen Provider; wenn Sie hier auf einen LLM-Node verweisen, werden diese Aufrufe nicht umgeleitet.

Diese Konfiguration wurde am unten genannten Datum anhand des Dify-Plugin-Eintrags und des Provider-Schemas von Dify selbst geprüft. Kunavo hat keinen Dify-Workspace mit seinem Endpunkt ausgeführt – kein Modell zu einem Live-Workspace hinzugefügt, keinen Workflow ausgeführt und keinen gestreamten Tool-Roundtrip durchgeführt. Eine veröffentlichte Einrichtungsseite ist kein Test. Den curl unten können Sie in zehn Sekunden überprüfen; alles Weitere liegt zwischen Ihnen und Dify.

Noch kein Schlüssel? Erstelle ein Kunavo-Konto, erstelle einen Schlüssel (er beginnt mit sk-kn-) und füge ab $10 Guthaben hinzu – Aufrufe werden aus diesem Guthaben bezahlt, fehlgeschlagene Aufrufe werden nicht berechnet. Das Dashboard öffnet anschließend die Dify-Einrichtung.

Schritt für Schritt

Erstellen Sie unter /app/keys einen Schlüssel und kopieren Sie ihn — er wird nur einmal angezeigt.
Öffnen Sie in Dify Integrations → Model Provider, wählen Sie Install model providers (oder den Marketplace) und installieren Sie OpenAI-API-compatible, veröffentlicht von langgenius. Laut Dify-Dokumentation können nur der Workspace-Eigentümer und Administratoren Provider verwalten.
Klicken Sie auf der Karte dieses Providers auf Add Model. Das Plugin bietet keine vordefinierten Modelle – es ist ein Provider für customizable-model –, daher müssen Sie für jede gewünschte ID einen eigenen Eintrag anlegen.
Füllen Sie das Formular wie oben aus. Type = LLM, Model Name = exakt die Kunavo-ID, API Key = Ihr sk-kn--Schlüssel, API Base URL = https://api.kunavo.com/v1, Completion mode = Chat und Model context size gemäß der Tabelle unten. Legen Sie anschließend Function Call Type fest sowie Structured Output und Vision Support, falls benötigt. Speichern Sie.
Öffnen Sie einen Workflow und wählen Sie das Modell auf dem Node aus, der es verwenden soll – Dify weist Modelle pro Node und nicht pro App zu. Daher können ein Classifier und ein abschließender Writer unterschiedliche IDs und Preise haben. Apps und Nodes, für die nichts ausgewählt wurde, greifen auf Default Models → System Reasoning Model zurück.
Führen Sie einen einzelnen, begrenzten Workflow aus und prüfen Sie die Belastung in Ihrem Kunavo-Konto statt in Dify – siehe den Hinweis zur Kostenanzeige weiter unten.

Abgeglichen mit Dify-Pluginseite zu OpenAI-API-compatible am 21. September 2026. Einstellungen von Drittanbietern können sich ändern; wenn ein Feldname hier nicht mehr mit deiner Ansicht übereinstimmt, ist diese Seite maßgeblich, nicht diese hier.

Dies ist die Kurzfassung. Die vollständige Anleitung – Modellauswahl, Kosten einer tatsächlichen Sitzung und Fehlerszenarien – findest du in der Dify-Leitfaden zur Kostenanzeige.

Vor dem Debugging des Clients prüfen

Eine Anfrage klärt, ob der Fehler am Endpunkt, am Schlüssel oder an der Konfigurationsdatei liegt. Wenn diese Anfrage JSON zurückgibt, funktionieren dieselbe Basis-URL und derselbe Schlüssel in Dify.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Welche Modell-ID in das Feld gehört

Jedes Textmodell ist über eine Modell-ID erreichbar – die aktuelle Liste findest du unter GET /v1/models, den Katalog mit Preisen auf der Modellseite. Die Tarife sind USD pro 1 Mio. Token, Eingabe / Ausgabe.

Modell-ID	Kunavo: Ein- und Ausgabe	Wo es in Dify hineinpasst
`claude-sonnet-5`	$1.40 / $7.00	das Arbeitsmodell für Writer- und Agent-Nodes – Kontextgröße 1000000
`claude-opus-5`	$3.50 / $17.50	der Node, dessen Ausgabe ein Mensch liest, oder ein Plan, bei dem Fehler teuer wären – 1000000
`claude-haiku-4-5`	$0.70 / $3.50	Classifier-, Router- und Extraktions-Nodes, auf denen das tatsächliche Aufrufvolumen liegt – 200000
`gpt-5-6-sol`	$2.00 / $12.00	eine zweite Modellfamilie mit demselben Schlüssel, als eigener Modelle intrag – 1050000
`gpt-5-6-terra`	$0.70 / $4.20	Nodes für lange Dokumente – 1050000

Die Abrechnung erfolgt pro Token aus einem vorausbezahlten Guthaben ohne Monatsgebühr – siehe Abrechnung. Bei wiederholtem Kontext – dem Großteil dessen, was ein Editor oder Chat-Client sendet – verändert Prompt-Caching die Rechnung stärker als die Modellwahl.

Zwei verschiedene Dinge werden als „die Dify-API“ bezeichnet

Auf dieser Seite geht es um eines davon; in Suchergebnissen werden beide ständig vermischt.

Ein Modell in Dify einbinden – darum geht es im Einrichtungsabschnitt oben. Dify ist der Client, Kunavo der Endpunkt, und die eingefügte Zugangsdaten sind ein sk-kn--Schlüssel. Anschließend kann jeder LLM-Node in jeder App dieses Workspaces auf die hinzugefügten IDs zugreifen.
Eine Dify-App aus dem eigenen Code aufrufen – die Service API, die Dify für eine veröffentlichte App bereitstellt, mit einem eigenen, von Dify ausgestellten app--Schlüssel. Dieser Schlüssel stammt von Dify, nicht von uns; Sie können ihn nicht auf einen anderen Endpunkt verweisen. Kunavo ist an diesem Ablauf nicht beteiligt.

Beides kann gleichzeitig in derselben App laufen und tut es meist auch: Ihr Backend ruft die Dify-App mit einem Dify-Schlüssel auf, und die Nodes der App rufen Kunavo mit einem Kunavo-Schlüssel auf. Zwei Schlüssel, zwei Abrechnungen, zwei Stellen, an denen Sie nachsehen müssen, wenn ein 401 auftritt.

Warum Dify für das hinzugefügte Modell keine Kosten anzeigt

Die Modelldateien der Dify-eigenen vordefinierten Modelle enthalten einen Preisblock – Tarife für Ein- und Ausgabe sowie eine Einheit pro Token. Dify multipliziert damit Ihre Token-Anzahlen und zeigt einen Betrag im Protokoll an. Das Schema des OpenAI-API-compatible-Providers enthält dagegen, wie am obigen Datum geprüft, an keiner Stelle ein Feld für Preis, Einheit oder Währung. Daher hat Dify für ein über dieses Plugin hinzugefügtes Modell keinen Tarif, mit dem es multiplizieren kann. Die Geldspalte ist also weder ein Rabatt, den Sie entdeckt haben, noch ein von Ihnen verursachter Fehler: Das entsprechende Feld existiert schlicht nicht. Den tatsächlichen Betrag finden Sie in Ihrer Kunavo-Nutzung; die Token-Anzahlen in Dify sind als Token-Anzahlen zu verstehen.

Einen verwandten Schalter sollten Sie aktiviert lassen: Include Usage in Stream ist standardmäßig eingeschaltet und fordert den Endpunkt auf, die Anzahl der Prompt- und Completion-Tokens im letzten Stream-Chunk anzugeben. Wenn Sie die Option deaktivieren, gehen auch diese Token-Anzahlen verloren.

Wenn Sie Dify selbst hosten

Der Docker-Compose-Stack leitet ausgehende Anfragen über einen ssrf_proxy-Dienst weiter. Daher muss der Endpunkt aus dem Container-Netzwerk erreichbar sein – nicht nur über den Browser auf Ihrem Laptop. Wenn die Konfiguration an einem Ort funktioniert und am anderen in einen Timeout läuft, ist das meist die Ursache. Es handelt sich dann um eine Netzwerkfrage, nicht um ein Problem mit den Zugangsdaten. Der obige curl, ausgeführt innerhalb des Containers, klärt das direkt.

Häufig gestellte Fragen

Wie verbinde ich eine benutzerdefinierte OpenAI-kompatible API mit Dify?

Installieren Sie das OpenAI-API-compatible-Plugin von langgenius über Integrations → Model Provider → Install model providers oder den Dify Marketplace. Klicken Sie auf der zugehörigen Karte auf Add Model und füllen Sie das Formular aus: Type, Model Name, Model display name, API Key, API Base URL, Completion mode und Model context size sowie die Schalter für die Fähigkeiten. Dieser Provider enthält keine vordefinierten Modelle – er ist ein Provider für anpassbare Modelle. Daher benötigt jede gewünschte Modell-ID einen eigenen Eintrag, und jeder Eintrag hat eine eigene Basis-URL und einen eigenen Schlüssel.

Muss die Dify-API-Base-URL mit /v1 enden?

Ja, bei einem Chat-Modell. Das Provider-Schema des Plugins bezeichnet das Feld als API Base URL, markiert es als erforderlich und gibt den Platzhalter „Base URL, e.g. https://api.openai.com/v1“ an. Die dokumentierte Form ist daher die /v1-Basis-URL – für Kunavo: https://api.kunavo.com/v1. Die Basis-URL ohne /v1 ist nur für Modelltypen dokumentiert, bei denen das Plugin die API-Version selbst anhängt; andernfalls entstünde ein doppelter /v1/v1-Pfad. Kunavo bietet keine Modelle dieser Typen an, verwenden Sie daher die Form mit /v1. Fehlt /v1, erhalten Sie einen 404-Fehler statt eines Authentifizierungsfehlers.

Warum kann mein Dify-Agent-Node keine Tools mit dem hinzugefügten Modell verwenden?

Weil Function Call Type bei einem Modell, das über das OpenAI-API-compatible-Plugin hinzugefügt wurde, standardmäßig auf no_call gesetzt ist und Structured Output, Vision Support, Stream function calling sowie Thinking Mode Support standardmäßig auf „nicht unterstützt“ stehen. Das sind Angaben, denen Dify vertraut, statt die Fähigkeiten zu prüfen. Daher wird ein fähiges Modell mit den Standardwerten weiterhin von einem Agent- oder Tool-Node abgewiesen. Öffnen Sie die Modellkonfiguration und setzen Sie Function Call Type auf Tool Call – Function Call ist das ältere Format. Testen Sie es anschließend erneut, bevor Sie von einem Fehler am Endpunkt ausgehen.

Warum zeigt Dify für ein Modell, das über das kompatible Plugin hinzugefügt wurde, keinen Preis an?

Weil das Provider-Schema dieses Plugins keinerlei Preisfelder enthält, die Dify-eigenen vordefinierten Modelldateien hingegen schon. Dify hat somit keinen Tarif pro Token, mit dem es Ihre Token-Anzahlen multiplizieren könnte, und zeigt daher nichts statt einer Schätzung an. Den Betrag entnehmen Sie den Nutzungsdaten des Providers; die Zahlen in Dify sind Token-Anzahlen. Wenn Include Usage in Stream aktiviert bleibt, werden diese Token-Anzahlen weiterhin übermittelt.

Ist das Hinzufügen von Kunavo zu Dify dasselbe, wie eine Dify-App als API bereitzustellen?

Nein, die Abläufe gehen in entgegengesetzte Richtungen. Wenn Sie Kunavo hinzufügen, ist Dify der Client: Die Nodes von Dify senden Anfragen an einen Endpunkt, den Sie mit einem Kunavo-Schlüssel konfiguriert haben. Über Dify's Service API ist Ihr Code der Client: Er ruft eine veröffentlichte Dify-App mit einem von Dify ausgestellten Schlüssel auf; unsere Basis-URL gehört nicht in diesen Ablauf. Häufig führt eine einzelne App beides gleichzeitig aus. Deshalb sollten Sie bei einem 401 zuerst herausfinden, welcher Schlüssel betroffen ist.

Hat Kunavo diese Einrichtung in Dify getestet?

Nein. Am 21. September 2026 wurden Dify-eigene Materialien geprüft – der Plugin-Eintrag im Dify Marketplace und das Provider-Schema im offiziellen Plugin-Repository von Dify. Daher stammen die hier genannten Feldnamen, ihre Reihenfolge, die Pflichtfeldkennzeichnungen und Standardwerte. Niemand hat ein Kunavo-Modell zu einem Live-Dify-Workspace hinzugefügt und einen Workflow damit ausgeführt. Daher werden keine Aussagen zu Streaming, Tool-Roundtrips oder lang laufenden Agent-Schleifen in diesem Client gemacht. Eine Sache können Sie selbstständig prüfen: ob Endpunkt und Schlüssel funktionieren. Der curl-Aufruf auf dieser Seite erledigt das.