Outil en ligne de commande (CLI)

Ce qu’est la CLI

spicyapi est un petit programme qui s’exécute dans un terminal, la fenêtre où l’on tape des commandes au lieu de cliquer sur des boutons. Chaque commande remplit une seule fonction : lister les modèles que votre compte peut utiliser, vous dire ce que coûtera une génération, lancer une génération d’image ou de vidéo, attendre qu’elle se termine et vous donner un lien pour télécharger le résultat.

Vous n’écrivez aucun code. Vous tapez une commande, vous appuyez sur Entrée et vous lisez la réponse.

Elle est tout indiquée quand vous voulez :

• essayer des modèles et comparer les prix avant que quiconque écrive une intégration ;
• générer des images ou des vidéos depuis votre propre ordinateur et enregistrer les fichiers ;
• répéter le même type de génération sans refaire tous les clics sur une page à chaque fois ;
• vérifier les réglages exacts d’un modèle avant de construire quelque chose par-dessus.

La CLI couvre la génération d’images et de vidéos. Les modèles de texte et de chat s’appellent via les points de terminaison compatibles chat décrits dans Texte et streaming.

Il existe trois autres outils officiels. Choisissez la CLI si vous voulez taper les commandes vous-même :

Vous écrivez dans un autre langage ? Il existe aussi des SDK officiels pour Python, Go, PHP et Java.

Ce que vous pouvez faire

Dans les commandes ci-dessus, un mot entre chevrons comme <task-id> signifie « mettez ici votre propre valeur », sans les chevrons.

Avant de commencer

Il vous faut quatre choses : un terminal, Node.js, une clé API et un moyen de lancer la CLI. Comptez une dizaine de minutes la première fois.

node -v

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

Votre premier résultat

Ce parcours génère une image et la télécharge. Chaque étape montre la commande, à peu près ce que vous verrez, et ce qui vient de se passer. Vos chiffres, vos identifiants et vos horaires seront différents.

spicyapi status

SpicyAPI is reachable — api.spicyapi.ai answered in 523 ms.

spicyapi balance

available: 12.34
held: 0.06
total: 12.40

spicyapi models list --modality image --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example image model",
      "modality": "image",
      "tasks": ["text-to-image"],
      "enabled": true,
      "available": true,
      "pricing": [
        { "variant": "", "unit": "per_image", "price": "0.03", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

{
  "model": "MODEL_ID_FROM_CATALOG",
  "enabled": true,
  "available": true,
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "9:16"] }
    },
    "additionalProperties": false
  }
}

cat > input.json <<'EOF'
{"prompt": "A paper lantern glowing on a rainy street at night, cinematic light"}
EOF

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: 0.03
maxCharge: 0.03
currency: USD
quantity: 1
unit: per_image
expiresAt: 2026-09-17T08:05:00Z

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z. Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241. Continue? [y/N]

Accepted: job_01k3m8x9q2z4v7n5p6r8s0t1w3
If waiting is interrupted: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
accepted: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","state":"queued","estimatedCost":"0.03","deadlineAt":"2026-09-17T08:30:00Z"}
task: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","model":"MODEL_ID_FROM_CATALOG","state":"succeeded","output":{"assets":[{"key":"tasks/…/result.png","url":"https://…","expiresAt":"2026-09-17T08:20:00Z","mime":"image/png","width":1024,"height":1024}]},"cost":"0.03","settled":true,…}

curl -L -o result.png "PASTE_THE_URL_HERE"

Lire ce qu’affiche la CLI

