Comment fonctionne SpicyAPI

Si vous découvrez SpicyAPI, commencez par cette page. Elle explique avec des mots simples ce que fait le service, vous aide à choisir la façon de l’utiliser qui vous convient et présente les quelques notions que le reste de la documentation suppose connues. Inutile de savoir programmer pour la lire.

Ce qu’est SpicyAPI

SpicyAPI vous donne une seule clé API pour accéder à des modèles d’image, de vidéo et de texte conçus par de nombreux éditeurs, et facture chaque utilisation en dollars américains.

Sans SpicyAPI, utiliser plusieurs modèles d’IA oblige à ouvrir un compte auprès de chaque entreprise, à apprendre le format de requête de chacune et à approvisionner chaque compte séparément. Avec SpicyAPI, vous avez un seul compte et un seul solde. Vous choisissez un modèle, vous envoyez votre prompt (et une image de référence si le modèle en accepte une), et vous recevez en retour une image, une vidéo ou du texte. Changer de modèle ne change rien à la façon d’envoyer une requête ni à celle de récupérer le résultat.

• Une seule clé, de nombreux modèles. Tous les modèles d’image et de vidéo s’utilisent de la même manière : vous soumettez une tâche, puis vous récupérez le résultat. Les modèles de texte acceptent en plus les formats de requête des bibliothèques officielles d’OpenAI, d’Anthropic et de Google Gemini.
• Paiement à l’usage, en dollars. Selon le modèle, le prix s’entend par image, par seconde de vidéo, par requête ou par token. Pas d’abonnement, ni de système de crédits ou de points : le prix affiché est le montant en dollars prélevé sur votre solde. Il n’existe pas non plus d’offre gratuite : vous devez approvisionner votre compte avant votre première génération. Voir Facturation.
• Quand une tâche est acceptée, son coût estimé est mis de côté sur votre solde. Si elle réussit, vous payez ce qu’elle a réellement consommé, jamais plus que ce montant. Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final.
• Aucun réglage de contenu à activer. SpicyAPI n’exige aucun indicateur de mode de contenu dans les requêtes et n’effectue aucun contrôle du contenu requête par requête. Ce qu’un modèle accepte de produire dépend de ce modèle : certains refusent ou atténuent certaines demandes. Vous restez responsable de l’usage que vous faites de ce que vous générez ; voir Politique de contenu.

SpicyAPI ne sert pas la Chine continentale, et quelques autres régions font également l’objet de restrictions ; voir cette même page de politique.

Ce que vous pouvez créer

Le catalogue propose aussi quelques tâches vidéo plus spécialisées, comme animer un personnage avec les mouvements d’un autre clip ou prolonger un clip existant. Des modèles sont ajoutés et retirés au fil du temps : seul le catalogue en direct fait foi sur ce qui existe aujourd’hui.

Pour voir les modèles actuels avec images, descriptions et prix, ouvrez spicyapi.ai/explore. La même liste est disponible sans compte ni clé, au format JSON brut, si vous voulez la consulter depuis un terminal :

curl "https://api.spicyapi.ai/console/v1/catalog/models?locale=en&strict=1"

La commande affiche un long bloc de texte. Chaque modèle y possède une modality (image, video ou text), ses tasks et un price de départ. Cette liste publique sert à parcourir l’offre ; une fois votre clé en main, la liste des modèles que votre clé peut réellement appeler vient de GET /api/v1/models. Voir Catalogue dans le glossaire.

Choisir votre parcours

Il existe cinq façons d’utiliser SpicyAPI. Elles partagent le même compte, le même solde, les mêmes modèles et les mêmes prix : vous pouvez commencer par l’une et en ajouter une autre plus tard.

Essayer dans votre navigateur

• Pour qui : toute personne qui veut voir ce que fait un modèle avant de décider quoi que ce soit. Rien à installer, aucun code.
• Ce qu’il vous faut : un navigateur web. Vous pouvez ouvrir n’importe quel modèle et remplir son formulaire sans compte. Pour appuyer sur Exécuter, vous devez être connecté et disposer d’un solde.
• Est-ce payant ? Chaque exécution est facturée comme un appel API. Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final.
• Pour commencer : ouvrez spicyapi.ai/explore, choisissez un modèle et utilisez l’onglet Playground de sa page. Les exécutions terminées apparaissent aussi dans Journal, dans la console.

