OpenRouter

Une seule clé pour des centaines de modèles de tous les éditeurs. La clé se crée sur openrouter.ai/keys.

Connectez une clé d’API OpenRouter pour appeler, avec une seule clé, des modèles de nombreux éditeurs via OpenRouter. La connexion est réglée une fois pour toute l’organisation par un administrateur ; les membres l’emploient ensuite depuis l’éditeur de workflow sans jamais voir la clé.

Les requêtes partent vers l’API d’OpenRouter, à l’adresse https://openrouter.ai/api/v1. L’adresse est fixe et ne se modifie pas. Les identifiants de modèle OpenRouter s’écrivent éditeur/modèle.

En bref

• Identifiant : openrouter
• Famille : Fournisseur d’IA
• Configurée par : Un administrateur, pour toute l’organisation
• Authentification : Clé d’API du fournisseur
• Type de credential : llm_provider

Avant de commencer

• Un compte OpenRouter crédité, pour que la clé puisse effectuer des appels payants.
• Un compte administrateur sur Mankomail : seuls les administrateurs gèrent les connexions d’IA.
• Une instance dotée d’une clé de chiffrement (ENCRYPTION_KEY), indispensable pour stocker un secret.

Qui la configure

Les connexions d’IA appartiennent à l’organisation, pas à un membre. Seul un administrateur peut les créer, les modifier, les tester ou les supprimer, depuis la page Connexions. Un membre voit la section Intelligence artificielle avec la mention « Les fournisseurs d’IA sont configurés une fois pour toute l’organisation, par un administrateur. » Il ne voit jamais de clé : dans l’éditeur de workflow, il choisit seulement une connexion par son libellé, et un modèle.

La clé est chiffrée avant d’être enregistrée et n’est plus jamais réaffichée : l’écran n’en montre que les quatre derniers caractères (« Clé enregistrée (se termine par …) »). Enregistrer une clé exige la clé de chiffrement de l’instance (ENCRYPTION_KEY, voir Variables d’environnement) ; sans elle, l’enregistrement échoue avec llm.encryption_disabled.

Créer une clé d’API chez OpenRouter

1. Connectez-vous à OpenRouter et ouvrez la page des clés : https://openrouter.ai/keys. Dans Mankomail, le lien Où trouver cette clé ? de la carte OpenRouter ouvre cette page.
2. Créez une nouvelle clé. Nommez-la d’après votre instance pour la reconnaître plus tard. Si vous fixez une limite de crédit sur la clé, OpenRouter refuse les appels au-delà.
3. Copiez la clé tout de suite et gardez-la jusqu’à la coller dans Mankomail : elle n’est plus réaffichée en entier.

Ajouter la connexion

1. Ouvrez Connexions dans la navigation principale.
2. Dans la section Intelligence artificielle, repérez la ligne OpenRouter et cliquez sur Configurer. (Vous pouvez aussi cliquer sur Ajouter dans cette section et choisir OpenRouter dans le catalogue.)
3. Libellé : pré-rempli avec le nom du fournisseur. Changez-le si vous comptez détenir plusieurs clés (« Prod », « Client X »).
4. Clé d’API : collez la clé. Elle est obligatoire pour une nouvelle connexion et n’est jamais réaffichée.
5. (Aucune URL de serveur à saisir : les requêtes partent toujours vers l’adresse officielle du fournisseur, qui ne se modifie pas.)
6. Modèles activés : voir la section sur les modèles activés ci-dessous.
7. Cliquez sur Enregistrer, puis sur Tester.

Tester et Voir les modèles disponibles ne sont proposés qu’une fois la connexion enregistrée. Quand vous modifiez une connexion enregistrée, laissez le champ Clé d’API vide pour conserver la clé ; n’en collez une que pour la remplacer.

Choisir les modèles activés