• L’affichage normal montre une paire name: value par ligne. Les valeurs composées de plusieurs parties, comme output ou retention, sont affichées en JSON sur une seule ligne.
• --json affiche la réponse complète en JSON indenté. L’option fonctionne avec toutes les commandes, avant ou après le nom de la commande : spicyapi --json balance et spicyapi balance --json reviennent au même.
• Les résultats vont sur la sortie normale de l’écran ; les messages vont sur la sortie d’erreur. Les prix, la clé d’idempotence, les lignes Accepted: et les erreurs sont des messages. Ainsi, spicyapi --json tasks get <task-id> > task.json n’enregistre que le résultat dans task.json, tandis que les messages continuent de s’afficher à l’écran.
• Les erreurs ressemblent à Error: <what went wrong> (request req_…), généralement suivies d’une ligne Next: qui indique quoi faire. Avec --json, une erreur est un objet JSON sur une seule ligne avec error, type, status, code et requestId, sans ligne Next:. Quand aucune clé n’est définie, type vaut MissingApiKeyError. Citez la valeur req_… si vous contactez l’assistance.
• Les montants sont des dollars américains écrits en texte simple, sans signe $, comme 0.03.
• Les heures sont en UTC. Le Z à la fin de 2026-09-17T08:05:00Z signifie UTC.
• Le code de sortie vaut 0 quand une commande réussit et une autre valeur quand elle échoue, ce que les scripts peuvent vérifier.

Référence des commandes

Chaque commande a aussi une aide intégrée : ajoutez --help, par exemple spicyapi tasks create --help.

Options globales et variables d’environnement

Ces options fonctionnent avec toutes les commandes.

status

Ce qu’elle fait : vérifie que SpicyAPI fonctionne et qu’il est joignable depuis votre ordinateur.

spicyapi status

Aucune option. Aucune clé nécessaire. Gratuit.

Ce qui s’affiche : une phrase. SpicyAPI is reachable — … answered in … ms. signifie que tout va bien. could not be reached signifie que votre ordinateur n’a obtenu aucune réponse : vérifiez votre réseau ou votre proxy. is not healthy ou reports it is not ready signalent un problème de notre côté ; les incidents en cours sont listés sur status.spicyapi.ai.

Avec --json, vous voyez les vérifications brutes. operational: true est la réponse qui compte ; une entrée readiness avec le statut 404 est normale sur l’adresse publique.

docs search

Ce qu’elle fait : trouve la page de documentation qui traite d’un sujet. Elle cherche dans un petit index intégré à la CLI : elle fonctionne donc sans clé et sans appeler SpicyAPI. Chaque résultat renvoie vers la page correspondante de ce site de documentation, docs.spicyapi.ai.

spicyapi docs search [words] [--limit <count>]

spicyapi docs search retention

slug: retention
title: Retention and destruction
summary: What the platform caps are, how far down you can dial them, how to destroy a task's content, and what we cannot promise.
keywords: ["privacy","delete","storage","retention","per-request retention","purge","destroy"]
url: https://docs.spicyapi.ai/docs/retention

Quand il y a plusieurs résultats, ils s’affichent les uns après les autres, et chacun commence par slug:. Si rien ne correspond, la commande le dit et se termine quand même avec le code 0 :

No documentation matched "refnd". Try fewer or different words, or run `spicyapi docs search` without words to browse pages.

Avec --json, l’absence de résultat affiche une liste vide, []. Gratuit.

models list

Ce qu’elle fait : liste les modèles que votre compte peut appeler aujourd’hui, aux prix que paie votre compte.

spicyapi models list [options]

spicyapi models list --modality video --task image-to-video --json

Ce qui s’affiche : total et items. Utilisez --json, car sans cette option tous les éléments s’affichent sur une seule ligne. Les champs les plus utiles de chaque élément :

Gratuit. La liste des modèles compte dans le débit de requêtes de votre compte : inutile de la lancer avant chaque génération.

models get

Ce qu’elle fait : affiche un modèle en détail, y compris les réglages qu’il accepte.

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

