Documentation

Dify

Dify accède à un point de terminaison externe au moyen d’un seul module — OpenAI-API-compatible — et d’un champ obligatoire, API Base URL. Renseignez-le pour que chaque nœud LLM de vos flux de travail puisse appeler des identifiants Claude et GPT avec une seule clé.

Un seul champ obligatoire — API Base URL, dans le formulaire Add Model du plugin compatible avec l’API OpenAI — dirige chaque nœud LLM d’un espace Dify vers Kunavo.

Fournisseur de modèles → Compatible avec l’API OpenAI → Ajouter un modèle

# 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 conserve le /v1. Le module déclare endpoint_url sous le libellé API Base URL, le présente comme l’unique champ obligatoire à côté du nom du modèle et l’accompagne de l’indication « Base URL, e.g. https://api.openai.com/v1 » — c’est cette indication qui clarifie le formulaire. Le fichier README du module explique l’exception, sans contredire cette règle : pour les types de modèles autres que LLM, le module « ajoute la version de l’API en interne », qui doit donc recevoir une origine sans chemin afin d’éviter la répétition de /v1/v1. Aucun modèle Kunavo n’appartient à ces types ; le formulaire /v1 est donc le seul dont vous avez besoin.

Trois options sont désactivées par défaut, et c’est généralement là que se trouve le problème. Function Call Type est réglé sur no_call, et Structured Output ainsi que Vision Support sur « non pris en charge ». Avec ces valeurs par défaut, un modèle ajouté répond parfaitement dans un simple nœud de chat, puis échoue dans un nœud Agent ou un workflow utilisant des outils — ce qui ressemble à un problème de point de terminaison, alors que ce n’en est pas un. Réglez ces options lors de l’ajout du modèle, avant de chercher ailleurs.

Kunavo ne propose aucun modèle d’embeddings, de synthèse vocale ou de transcription de la parole, ni de reclassement — cette configuration de fournisseur ne couvre donc que l’emplacement LLM de Dify. Une base de connaissances indexée en mode Haute qualité, une URL de point de terminaison de reclassement ou un nœud vocal conserve son fournisseur actuel ; configurer un nœud LLM ici ne redirige pas ces appels.

Cette configuration a été relevée dans la liste des extensions et le schéma de fournisseur de Dify à la date indiquée ci-dessous. Kunavo n’a pas exécuté d’espace de travail Dify avec son point de terminaison : aucun modèle n’a été ajouté à un espace de travail actif, aucun workflow n’a été exécuté et aucun aller-retour d’outil en mode streaming n’a été effectué. Une page de configuration publiée ne constitue pas un test. Le curl ci-dessous est le point que vous pouvez vérifier en dix secondes ; tout le reste se joue entre vous et Dify.

Pas encore de clé ? Créez un compte Kunavo, créez une clé (elle commence par sk-kn-) et ajoutez un crédit à partir de 10 $ — les appels sont payés sur ce solde et les appels échoués ne sont pas facturés. Le tableau de bord s’ouvre ensuite sur la configuration Dify.

Étape par étape

Créez une clé sur /app/keys et copiez-la — elle n’est affichée qu’une seule fois.
Dans Dify, ouvrez Intégrations → Fournisseur de modèles, parcourez Installer des fournisseurs de modèles (ou la Marketplace), puis installez OpenAI-API-compatible, publié par langgenius. La documentation de Dify précise que seuls le propriétaire de l’espace de travail et les administrateurs peuvent gérer les fournisseurs.
Cliquez sur Ajouter un modèle sur la fiche de ce fournisseur. L’extension ne propose aucun modèle prédéfini : c’est un fournisseur customizable-model ; chaque identifiant souhaité doit donc faire l’objet d’une entrée distincte.
Remplissez le formulaire comme ci-dessus. Type = LLM, Nom du modèle = l’identifiant Kunavo exact, Clé API = votre clé sk-kn-, URL de base de l’API = https://api.kunavo.com/v1, Mode de complétion = Chat et Taille du contexte du modèle = la valeur du tableau ci-dessous. Réglez ensuite Type d’appel de fonction, puis Sortie structurée et Prise en charge de la vision si nécessaire. Enregistrez.
Ouvrez un workflow et choisissez le modèle sur le nœud qui doit l’utiliser — Dify attribue les modèles par nœud, et non par application ; un classificateur et un rédacteur final peuvent donc utiliser des identifiants et des tarifs différents. Les applications et les nœuds pour lesquels aucun modèle n’est choisi utilisent Modèles par défaut → Modèle de raisonnement système.
Exécutez un workflow limité, puis consultez le montant facturé dans votre compte Kunavo plutôt que dans Dify — voir la remarque sur l’affichage des coûts ci-dessous.