Mankomail n’a pas de catalogue de modèles intégré pour OpenRouter : les identifiants changent trop souvent pour être écrits à l’avance. Vous les choisissez parmi ce que votre propre compte ou serveur expose :

1. Enregistrez d’abord la connexion (la carte indique « Ce fournisseur n’a pas de catalogue figé. Enregistrez la configuration, puis demandez-lui ses modèles disponibles. »).
2. Cliquez sur Voir les modèles disponibles. La carte affiche « n modèles rendus par le fournisseur. » et les liste.
3. Cochez les modèles que vos workflows peuvent employer, puis cliquez sur Enregistrer.

Les modèles cochés deviennent la liste d’autorisation de cette connexion :

• un nœud qui nomme un autre modèle échoue avec llm.model_not_allowed, et l’éditeur le signale dans le nœud fournisseur ;
• quand un nœud ne nomme aucun modèle, Mankomail emploie le premier modèle activé — le premier coché (il n’y a pas de modèle recommandé par usage pour OpenRouter) ;
• le bouton Tester a besoin d’au moins un modèle activé pour tester (sinon llm.no_default_model).

Les modèles restés cochés restent listés même si une liste ultérieure ne les rend plus : un trou passager chez le fournisseur ne les décoche jamais en silence.

OpenRouter est le seul fournisseur dont la liste comporte des tarifs : la carte les affiche par million de tokens à côté de chaque modèle. Ces tarifs aident à choisir ; ils ne servent pas à calculer les coûts affichés dans Usage et coûts de l’IA (voir Coûts et données).

Tester la connexion

Tester envoie une vraie requête minimale (« ping », 5 tokens de sortie au plus) avec la clé de la connexion affichée dans la carte. Il prouve que la clé peut compléter, pas seulement qu’elle est acceptée. Le test emploie le premier modèle activé. En cas de succès, la carte affiche « Connexion établie avec modèle en n ms. » ; sinon « Le test a échoué : » suivi de la raison (voir Erreurs fréquentes).

Voir les modèles disponibles est une autre vérification : elle demande au fournisseur la liste des modèles que cette clé voit. Une liste obtenue prouve que la clé est lue, pas qu’elle peut compléter — un point d’accès de métadonnées peut répondre alors que l’inférence est refusée (plus de crédits, modèle non autorisé sur le compte). La liste est gardée dix minutes, par connexion ; enregistrer ou supprimer une connexion du fournisseur l’efface.

Quel fournisseur et quel modèle un nœud IA utilise

Les nœuds IA (par exemple Catégoriser, Extraire, Rédiger (IA), Résumer et Instruction libre (IA)) appellent chacun le modèle avec un usage : classer, extraire, rédiger ou usage général. L’analyse de boîte a son propre usage. Pour chaque appel, le fournisseur et le modèle se résolvent dans cet ordre — la première règle applicable l’emporte :

1. Un nœud fournisseur câblé sur le port model du nœud — par exemple un nœud OpenRouter. Ses champs Connexion et Modèle s’appliquent ; un Modèle vide signifie « le modèle recommandé pour cet usage chez ce fournisseur ».
2. Le choix de l’administrateur pour cet usage, dans le panneau Quelle IA pour quel usage de la page Connexions.
3. Le défaut de l’instance — la première ligne de ce panneau, « Par défaut (tous les usages non réglés) ». Elle peut nommer un fournisseur seul (« … · modèle recommandé ») ou un fournisseur et un modèle.
4. Le premier fournisseur configuré, par date de configuration (sans préférence de marque), avec le modèle recommandé pour l’usage.

Un choix devenu inutilisable (clé retirée, modèle décoché) est ignoré au profit de la règle suivante, et le panneau affiche « Choix inapplicable » à côté. Sous chaque ligne, « Utilise : fournisseur · modèle » montre ce que le prochain appel obtiendra réellement. Quand rien ne peut servir un usage, la ligne affiche « Aucun » et les nœuds échouent avec llm.no_provider_configured ou llm.no_default_model.