Ce qui s’affiche : les mêmes champs que models list, plus inputSchema. Dans inputSchema, lisez required (les réglages à envoyer obligatoirement), properties (chaque réglage autorisé et son type), enum (les seules valeurs autorisées), minimum et maximum (les bornes des nombres) et default (la valeur utilisée si vous omettez le réglage). Les entrées nommées x-ui sont des indications pour construire des formulaires ; vous pouvez les ignorer. Gratuit.

balance

Ce qu’elle fait : indique combien d’argent est disponible sur votre compte.

spicyapi balance

Aucune option. Gratuit.

Ce qui s’affiche : available (ce que vous pouvez dépenser maintenant), held (mis de côté pour des tâches encore en cours) et total, le tout en dollars américains. L’affichage peut aussi inclure funding, qui répartit le solde entre fonds prépayés et dotations promotionnelles, avec la date d’expiration des dotations et les modèles qu’elles financent. Inutile de vérifier le solde avant chaque génération : tasks create le fait pour vous.

usage

Ce qu’elle fait : indique combien de générations la clé API actuelle a exécutées et ce qu’elles ont coûté, regroupées par jour et par modèle.

spicyapi usage [--from <date>] [--to <date>]

spicyapi usage --from 2026-09-01 --to 2026-10-01

Cette commande couvre tout le mois de septembre : --to est le premier jour non inclus. Omettez les deux options pour voir les sept derniers jours, aujourd’hui compris.

Ce qui s’affiche : from, to, currency, totalCalls, totalSpend, puis days (par jour : calls, succeeded, failed, spend) et models (les mêmes chiffres par modèle). totalSpend ne compte que les montants définitivement facturés. days et models décrivent les mêmes tâches de deux façons : ne les additionnez donc pas. Pour votre compte entier plutôt que pour une seule clé, utilisez la page Consommation de la console.

Gratuit. La commande est limitée à 30 appels par minute : servez-vous-en pour vérifier des totaux, pas dans une boucle.

tasks quote

Ce qu’elle fait : vous dit exactement ce que coûterait une génération, sans la lancer et sans mettre d’argent de côté.

spicyapi tasks quote --model <model> --input-file <path>

Ce qui s’affiche : quoteId, model, estimatedCost, maxCharge, currency, quantity (par exemple le nombre de secondes facturées), unit et expiresAt. Un devis est valable cinq minutes.

Gratuit, sans confirmation. Servez-vous-en pour comparer des modèles ou des réglages. Vous n’êtes pas obligé de la lancer avant tasks create, qui obtient son propre devis.

tasks create

Ce qu’elle fait : lance une génération d’image ou de vidéo. Elle coûte de l’argent. La CLI affiche toujours le prix et demande d’abord votre accord.

spicyapi tasks create --model <model> --input-file <path> [options]

Ce qui se passe, dans l’ordre :

1. La CLI lit votre entrée et vérifie qu’il s’agit d’un objet JSON. Si vous n’avez fourni aucune entrée, elle s’arrête ici.
2. Si personne ne peut répondre à une question, par exemple dans un script, et que vous n’avez pas passé --yes, elle s’arrête ici.
3. Elle obtient un devis et affiche le montant estimé, le montant maximal, l’heure d’expiration du devis et la clé d’idempotence.
4. Elle demande Continue? [y/N]. Seuls y ou yes permettent de continuer. La réponse par défaut est non.
5. Elle crée la tâche au prix du devis. Le montant estimé est mis de côté sur votre solde, et ce montant est aussi le maximum que la tâche peut coûter.
6. Sans --wait, elle affiche idempotencyKey, taskId, state (queued), estimatedCost et deadlineAt, puis rend la main. Avec --wait, elle affiche aussitôt Accepted: <task-id> et une commande de reprise, attend, puis affiche idempotencyKey, accepted et la task terminée.

deadlineAt est l’heure limite à laquelle la tâche peut se terminer avant de passer en expired. Ce n’est pas l’heure d’expiration de votre lien de téléchargement ni de vos fichiers.

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Sur macOS et Linux, vous pouvez aussi fournir l’entrée directement dans la commande :

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-json '{"prompt": "A paper lantern on a rainy street"}'

