Agents et automatisation

Ce guide s’adresse aux agents de code IA et aux backends automatisés qui intègrent SpicyAPI. Il transforme la référence API en un parcours borné, reprenable et vérifiable : découvrir le contrat, valider l’entrée, créer une seule fois, attendre sans boucle infinie, confirmer l’état final et conserver les sorties avant expiration.

Points de découverte lisibles par machine

Commencez par le plus petit artefact qui répond à la question. Vous économisez ainsi du contexte et limitez les hypothèses périmées.

OpenAPI et le catalogue de modèles à jour constituent le contrat. Les exemples marketing ne sont pas une source de Schema. Rafraîchissez les documents de découverte avant de générer du code et dès qu’une validation commence à échouer.

Intégrations npm officielles

Le SDK, la CLI, MCP et le Skill Agent portable sont quatre paquets npm MIT indépendants. Installez uniquement la surface nécessaire. @spicyapi/skill suit le format portable Agent Skills et n’est pas réservé à Codex.

npm install @spicyapi/sdk
npx --yes --package=@spicyapi/cli spicyapi --help
npx --yes --package=@spicyapi/mcp spicyapi-mcp
npx --yes --package=@spicyapi/skill spicyapi-skill install

Le Skill s’installe par défaut dans ~/.agents/skills/spicyapi. Pour un Agent utilisant un autre dossier Skills, indiquez la destination exacte avec --target /chemin/exact/spicyapi.

L’utiliser dans un agent de code

Le serveur MCP tourne en local via stdio et donne à l’agent le catalogue de modèles, les devis, la création de tâches et la récupération des résultats. Toute action facturable s’arrête sur une confirmation que l’agent ne peut pas contourner. Voici la forme recommandée par chaque client aujourd’hui ; l’emplacement et le format de la configuration sont définis par le client et évoluent d’une version à l’autre, la documentation de l’éditeur fait donc foi.

Claude Code

claude mcp add spicyapi \
  -e SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

npx --yes --package=@spicyapi/skill spicyapi-skill install \
  --target ~/.claude/skills/spicyapi

Codex CLI

codex mcp add spicyapi \
  --env SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp

npx --yes --package=@spicyapi/skill spicyapi-skill install \
  --target ~/.codex/skills/spicyapi

Les deux commandes recopient SPICY_API_KEY depuis votre shell courant dans la configuration locale du client. Exécutez-les dans un terminal où la clé est déjà exportée. Elle reste sur votre machine : ne la versionnez jamais.

Cursor, Windsurf et Gemini CLI

Leurs fichiers de configuration sont respectivement ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json et ~/.gemini/settings.json, avec la même structure :

{
  "mcpServers": {
    "spicyapi": {
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "YOUR_SERVER_SIDE_KEY" }
    }
  }
}

Ce sont des fichiers utilisateur, hors de votre dépôt. Une fois YOUR_SERVER_SIDE_KEY remplacé par une vraie clé, ne recopiez jamais ce bloc dans un fichier de projet versionné.

VS Code

.vscode/mcp.json est versionné avec votre dépôt : la clé ne doit donc pas s’y trouver. Laissez VS Code demander la valeur au premier démarrage et la conserver dans son propre coffre :

{
  "inputs": [
    {
      "id": "spicyapi-key",
      "type": "promptString",
      "description": "SpicyAPI key",
      "password": true
    }
  ],
  "servers": {
    "spicyapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"],
      "env": { "SPICY_API_KEY": "${input:spicyapi-key}" }
    }
  }
}

Une fois connecté

Confiez directement une vraie tâche à l’agent :

Avec SpicyAPI, liste les modèles d’image que je peux appeler, choisis-en un peu coûteux, génère un portrait nocturne cinématographique et donne-moi le lien du résultat une fois terminé.

L’agent lit le catalogue, récupère le schéma du modèle et obtient un devis exact, puis s’arrête pour votre confirmation avant toute facturation. Avec le Skill installé, il conserve aussi une seule clé d’idempotence et lit les liens de résultat déjà prêts au lieu d’interroger en boucle.

Parcours de production