Dans le panneau Quelle IA pour quel usage, les lignes par usage ne proposent que les modèles des fournisseurs dotés d’un catalogue intégré. Pour tout envoyer chez OpenRouter, choisissez « OpenRouter · modèle recommandé » sur la première ligne, « Par défaut (tous les usages non réglés) » : chaque usage non réglé emploie alors le premier modèle activé sur la connexion OpenRouter par défaut. Pour employer un modèle OpenRouter précis sur un nœud, câblez un nœud fournisseur et nommez le modèle.

Plusieurs clés pour un même fournisseur

Une organisation peut détenir plusieurs connexions OpenRouter — par exemple une clé de production et une clé refacturée à un client. Chaque connexion a son Libellé, sa clé et sa liste de modèles activés.

• Pour en ajouter une, ouvrez la carte du fournisseur et cliquez sur Ajouter une connexion. Le libellé est obligatoire et doit être unique (sinon : « Ce libellé est déjà utilisé par une autre connexion. »).
• La première connexion d’un fournisseur devient automatiquement sa connexion Par défaut. À partir de deux, la carte les liste ; cliquez sur Mettre par défaut sur une autre pour déplacer le défaut.
• La connexion par défaut est celle qu’emploie tout ce qui n’en nomme aucune : les défauts par usage, le défaut de l’instance, l’analyse de boîte, et tout nœud fournisseur dont le champ Connexion reste sur « Par défaut (…) ».
• Pour imposer une clé précise à un nœud, choisissez-la dans le champ Connexion du nœud fournisseur OpenRouter.

Pour supprimer une connexion, sélectionnez-la, cliquez sur Supprimer, puis sur Confirmer la suppression. Deux refus protègent les workflows en service :

• si des workflows publiés référencent la connexion, la carte affiche « Des workflows publiés utilisent cette connexion ; confirmez pour la supprimer quand même. » et les nomme. Confirmer une nouvelle fois la supprime, et ces nœuds échoueront alors avec llm.connection_not_found jusqu’à ce que vous choisissiez une autre connexion ;
• la connexion par défaut ne se supprime pas tant que le fournisseur en a d’autres (llm.connection_is_default) : mettez-en d’abord une autre par défaut. Supprimer la dernière connexion retire le fournisseur de l’instance.

Utiliser OpenRouter dans un workflow

Pour qu’un nœud IA travaille avec OpenRouter quels que soient les défauts de l’instance, câblez-lui un nœud fournisseur :

1. Ajoutez le nœud OpenRouter sur le canevas (fiche du nœud).
2. Tirez un lien de ce nœud vers le port model du nœud IA.
3. Dans Connexion, gardez « Par défaut (…) » pour employer la connexion par défaut du fournisseur, ou choisissez une autre connexion par son libellé.
4. Dans Modèle, laissez le champ vide pour employer le modèle recommandé pour l’usage du nœud, ou saisissez un identifiant de modèle. L’éditeur propose les modèles activés sur la connexion choisie et prévient quand l’identifiant n’y est pas activé (« Ce modèle n’est pas activé sur la connexion choisie : l’exécution le refusera. »).
5. Température est facultative ; laissez-la vide pour garder le réglage du fournisseur.

Le nœud fournisseur n’est pas une étape : il ne s’exécute jamais seul, ne porte aucune clé, et indique seulement au nœud IA câblé quel fournisseur, quelle connexion et quel modèle employer. Un même nœud fournisseur peut alimenter plusieurs nœuds IA.

Si la connexion choisie a été supprimée, l’exécution échoue avec llm.connection_not_found — elle ne se rabat jamais sur une autre clé. Si la connexion appartient à un autre fournisseur, l’exécution échoue avec llm.connection_provider_mismatch.

Dans le champ Modèle d’un nœud fournisseur OpenRouter, écrivez l’identifiant OpenRouter complet, éditeur/modèle, exactement comme il apparaît dans la liste des modèles activés.

