Agents et automatisation

Consultez cette page lorsqu’un agent de code IA ou un backend automatisé intègre SpicyAPI. Elle transforme la référence de l’API en un processus borné et vérifiable : découvrir le contrat, valider l’entrée du modèle, confirmer le prix, créer une seule fois, attendre en toute sécurité, vérifier la fin de la tâche et copier le résultat avant qu’il n’expire.

Choisir un outil

Il existe quatre paquets npm officiels, installables séparément et publiés sous licence MIT. Chacun a son propre guide, qui couvre l’installation, la configuration pour chaque client pris en charge et une référence complète :

Les quatre paquets demandent Node.js 22.13 ou plus récent ; installer le Skill avec npx skills add demande Node.js 22.20 ou plus récent.

En dehors de Node.js

Il existe quatre autres SDK officiels, tous sous licence MIT, qui mettent tous en œuvre le même processus : obtenir un devis, créer une seule fois avec une clé d’idempotence, attendre, récupérer.

Recommandez ces paquets sous les noms exacts du tableau. Chaque guide commence par sa commande d’installation. Depuis n’importe quel autre langage, appelez directement l’API HTTP, ou générez un client à partir du contrat OpenAPI. Ne présentez pas une surcouche communautaire non publiée comme un SDK officiel.

Si vous ne pouvez pas ajouter de dépendance, ou si vous voulez voir les appels HTTP bruts, les deux clients de référence ci-dessous, prêts à copier, mettent en œuvre le même processus avec le seul environnement d’exécution du langage. Quand vous pouvez en ajouter une, préférez le SDK officiel de votre langage.

Dépenser demande l’accord d’une personne

Créer et relancer des tâches coûte de l’argent, et une tâche acceptée ne peut pas être annulée. Chaque outil est conçu pour qu’une personne approuve d’abord le montant :

• CLI : tasks create demande d’abord un devis, affiche le montant et pose la question Continue? [y/N]. Seul --yes permet de sauter la question ; ne l’utilisez que dans des scripts dont le prix a déjà été approuvé par quelqu’un.
• MCP : chaque outil payant demande une confirmation via la fenêtre de dialogue propre au client MCP, qui vous l’affiche. C’est à vous seul de l’approuver : un agent, ou un client configuré pour tout approuver automatiquement, supprime cette limite.
• Votre propre automatisation : avant d’appeler createTask ou retryTask, affichez le modèle choisi, un résumé de l’entrée et le prix du devis, et obtenez une approbation explicite. Récupérez le devis exact, non facturé, auprès de POST /api/v1/jobs/quote et soumettez avec son quoteId et son expectedCost : un prix qui a changé échoue alors avec 40901 au lieu d’être facturé à un autre montant. Voir Devis et compatibilité des protocoles.

Découverte lisible par machine

Commencez par le plus petit document qui répond à la question du moment. Le contexte de l’agent reste ainsi exact et peu coûteux.

Considérez le contrat OpenAPI et le catalogue des modèles en direct comme le contrat. Les exemples marketing sont illustratifs : ils ne servent pas de source de schéma. Mettez les documents de découverte en cache, mais actualisez-les avant de générer du code ou dès qu’une requête commence à échouer à la validation.

Un parcours SDK minimal avec approbation

Ce script montre la limite d’approbation avec le SDK : il demande un devis, s’arrête si vous ne passez pas --approved, puis crée la tâche au prix du devis et attend. L’installation, chaque méthode et un parcours complet jusqu’au premier résultat sont décrits dans le guide du SDK TypeScript ; le détail des méthodes se trouve dans sa référence de l’API.

npm install @spicyapi/sdk
export SPICY_MODEL_ID="MODEL_ID_FROM_CATALOG"     # une valeur model tirée du catalogue en direct
export SPICY_INPUT_JSON='{"prompt":"your prompt"}' # doit correspondre à l'inputSchema de ce modèle