Vérifié avec La page de l’extension OpenAI-API-compatible de Dify le 21 septembre 2026. Les paramètres tiers évoluent ; si le nom d’un champ ne correspond plus à ce que vous voyez ici, cette page fait autorité, pas celle-ci.

Voici la version courte. Le guide complet — choix du modèle, coût d’une session réelle et modes d’échec — se trouve dans le guide des coûts de Dify.

Vérifiez avant de déboguer le client

Une requête suffit à déterminer si l’échec vient de l’endpoint, de la clé ou du fichier de configuration. Si cette requête renvoie du JSON, la même URL de base et la même clé fonctionnent dans 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-..."

Quel identifiant de modèle saisir dans le champ

Tous les modèles textuels sont accessibles sous forme d’identifiant de modèle — la liste à jour se trouve sur GET /v1/models, et le catalogue avec les prix sur la page des modèles. Les tarifs sont en USD par million de tokens, entrée / sortie.

Identifiant du modèle	Entrée / sortie sur Kunavo	Où cela s’intègre dans Dify
`claude-sonnet-5`	$1.40 / $7.00	le modèle de travail pour les nœuds Writer et Agent — taille du contexte : 1000000
`claude-opus-5`	$3.50 / $17.50	le nœud dont la sortie est lue par une personne, ou un plan qu’il serait coûteux de mal établir — 1000000
`claude-haiku-4-5`	$0.70 / $3.50	les nœuds de classification, de routage et d’extraction, où se concentre réellement le volume d’appels — 200000
`gpt-5-6-sol`	$2.00 / $12.00	une deuxième famille sur la même clé, comme entrée de modèle distincte — 1050000
`gpt-5-6-terra`	$0.70 / $4.20	les nœuds traitant de longs documents — 1050000

La facturation se fait au token à partir d’un solde prépayé, sans frais mensuels — consultez la facturation. Avec un contexte répété — ce qu’envoient la plupart des éditeurs et clients de chat — la mise en cache des prompts influe davantage sur la facture que le choix du modèle.

Deux choses différentes sont appelées « l’API Dify »

Cette page porte sur l’une d’elles, et les résultats de recherche les mélangent constamment.

Ajouter un modèle à Dify — c’est ce que fait le bloc de configuration ci-dessus. Dify est le client, Kunavo est le point de terminaison et l’identifiant que vous collez est une clé sk-kn-. Tous les nœuds LLM de toutes les applications de cet espace de travail peuvent alors utiliser les identifiants que vous avez ajoutés.
Appeler une application Dify depuis votre propre code — il s’agit de l’API de service que Dify expose pour une application publiée, avec sa propre clé app- délivrée par Dify. Cette clé appartient à Dify, pas à Kunavo, et il n’est pas possible de la diriger ailleurs. Kunavo n’intervient pas dans ce sens de communication.

Ces deux usages peuvent fonctionner simultanément sur la même application, et c’est généralement le cas : votre serveur appelle l’application Dify avec une clé Dify, et les nœuds de l’application appellent Kunavo avec une clé Kunavo. Deux clés, deux factures et deux endroits à vérifier en cas d’erreur 401.

Pourquoi Dify n’affiche aucun coût pour le modèle que vous avez ajouté

Les fichiers de modèles prédéfinis de Dify incluent un bloc tarifaire — tarifs d’entrée et de sortie, ainsi qu’une unité par jeton — que Dify utilise pour multiplier vos nombres de jetons et afficher un montant dans le journal. Le schéma du fournisseur OpenAI-API-compatible ne déclare aucun champ de prix, d’unité ou de devise ; cela a été vérifié à la date indiquée ci-dessus. Ainsi, pour un modèle ajouté via cette extension, Dify n’a aucun tarif à appliquer. Le montant absent n’est ni une remise que vous auriez trouvée ni un bogue que vous auriez provoqué : le champ n’existe pas. Consultez le montant réel dans votre consommation Kunavo, et considérez les nombres de jetons affichés par Dify comme des nombres de jetons.

Il vaut mieux laisser activée une option connexe : Inclure l’utilisation dans le flux est activée par défaut et demande au point de terminaison d’inclure les nombres de jetons de l’invite et de la complétion dans le dernier bloc du flux. La désactiver vous fait aussi perdre ces nombres de jetons.

Si vous hébergez Dify vous-même

La pile Docker Compose achemine les requêtes sortantes par un service ssrf_proxy ; le point de terminaison doit donc être joignable depuis le réseau des conteneurs, et pas seulement depuis le navigateur de votre ordinateur portable. Si la configuration fonctionne à un endroit et expire à l’autre, c’est généralement la cause : il s’agit d’un problème réseau, pas d’identifiants. Le curl ci-dessus, exécuté depuis l’intérieur du conteneur, permet de le vérifier directement.

