Une clé API Perplexity est le credential que vous envoyez à chaque requête à api.perplexity.ai. Elle identifie votre projet, débite votre solde de crédit prépayé et définit votre niveau de limite de débit. Si vous n'en avez jamais utilisé auparavant, notre introduction sur ce qu'est une clé API en couvre les bases. Ce guide couvre la partie spécifique à Perplexity : la création du compte, l'ajout de crédits, la génération de la clé et l'envoi de votre première requête Sonar contextualisée depuis curl, Python et Apidog.
Une note sur le timing avant de commencer. Perplexity a migré Sonar vers son API Agent, et le guide de démarrage rapide officiel y renvoie désormais. L'ancien point d'accès Sonar chat-completions continuera de fonctionner jusqu'au 27 septembre 2026, puis sera retiré. Chaque exemple ci-dessous utilise le point d'accès actuel, avec une brève note sur la forme héritée au cas où vous maintiendriez du code plus ancien.
Ce dont vous avez besoin avant de commencer
- Un compte Perplexity. Google, Apple, SSO ou une connexion par e-mail sans mot de passe fonctionnent tous et se résolvent au même compte par adresse e-mail.
- Une carte de paiement. L'API est un service payant à l'utilisation sans abonnement, mais les requêtes échouent une fois que votre solde de crédits atteint zéro.
- curl ou Python 3.9+ pour la première requête.
- Apidog si vous souhaitez que la clé soit stockée en tant que secret local et que la requête soit enregistrée en tant que test répétable.
Étape 1 : Connectez-vous à la console API et créez un projet
Allez sur console.perplexity.ai et choisissez une méthode de connexion. La connexion crée un compte Perplexity, mais pas un projet API. Lors de votre première visite, l'assistant de configuration vous invite à créer ou à rejoindre un projet avant de pouvoir générer une clé, car les clés sont associées à des projets.
Ouvrez les Paramètres dans la barre latérale gauche et remplissez le nom, l'adresse et les détails fiscaux de votre organisation ; ils figureront sur vos factures. Si votre entreprise a déjà un projet, demandez à un administrateur de vous y ajouter au lieu d'en créer un second. Des projets distincts obtiennent des soldes de crédits et des clés distincts, ce qui est utile pour isoler une application de production d'une expérimentation.
Étape 2 : Ajoutez un mode de paiement et des crédits
Ouvrez la page de facturation et ajoutez une carte. Selon la documentation, l'ajout d'un mode de paiement ne débite pas la carte ; il stocke les détails pour une utilisation future. Ensuite, achetez des crédits. Le solde, les détails d'utilisation par modèle et l'historique des factures se trouvent tous sur cette page.
Deux détails sont importants ici. L'API est facturée à partir de crédits prépayés, et si le solde s'épuise, vos clés sont bloquées jusqu'à ce que vous réapprovisionniez. La documentation décrit cet échec comme une 401, et non une 402, de sorte qu'une application à court de crédits ressemble à un bug d'authentification au premier coup d'œil. Et à côté de Rechargement automatique, cliquez sur Modifier les préférences pour que la console ajoute automatiquement des crédits lorsque le solde passe sous un seuil que vous avez défini. Activez cette option avant que quoi que ce soit ne passe en production.
La documentation ne publie pas de montant d'achat minimum, fiez-vous donc à ce que la page de facturation vous indique. Votre niveau d'utilisation, qui définit vos limites de débit, est basé sur les crédits cumulés achetés sur la durée de vie du compte, et non sur le solde actuel.
Étape 3 : Générez la clé API
Ouvrez la page des clés API dans la console et créez une clé. Donnez-lui un nom descriptif tel que dev-laptop ou prod-search-worker. Après la création, le nom est le seul moyen de distinguer les clés, car la valeur complète n'est affichée qu'une seule fois et ne peut pas être récupérée à nouveau. Copiez-la immédiatement.
Placez la clé dans une variable d'environnement, jamais dans le code :
export PERPLEXITY_API_KEY="pplx-your-key-here"
Sous Windows, utilisez setx PERPLEXITY_API_KEY "pplx-your-key-here" et ouvrez un nouveau terminal.
Vous pouvez créer plusieurs clés au sein d'un même projet, alors créez-en une par environnement et par service. La révocation d'une clé est permanente, ce que vous voulez lorsqu'une clé fuit. Si vous n'êtes pas sûr qu'une clé ait déjà fui dans un dépôt, exécutez un scanner de secrets sur votre historique Git avant de la faire pivoter.
Étape 4 : Effectuez votre première requête Sonar
Le point d'accès actuel est POST https://api.perplexity.ai/v1/agent. L'authentification est un en-tête bearer standard, Authorization: Bearer $PERPLEXITY_API_KEY. Le corps prend un model et une chaîne input. L'ID du modèle Sonar sur ce point d'accès est perplexity/sonar, et l'ajout de l'outil web_search lui indique de rechercher sur le web en direct et de joindre les sources.
Posez-lui une question avec une vraie réponse qui change avec le temps :
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "perplexity/sonar",
"input": "Which Node.js release line is currently Active LTS, and when does it reach end of life?",
"tools": [{ "type": "web_search" }]
}' | jq
La réponse contient output_text, la réponse en texte brut, et un tableau output avec un élément par étape que le modèle a effectuée. L'élément message contient la réponse ; l'élément search_results liste les pages qu'il a lues, chacune avec une url, un title, un snippet et une date. L'objet usage rapporte le nombre de jetons et le coût. Un status de completed signifie que l'exécution est terminée.
La même requête en Python avec le SDK officiel :
pip install perplexityai
from perplexity import Perplexity
client = Perplexity() # reads PERPLEXITY_API_KEY from the environment
response = client.responses.create(
model="perplexity/sonar",
input="Quelle version de Node.js est actuellement Active LTS, et quand atteint-elle la fin de vie ?",
tools=[{"type": "web_search"}],
)
print(response.output_text)
Si vous préférez le SDK OpenAI, définissez base_url="https://api.perplexity.ai/v1" et appelez client.responses.create() avec les mêmes arguments. Le SDK le route vers /v1/responses, que Perplexity accepte comme alias. Les préréglages (fast, low, medium, high, xhigh) regroupent un modèle, des budgets de jetons et des outils pour vous ; sur le SDK OpenAI, vous les passez via extra_body.
Si vous utilisez l'ancienne forme de chat-completions
Le code plus ancien envoie des messages à https://api.perplexity.ai/v1/sonar avec les ID de modèle sonar, sonar-pro, sonar-reasoning-pro ou sonar-deep-research, et lit choices[0].message.content. Cette forme fonctionne jusqu'au 27 septembre 2026. Le guide de migration mappe sonar à perplexity/sonar, sonar-pro à perplexity/sonar avec le préréglage low, et la recherche approfondie au préréglage high. Les options search_domain_filter et search_recency_filter se déplacent à l'intérieur de l'outil web_search sous la forme d'un objet filters.
Étape 5 : Stockez la clé et enregistrez la requête dans Apidog
Une commande curl qui fonctionne une fois n'est pas un test. Voici la configuration que nous utilisons dans Apidog afin que la clé reste hors du cloud et que la requête s'exécute à la demande.
Créez un environnement. Ajoutez un environnement nommé Perplexity avec deux variables : base_url défini sur https://api.perplexity.ai comme valeur partagée, et PERPLEXITY_API_KEY avec la valeur partagée laissée comme espace réservé et la clé réelle uniquement dans la valeur locale. Les valeurs locales résident dans le cache de votre client et ne sont jamais synchronisées avec vos coéquipiers, ce qui est tout l'intérêt. Notre guide sur les environnements et variables secrètes dans Apidog approfondit la division entre partagé et local.
Construisez la requête. Nouvelle requête, POST {{base_url}}/v1/agent. Ajoutez un en-tête Authorization: Bearer {{PERPLEXITY_API_KEY}}, définissez le type de corps sur JSON et collez le même corps que la commande curl ci-dessus. Sélectionnez l'environnement Perplexity et cliquez sur Envoyer. Vous devriez voir le output_text et le bloc search_results dans le panneau de réponse.
Transformez-le en test. Ajoutez trois assertions : le code de statut est 200, $.status est égal à completed, et $.output_text n'est pas vide. Enregistrez la requête dans un scénario de test. Maintenant, n'importe qui dans l'équipe peut récupérer le projet, coller sa propre clé dans la valeur locale et vérifier sa configuration en un clic. Faire pivoter la clé signifie modifier un champ, pas chercher à travers des scripts.
Si vous ne l'avez pas encore, Téléchargez Apidog gratuitement ; le plan gratuit couvre quatre utilisateurs, suffisant pour qu'une petite équipe partage le projet.
Limites de débit et coût d'une requête
Les limites de débit sur l'API Agent évoluent avec votre niveau d'utilisation, et les niveaux sont définis par les achats de crédits cumulés, selon la page des limites de débit :
| Niveau | Crédits achetés | Requêtes par seconde | Requêtes par minute |
|---|---|---|---|
| 0 | $0 | 1 | 50 |
| 1 | $50+ | 3 | 150 |
| 2 | $250+ | 8 | 500 |
| 3 | $500+ | 17 | 1,000 |
| 4 | $1,000+ | 33 | 4,000 |
| 5 | $5,000+ | 33 | 8,000 |
Les limites utilisent un algorithme de "leaky-bucket", de sorte que de courtes rafales jusqu'à la limite passent. Lorsque vous la dépassez, l'API renvoie un 429 avec un en-tête Retry-After, et les requêtes rejetées ne sont pas facturées. Votre niveau actuel s'affiche sur la page de tarification de la console, sous l'onglet des niveaux d'utilisation.
En ce qui concerne la tarification, un paragraphe suffit ici. La page de tarification liste perplexity/sonar sur l'API Agent à 0,25 $ par million de jetons d'entrée et 2,50 $ par million de jetons de sortie, plus 0,0025 $ par invocation de web_search. Les modèles Sonar chat-completions hérités sont facturés différemment : sonar à 1 $ par million de jetons en entrée et en sortie, plus 5 $ à 12 $ par mille requêtes selon la taille du contexte de recherche. Pour la répartition complète et l'angle du compte Pro, consultez notre guide API Perplexity.
Erreurs courantes et comment les corriger
401 Non autorisé. Trois causes, par ordre de probabilité : l'en-tête est incorrect (il doit être Authorization: Bearer <clé>, et la variable d'environnement doit être exportée dans le même terminal), la clé a été révoquée, ou le solde de crédit est à zéro. Vérifiez la page de facturation avant de régénérer quoi que ce soit. Le SDK Python lève une AuthenticationError pour cela.
400 Mauvaise requête. Généralement un corps de l'ancien format envoyé au nouveau point d'accès : messages au lieu de input, ou un ID de modèle sonar-pro nu sur /v1/agent. Le SDK signale cela comme une ValidationError.
404 Non trouvé. Le chemin est incorrect. /v1/agent est l'API Agent et /v1/sonar est le point d'accès chat-completions hérité ; la documentation ne liste rien d'autre.
429 Trop de requêtes. Vous avez atteint la limite de votre niveau. Lisez Retry-After, attendez ce temps, puis réessayez avec un backoff exponentiel et un jitter. L'achat de crédits augmente votre niveau si vous avez besoin d'un débit soutenu. Le guide de gestion des erreurs du SDK montre le modèle RateLimitError.
500 ou 503. Côté serveur. Réessayez avec un délai ; des boucles de réessai trop serrées aggravent la limitation de débit.
FAQ
Existe-t-il une clé API Perplexity gratuite ?
Aucun niveau gratuit n'est documenté. L'API est payante à l'utilisation à partir d'un solde de crédit prépayé, et un projet sans crédits est bloqué. Le coût d'une première requête avec perplexity/sonar et une recherche web est une fraction de centime, donc un petit rechargement couvre de nombreux tests.
Quel ID de modèle dois-je utiliser pour une première requête ?
Utilisez perplexity/sonar sur /v1/agent avec l'outil web_search. C'est l'option contextualisée la moins coûteuse et celle sur laquelle le guide de migration mappe les anciens ID sonar et sonar-pro. Passez à un préréglage tel que low ou medium lorsque vous souhaitez que Perplexity choisisse le modèle et le budget de recherche pour vous.
Ai-je besoin de l'API Agent si je ne veux que des résultats de recherche ?
Non. L'API de recherche séparée renvoie des résultats classés sans exécuter de modèle, ce qui est moins cher lorsque vous alimentez votre propre pipeline avec des pages. Notre présentation de l'API de recherche Perplexity montre la forme de la requête et les filtres.
Comment faire pivoter une clé sans temps d'arrêt ?
Créez une deuxième clé dans le même projet, déployez-la partout où l'ancienne était utilisée, confirmez le trafic sur la nouvelle clé, puis révoquez l'ancienne. La révocation est permanente, alors mettez à jour chaque consommateur en premier. Perplexity expose également les points d'accès /generate_auth_token et /revoke_auth_token si vous souhaitez scripter la rotation.
En résumé
Connectez-vous, créez un projet, achetez des crédits, générez une clé, envoyez une requête à /v1/agent avec perplexity/sonar. C'est tout le chemin. Stockez la clé comme valeur locale dans Apidog et enregistrez la requête comme test, et la prochaine personne de votre équipe obtiendra une configuration vérifiable en quelques minutes. Si vous avez encore du code sur le point d'accès chat-completions, migrez-le avant le 27 septembre 2026.