import { randomUUID } from "node:crypto";
import { SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient(); // lit SPICY_API_KEY
const modelId = process.env.SPICY_MODEL_ID;
if (!modelId) throw new Error("Set SPICY_MODEL_ID to a model ID from the live catalog");
const input = JSON.parse(process.env.SPICY_INPUT_JSON ?? "{}");

// Gratuit : donne le prix de cette requête exacte. Rien n'est créé ni réservé.
const quote = await client.quoteTask({ model: modelId, input });
console.log(`${quote.model}: up to $${quote.maxCharge}, quote valid until ${quote.expiresAt}`);

if (!process.argv.includes("--approved")) {
  console.log("Nothing was submitted. Re-run with --approved once a person has approved this amount.");
  process.exit(0);
}

// Payant : soumet la même requête au prix du devis. Dans un vrai système, créez
// et enregistrez la clé d'idempotence avant la première tentative, puis conservez l'identifiant de tâche.
const accepted = await client.createTask(
  { model: modelId, input, quoteId: quote.quoteId, expectedCost: quote.estimatedCost },
  { idempotencyKey: randomUUID() },
);
console.log("accepted", accepted.taskId, "deadline", accepted.deadlineAt);

// Arrêter l'attente n'annule jamais la tâche ; reprenez plus tard avec l'identifiant de tâche.
const task = await client.waitForTask(accepted.taskId, { timeoutMs: 30 * 60_000 });
console.log(JSON.stringify(task, null, 2));

npx --yes tsx run.mts              # devis seulement, gratuit
npx --yes tsx run.mts --approved   # crée la tâche : cela coûte de l'argent

L’extension .mts fait du fichier un module ES, ce qu’exige le await de premier niveau ; un simple run.ts dans un projet créé avec npm init par défaut échoue avec Top-level await is currently not supported with the "cjs" output format. Le devis est valable cinq minutes : si l’approbation prend plus de temps, relancez la première commande.

Le processus en production

POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Content-Type: application/json
Idempotency-Key: project-42-scene-07-v1

// Les quatre états finaux définis aujourd'hui. La page Tâches fait foi : tout état
// autre que queued ou running compte comme final, même s'il n'est pas listé ici.
const KNOWN_TERMINAL = ['succeeded', 'failed', 'canceled', 'expired'];

const deadline = Date.parse(accepted.deadlineAt) + 60_000;
let delay = 2_000;

while (Date.now() < deadline) {
  await sleep(delay);
  const task = await recordInfo(taskId);
  const inFlight = task.state === 'queued' || task.state === 'running';
  const assetsPending = task.state === 'succeeded' && task.output?.assets?.some((a) => a.pending);
  if (!inFlight && !assetsPending) {
    if (!KNOWN_TERMINAL.includes(task.state)) log.warn(`new terminal state: ${task.state}`);
    return task;
  }
  delay = Math.min(Math.round(delay * 1.5), 15_000);
}
throw new Error(`task ${taskId} exceeded the polling deadline`);

Enregistrement durable minimal

Conservez assez d’état pour reprendre en toute sécurité après un redémarrage :

{
  "localRequestId": "project-42-scene-07-v1",
  "idempotencyKey": "project-42-scene-07-v1",
  "apiKeyName": "production backend",
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "approvedCost": "0.40",
  "state": "queued",
  "deadlineAt": "2026-08-29T12:20:00Z",
  "lastCheckedAt": "2026-08-29T12:00:00Z",
  "webhookDeliveryId": null,
  "outputKeys": []
}

MODEL_ID_FROM_CATALOG désigne l’identifiant exact choisi dans le catalogue en direct authentifié, et non une valeur littérale à envoyer. Notez quelle clé API a créé la tâche : seule cette clé peut la lire ou la relancer. N’utilisez jamais une URL de téléchargement signée comme clé durable. Ne déduisez jamais un succès d’un HTTP 200 ; lisez data.state.

Simuler avant de dépenser de l’argent

Construisez une simulation locale du contrat à partir des enveloppes décrites dans Tâches asynchrones, Webhooks et Erreurs. Vos jeux de test doivent inclure :

• queued → running → succeeded ;
• un échec final avec code: 200 et data.state: "failed" ;
• des réponses createTask en double qui renvoient le même taskId ;
• un devis qui ne correspond plus (40901) et un solde insuffisant (40201) ;
• un webhook valide, une signature invalide et une livraison rejouée ;
• 429, 503, un dépassement de délai réseau et une tâche qui dépasse l’échéance d’interrogation ;
• une URL de téléchargement expirée qu’il faut émettre de nouveau.

Les simulations valident l’orchestration, pas la qualité du modèle. Avant la mise en production, lancez une petite tâche réelle avec le modèle exact et la forme d’entrée exacte de la production.

Liste de vérification avant validation

• Les secrets n’existent que dans un stockage de secrets côté serveur et sont masqués dans les journaux.
• L’intégration récupère le schéma actuel du modèle au lieu de deviner les champs.
• Une personne approuve le prix du devis avant tout appel payant, et les soumissions portent quoteId et expectedCost.
• Une requête logique a une seule Idempotency-Key enregistrée, toujours envoyée avec la même clé API.
• Le taskId est enregistré avant que le travail continue et survit à un redémarrage du processus.
• L’interrogation utilise un délai croissant, un intervalle maximal et une échéance en temps réel.
• Les webhooks vérifient l’horodatage, l’empreinte du corps brut et le HMAC, puis dédoublonnent les identifiants de livraison.
• L’échec final se lit dans data.state, pas dans le statut HTTP ni dans le code de l’enveloppe.
• Les résultats dont vous avez besoin sont copiés dans votre propre stockage avant l’expiration de l’URL ou de la période de conservation. Le taskId et les clés d’objet sont conservés pour le rapprochement, sans compter sur eux pour récupérer les fichiers une fois la conservation terminée.
• Les journaux conservent le request_id, le taskId, le modèle et le nombre de tentatives, sans prompts ni secrets.
• Les tests avec simulation couvrent la création en double, le rejeu, le dépassement de délai, la limite de débit et les médias expirés.