Quand l’attente échoue sur une erreur (et non sur un Ctrl + C), les dernières lignes répètent tout ce dont vous avez besoin : inutile de remonter chercher la ligne Accepted:.

Error: task job_01k3m8x9q2z4v7n5p6r8s0t1w3 did not reach a terminal state within 600000ms
Task job_01k3m8x9q2z4v7n5p6r8s0t1w3 was accepted and may still be running; only the wait stopped.
Recover: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3
To replay the same request without creating a second task, reuse --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241.

Si l’erreur fait partie de celles qui ont une solution connue, comme un 429 ou une erreur serveur, une ligne Next: suit. Avec --json, les mêmes informations se trouvent dans l’objet d’erreur, sous taskId, idempotencyKey et recover.

tasks wait

Ce qu’elle fait : attend qu’une tâche déjà lancée se termine.

spicyapi tasks wait <task-id> [options]

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000

Ce qui s’affiche : la tâche terminée, avec les mêmes champs que tasks get, une fois que son état est succeeded, failed ou expired. Si la tâche a réussi mais que ses fichiers sont encore en cours de copie, la commande attend encore un peu.

Si la limite de temps est atteinte, vous voyez Error: task … did not reach a terminal state within 600000ms. Ce n’est pas un échec : la tâche est toujours en cours. Attendez de nouveau, avec un --wait-timeout-ms plus long si nécessaire. Arrêter une attente n’annule jamais une tâche. Gratuit.

tasks get

Ce qu’elle fait : montre une tâche à l’instant présent : son état, son coût, ses liens de résultat et la date à laquelle son contenu sera supprimé.

spicyapi tasks get <task-id>

Utilisez la même clé API que celle qui a créé la tâche : une autre clé obtient « not found ».

Champs affichés :

L’affichage normal se termine par un résumé en langage courant, comme Outputs expire: … ou Content: Destroyed — you removed the outputs …. Chaque appel renvoie des liens de téléchargement neufs. Gratuit.

tasks list

Ce qu’elle fait : liste les tâches créées avec la clé API actuelle, une page à la fois.

spicyapi tasks list [options]

spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --state failed

Ce qui s’affiche : items (chacun avec taskId, model, state, cost, settled, createdAt, deadlineAt et completedAt), hasMore et nextCursor. Si hasMore vaut true, relancez la même commande avec les mêmes --from et --to, en ajoutant --cursor suivi de la valeur nextCursor. La liste ne contient aucun lien de téléchargement ; utilisez tasks get pour la tâche qui vous intéresse. Gratuit.

tasks retry

Ce qu’elle fait : relance une tâche failed ou expired, sous la forme d’une nouvelle tâche avec un nouvel identifiant. Elle coûte de l’argent.

spicyapi tasks retry <task-id> [options]

La commande demande Retry source task … Continue? [y/N]. Contrairement à tasks create, elle n’affiche aucun prix avant de poser la question. La nouvelle tâche est facturée au prix actuel du modèle : si le prix compte pour vous, vérifiez-le d’abord avec spicyapi models get <model>.

Ce qui s’affiche : idempotencyKey, le nouveau taskId, sourceTaskId (la tâche d’origine), state, estimatedCost (le montant mis de côté) et deadlineAt.

• Seules les tâches failed et expired peuvent être relancées, ainsi que les anciennes tâches canceled. Pour obtenir une autre version d’un résultat réussi, utilisez tasks create.
• L’entrée d’origine est réutilisée telle quelle : une relance n’aide donc que si l’échec était temporaire. Vérifiez d’abord errorCode ; voir Relancer une tâche échouée et Erreurs.
• Si l’entrée pointait vers un fichier téléversé qui a expiré depuis, la relance échoue ; téléversez de nouveau le fichier et utilisez tasks create.
• La relance conserve le réglage de conservation de la tâche d’origine.
• Si tasks create a perdu la connexion avant que vous voyiez un identifiant de tâche, il ne s’agit pas d’une tâche échouée. Suivez plutôt les étapes de Reprendre une tâche après une attente interrompue.

