n8n

n8n est un outil d’automatisation de workflows. SpicyAPI lui apporte des modèles d’image, de vidéo, d’audio et de chat derrière une seule API et un seul solde prépayé. Il existe trois façons de les connecter, et elles peuvent être combinées dans un même workflow :

Les trois utilisent le même compte, la même clé, les mêmes modèles et les mêmes prix. Pour les médias, le nœud et les modèles HTTP Request vérifient le prix avant l’envoi. Renvoyer la même requête média acceptée avec son Idempotency-Key d’origine renvoie la tâche existante.

Pour démarrer un workflow d’images, consultez le guide des workflows d’images NSFW avec n8n : choix du modèle, retouche d’une référence, premier portrait et exemples de coût. Les étapes ci-dessous permettent de le connecter à votre instance n8n.

Avant de commencer

• Une clé API. Créez-en une dans la console ; elle commence par sk-spicy-. Voir Préparer votre compte si vous n’avez pas encore de compte.
• Un solde. Ajoutez des fonds dans Billing de la console avant votre première génération. Vos workflows n8n, Studio et l’API partagent le même solde de compte. Voir Facturation pour le règlement des appels.
• Une clé par automatisation. Les workflows peuvent s’exécuter bien plus souvent qu’une personne ne clique. Créez une clé dédiée à n8n et définissez-lui un plafond de dépense quotidien ou mensuel, pour qu’une erreur dans une boucle ait une limite. Voir Authentification.
• n8n peut joindre api.spicyapi.ai. Les appels sont effectués par le serveur n8n, pas par votre navigateur.

Option 1 : le nœud communautaire SpicyAPI

Le nœud est open source (MIT) sur github.com/spicyapi-ai/n8n-nodes-spicyapi et publié sur npm sous le nom @spicyapi/n8n-nodes-spicyapi. Il n’a aucune dépendance d’exécution et ne communique qu’avec api.spicyapi.ai.

D’autres paquets npm portent des noms similaires mais appartiennent à des services sans rapport. Celui-ci est le paquet nommé @spicyapi/n8n-nodes-spicyapi, et son identifiant s’appelle SpicyAPI (spicyapi.ai) API.

Installation

cd ~/.n8n/nodes
npm install @spicyapi/n8n-nodes-spicyapi

Opérations

Générer des images, de la vidéo et de l’audio

Les trois opérations Generate partagent les mêmes champs :

1. Model. Choisissez dans la liste, qui affiche les modèles de la ressource sélectionnée avec leur prix de départ, ou saisissez un identifiant de modèle à la main. Chaque modèle et ses paramètres sont listés sur spicyapi.ai/models.
2. Prompt. L’entrée de texte principale du modèle. Pour les modèles vocaux, c’est le texte à prononcer. Laissez-le vide pour les modèles qui n’ont pas de prompt, comme les outils d’agrandissement.
3. Media Inputs. Les images, vidéos ou fichiers audio que le modèle lit. Choisissez le champ (la liste affiche les entrées de fichier du modèle sélectionné), puis utilisez un champ binaire du nœud précédent ou une URL. Les fichiers binaires sont envoyés automatiquement à SpicyAPI. Ajoutez plusieurs entrées pour le même champ afin de remplir les champs de type liste, comme les images de référence.
4. Model Parameters. Un formulaire généré à partir du schéma du modèle sélectionné : format d’image, résolution, durée, seed, etc. Les champs laissés vides ne sont pas envoyés : le modèle utilise alors sa propre valeur par défaut.
5. Additional Parameters (JSON). Tout autre champ d’entrée sous forme d’objet JSON. Ils remplacent les champs ci-dessus.

La sortie contient l’enregistrement de la tâche (taskId, state, cost, settled, output). Avec Download Output activé, ce qui est le cas par défaut, les fichiers sont aussi joints comme données binaires dans data, data_1, etc. Les liens de output.assets[].url expirent après environ 20 minutes ; les copies binaires, non.

Les vidéos volumineuses sont conservées en mémoire, sauf si n8n stocke les données binaires sur disque. Sur n8n auto-hébergé, définissez N8N_DEFAULT_BINARY_DATA_MODE=filesystem lorsque vous travaillez avec de la vidéo.

Maîtrise des coûts et nouvelles tentatives

• Chaque élément est chiffré d’abord. Le nœud demande un devis. Si le devis dépasse Max Cost per Item (USD), qui vaut 2 $ par défaut, il s’arrête avec une erreur avant que quoi que ce soit ne soit créé, et rien n’est débité. Réglez la limite sur 0 pour la supprimer.
• La tâche est créée au prix devisé. Si le prix change entre le devis et l’envoi, le nœud redemande un devis, revérifie la limite et renvoie la requête.
• Les nouvelles tentatives ne facturent pas deux fois. Voir Limites de coût et nouvelles tentatives.

Tâches longues

Voir Tâches vidéo longues pour les options et les cas où utiliser chacune.

Option 2 : modèles HTTP Request

Deux workflows importables n’utilisent que des nœuds n8n intégrés : ils fonctionnent donc sur n8n auto-hébergé et sur n8n Cloud, sans nœud communautaire. Ils se trouvent dans le dossier d’exemples du dépôt du nœud.

Comment le modèle d’image est construit

Les mêmes étapes fonctionnent pour n’importe quel modèle média : vous pouvez donc recopier ce schéma dans votre propre workflow.

Le format des requêtes et des réponses est décrit dans Tâches, Devis et compatibilité et Entrées et sorties média. Les fichiers qu’un modèle lit, comme une image de départ, peuvent être une URL publique ou un fichier spicy:// envoyé.

