Agent Skill

Si vous utilisez un assistant de code IA comme Claude Code, Codex ou Cursor, le Skill SpicyAPI lui apprend à travailler correctement avec SpicyAPI. Vous l’installez une seule fois. Ensuite, vous pouvez dire « ajoute la génération d’images SpicyAPI à mon application » et l’assistant suit les règles de SpicyAPI au lieu de deviner.

Pas besoin d’être développeur pour suivre cette page. Si vous savez coller une commande dans un terminal, vous savez installer le Skill.

Qu’est-ce qu’un Skill ?

Un Skill est un dossier d’instructions écrites pour un assistant IA plutôt que pour des personnes. Voyez-le comme le manuel de procédures que vous remettriez à un nouveau collègue : il ne fait pas le travail lui-même, mais il indique à celui qui le fait quelles étapes suivre, dans quel ordre, et ce qu’il ne faut jamais faire.

Les assistants IA en savent beaucoup sur la programmation en général, mais ils n’ont aucune connaissance fiable des règles propres à SpicyAPI. Livré à lui-même, un assistant risque :

• d’inventer un identifiant de modèle ou un champ d’entrée qui n’existe pas ;
• de coller votre clé API directement dans votre code ;
• d’envoyer deux fois la même requête payante après une coupure réseau, et de payer deux fois ;
• de vous donner un lien de résultat qui cesse de fonctionner quelques jours plus tard.

Une fois le Skill installé, l’assistant lit les règles de SpicyAPI avant de commencer. Concrètement, cela se passe ainsi :

1. Le dossier du Skill se trouve à un endroit que votre assistant consulte au démarrage d’une session.
2. L’assistant lit le résumé d’un paragraphe du Skill. Quand votre demande concerne SpicyAPI, il ouvre les instructions complètes. Vous n’avez pas à citer le Skill par son nom.
3. Il suit ces instructions pendant qu’il écrit du code ou exécute des commandes pour vous.

Trois choses à savoir d’emblée :

• Ce n’est que du texte. Des fichiers Markdown et YAML : aucun programme, aucun script, rien qui s’exécute à l’installation. Vous pouvez ouvrir chaque fichier dans un éditeur de texte ; voir Contenu du Skill.
• Il ne contient aucune clé API et n’effectue aucun appel. À lui seul, il ne peut ni accéder à votre compte ni dépenser d’argent.
• Il est gratuit et open source. Sous licence MIT, publié sur npm sous le nom @spicyapi/skill et développé au grand jour sur github.com/spicyapi-ai/spicy-skill.

Skill, MCP, SDK et CLI

SpicyAPI propose quatre outils officiels. Ils répondent à des besoins différents et sont conçus pour être utilisés ensemble.

Le Skill ne remplace aucun d’entre eux. Il explique à l’assistant comment s’en servir : les outils MCP lorsqu’ils sont connectés, la CLI pour les opérations ponctuelles et le SDK de votre langage pour le code destiné à votre application.

• Skill seul. L’assistant écrit un code d’intégration correct pour votre projet, mais il ne peut rien consulter dans votre compte ni lancer de tâches pour vous.
• MCP seul. L’assistant peut agir sur votre compte, mais il doit deviner lui-même, à chaque fois, le bon enchaînement des étapes.
• Les deux. L’assistant peut faire des essais pour vous et les fait de la manière documentée. Si vous voulez que votre assistant lance de vraies tâches, installez les deux. Ils ne se gênent pas.

Ce qu’il vous apporte

La colonne de gauche indique ce que vous demandez. Celle de droite, ce que le Skill fait faire à l’assistant pour y répondre.

Ce qu’il ne fera pas

• Dépenser de l’argent de son propre chef. Le Skill est du texte et ne peut rien appeler. Si votre assistant dispose aussi du serveur MCP ou de la CLI et d’une clé API, il peut créer des tâches payantes. Le Skill lui demande de vous montrer d’abord le prix et d’obtenir votre confirmation explicite, sauf si votre demande autorisait déjà clairement cette exécution payante précise. Avec le serveur MCP, chaque action payante s’arrête en plus pour une confirmation que l’assistant ne peut pas contourner.
• Inventer des fonctionnalités. Il n’écrira pas d’appels pour ce que l’API publique ne propose pas, comme annuler une tâche, supprimer l’enregistrement d’une tâche ou renvoyer un webhook.
• Toucher aux réglages de votre compte. L’inscription, la connexion, les paiements, les recharges, les membres d’équipe, les demandes relatives à la vie privée et la clôture du compte restent dans la console SpicyAPI. L’assistant ne tentera pas de les automatiser.
• Truquer un test. Si vous demandez un vrai test, il envoie une vraie requête (éventuellement payante, après votre confirmation) et rend compte de ce qui s’est réellement passé. Une simulation qui réussit n’est jamais présentée comme « vérifiée ».
• Ajouter un réglage de contenu. SpicyAPI n’a ni option de mode de contenu ni contrôle du contenu requête par requête, et le Skill n’en invente pas. C’est le modèle que vous choisissez qui détermine ce qu’il peut faire.

