Intégration en production

Servez-vous de cette page comme d’une liste de contrôle avant que de vrais utilisateurs ou de l’argent réel dépendent de votre intégration. Chaque section indique quoi faire, pourquoi c’est important et où trouver les détails. Si vous n’avez pas encore fait de premier appel, commencez par Préparer votre compte et le démarrage rapide.

Choisir un modèle et un protocole

• Choisissez un modèle que votre clé peut réellement appeler. Appelez GET /api/v1/models avec votre clé API et n’utilisez que les modèles dont enabled et available valent tous deux true. Lisez dans cette même réponse l’inputSchema du modèle (la liste des champs qu’il accepte) et ses examples. La page d’un modèle sur le site vous dit ce qu’il sait faire ; elle ne prouve pas que votre clé a le droit de l’appeler en ce moment. Voir Modèles et points de terminaison.
• Passez par le bon point d’entrée. Les tâches d’image, de vidéo et d’autres médias passent par l’API de tâches sous /api/v1 (createTask, puis recordInfo ou un callback). Les modèles de texte peuvent aussi être appelés par des clients compatibles OpenAI ou Anthropic sous /v1, ou par des clients compatibles Gemini sous /v1beta. Voir Texte et streaming.
• Authentifiez-vous uniquement avec une clé API. Un cookie de connexion à la console n’est pas un identifiant d’API et ne doit jamais être copié dans du code.

Protéger vos clés et votre solde

• Gardez la clé sur votre serveur. Placez-la dans une variable d’environnement (SPICY_API_KEY) de votre backend, jamais dans du code exécuté par le navigateur, dans une application mobile ou dans un dépôt public. Voir Authentification.
• Une clé par environnement et par service. Nommez chaque clé d’après ce qui l’utilise (par exemple « production-worker »), pour pouvoir en révoquer une sans arrêter les autres.
• Fixez des limites sur la clé de production : un plafond quotidien dimensionné pour une mauvaise journée, un budget mensuel, des modèles autorisés et, pour les appels côté serveur, une liste d’adresses IP autorisées. Voir les restrictions par clé. Quand vous modifiez une clé, rappelez-vous qu’un plafond vide signifie aucune limite.
• Surveillez les dates d’expiration. Une clé dotée d’une date d’expiration cesse de fonctionner à la fin de ce jour (UTC) et renvoie le même 401 qu’une clé révoquée. Notez la date dans votre agenda, ou n’en fixez pas pour un backend appelé à durer.
• Ne tombez pas à court d’argent au milieu d’un lot. Une tâche refusée faute de solde renvoie 40201 et n’est jamais mise en file d’attente. Activez l’Alerte de solde faible dans Notifications, et envisagez la recharge automatique.
• Les limites d’équipe s’appliquent aussi. Si votre clé appartient à une équipe, les limites quotidiennes et mensuelles de l’équipe peuvent bloquer des tâches avec 40202 même lorsque les plafonds propres à la clé ne sont pas atteints, et chaque tâche est payée sur le solde du propriétaire de l’équipe. Voir Plafonds de dépense.
• Planifiez le renouvellement de la clé de signature des webhooks. Renouveler la clé dans la console ne laisse aucune période de chevauchement : l’ancienne clé cesse immédiatement de signer. Les livraisons encore en cours de nouvelle tentative sont signées avec la nouvelle clé. Renouvelez-la pendant une période calme, déployez tout de suite la nouvelle clé sur votre récepteur, et rattrapez ce qui a été manqué avec recordInfo. Voir Webhooks.

Préparer les entrées sur votre serveur

• Validez par rapport au schéma actuel. Respectez les types de champs, les valeurs autorisées et les champs obligatoires sous condition définis dans inputSchema, et validez à nouveau après un changement de modèle : chaque modèle a le sien.
• Envoyez les médias par une voie prise en charge. Utilisez une URL https:// accessible publiquement ou une entrée Base64 prise en charge. Pour des fichiers locaux, demandez une URL de téléversement, envoyez les octets avec PUT, appelez files/{fileId}/commit, puis passez l’URI spicy:// renvoyée dans le champ d’entrée du modèle. Voir Médias.
• Utilisez chaque fichier téléversé pendant sa durée de vie. Une URI spicy:// fonctionne jusqu’à l’expiresAt indiqué dans la réponse de validation (1 jour par défaut). Ne demandez pas en masse des URL de téléversement que vous n’utiliserez jamais : celles qui restent inutilisées comptent dans une limite. Voir Limites de débit.

Demander un devis avant d’accepter une dépense

