Authentification

Chaque appel API qui crée, lit ou facture quoi que ce soit transmet votre clé API dans l’en-tête Authorization. Le catalogue public utilisé pour évaluer les modèles est la seule exception : il ne nécessite pas de clé.

Authorization: Bearer sk-spicy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

L’API native (/api/v1/*) accepte uniquement les clés bearer : ni cookies ni paramètres d’URL.

Les points de terminaison compatibles de texte et de vidéo (/v1, /v1beta) utilisent la même clé et acceptent aussi l’en-tête x-api-key des SDK Anthropic et l’en-tête x-goog-api-key des SDK Google GenAI. Les SDK officiels fonctionnent ainsi en ne changeant que l’URL de base ; voir Texte et streaming. Ces deux en-têtes sont sans effet sur /api/v1, et aucun point de terminaison n’accepte une clé dans les paramètres de l’URL.

Les clés API et la console sont distinctes

Seuls /api/v1, /v1 et /v1beta acceptent les clés API. La console web utilise sa propre session de navigateur. Une connexion à la console ne sert donc pas de clé API, et une clé API divulguée ne permet pas de se connecter à votre console. Envoyer le mauvais type d’identifiant renvoie toujours 401, jamais une erreur de permissions.

Le format d’une clé

Un préfixe fixe sk-spicy-, suivi de 48 caractères hexadécimaux minuscules.

Le préfixe est volontaire : mieux vaut une détection suivie d’une notification que découvrir la fuite après que quelqu’un a dépensé votre solde.

Créer une clé

1. Ouvrez Console → Clés API et cliquez sur Créer une clé.
2. Nommez-la selon le service qui l’utilisera (production backend, staging worker). Vous devrez la reconnaître pour la révoquer.
3. Vous pouvez ouvrir Avancé pour définir des plafonds de dépenses, une liste de modèles autorisés, une liste d’IP autorisées et une date d’expiration. Vous pourrez tout modifier ensuite.
4. Copiez la clé ou cliquez sur Enregistrer dans un fichier, puis confirmez que vous l’avez conservée. Une fois la fenêtre fermée, elle ne peut plus être affichée.

La création de clés exige un rôle de propriétaire, administrateur ou développeur dans l’équipe. La clé appartient à l’équipe sélectionnée en haut à gauche de la console : son utilisation et ses plafonds sont comptés pour cette équipe. Chaque équipe peut avoir jusqu’à 50 clés actives. Votre compte doit aussi avoir une adresse e-mail vérifiée et un solde avant que la clé puisse exécuter des tâches payantes ; voir Configuration du compte.

Où conserver la clé

• Sur votre ordinateur, pour les tests : export SPICY_API_KEY="…" dans le terminal, valable jusqu’à la fermeture de la fenêtre, ou un fichier .env chargé par votre code. Ajoutez .env à .gitignore avant votre premier commit.
• Sur un serveur ou une plateforme d’hébergement : utilisez ses réglages de secrets ou de variables d’environnement et lisez SPICY_API_KEY dans l’environnement de votre code.
• Ne collez jamais la clé dans le code source, une conversation, une capture d’écran, un ticket de support ou le prompt d’un assistant IA.

Ne transmettez jamais une clé au client

La même règle vaut pour les binaires mobiles, les clients de bureau, les notebooks publics, les journaux CI et tout contenu d’une sortie curl -v collée dans un ticket de support.

Vos propres outils dans votre propre navigateur sont un autre cas. L’API accepte les appels depuis un navigateur. Des outils personnels tels que l’extension SillyTavern ou une application de roleplay où vous collez votre propre clé peuvent l’appeler directement. La règle précédente concerne une clé intégrée dans ce que d’autres personnes chargent. Donnez à chaque outil sa propre clé avec un plafond quotidien pour suivre ses dépenses et la révoquer séparément.

Restrictions par clé

Configurez-les dans la console, à la création de la clé ou plus tard. Elles sont appliquées côté serveur.

La carte de chaque clé affiche ses plafonds actuels, que vous pouvez modifier à tout moment.

Les plafonds comptent les fonds réservés pour les tâches en cours aussi bien que ceux déjà dépensés. Une clé peut donc atteindre son plafond avant la fin des tâches. Le msg indique le plafond atteint. Un 40202 dont le msg mentionne le quota de la plateforme ne concerne pas votre clé : en créer une autre ne changera rien ; réessayez plus tard.

La liste d’IP autorisées est comparée à votre véritable adresse publique vue par notre réseau périphérique, pas à l’adresse du dernier proxy. Votre adresse de sortie est l’IP publique d’où partent les requêtes de votre serveur. La plupart des hébergeurs la listent dans les réglages réseau ; sur votre propre machine, curl https://ifconfig.me l’affiche.

Les tâches appartiennent à la clé qui les a créées

Une tâche est visible par l’API uniquement avec la clé API qui l’a créée. Avec toute autre clé, même de la même équipe :

Deux éléments ne dépendent pas de la clé. Les webhooks d’une tâche sont livrés même après révocation de la clé qui l’a créée. Et toutes les tâches de l’équipe, quelle que soit leur clé de création, figurent dans Console → Journaux, avec la Clé utilisée dans leur détail.

Rotation

• Une clé par environnement (production / test / local), pour pouvoir en révoquer une sans toucher aux autres.
• Rotation planifiée : créez la nouvelle clé et utilisez-la uniquement pour les nouvelles tâches. Gardez l’ancienne active jusqu’à ce que toutes ses tâches aient atteint un état terminal, au plus tard à leur deadlineAt, et que vous ayez récupéré leurs résultats, puis révoquez-la. Suivez cet ordre uniquement si l’ancienne clé reste fiable.
• La révocation est immédiate et irréversible. Aucun cache à attendre, aucune possibilité de réactiver la clé : vous en créez une nouvelle.

Après une fuite

En cas de dépenses inattendues, contactez-nous dans Console → Support avec les IDs de tâches ou les valeurs request_id.

À quoi ressemble un échec

{
  "code": 401,
  "msg": "Credentials are invalid or expired",
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

Le statut HTTP est aussi 401. Tout échec d’authentification renvoie code: 401, et msg précise son type :

Utilisez code pour vos décisions, pas le texte : sa formulation peut changer et suit votre langue d’erreur. Voir Erreurs pour mieux les distinguer.

Lorsque le compte lui-même ne peut pas appeler l’API, par exemple adresse e-mail non vérifiée ou compte suspendu, vous recevez plutôt 403. Changer de clé ne résout pas ce cas.