Avant de commencer

Il vous faut quatre choses. Seules les trois premières sont nécessaires pour l’installation.

1. Un assistant de code IA compatible avec les Agent Skills. C’est le cas de Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf et bien d’autres. Le Skill utilise le format de dossier portable Agent Skills : il fonctionne donc avec tout assistant qui lit ce format. En cas de doute sur le vôtre, cherchez « skills » dans sa documentation.

2. Node.js 22 ou plus récent, qui fournit la commande npx. Vérifiez avec :

   node --version

   L’installeur skills demande actuellement Node.js 22.20 ou plus récent, et l’installeur propre au paquet a besoin de la version 22.13 ou plus récente. Si la commande est introuvable ou si la version est inférieure, installez la version LTS depuis nodejs.org et ouvrez un nouveau terminal.

3. Un terminal. Sur macOS, l’application Terminal. Sur Windows, PowerShell. Lancez les commandes depuis le dossier de votre projet si vous voulez une installation limitée à ce projet.

4. Une clé API SpicyAPI, dès que vous commencez à appeler l’API. L’installation du Skill n’en demande pas. Créez une clé dans la console ; elle commence par sk-spicy- et n’est affichée qu’une seule fois. Rangez-la dans une variable d’environnement nommée SPICY_API_KEY et ne collez jamais la clé elle-même dans une conversation avec votre assistant. Voir Authentification.

Installation

Il existe deux façons d’installer le Skill. Toutes deux mettent en place les mêmes fichiers. Prenez la première, sauf si vous avez une raison de ne pas le faire.

npx skills add spicyapi-ai/spicy-skill

# Claude Code, pour ce projet uniquement
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex, pour tous les projets
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code et Codex, pour tous les projets, sans aucune question
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

Vérifier que le Skill fonctionne

npx skills list      # Skills installés dans le projet actuel
npx skills list -g   # Skills installés pour tous les projets

Exemples de demandes

Collez l’une de ces demandes dans votre assistant et adaptez les détails. Mentionnez SpicyAPI dans la demande pour que l’assistant sache que le Skill s’applique.

Si vous savez déjà quel modèle vous voulez, copiez son identifiant exact depuis l’onglet API de la page du modèle ou depuis le catalogue en direct authentifié (GET /api/v1/models), et mettez-le dans la demande. Les exemples écrivent MODEL_ID_FROM_CATALOG à l’endroit de cet identifiant ; c’est un emplacement réservé, pas un vrai identifiant. Si vous n’en avez pas, demandez à l’assistant de choisir dans le catalogue en direct. Voir Modèles et points de terminaison.

Ajouter un point de terminaison d’image à une application Next.js

Ajoute à mon application Next.js une route d’API côté serveur qui reçoit un prompt texte, génère une image avec SpicyAPI en utilisant le modèle MODEL_ID_FROM_CATALOG, attend le résultat et renvoie le lien de l’image. Lis la clé API dans SPICY_API_KEY.

Ce à quoi le Skill demande à l’assistant de veiller :

• La clé reste sur votre serveur, dans SPICY_API_KEY. Votre page web appelle votre route ; elle n’appelle jamais SpicyAPI avec la clé.
• Il lit les champs d’entrée actuels de ce modèle dans le catalogue en direct avant de construire la requête.
• Il obtient d’abord un devis exact et vous montre le coût estimé et le montant maximal facturable. La requête payante transmet ce devis confirmé.
• Il crée une seule clé d’idempotence pour la génération et la réutilise si la requête dépasse le délai.
• Il attend avec une échéance, puis contrôle le state de la tâche : une attente qui s’est terminée n’est pas la même chose qu’une génération réussie.

Recevoir les résultats par webhook dans Express

Ajoute à mon serveur Express un point de terminaison de webhook qui reçoit les résultats des tâches SpicyAPI, vérifie la signature avec SPICY_WEBHOOK_SECRET et enregistre le lien du résultat dans ma base de données.

• Il vérifie la signature sur le corps brut exact de la requête, avant de l’analyser comme du JSON.
• Il utilise le request_id de la livraison pour ignorer les doublons, car un même événement peut arriver plusieurs fois.
• Il lit le résultat directement dans un webhook complet et vérifié, sans consultation supplémentaire.

Copier les vidéos terminées dans votre propre stockage

Quand une tâche vidéo SpicyAPI réussit, télécharge la vidéo, envoie-la dans mon bucket S3, puis enregistre mon propre lien au lieu de celui de SpicyAPI.

• Les liens de résultat sont temporaires et les fichiers générés sont conservés environ 14 jours : il enregistre donc une copie durable que vous contrôlez.
• Il n’envoie pas votre clé API quand il télécharge depuis un lien de résultat.
• Si un lien a expiré, il redemande la même tâche à SpicyAPI pour obtenir un nouveau lien. Il ne crée jamais une nouvelle tâche juste pour obtenir un lien.