Demander à votre assistant IA

• Pour qui : les personnes qui utilisent déjà un assistant IA comme Claude, Cursor, VS Code, Codex, Windsurf ou Gemini CLI, et qui veulent parcourir les modèles, comparer les prix et générer des images ou des vidéos en discutant. Les développeurs s’en servent aussi pour explorer avant de construire.
• Ce qu’il vous faut : Node.js 22.13 ou plus récent, une clé API et une application d’assistant compatible MCP. Les étapes payantes ne fonctionnent que dans les applications capables de vous poser une question de confirmation.
• Est-ce payant ? Parcourir le catalogue, demander un devis et consulter des résultats est gratuit. Lancer ou relancer une génération commence toujours par un arrêt qui vous montre le prix ; l’assistant ne peut pas répondre à cette question à votre place.
• Pour commencer : le serveur MCP donne à l’assistant des actions SpicyAPI. L’Agent Skill apprend à un assistant de code IA à écrire des intégrations SpicyAPI de façon sûre, et se combine bien avec le serveur MCP.

Taper des commandes dans un terminal

• Pour qui : comparer les prix, générer des images et des vidéos sur votre propre ordinateur et enregistrer les fichiers, répéter le même type de travail ou lancer un script simple. Sans programmer.
• Ce qu’il vous faut : un terminal, Node.js 22.13 ou plus récent et une clé API enregistrée dans la variable d’environnement SPICY_API_KEY.
• Est-ce payant ? Seules spicyapi tasks create et spicyapi tasks retry peuvent vous coûter de l’argent, et toutes deux vous demandent votre accord avant toute facturation.
• Pour commencer : Outil en ligne de commande (CLI).

Construire des workflows de nœuds dans ComfyUI

• Pour qui : les personnes qui travaillent déjà dans ComfyUI et veulent des modèles hébergés à côté de leurs nœuds locaux : enchaîner un modèle d’image et un modèle vidéo, ajouter une bande-son ou laisser un modèle de chat écrire le prompt.
• Ce qu’il vous faut : ComfyUI sur votre ordinateur ou sur un serveur, et une clé API. Les modèles de SpicyAPI s’exécutent sur nos serveurs : aucun GPU n’est nécessaire pour eux.
• Est-ce payant ? Chaque exécution est facturée comme un appel API. Chaque nœud affiche son tarif, fait un devis avant de s’exécuter et peut bloquer toute exécution qui dépasse un plafond que vous fixez.
• Pour commencer : Nœuds ComfyUI.

Écrire du code

• Pour qui : ajouter la génération d’images, de vidéos ou de texte à votre propre application, au backend de votre site web ou à votre pipeline de données.
• Ce qu’il vous faut : du code qui s’exécute sur un serveur ou sur votre propre ordinateur, car une clé API ne doit jamais se trouver dans une page web ni dans une application mobile. Il existe des SDK officiels pour TypeScript (Node.js 22.13 ou plus récent), Python 3.11+, Go 1.23+, PHP 8.1+ et Java 17+ ; n’importe quel autre langage peut appeler directement l’API HTTP.
• Est-ce payant ? Chaque génération acceptée est facturée. Les devis, la lecture du catalogue et la consultation des tâches sont gratuits.
• Pour commencer : le SDK TypeScript pour Node.js, ou les SDK Python, Go, PHP et Java. Pour du HTTP simple avec des exemples en curl, Node.js, Python et Go, prenez le Démarrage rapide ; voir Texte et streaming pour les modèles de chat et le tutoriel image vers vidéo pour un exemple complet de bout en bout.

Les notions que vous croiserez partout

Rien de tout cela n’est nécessaire pour essayer le Playground, mais toutes les autres pages le supposent connu. Chaque notion est résumée ici en une ou deux phrases, avec un lien vers la page qui en détaille les règles et une explication plus longue en langage courant dans le glossaire.

Ce qui se passe quand vous générez quelque chose