En-têtes d’attribution

OpenRouter accepte deux en-têtes d’attribution facultatifs qui font apparaître une application dans ses classements publics. Ils n’ont aucun effet sur la facturation ni sur le routage. Mankomail les envoie avec les valeurs de votre instance, jamais celles de l’éditeur du logiciel :

• HTTP-Referer : l’adresse de l’instance, PUBLIC_BASE_URL. Envoyé seulement quand la variable est explicitement définie.
• X-Title : le nom de l’instance, BRAND_NAME.

Les deux en-têtes accompagnent les complétions comme la liste des modèles. Voir Variables d’environnement.

Sortie structurée

Quand un nœud attend une réponse structurée, Mankomail envoie le schéma JSON attendu sous forme de format de réponse json_schema non strict, qu’OpenRouter transmet au modèle choisi. La prise en charge dépend de ce modèle. Si la réponse reste illisible, Mankomail tente une réparation ; au-delà, l’étape échoue avec llm.invalid_json.

Pendant un essai

Un essai appelle le vrai modèle : vous voyez la catégorie, l’extraction ou le brouillon que le modèle produit réellement. Seules les actions irréversibles (envoi, déplacement, requêtes HTTP) sont simulées. Un appel d’essai coûte autant qu’en production et apparaît dans Usage et coûts de l’IA.

La sortie n’est fabriquée que si l’instance n’a aucun fournisseur utilisable — aucune connexion d’IA, ou un nœud fournisseur câblé vers un fournisseur non configuré. L’éditeur affiche alors « IA sautée : aucune clé sur cette instance », et l’effet de l’étape indique qu’aucun modèle n’aurait été appelé faute de fournisseur d’IA configuré. Quand un modèle peut être résolu, l’effet nomme le modèle que l’exécution emploierait réellement. La sortie fabriquée est la plus petite valeur conforme à la forme attendue : la première catégorie à vrai, les champs texte à simulated.

Les refus de politique ne sont pas masqués pendant un essai : un modèle non activé (llm.model_not_allowed), une connexion supprimée (llm.connection_not_found), un quota épuisé ou une panne du fournisseur font échouer l’essai exactement comme en production.

Coûts et données

Les appels sont comptés dans Usage et coûts de l’IA (appels et tokens, par jour, fournisseur, modèle et origine). La colonne de coût reste vide pour les modèles dont le tarif ne figure pas dans le catalogue intégré : un tarif inconnu s’affiche comme inconnu, jamais comme zéro.

Pour OpenRouter, suivez les dépenses dans votre compte OpenRouter. Le contenu des e-mails traités par un nœud IA est envoyé à OpenRouter, puis à l’éditeur du modèle choisi.

Erreurs fréquentes

Les erreurs sont signalées par un code stable, que l’interface traduit. Sur la page Connexions, la raison d’un Tester ou d’une liste de modèles en échec s’affiche dans la carte du fournisseur, et les autres refus (enregistrement, suppression) dans un bandeau en haut de la section ; pendant une exécution, le code figure dans l’erreur de l’étape. Voir aussi Gestion des erreurs et rejeu et la référence des codes d’erreur.