1. Résoudre le modèle et son entrée. Choisissez l’endpoint correspondant à la modalité et validez avec son Schema actuel. Ne devinez pas les champs et ne supprimez pas silencieusement les champs inconnus.
2. Créer une seule fois. Créez un Idempotency-Key stable pour chaque génération logique et persistez-le avant le premier appel. Réutilisez la même valeur pour renvoyer la même requête dans les 24 heures. Une nouvelle génération nécessite une nouvelle clé. Voir Idempotence.
3. Persister immédiatement taskId. C’est l’identité durable commune au suivi, au rapprochement Webhook, au support et à la facturation. Une relance peut retourner le même ID : elle ne doit pas créer un second enregistrement local.
4. Attendre avec une limite. Préférez un Webhook signé. Pour le polling, partez par exemple de 2 secondes, multipliez par 1,5, plafonnez à 15 secondes et fixez une échéance globale. succeeded, failed, canceled et expired sont terminaux.
5. Vérifier le callback avant de l’utiliser. Contrôlez X-Webhook-Timestamp, l’empreinte du corps brut et la signature HMAC. Dédupliquez avec le request_id de livraison, répondez rapidement en 2xx puis traitez en file. Voir Webhooks.
6. Copier la sortie utile. Utilisez directement l’URL signée dans output.assets[].url et copiez les fichiers à conserver dans votre propre stockage. L’appel permettant de convertir une clé d’objet en URL reste facultatif. L’URL expire actuellement après 20 minutes. Consultez aussi Médias et Conservation.

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

const deadline = Date.now() + 10 * 60_000;
let delay = 2_000;
while (Date.now() < deadline) {
  await sleep(delay);
  const task = await recordInfo(taskId);
  if (['succeeded', 'failed', 'canceled', 'expired'].includes(task.state)) return task;
  delay = Math.min(Math.round(delay * 1.5), 15_000);
}
throw new Error(`task ${taskId} exceeded the polling deadline`);

Un timeout local ne prouve pas l’échec de la génération. Conservez taskId et rapprochez l’état plus tard. De même, HTTP 200 ne signifie pas que le média a réussi : lisez data.state.

Enregistrement durable minimal

Conservez localRequestId, idempotencyKey, taskId, model, state, lastCheckedAt, webhookDeliveryId et outputKeys afin de reprendre après un redémarrage. Une URL de téléchargement temporaire ne doit jamais servir d’identifiant durable.

Mock et recette

Construisez un mock contractuel local à partir des enveloppes de Tâches, Webhooks et Erreurs. Il doit couvrir au minimum :

• queued → running → succeeded et un échec terminal où code: 200 mais data.state: "failed" ;
• deux créations qui retournent le même taskId ;
• une signature valide, une signature invalide et une livraison rejouée ;
• 429, 503, un timeout réseau et le dépassement de l’échéance de polling ;
• la réémission d’une URL de téléchargement expirée.

Le mock vérifie l’orchestration, pas la qualité du modèle. Avant la mise en ligne, exécutez une petite tâche réelle avec le modèle et la forme d’entrée exacts de production.

Checklist de mise en production

• Les secrets vivent uniquement dans le coffre serveur et sont masqués dans les logs.
• L’intégration lit le Schema actuel du modèle au lieu d’inventer des champs.
• Une requête logique possède un seul Idempotency-Key persisté.
• taskId est sauvegardé avant la suite et survit à un redémarrage.
• Le polling possède backoff, intervalle maximum et échéance globale.
• Les Webhooks vérifient horodatage, corps brut et HMAC, puis dédupliquent les livraisons.
• L’état final vient de data.state, pas du statut HTTP ni du code de l’enveloppe.
• Les sorties sont copiées avant expiration et les clés d’objet restent la référence durable.
• Les logs gardent request_id, taskId, modèle et numéro d’essai, sans secret ni prompt complet.

Demandez enfin à l’agent de restituer l’endpoint retenu, l’heure de lecture du Schema, la stratégie d’idempotence, l’échéance de polling, la méthode de vérification Webhook et cette checklist complétée.