Option 3 : modèles de chat dans AI Agent et les autres nœuds d’IA

Le point de terminaison de chat de SpicyAPI est compatible OpenAI : les nœuds OpenAI de n8n peuvent donc l’utiliser. Vous n’avez pas besoin du nœud communautaire pour cela, et cela fonctionne sur n8n Cloud.

https://api.spicyapi.ai/v1

À savoir :

• La liste de modèles inclut des modèles d’image et de vidéo. Avec une Base URL personnalisée, n8n affiche tout ce que renvoie /v1/models, et la liste de SpicyAPI couvre tous ses modèles. Choisissez-en un qui se termine par /chat, ou saisissez l’identifiant en mode expression. Les modèles d’image et de vidéo ne sont pas des modèles de chat et échoueront dans un agent.
• Use Responses API. Les versions récentes du nœud OpenAI Chat Model peuvent envoyer les requêtes à /v1/responses au lieu de /v1/chat/completions. SpicyAPI prend en charge /v1/responses, mais pas previous_response_id. Si une requête d’agent échoue avec Responses API activé, désactivez Use Responses API dans le nœud.
• Réglages d’échantillonnage. Si vous définissez une option que le modèle ne déclare pas, comme temperature sur un modèle de raisonnement, SpicyAPI l’ignore au lieu d’échouer et liste les noms ignorés dans l’en-tête de réponse X-Spicy-Ignored-Params ; une valeur hors de la plage du modèle est remplacée par la valeur acceptée la plus proche et listée dans X-Spicy-Adjusted-Params. Les autres champs non déclarés renvoient toujours 400.
• Les outils et la sortie JSON dépendent du modèle. Consultez les supported_parameters du modèle dans /v1/models.
• Les modèles de raisonnement comptent les tokens de raisonnement dans max_tokens. Avec une valeur très petite, comme 20, un modèle de raisonnement peut dépenser tout le budget à réfléchir et ne renvoyer aucun texte (upstream_failed : « the output budget was spent on reasoning »). Augmentez max_tokens ou réduisez reasoning_effort. Les valeurs de reasoning_effort diffèrent selon le modèle.
• Streaming et coût. Le chat est facturé au token après l’appel. La page Texte et streaming donne les détails, et Recettes de chat propose des exemples de requêtes.

Limites de coût et nouvelles tentatives

Limiter les dépenses

• Utilisez une clé dédiée à n8n avec un plafond de dépense quotidien ou mensuel dans la console, et une liste de modèles autorisés si le workflow n’a besoin que de quelques modèles. Lorsqu’un plafond est atteint, l’appel échoue avec 40202 et rien n’est débité pour lui.
• Pour les modèles média, demandez d’abord un devis. Le nœud le fait pour vous ; les modèles le font avec les nœuds Get Quote et If. Le devis est le prix exact de cette requête, y compris les suppléments comme les frais par image de référence : une vérification de prix fondée sur un devis est donc fiable, alors qu’une vérification fondée sur le tableau du catalogue ne l’est pas.
• Les échecs ordinaires et les tâches expirées libèrent toute la réservation. Certains refus de contenu ne sont facturés que si la page du modèle l’indique explicitement. Lisez settled et cost pour le montant final ; voir Facturation.

Pourquoi une nouvelle tentative ne facture pas deux fois

Chaque appel qui crée une tâche porte un Idempotency-Key. Si la même clé arrive de nouveau avec la même requête, SpicyAPI renvoie la tâche qu’il a déjà créée au lieu d’en créer une seconde : aucune seconde réservation ni aucun second débit n’a lieu. C’est important dans n8n, car une requête peut être envoyée deux fois sans que vous fassiez quoi que ce soit : Retry On Fail sur un nœud, ou un délai d’attente alors que la première requête est bien passée.

• Le nœud communautaire construit la clé à partir de l’exécution, du nœud, de l’élément et de son entrée. Une nouvelle tentative du nœud réutilise la même clé. Une nouvelle exécution, une entrée modifiée ou un autre passage dans une boucle constituent un nouveau travail et reçoivent une nouvelle clé.
• Les modèles la construisent à partir de l’identifiant d’exécution et de l’indice de l’élément, par exemple n8n-<execution id>-<item index>. Si vous recopiez ce schéma dans une boucle, ajoutez le compteur de boucle à la clé, sinon chaque passage renverra la tâche du premier passage.
• N’utilisez pas de valeur aléatoire qui change à chaque tentative, comme $now : elle fait passer chaque nouvelle tentative pour un nouveau travail.

Plus de détails dans Idempotence.

Tâches vidéo longues

Les modèles d’image et d’audio terminent généralement en une seule requête. La vidéo peut prendre plusieurs minutes. Vous avez trois façons de gérer cela, de la plus simple à la plus légère pour n8n :

Si le nœud cesse d’attendre, la tâche continue de s’exécuter sur SpicyAPI et elle est facturée si elle réussit. Récupérez-la plus tard avec Task > Get ; ne la renvoyez pas. Vous pouvez aussi la retrouver sous Logs dans la console.

Les résultats sont conservés pendant une durée limitée et les liens de téléchargement durent environ 20 minutes. Enregistrez les fichiers dans le workflow, par exemple vers un stockage cloud, si vous en avez besoin plus longtemps. Voir Conservation des données.

Dépannage

Les erreurs de SpicyAPI se terminent par un request_id ou un identifiant de tâche. Communiquez-le au support et la requête pourra être retrouvée précisément. Les codes d’erreur sont expliqués dans Erreurs, et une liste de vérification plus large figure dans Dépannage.

L’utilisation des modèles est soumise aux conditions de SpicyAPI et aux conditions de l’édition de n8n que vous utilisez.