Transformer la photo d’un utilisateur en vidéo

Permets aux utilisateurs de téléverser une photo dans mon application et de la transformer en courte vidéo avec SpicyAPI.

• Il téléverse d’abord le fichier sur SpicyAPI et place l’adresse spicy:// renvoyée dans la requête, au lieu d’y coller le fichier en base64.
• Il respecte les limites de téléversement : 10 MiB pour les images, 90 MiB pour les vidéos MP4 ou WebM et l’audio MP3 ou WAV.
• Une photo déjà accessible par un lien HTTPS public peut être transmise directement, sans téléversement.

Gérer les nouvelles tentatives et un solde insuffisant

Fais en sorte que mon intégration SpicyAPI gère les échecs : qu’elle retente les dépassements de délai réseau sans payer deux fois, qu’elle affiche un message clair quand le solde de mon compte est insuffisant et qu’elle ralentisse quand je suis limité en débit.

• Après un dépassement de délai, il retente avec la même clé d’idempotence, pour qu’une nouvelle tentative ne puisse pas créer une seconde tâche payante.
• Il ne retente pas un « solde insuffisant » (code 40201) : votre utilisateur voit un message clair et vous rechargez votre solde dans la console.
• Il attend aussi longtemps que l’indique Retry-After avant de réessayer.
• Si le devis a expiré ou si le prix a changé (code 40901), il demande un nouveau devis et vous consulte de nouveau, au lieu de renoncer à la vérification du prix.
• Il sait que relancer une tâche échouée crée une nouvelle tâche qui peut être facturée à nouveau : il ne le fait donc que si vous voulez un nouvel essai.

Générer un lot

Génère avec SpicyAPI des photos produit pour les 20 articles de products.csv, 3 au maximum en même temps, et consigne l’identifiant de chaque tâche.

• SpicyAPI n’a pas de point de terminaison de traitement par lot : il exécute donc un nombre limité de requêtes à la fois.
• Chaque élément reçoit sa propre clé d’idempotence et son propre prix.
• Il consigne l’identifiant de chaque tâche dès qu’elle est acceptée.
• Si un élément dépasse le délai, il ne récupère que cet élément et ne resoumet jamais le lot entier.

Contenu du Skill

Le dossier installé ressemble à ceci :

spicyapi/
├── SKILL.md
├── references/
│   ├── api-workflows.md
│   └── safety.md
└── agents/
    └── openai.yaml

L’assistant n’ouvre les deux fichiers de référence que lorsqu’une tâche en a besoin, ce qui laisse sa mémoire de travail disponible pour votre projet. Pour lire les fichiers avant d’installer, lancez npx @spicyapi/skill path : la commande affiche le dossier où le paquet les conserve.

Le Skill demande à l’assistant de configurer votre code et vos outils avec les variables d’environnement ci-dessous. Le Skill lui-même n’en lit aucune.

Mettre à jour et désinstaller

Mettre à jour

Le Skill évolue quand le mode de travail recommandé par SpicyAPI change, et les copies installées ne se mettent pas à jour toutes seules. Le dossier installé ne porte aucun numéro de version : réinstaller est donc le moyen le plus simple d’être sûr d’avoir la dernière version.

• Installé avec npx skills add : relancez la même commande, avec la même portée et les mêmes assistants. Elle remplace les fichiers installés par le contenu actuel du dépôt : une mise à jour vous parvient dès sa publication, sans aucun délai.

• Installé avec l’installeur du paquet : relancez-le avec --force et le même --target. Ajouter @latest oblige npx à récupérer le paquet le plus récent au lieu de réutiliser une copie en cache :

  npx @spicyapi/skill@latest install --target ~/.claude/skills/spicyapi --force

Désinstaller

Désinstaller le Skill n’a aucun effet sur votre compte SpicyAPI, vos clés API ni le code que l’assistant a déjà écrit.

• Installé avec npx skills add : lancez ceci depuis le même dossier de projet, en ajoutant -g si vous aviez fait une installation globale. Vérifiez ensuite que le dossier spicyapi a disparu.

  npx skills remove spicyapi

• Installé avec l’installeur du paquet : supprimez le dossier spicyapi, dans le Finder ou l’Explorateur de fichiers, ou depuis un terminal :

  # macOS et Linux : indiquez le dossier dans lequel vous avez installé le Skill
  rm -rf ~/.agents/skills/spicyapi

  # Windows PowerShell
  Remove-Item -Recurse -Force "$HOME\.agents\skills\spicyapi"

  Vérifiez deux fois le chemin avant d’appuyer sur Entrée : il doit se terminer par spicyapi.

Ouvrez ensuite une nouvelle session pour que l’assistant cesse d’utiliser le Skill.

Dépannage

Le code source

Le paquet est sous licence MIT et développé au grand jour sur github.com/spicyapi-ai/spicy-skill. C’est là qu’on lit les instructions que le Skill installe réellement, qu’on signale un comportement qui s’écarte de ce qui est décrit ici et qu’on propose une modification.

Étapes suivantes