1. Vous choisissez un modèle et remplissez ses entrées.
2. Si vous le souhaitez, vous demandez un devis : le prix exact, gratuitement.
3. Vous soumettez. SpicyAPI accepte la requête sous forme de tâche, vous donne un identifiant de tâche et met le coût estimé de côté sur votre solde.
4. Le modèle travaille en arrière-plan. Une image prend généralement quelques secondes ; une vidéo, souvent plusieurs minutes.
5. La tâche se termine. Si elle a réussi, vous payez ce qu’elle a réellement consommé, jamais plus que le montant mis de côté. Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final.
6. Vous récupérez le résultat, soit parce que SpicyAPI rappelle votre serveur, soit parce que vous le demandez, puis vous téléchargez le fichier. Les liens de téléchargement sont temporaires et les fichiers ne sont conservés que pendant une durée limitée : enregistrez ce que vous voulez garder.

Identifiant de modèle

Chaque modèle possède un identifiant exact de la forme publisher/model/task. Copiez-le depuis le catalogue en direct (GET /api/v1/models, spicyapi models list ou listModels()) plutôt que de mémoire ou depuis une page web : des modèles sont ajoutés, mis en pause et retirés. Dans les exemples de code de cette documentation, MODEL_ID_FROM_CATALOG marque l’emplacement d’un vrai identifiant. Modèles et points de terminaison · Glossaire : identifiant de modèle

Les tâches et leurs états

La génération d’images et de vidéos est asynchrone : soumettre et récupérer le résultat sont deux étapes distinctes, reliées par un identifiant de tâche qui commence par job_. Une tâche passe de queued à running, puis se termine en succeeded, failed ou expired ; tout état autre que queued ou running est définitif. Les modèles de texte, eux, répondent sur la même connexion, souvent mot par mot. Tâches asynchrones · Texte et streaming · Glossaire : état d’une tâche

Devis

Un devis chiffre votre requête exacte sans rien lancer ni mettre d’argent de côté. Il est valable cinq minutes. Si vous soumettez avec ce devis alors que le prix ou la requête a changé entre-temps, la soumission est refusée au lieu d’être facturée à un autre montant. Devis et compatibilité des protocoles · Glossaire : devis

Clé d’idempotence

Une étiquette que vous choisissez pour une opération donnée et que vous envoyez avec elle. Si votre connexion coupe et que vous renvoyez la même requête avec la même étiquette et la même clé API dans les 24 heures, vous récupérez la tâche d’origine au lieu d’en lancer, et d’en payer, une seconde. La CLI et le serveur MCP en créent une pour vous ; avec le SDK ou en HTTP simple, vous fournissez la vôtre. Idempotence · Glossaire : clé d’idempotence

Callbacks

Au lieu de demander encore et encore si une tâche est terminée, vous pouvez lui donner une callBackUrl : une adresse HTTPS publique sur votre serveur. Quand la tâche se termine, SpicyAPI y envoie le résultat, signé pour que vous puissiez vérifier qu’il vient bien de SpicyAPI. Demander à répétition, ce qu’on appelle le polling, convient très bien pendant que vous testez sur votre propre ordinateur. Webhooks · Glossaire : webhook

Durée de conservation des résultats

Le lien de téléchargement d’un résultat dure environ 20 minutes ; redemandez la tâche pour en obtenir un nouveau. Les fichiers générés sont conservés au plus environ 14 jours, les fichiers téléversés un jour et le texte des prompts 30 jours ; vous pouvez raccourcir ces trois durées ou détruire à la demande le contenu d’une tâche. Les enregistrements de facturation sont conservés bien plus longtemps. Téléchargez tout ce que vous voulez garder. Conservation et destruction · Glossaire : conservation

Solde et plafonds de dépense

Votre solde est constitué de dollars américains prépayés. Chaque clé API peut en outre avoir un plafond de dépense quotidien, mensuel et cumulé, que vous réglez vous-même. Quand votre solde ne couvre pas une tâche, vous obtenez l’erreur 40201 ; quand un plafond est atteint, vous obtenez 40202. Dans les deux cas, aucune tâche n’est créée et rien n’est facturé. Facturation · Authentification · Glossaire : plafond de dépense

Votre première fois, dans l’ordre

Où trouver de l’aide

• Réponses rapides : FAQ, Glossaire, Dépannage et reprise et Erreurs.
• Le service fonctionne-t-il ? status.spicyapi.ai.
• Nous écrire : ouvrez une conversation sur la page Assistance de la console, ou utilisez la page de contact. Indiquez le request_id ou l’identifiant de tâche et l’heure en UTC. N’envoyez jamais votre clé API.

Et ensuite