Questions fréquentes

Comment connecter une API OpenAI compatible personnalisée à Dify ?

Installez l’extension OpenAI-API-compatible, publiée par langgenius, depuis Intégrations → Fournisseur de modèles → Installer des fournisseurs de modèles ou depuis la Dify Marketplace. Cliquez sur Ajouter un modèle sur sa fiche et remplissez le formulaire : Type, Nom du modèle, Nom d’affichage du modèle, Clé API, URL de base de l’API, Mode de complétion et Taille du contexte du modèle, ainsi que les options de capacités. Ce fournisseur ne propose aucun modèle prédéfini : c’est un fournisseur de modèles personnalisables. Chaque identifiant de modèle souhaité doit donc avoir sa propre entrée, avec sa propre URL de base et sa propre clé.

L’URL de base de l’API Dify doit-elle se terminer par /v1 ?

Oui pour un modèle de chat. Le schéma du fournisseur de l’extension nomme le champ « API Base URL », le rend obligatoire et indique comme exemple « Base URL, e.g. https://api.openai.com/v1 » : la racine /v1 est donc la forme documentée — pour Kunavo, https://api.kunavo.com/v1. L’origine seule est documentée uniquement pour les types de modèles auxquels l’extension ajoute elle-même la version de l’API, ce qui produirait sinon un chemin /v1/v1 en double. Kunavo ne propose aucun modèle de ces types ; utilisez donc la forme /v1. Sans /v1, vous obtiendrez une erreur 404 plutôt qu’une erreur d’authentification.

Pourquoi mon nœud Agent Dify ne peut-il pas utiliser les outils avec le modèle que j’ai ajouté ?

Parce que, pour un modèle ajouté via l’extension OpenAI-API-compatible, le type d’appel de fonction est défini par défaut sur no_call, et les options Sortie structurée, Prise en charge de la vision, Appels de fonction en streaming et Prise en charge du mode Thinking sont toutes définies sur « non pris en charge ». Dify considère ces valeurs comme des déclarations plutôt que comme des résultats de vérifications ; même un modèle compatible ajouté avec les valeurs par défaut sera donc refusé par un nœud Agent ou utilisant des outils. Ouvrez la configuration du modèle et définissez le type d’appel de fonction sur Tool Call — Function Call est l’ancien format — puis effectuez un nouveau test avant de conclure que le point de terminaison est en cause.

Pourquoi Dify n’affiche-t-il aucun prix pour un modèle ajouté via l’extension compatible ?

Parce que le schéma du fournisseur de cette extension ne comporte aucun champ tarifaire, contrairement aux fichiers de modèles prédéfinis de Dify. Dify n’a donc aucun tarif par jeton à appliquer au nombre de jetons et n’affiche rien plutôt qu’une estimation. Consultez le montant dans les relevés d’utilisation du fournisseur et considérez les chiffres de Dify comme des nombres de jetons. Laisser l’option Inclure l’utilisation dans le flux activée permet de recevoir ces nombres de jetons.

Ajouter Kunavo à Dify revient-il à exposer une application Dify sous forme d’API ?

Non, les deux fonctionnent dans des sens opposés. Ajouter Kunavo fait de Dify le client : les nœuds de Dify envoient des requêtes à un point de terminaison configuré avec une clé Kunavo. L’API de service de Dify fait de votre code le client : il appelle une application Dify publiée avec une clé délivrée par Dify, et aucune de nos URL de base n’intervient dans ce parcours. Une même application fait souvent les deux à la fois ; en cas d’erreur 401, il est donc utile de commencer par vérifier à quelle clé elle se rapporte.

Kunavo a-t-il testé cette configuration dans Dify ?

Non. La vérification effectuée le 21 septembre 2026 porte sur les propres ressources de Dify : la liste de l’extension dans la Dify Marketplace et le schéma du fournisseur dans le dépôt officiel des extensions de Dify. C’est là que figurent les noms et l’ordre des champs, les indicateurs de champs obligatoires et les valeurs par défaut cités ici. Personne n’a ajouté de modèle Kunavo à un espace de travail Dify actif ni exécuté un workflow avec celui-ci ; aucune affirmation n’est donc faite au sujet du streaming, des allers-retours d’outils ou des boucles d’agents de longue durée dans ce client. Le seul point que vous pouvez vérifier indépendamment est le fonctionnement du point de terminaison et de la clé ; la commande curl de cette page permet de le faire.