tasks purge

Ce qu’elle fait : supprime définitivement les médias générés, le résultat (les données de résultat stockées), le prompt et les autres textes d’entrée d’une tâche terminée, immédiatement, au lieu d’attendre qu’ils expirent.

spicyapi tasks purge <task-id> [--yes]

Le contenu d’une tâche encore queued ou running ne peut pas être détruit. Une telle tâche ne peut pas non plus être annulée, car il n’existe ni commande ni API d’annulation : attendez qu’elle se termine avec spicyapi tasks wait <task-id>, puis détruisez son contenu.

La commande explique ce qui va être supprimé et vous demande de confirmer, car l’opération est irréversible. Téléchargez d’abord tout ce que vous voulez garder.

Ce qui s’affiche : taskId, contentState (purged), purgedAt, contentRemovedBy (user), billingRetained (toujours true) et mediaDeletionPending, puis une ligne qui nomme ce qui a été détruit et indique que les médias stockés sont supprimés en une minute environ. Si contentState vaut encore present, rien n’a été supprimé cette fois-ci ; réessayez plus tard.

Gratuit, et ce n’est pas un remboursement : l’écriture comptable, le montant facturé, le modèle, l’état, les horodatages et l’identifiant de requête restent enregistrés. Voir Conservation et destruction.

files upload

Ce qu’elle fait : téléverse un fichier depuis votre ordinateur, comme l’image de départ d’une génération image-vers-vidéo, et vous donne une adresse spicy:// à placer dans votre entrée.

spicyapi files upload <path> [--content-type <type>]

Les fichiers acceptés sont les images .jpg, .jpeg, .png, .webp et .gif jusqu’à 10 MiB, les vidéos .mp4 et .webm et les fichiers audio .mp3 et .wav jusqu’à 90 MiB et 600 secondes. Un modèle peut fixer ses propres limites, plus basses.

spicyapi files upload ./start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z
width: 1280
height: 720

Ce qui s’affiche : copiez la valeur uri exactement telle qu’elle est affichée dans le réglage de fichier du modèle, souvent image_url. Elle est utilisable jusqu’à expiresAt, normalement pendant un jour. Passé ce délai, téléversez de nouveau le fichier. Le téléversement est gratuit.

files download-url

Ce qu’elle fait : crée un nouveau lien de téléchargement pour le résultat d’une tâche terminée. Elle affiche le lien ; elle n’enregistre pas le fichier.

spicyapi files download-url <task-id> [--key <key>]

Ce qui s’affiche : key, url et expiresAt. Le lien fonctionne pendant environ 20 minutes ; ouvrez-le dans un navigateur ou téléchargez-le avec curl. Une tâche qui n’a pas encore réussi répond « not found ». Si le fichier est encore en cours de copie, vous obtenez une erreur de conflit ; attendez quelques secondes et réessayez. Une fois les fichiers de la tâche supprimés, plus aucun lien ne peut être créé. Gratuit.

webhooks verify

Ce qu’elle fait : si vous gérez un serveur qui reçoit les callbacks de SpicyAPI (voir --callback-url), elle vérifie qu’un callback enregistré est authentique et n’a pas été modifié. Elle s’exécute entièrement sur votre ordinateur et ne demande aucune clé API.

spicyapi webhooks verify --body-file <path> --timestamp <seconds> --signature <base64> --payload-version <version>

Ce qui s’affiche : en cas de succès, payload (le contenu du callback), payloadVersion, taskId, deliveryId (version 2) et timestamp. Si quoi que ce soit ne correspond pas, la commande affiche une erreur et se termine avec un code différent de zéro. Gratuit.

