Comment travailler avec l'API Cohere

Cohere permet aux développeurs d'accéder à des modèles de langage volumineux (LLM) sophistiqués, capables de comprendre et de générer du texte semblable à celui des humains. Pour interagir avec ces modèles par programmation, vous avez besoin d'une clé API. Cette clé sert d'identifiant et de mot de passe uniques, permettant aux systèmes de Cohere d'authentifier vos requêtes et de suivre votre utilisation.

Ce guide vous guidera à travers les étapes essentielles : obtenir votre clé API, comprendre les différences cruciales entre les types de clés (en particulier en ce qui concerne les coûts et les limites d'utilisation), et effectuer un simple test initial à l'aide de l'outil Apidog pour vous assurer que votre clé fonctionne correctement.

Étape 1 : Obtention de votre clé API Cohere

Obtenir votre clé est la première étape et la plus cruciale. Cohere simplifie relativement ce processus via son tableau de bord en ligne.

Accédez au tableau de bord Cohere : Ouvrez votre navigateur Web et accédez au point d'accès principal de la plateforme Cohere. Vous trouverez généralement une page de connexion ou d'inscription.
Accédez à votre compte :

Si vous avez déjà un compte Cohere, connectez-vous en utilisant vos identifiants.
Si vous êtes nouveau sur Cohere, vous devrez vous inscrire pour un compte. Suivez le processus d'inscription, qui implique généralement de fournir une adresse e-mail et de définir un mot de passe.

Localisez la section Clés API : Une fois que vous êtes connecté avec succès au tableau de bord Cohere, recherchez une section spécifiquement dédiée à la gestion des clés API. Cela peut se trouver sous les paramètres du compte, une section développeur, ou être directement accessible via un élément de menu intitulé "Clés API". L'interface est conçue pour être conviviale, elle devrait donc être relativement visible.

Initier la génération de clés : Dans la section Clés API, vous trouverez une option pour créer une nouvelle clé. Vous verrez probablement des choix différenciant les types de clés, notamment "Clé d'essai" et potentiellement "Clé de production". Pour les tests et l'apprentissage initiaux, sélectionnez l'option pour générer une Clé d'essai.

Attribuer un nom : Une invite vous demandera de nommer votre clé. Choisissez un nom descriptif qui vous aidera à vous souvenir de son objectif plus tard, surtout si vous générez plusieurs clés pour différents projets. Les exemples incluent "MyFirstTestKey", "LearningProjectKey" ou "ApidogTestingKey".

Générer et sécuriser votre clé : Cliquez sur le bouton pour confirmer et générer la clé (par exemple, "Générer une clé d'essai"). Cohere affichera ensuite votre clé API nouvellement générée. C'est la seule fois où la clé complète sera affichée. Il est absolument essentiel que vous copiez cette clé immédiatement et que vous la stockiez dans un endroit très sûr, tel qu'un gestionnaire de mots de passe ou une note sécurisée. Traitez-la avec le même niveau de sécurité qu'un mot de passe. Ne la partagez pas publiquement, ne l'intégrez pas directement dans le code côté client et ne la soumettez pas à des systèmes de contrôle de version comme Git. Une fois que vous fermez la fenêtre contextuelle ou que vous naviguez ailleurs, vous ne pouvez plus récupérer la clé complète pour des raisons de sécurité (bien que vous puissiez voir le nom de la clé et potentiellement ses premiers/derniers caractères dans le tableau de bord). Si vous la perdez, vous devrez en générer une nouvelle.

Avec votre clé API copiée et sécurisée, vous êtes prêt à comprendre ce que vous pouvez en faire et les règles associées.

Étape 2 : Comprendre les types de clés, les coûts et les limites d'utilisation

Toutes les clés API Cohere ne sont pas créées de la même manière. Le type de clé dont vous disposez dicte la quantité que vous pouvez utiliser de l'API, à quelle vitesse et si cela entraîne des coûts. Comprendre ces différences est essentiel pour éviter des interruptions ou des frais inattendus.

A. Clés API d'essai : gratuites pour l'évaluation

Lorsque vous vous inscrivez pour la première fois ou générez une clé sans configurer la facturation, vous recevez généralement une clé d'essai. Celles-ci sont conçues pour l'exploration, l'apprentissage et les tests à petite échelle.

Coût : Les clés d'essai sont gratuites à utiliser. Vous ne serez pas facturé pour l'utilisation associée à une clé d'essai.
Limite d'utilisation globale : La restriction la plus importante est une limite mensuelle de 1 000 appels d'API au total sur tous les points de terminaison Cohere combinés. Cela signifie que chaque requête que vous effectuez (que ce soit vers Chat, Embed, Rerank, etc.) compte pour ce total mensuel. Une fois que vous atteignez 1 000 appels au cours d'un mois calendaire, votre clé cessera de fonctionner jusqu'au début du mois suivant.
Limites de débit (Requêtes par minute - RPM) : Pour garantir une utilisation équitable et la stabilité du système, les clés d'essai ont également des limites de débit strictes, limitant le nombre de requêtes que vous pouvez envoyer dans une fenêtre d'une minute vers des points de terminaison spécifiques. Il est essentiel d'en être conscient, car les dépasser entraînera des erreurs 429 Too Many Requests. Les limites de débit des clés d'essai incluent :
Point de terminaison Chat (/v2/chat) : 20 requêtes par minute. Il s'agit du point de terminaison utilisé pour l'IA conversationnelle, la génération de texte, la synthèse, etc.
Point de terminaison Embed (/v2/embed) - Texte : 100 requêtes par minute. Utilisé pour générer des intégrations vectorielles pour les données textuelles (recherche sémantique, clustering).
Point de terminaison Embed (/v2/embed) - Images : 5 requêtes par minute. Utilisé pour générer des intégrations vectorielles pour les données d'image (recherche multimodale).
Point de terminaison Rerank (/v2/rerank) : 10 requêtes par minute. Utilisé pour améliorer le classement de pertinence des résultats de recherche.
Point de terminaison Tokenize (/v2/tokenize) : 100 requêtes par minute. Utilisé pour voir comment le texte est décomposé en jetons par les modèles de Cohere.
Point de terminaison Classify (/v1/classify) : 100 requêtes par minute. Utilisé pour les tâches de classification de texte (hérité, l'affinage est désormais préféré).
Points de terminaison hérités (Summarize, Generate) : 5 requêtes par minute.
Autres/Par défaut : Des limites peuvent s'appliquer à d'autres points de terminaison moins courants ou de gestion.

Les clés d'essai sont idéales pour :

Apprendre à utiliser l'API Cohere.
Expérimenter différents modèles et paramètres dans le Playground ou via des appels directs.
Construire de petits projets personnels ou des prototypes avec une utilisation limitée prévue.
Évaluer les capacités de Cohere avant de s'engager dans une utilisation payante.

Si vous atteignez constamment le plafond mensuel ou les limites de débit par minute, cela indique fortement que vous devez passer à une clé de production.

B. Clés API de production : pour la construction et la mise à l'échelle

Lorsque vous êtes prêt à créer des applications avec de vrais utilisateurs, à gérer des charges de travail plus importantes ou à dépasser les limites d'essai, vous aurez besoin d'une clé de production. Cela nécessite de configurer les informations de facturation dans votre compte Cohere.

Coût : Les clés de production fonctionnent sur un modèle prépayé basé principalement sur l'utilisation des jetons. Les jetons sont des unités de texte (correspondant approximativement à des mots ou à des parties de mots) que les modèles traitent. Vous êtes facturé à la fois pour les jetons que vous envoyez au modèle (jetons d'entrée) et pour les jetons que le modèle génère dans sa réponse (jetons de sortie).
La tarification varie selon le modèle : Les modèles plus puissants coûtent généralement plus cher par jeton que les modèles plus légers et plus rapides.
Exemple de tarification (illustratif - consultez la page de tarification officielle de Cohere pour connaître les tarifs actuels) :
Modèle Command R : Pourrait coûter environ 0,50 $ par million de jetons d'entrée et 1,50 $ par million de jetons de sortie. (Remarque : le résultat de recherche précédent indiquait 2,50 $ d'entrée / 10,00 $ de sortie pour Command R - en utilisant ces valeurs : 2,50 $ / 1M de jetons d'entrée, 10,00 $ / 1M de jetons de sortie.)
Modèle Command R+ : Étant plus performant, il aurait probablement un prix plus élevé, peut-être 3,00 $ par million de jetons d'entrée et 15,00 $ par million de jetons de sortie.
Modèles Embed (par exemple, embed-english-v3.0) : Les modèles d'intégration sont généralement tarifés uniquement sur les jetons d'entrée, car ils ne génèrent pas de longues sorties de texte. La tarification pourrait être d'environ 0,10 $ par million de jetons d'entrée.
Calcul des jetons : Cohere fournit un point de terminaison Tokenizer et une documentation pour vous aider à comprendre comment le texte se traduit en jetons pour une estimation précise des coûts. Les entrées et les sorties plus longues coûtent naturellement plus cher.
Limite d'utilisation globale : Il n'y a pas de limite d'appel totale mensuelle pour les clés de production. Vous pouvez effectuer autant d'appels que nécessaire, à condition de respecter les limites de débit et de gérer vos coûts.
Limites de débit (Requêtes par minute - RPM) : Les clés de production bénéficient de limites de débit considérablement plus élevées, permettant aux applications de gérer beaucoup plus de trafic :
Point de terminaison Chat (/v2/chat) : 500 requêtes par minute (contre 20/min pour l'essai).
Point de terminaison Embed (/v2/embed) - Texte : 2 000 requêtes par minute (contre 100/min).
Point de terminaison Embed (/v2/embed) - Images : 400 requêtes par minute (contre 5/min).
Point de terminaison Rerank (/v2/rerank) : 1 000 requêtes par minute (contre 10/min).
Point de terminaison Tokenize (/v2/tokenize) : 2 000 requêtes par minute.
Point de terminaison Classify (/v1/classify) : 1 000 requêtes par minute.
Augmentations des limites de débit : Pour les applications à très haut volume, il est possible de demander d'autres augmentations des limites de débit en contactant le support Cohere.

Les clés de production sont nécessaires pour :

Développer et déployer des applications destinées aux utilisateurs finaux.
Gérer des volumes constants ou élevés de requêtes API.
Tout cas d'utilisation commerciale.
Débloquer tout le potentiel de performance sans être contraint par les limites d'essai.

C. Choisir la bonne clé :

Commencez par l'essai : Commencez toujours par une clé d'essai pour l'apprentissage et le développement initial.
Surveillez l'utilisation : Gardez un œil sur le volume et la fréquence de vos appels.
Mettez à niveau si nécessaire : Si votre application atteint constamment les limites de débit, dépasse la limite d'appel mensuelle de 1 000 ou si vous vous préparez à lancer publiquement ou commercialement, passez à une clé de production en ajoutant les détails de facturation dans le tableau de bord Cohere.

D'accord, voici la section révisée de l'étape 3, axée sur le test de la requête de chat en streaming fournie dans la commande curl à l'aide d'Apidog, présentée en Markdown :

Étape 3 : Effectuer un appel de test d'API de base pour le chat en streaming avec Apidog

Avant d'intégrer l'API dans un code complexe, en particulier pour les réponses en streaming, il est utile d'effectuer un test direct. Apidog vous permet de reproduire la structure de la commande curl pour vérifier votre clé et comprendre le flux de requête/réponse de base pour le streaming.

Lancez Apidog : Ouvrez l'application Apidog sur votre ordinateur.
Créez une nouvelle requête : Cliquez sur le bouton '+' ou équivalent pour créer une nouvelle requête API. Nommez-la de manière descriptive, comme "Cohere Streaming Chat Test".
Configurez le point de terminaison :

Méthode HTTP : Sélectionnez POST.
URL : Entrez l'URL du point de terminaison Cohere v2 Chat : https://api.cohere.ai/v2/chat

4. Configurer les en-têtes :

Accédez à l'onglet "Headers". Vous devrez ajouter plusieurs en-têtes en fonction de la commande curl :
Accept : Clé : Accept, Valeur : application/json
Content-Type : Clé : Content-Type, Valeur : application/json
Authorization : Clé : Authorization, Valeur : Bearer YOUR_API_KEY (Remplacez YOUR_API_KEY par votre clé API Cohere réelle. Assurez-vous qu'il y a un espace après Bearer).

5. Construire le corps de la requête (avec le streaming activé) :

Accédez à l'onglet "Body".
Sélectionnez l'option pour l'entrée "raw".
Choisissez JSON comme format.
Collez la charge utile JSON suivante, reflétant les données de la commande curl, y compris l'indicateur crucial "stream": true :

{
  "stream": true,
  "model": "command-r",
  "messages": [
    {
      "role": "user",
      "content": "Hello world!"
    }
  ]
}

(Remarque : l'exemple curl utilisait "role": "user" (minuscule) et le modèle "command-a-03-2025". J'ai conservé "role": "USER" et le modèle "command-r" pour la cohérence avec les exemples précédents, mais vous devez ajuster le modèle et la casse du rôle dans le JSON ci-dessus pour correspondre précisément à la requête spécifique que vous souhaitez tester si elle est différente.)

6. Exécuter la requête : Cliquez sur le bouton "Envoyer" dans Apidog.

7. Analyser la réponse (spécificités du streaming) :

Code d'état : Vous devriez toujours recevoir un code d'état 200 OK si la requête initiale est acceptée par le serveur.
En-têtes de réponse : Vérifiez les en-têtes de réponse pour les signes de streaming, tels que Transfer-Encoding: chunked.
Corps de la réponse : La façon dont Apidog affiche la réponse en streaming peut varier. Il peut :
Attendre que le flux se termine et afficher le texte entièrement concaténé ou la charge utile de l'événement final.
Afficher les morceaux bruts ou les événements envoyés par le serveur (SSE) au fur et à mesure de leur arrivée, ressemblant potentiellement à plusieurs objets JSON les uns après les autres.
Il ne rendra probablement pas le texte en douceur jeton par jeton comme une application spécialement conçue.
Contenu : Examinez le contenu du corps de la réponse. Vous devriez voir des événements liés au flux, tels que des événements text-generation contenant des parties de la réponse "Hello world !", et finalement un événement stream-end indiquant que le processus est terminé.
Erreurs : Si vous obtenez des erreurs (401, 403, 400, 429), diagnostiquez-les comme décrit précédemment (vérifiez la clé API, la validité JSON, les limites de débit). Une 400 Bad Request peut se produire si le modèle spécifié ne prend pas en charge le streaming ou si d'autres paramètres sont incompatibles.

Ce test permet de confirmer que l'API accepte votre requête de streaming et que votre clé est valide pour ce type d'interaction, même si Apidog lui-même n'est pas l'outil idéal pour visualiser la nature en temps réel du flux. Il vérifie que la configuration de la requête fondamentale est correcte.

Conclusion

Vous avez maintenant votre clé API Cohere et comprenez les différences cruciales entre les clés d'essai et de production, en particulier en ce qui concerne la limite d'appel mensuelle de 1 000 et les limites de débit par minute sur les clés d'essai par rapport à la tarification à l'utilisation, basée sur les jetons et les limites plus élevées des clés de production. Vous avez également effectué un test de base mais essentiel à l'aide d'Apidog pour confirmer que votre clé fonctionne et que vous pouvez structurer un simple appel d'API.

Cette base est essentielle pour interagir efficacement avec l'API Cohere. N'oubliez pas de sécuriser votre clé, de surveiller votre utilisation par rapport aux limites (en particulier sur une clé d'essai) et de consulter la documentation de Cohere pour obtenir des informations détaillées sur des modèles spécifiques, des paramètres avancés et l'utilisation du SDK lorsque vous commencez à créer des applications plus sophistiquées.