• Montrez le prix avant de dépenser de l’argent. Envoyez model, input et callBackUrl, au complet, à POST /api/v1/jobs/quote. Montrez estimatedCost, maxCharge, la devise (USD) et expiresAt à la personne qui paie. Un devis est gratuit : il ne crée aucune tâche et ne réserve aucun fonds.
• Soumettez ce qui a été confirmé. Un devis dure cinq minutes. Après confirmation, envoyez la même requête à createTask en y ajoutant quoteId et expectedCost.
• Gérez 40901. Ce code signifie que le devis a expiré, que l’entrée a changé ou que le prix a changé depuis le devis. Demandez un nouveau devis et affichez le nouveau montant ; n’acceptez jamais en silence un montant plus élevé. Voir Devis.
• Gardez des montants exacts. Les montants sont des chaînes décimales comme "0.008". Stockez-les et additionnez-les avec une arithmétique décimale, pas en virgule flottante. Voir Facturation.

Garder la trace de l’opération métier

Ce sont vos propres enregistrements qui vous permettent de vous rétablir quand un appel réseau échoue à mi-parcours.

• Enregistrez avant l’envoi : votre propre identifiant de commande ou d’opération, une courte description de la requête sans secret ni prompt complet (de quoi la reconnaître plus tard), et l’Idempotency-Key que vous allez envoyer.
• Enregistrez après l’acceptation : le taskId et le request_id de la réponse.
• Réutilisez la clé pour la même soumission. Renvoyez l’Idempotency-Key d’origine pour le même compte, la même clé API et la même requête dans les 24 heures : vous récupérez la tâche d’origine au lieu d’être facturé une seconde fois. Voir Idempotence.
• Traitez un dépassement de délai comme « inconnu », pas comme « échoué ». Récupérez la soumission d’origine avec sa clé avant de décider d’en créer une nouvelle. Voir Dépannage et reprise.
• Sachez ce que coûte une relance. Relancer une tâche déjà échouée crée une nouvelle tâche, aux conditions et aux prix du moment.

Traiter les callbacks et les résultats de façon fiable

• Vérifiez chaque callback. Contrôlez la signature et l’horodatage sur les octets bruts de la requête avant de l’analyser, puis dédupliquez et enregistrez l’événement. Voir Webhooks.
• Accusez réception rapidement. Répondez immédiatement par un 2xx et effectuez les traitements lents dans votre propre file d’attente.
• Attendez-vous à des doublons et à des retards. Décidez quoi faire en fonction du state de la tâche, pas de l’ordre d’arrivée des callbacks.
• Gardez le polling comme solution de secours. Si un callback tarde, lisez recordInfo avec des pauses de plus en plus longues plutôt que toutes les secondes.
• Lisez le bon signal. Le HTTP 202 renvoyé par createTask signifie que la tâche a été acceptée. state: "succeeded" signifie que la génération est terminée. settled: true signifie que le montant facturé est définitif.

Limiter la concurrence et conserver les résultats

• Limitez le nombre de tâches en cours par compte, et fixez des échéances à vos propres requêtes. Chaque tâche acceptée réserve des fonds jusqu’à son règlement.
• Respectez Retry-After en cas de 429, et évitez que de nombreux clients interrogent le service toutes les secondes, tous au même rythme. Voir Limites de débit.
• Mettez les données du catalogue en cache brièvement et en privé, et ne traitez jamais un devis comme une grille tarifaire permanente.
• Archivez les résultats que vous devez garder. Les liens de téléchargement durent 20 minutes ; les médias générés sont conservés au plus environ 14 jours et les téléversements un jour. Vous pouvez raccourcir ces durées, ou supprimer plus tôt le contenu d’une tâche avec POST /api/v1/jobs/purge. Raccourcir une durée de conservation peut aussi supprimer les résultats de tâches déjà exécutées — voir Conservation.
• Ne comptez pas sur une déconnexion pour arrêter le travail. Une tâche acceptée continue de s’exécuter et ne peut pas être annulée.

Valider avant le lancement

Commencez par les appels gratuits : le catalogue (GET /api/v1/models), votre solde (GET /api/v1/chat/credit) et un devis. Lancez ensuite une vraie génération, de petite taille, en passant par votre propre parcours de confirmation des coûts : elle est facturée comme n’importe quelle autre tâche. Vérifiez que votre intégration gère chacun des cas suivants :

Journalisez request_id, taskId, l’heure, le state et les montants. Tenez les clés API et les prompts complets à l’écart des journaux généraux.

Parcours associés

Devis et compatibilité des protocoles · Modèles et points de terminaison · Médias · Webhooks · Erreurs · Dépannage et reprise · Facturation · Conservation