Une clé de signature est créée automatiquement à l’inscription, mais sa valeur n’est jamais affichée. Pour en obtenir une que vous pouvez copier, ouvrez Webhooks dans la console et cliquez sur Générer (ou sur Renouveler si une clé est déjà configurée). La nouvelle clé n’est affichée qu’une seule fois. Le renouvellement prend effet immédiatement, sans période de chevauchement : l’ancienne clé cesse aussitôt de signer. Voir Webhooks.

Recettes courantes

Générer une image

spicyapi models list --modality image --json
spicyapi models get MODEL_ID_FROM_CATALOG --json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Choisissez un identifiant avec la première commande, construisez input.json à partir des réglages affichés par la deuxième, puis lancez la troisième et confirmez avec y. Le parcours Votre premier résultat explique chaque étape.

Transformer une image en vidéo

spicyapi models list --modality video --task image-to-video --json
spicyapi models get MODEL_ID_FROM_CATALOG --json

spicyapi files upload ./start-frame.jpg

{
  "prompt": "Slow push-in, rain running down the window",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5
}

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait --wait-timeout-ms 1800000

L’image téléversée est utilisable pendant un jour. Passé ce délai, téléversez-la de nouveau.

Reprendre une tâche après une attente interrompue

Une tâche continue de s’exécuter même si le terminal se ferme, si le réseau coupe, si votre ordinateur se met en veille ou si l’attente arrive à son terme. La façon de la retrouver dépend de ce que vous avez vu :

• Vous avez vu Accepted: job_…, ou une ligne Recover: sous l’erreur. Vous avez l’identifiant de la tâche. Attendez de nouveau, ou consultez-la simplement :

  spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000
  spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

• Vous n’avez vu que la ligne Idempotency-Key:, par exemple parce que la connexion a coupé pendant la création de la tâche. Relancez la même commande, avec le même modèle et la même entrée, et ajoutez cette clé :

  spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241 --wait

  La CLI affiche le prix et redemande votre accord, mais si la première tentative a été acceptée, SpicyAPI vous rend cette même tâche au lieu d’en lancer et d’en facturer une seconde. Cela fonctionne pendant 24 heures avec la même clé API. Si la première tentative n’est jamais arrivée, la tâche est créée maintenant, une seule fois.

• Vous n’avez ni l’un ni l’autre. Listez vos tâches récentes et retrouvez la bonne d’après l’heure et le modèle :

  spicyapi --json tasks list --limit 10

Relancer une tâche échouée

Commencez par savoir pourquoi elle a échoué :

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Lisez ensuite errorCode. 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. tasks retry renvoie la même entrée : elle n’aide donc que si la cause était temporaire.

La liste complète se trouve dans Erreurs.

Quand une relance a du sens, lancez-la. Elle crée, et facture, une nouvelle tâche :

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

Exporter votre consommation

Enregistrez dans un fichier un mois de consommation de la clé actuelle :

spicyapi --json usage --from 2026-09-01 --to 2026-10-01 > usage-2026-09.json

Le fichier contient les totaux par jour et par modèle. Pour une liste tâche par tâche, enregistrez de la même façon spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100, en suivant nextCursor tant que hasMore vaut true. Les chiffres à l’échelle du compte et les factures se trouvent dans la console.

Lancer la CLI depuis un script

Dans un script, personne ne peut répondre à Continue? [y/N] : les commandes payantes refusent donc de s’exécuter sans --yes. Si vous l’ajoutez :

• demandez d’abord un devis et vérifiez le prix dans le script ;
• donnez à chaque génération sa propre --idempotency-key fixe, comme poster-2026-09-17-v1, pour qu’exécuter le script deux fois ne facture pas deux fois ;
• ajoutez --json et lisez state dans le résultat : une commande qui se termine avec le code 0 n’a pas forcément produit une tâche réussie ;
• fixez des plafonds de dépense sur la clé dans la console.