Code	Cause	Que faire
llm.invalid_api_key	Le fournisseur a refusé la clé (HTTP 401 ou 403) : révoquée, mal copiée ou sans accès.	Créez une nouvelle clé chez le fournisseur, collez-la dans la carte, Enregistrer, puis Tester. L’exécution n’est pas retentée.
llm.rate_limited	Le fournisseur a répondu 429, 502, 503, 504 ou 529 (quota, crédits ou surcharge), ou la limite propre à l’instance (LLM_MAX_REQUESTS_PER_MINUTE, 60 appels par minute et par fournisseur par défaut) est atteinte.	Rien à faire pour un pic passager : l’étape est différée puis reprise sans consommer de tentative. Si cela dure, vérifiez votre quota ou vos crédits chez le fournisseur.
llm.timeout	Le fournisseur n’a pas répondu dans le délai LLM_REQUEST_TIMEOUT_MS (120 secondes par défaut).	Retenté automatiquement. Pour de longues rédactions sur un serveur lent, relevez le délai.
llm.provider_unavailable	Erreur réseau, ou autre réponse 5xx du fournisseur.	Retenté automatiquement avec un délai croissant. Vérifiez l’état du fournisseur si cela dure.
llm.provider_rejected	Le fournisseur a refusé la requête elle-même (HTTP 400, 404 ou 422) : identifiant de modèle inconnu, entrée trop longue, schéma refusé.	Vérifiez l’identifiant du modèle dans le nœud fournisseur ou les modèles activés. L’exécution n’est pas retentée.
llm.model_not_allowed	Le modèle nommé par le nœud n’est pas activé sur la connexion employée.	Cochez le modèle dans la carte, ou nommez un modèle activé dans le nœud fournisseur.
llm.no_default_model	Aucun modèle ne peut être choisi pour cet usage : pas de modèle recommandé chez ce fournisseur et aucun modèle activé. Également renvoyé par Tester quand il n’y a aucun modèle avec lequel tester.	Activez au moins un modèle sur la connexion, ou nommez le modèle dans le nœud fournisseur.
llm.no_provider_configured	Aucune connexion d’IA n’existe sur l’instance.	Un administrateur ajoute une connexion sur la page Connexions.
llm.provider_not_configured	Un nœud fournisseur est câblé vers un fournisseur sans connexion, ou le premier enregistrement est parti sans clé.	Configurez le fournisseur, ou câblez un nœud fournisseur d’un fournisseur configuré.
llm.connection_not_found	La connexion choisie dans le nœud fournisseur a été supprimée.	Choisissez une autre connexion dans le champ Connexion du nœud, puis republiez.
llm.connection_provider_mismatch	La connexion choisie dans le nœud appartient à un autre fournisseur que le nœud.	Choisissez une connexion du bon fournisseur, ou remplacez le nœud fournisseur.
llm.invalid_json	Le modèle a rendu un JSON inexploitable pour une sortie structurée, même après une réparation automatique.	Relancez, ou employez un modèle plus capable pour ce nœud.
llm.output_truncated	La réponse structurée a été coupée par le plafond de tokens de sortie.	Demandez moins, ou relevez LLM_DEFAULT_MAX_OUTPUT_TOKENS (4 096 par défaut).
llm.empty_output	Un modèle à raisonnement a consacré tout son budget au raisonnement et n’a rien écrit.	Relancez, ou employez un autre modèle pour ce nœud.
llm.content_refused	Le modèle a refusé de répondre à ce contenu.	Revoyez la consigne ou l’entrée. L’exécution n’est pas retentée.
llm.connection_in_use	Suppression refusée : des workflows publiés utilisent la connexion (leurs noms sont listés).	Changez d’abord leur connexion, ou confirmez la suppression une seconde fois.
llm.connection_is_default	Suppression refusée : c’est la connexion par défaut du fournisseur et d’autres existent.	Cliquez sur Mettre par défaut sur une autre connexion, puis supprimez celle-ci.
llm.connection_label_taken	Une autre connexion utilise déjà ce libellé.	Choisissez un autre libellé.
llm.encryption_disabled	L’instance n’a pas de ENCRYPTION_KEY : elle ne peut stocker aucun secret.	Définissez la variable et redémarrez l’instance.
llm.discovery_failed	La liste des modèles n’a pas pu être lue : réponse inattendue du fournisseur.	Vérifiez la clé, l’URL et l’état du fournisseur, puis relancez Voir les modèles disponibles.

Nœuds qui utilisent cette connexion

• OpenRouter — llm.openrouter