spicyapi --json tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key poster-2026-09-17-v1 --yes --wait > result.json

Coûts, confirmation et sécurité

Quelles commandes coûtent de l’argent. Uniquement tasks create et tasks retry. Les prix sont en dollars américains. Demander un devis, lister, consulter, téléverser, télécharger et supprimer sont des opérations gratuites.

Voir le prix d’abord. tasks quote calcule le prix d’une requête sans rien lancer. tasks create obtient son propre devis et affiche Estimated charge et maximum charge avant de poser la question. Quand la tâche est acceptée, le montant estimé est mis de côté (held) et c’est aussi le maximum qui peut vous être facturé. Quand la tâche réussit, vous payez ce qui a réellement été produit, jamais plus que ce montant, et le reliquat revient sur votre solde.

La confirmation. Continue? [y/N] signifie que la réponse est non tant que vous ne tapez pas y. --yes répond à votre place : ne l’utilisez donc qu’une fois le prix connu. Si la CLI s’exécute dans un contexte où elle ne peut pas poser la question, comme un script ou une entrée redirigée, et qu’il n’y a pas de --yes, elle refuse au lieu de supposer un oui. tasks purge demande confirmation de la même façon, car une suppression est irréversible. tasks retry la demande aussi, mais sans afficher de prix au préalable.

La clé d’idempotence, en termes simples. C’est une étiquette pour une génération, comme un numéro de commande. Chaque tasks create et chaque tasks retry en affiche une. Si votre connexion internet coupe et que vous ne savez pas si la génération a démarré, relancez la même commande avec --idempotency-key et la valeur affichée : vous récupérez la tâche d’origine et vous n’êtes pas facturé deux fois. L’étiquette fonctionne pendant 24 heures avec la même clé API. Ne la réutilisez pas pour une autre génération : la même clé avec une entrée différente est refusée.

Pas d’annulation. Une fois acceptée, une tâche ne peut pas être annulée. Ctrl + C, la fermeture du terminal ou la révocation de la clé n’arrêtent que l’attente ; la tâche se termine et est facturée normalement.

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.

Téléchargez ce que vous voulez garder. Les fichiers de résultat sont conservés environ 14 jours au plus, ou moins si votre compte ou --retention le prévoit, puis supprimés définitivement. Les liens de téléchargement durent environ 20 minutes, mais vous pouvez toujours en demander un nouveau tant que le fichier existe. Les fichiers téléversés sont utilisables pendant un jour. Le texte des prompts est effacé au bout de 30 jours par défaut. Les enregistrements de facturation sont conservés. Voir Conservation et destruction.

Plafonds de dépense. Chaque clé peut avoir un plafond quotidien, mensuel et cumulé, à régler sur la page Clés API. Les nouvelles clés n’ont aucun plafond tant que vous n’en réglez pas un. Une tâche qui dépasserait un plafond est refusée avant de démarrer.

Votre clé. La CLI lit la clé uniquement dans SPICY_API_KEY, ne l’affiche jamais et, dans les indications d’erreur, n’en montre au plus que les neuf premiers caractères (sk-spicy-).

Pour aller plus loin : Facturation, Idempotence, Engagement et relance.

Dépannage

Cherchez le message que vous voyez. Les erreurs renvoyées par SpicyAPI se terminent par (request req_…) ; indiquez cette valeur si vous contactez l’assistance, mais n’envoyez jamais votre clé.

Tous les codes d’erreur sont expliqués dans Erreurs, et les étapes de reprise dans Dépannage et reprise.

Le code source

Le paquet est sous licence MIT et développé au grand jour sur github.com/spicyapi-ai/spicy-cli. C’est là qu’on lit le code derrière chaque commande de cette page, qu’on signale un comportement qui s’écarte de ce qui est décrit ici et qu’on propose une modification.

Étapes suivantes