Utiliser l'API Cohere en développeur : Chat, Embed et Rerank, SDK et limites des clés d'essai

Pour utiliser Cohere en développeur, il faut retenir trois endpoints : Chat pour générer du texte, Embed pour produire des vecteurs de recherche sémantique, Rerank pour classer des documents par pertinence. L’accès passe par un SDK officiel (Python, TypeScript, Go, Java) ou par de simples requêtes HTTP, avec une clé d’essai gratuite limitée à 1 000 appels par mois. Les exemples ci-dessous reprennent ceux de la documentation officielle, consultée en novembre 2026.

Cohere en bref : ce qu'un développeur doit savoir

Cohere est une entreprise canadienne fondée à Toronto en 2019 par Aidan Gomez, Nick Frosst et Ivan Zhang. Son positionnement est celui d’une IA pour les entreprises et le secteur public : déploiements privés, secteurs réglementés, recherche documentaire et multilinguisme, plutôt qu’un assistant grand public. C’est ce qui explique la forme de son API, pensée comme une boîte à outils à brancher dans un système existant.

La documentation décrit la famille Command pour l’endpoint Chat, avec Command A+, Command A, Command R7B, Command R+ et Command R. Command A+ (identifiant command-a-plus-05-2026) est présenté comme le premier modèle à mélange d’experts de Cohere, avec entrée texte et image, un contexte de 128 000 jetons et une sortie maximale de 64 000 jetons. Embed et Rerank, eux, alimentent la recherche : c’est là que le catalogue se distingue le plus de celui des assistants généralistes.

Les trois endpoints : Chat, Embed et Rerank

Chacun répond à un besoin précis, et la plupart des projets en utilisent deux sur trois.

• Chat : génération de texte conversationnelle (agents, résumés, rédaction), avec ou sans recherche documentaire. Chaque message porte un champ content et un rôle parmi user, assistant, system et tool.
• Embed : représentation du sens de textes (ou d'images) sous forme de listes de nombres, pour la recherche sémantique, la classification et le regroupement. Le modèle embed-v5.0-pro prend en charge plus de 100 langues, dont le français.
• Rerank : à partir d'une requête et d'une liste de documents, le endpoint les classe du plus au moins pertinent. La documentation le présente comme la façon la plus rapide d'injecter l'intelligence d'un modèle de langage dans un système de recherche existant.

La documentation mentionne aussi Classify, alimenté par les embeddings de Cohere, ainsi que des endpoints pour l’analyse de documents (Parse) et la transcription audio. Pour un premier projet, Chat, Embed et Rerank suffisent. Ces endpoints servent à intégrer l’IA dans votre propre application, ce qui diffère de l’usage d’un assistant pour écrire du code, dont le vibe coding en PHP et Symfony décrit les limites réelles.

SDK officiels et installation

Le tableau de compatibilité de la documentation liste quatre SDK officiels pour la plateforme Cohere : TypeScript, Python, Go et Java. En Python, l’installation tient en une commande, et le dépôt du SDK indique qu’une variable d’environnement CO_API_KEY évite d’écrire la clé dans le code :

pip install cohere
export CO_API_KEY=theapikeyforyouraccount

Le client à utiliser pour l’API v2 est cohere.ClientV2, que l’on instancie avec api_key ou, sans argument, en laissant le SDK lire CO_API_KEY. La même famille de SDK fonctionne aussi sur d’autres environnements (Amazon Bedrock, SageMaker, Azure, Oracle OCI, déploiement privé), avec de petits changements d’import et d’initialisation d’un environnement à l’autre.

Trois exemples minimaux tirés de la documentation

Chat

L’exemple de la page « Using the Cohere Chat API » envoie un message et lit le texte de la réponse dans res.message.content[0].text :

import cohere

co = cohere.ClientV2(api_key="<YOUR API KEY>")

res = co.chat(
    model="command-a-plus-05-2026",
    messages=[
        {
            "role": "user",
            "content": "Write a title for a blog post about API design. Only output the title text.",
        }
    ],
)

print(res.message.content[0].text)

La réponse contient un champ finish_reason, qui vaut COMPLETE si le modèle a terminé, ou MAX_TOKENS si la limite de contexte a été atteinte avant la fin. Pour piloter le style, on ajoute en première position un message {“role”: “system”, “content”: ”…”}.

Embed

La page d’introduction aux embeddings utilise embed-v5.0-pro. Le paramètre input_type y est obligatoire : search_query pour la requête, search_document pour les passages à indexer, classification ou clustering pour ces tâches.

import cohere

co = cohere.ClientV2(api_key="YOUR_API_KEY")

phrases = ["i love soup", "soup is my favorite", "london is far away"]

res = co.embed(
    texts=phrases,
    model="embed-v5.0-pro",
    input_type="search_query",
    output_dimension=1024,
    embedding_types=["float"],
)

soup1, soup2, london = res.embeddings.float

Les dimensions possibles sont 256, 512, 768, 1024, 1536 et 2048, cette dernière étant la valeur par défaut. Un vecteur plus court occupe moins de place en base, au prix d’une représentation plus compacte : la dimension se choisit donc avec le volume du corpus en tête.

Rerank

L’exemple de la page de présentation de Rerank classe cinq textes pour la requête « What is the capital of the United States? ». Voici la même structure d’appel, réduite à trois documents tirés de cette page :

import cohere

co = cohere.ClientV2()

query = "What is the capital of the United States?"
docs = [
    "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
    "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
    "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
]

results = co.rerank(
    model="rerank-v5.0-pro", query=query, documents=docs, top_n=3
)

La réponse contient une liste results ordonnée, dont chaque élément porte un index (la position du document dans la liste d’origine, à partir de 0) et un relevance_score normalisé entre 0 et 1. La documentation précise qu’un score de 0,9 ne signifie pas « deux fois plus pertinent » qu’un score de 0,45 : il sert à ordonner, pas à mesurer un rapport. Elle recommande aussi de ne pas envoyer plus de 1 000 documents par requête, et de formater les données structurées en chaînes YAML pour de meilleurs résultats.

Appeler Cohere depuis PHP et Symfony

Aucun SDK PHP n’apparaît dans le tableau de compatibilité officiel. Pour une application PHP, on passe donc par l’API HTTP, dont la documentation donne l’équivalent cURL de l’exemple Chat : requête POST sur https://api.cohere.ai/v2/chat, en-têtes accept et content-type en JSON, et Authorization: bearer suivi de la clé.

Voici une traduction directe de ce cURL avec le composant HttpClient de Symfony. Ce n’est pas un extrait de la documentation : seuls l’URL, les en-têtes, les champs du corps et le chemin de lecture de la réponse (message.content[0].text) en proviennent.

use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create();

$response = $client->request('POST', 'https://api.cohere.ai/v2/chat', [
    'headers' => [
        'accept' => 'application/json',
        'Authorization' => 'bearer ' . $_ENV['CO_API_KEY'],
    ],
    'json' => [
        'model' => 'command-a-plus-05-2026',
        'messages' => [
            ['role' => 'user', 'content' => 'Write a title for a blog post about API design. Only output the title text.'],
        ],
    ],
]);

$data = $response->toArray();
echo $data['message']['content'][0]['text'];

La clé reste dans une variable d’environnement et jamais dans le dépôt, comme pour n’importe quel secret. Pour les bases d’une intégration d’IA sans dépendance cloud, notre guide sur les LLM locaux avec Ollama montre l’alternative auto-hébergée et la même logique d’appel REST côté Symfony.

Clés d'essai, clés de production et limites

Cohere distingue deux types de clés : les clés d’évaluation (gratuites mais limitées) et les clés de production (payantes, beaucoup moins limitées). On crée l’une ou l’autre depuis la page des clés API du tableau de bord. L’usage d’une clé d’essai est gratuit, mais chaque clé d’essai, ainsi que les clés de production sur les variantes récentes du modèle Chat, est plafonnée à 1 000 appels d’API par mois.

Deux conséquences pratiques. D’abord, Command A+ n’est pas disponible en production sans passer par l’équipe commerciale de Cohere, à la date de la documentation consultée : l’exemple Chat ci-dessus convient pour un prototype, pas pour un déploiement immédiat. Ensuite, avec 10 requêtes par minute sur Rerank, un test de charge se heurte très vite au plafond. La facturation, elle, se fait par jetons pour les modèles de génération, par nombre de recherches pour Rerank et par jetons pour Embed ; les tarifs à jour sont publiés sur la page de tarification de Cohere, que je ne recopie pas ici pour ne pas figer un prix susceptible de changer.

Cohere et OpenAI : ce qui change dans le code

Cohere propose une API de compatibilité qui permet d’utiliser le SDK d’OpenAI avec ses modèles, pour migrer sans refactoring majeur. Il suffit de changer la base URL et la clé :

from openai import OpenAI

client = OpenAI(
    base_url="https://api.cohere.ai/compatibility/v1",
    api_key="COHERE_API_KEY",
)

completion = client.chat.completions.create(
    model="command-a-plus-05-2026",
    messages=[
        {
            "role": "user",
            "content": "Write a haiku about recursion in programming.",
        },
    ],
)

print(completion.choices[0].message)

La couche couvre les chat completions (streaming, historique, sortie structurée, appel d’outils), les embeddings et la transcription audio. Elle ne reproduit pas tout : voici les écarts les plus importants pour un développeur.

Le choix dépend du contexte. Si une application utilise déjà le SDK d’OpenAI et que le besoin se limite à du chat, la compatibilité permet de tester un modèle Cohere en changeant deux lignes. Si l’on veut Rerank, les citations ou les paramètres propres à Cohere, il faut passer par le SDK natif. Pour situer ces choix parmi les assistants de code, le comparatif des usages de Claude Sonnet pour un développeur PHP et Symfony offre un point de référence côté outils de développement.

Les pièges à éviter

Quelques erreurs reviennent quand on débute avec l’API :

• Oublier input_type sur Embed : il est obligatoire pour les modèles v3 et supérieurs, et il faut embarquer les requêtes avec search_query et les documents avec search_document.
• Prendre un relevance_score pour une probabilité ou un pourcentage : il n'a de sens que pour ordonner les documents d'une même requête.
• Brancher Command A+ en production avec une clé d'essai ou sans contrat, alors que ce modèle exige de contacter l'équipe commerciale.
• Copier un exemple de l'ancienne API : certains extraits de la documentation de compatibilité des SDK utilisent encore CohereClient et chatHistory, soit l'ancienne forme. Pour un projet neuf, on part de ClientV2.
• Transmettre des données sensibles à une clé d'essai sans lire les conditions d'utilisation : la page des limites ne tranche pas sur l'usage commercial, il faut donc consulter les conditions de Cohere avant tout usage hors prototype.

Dernier critère à connaître : l’ancrage canadien de Cohere. Le gouvernement du Canada a annoncé le 29 octobre 2026 une prise de participation pouvant aller jusqu’à 1,6 milliard de dollars canadiens, versée par étapes, d’après le communiqué du premier ministre (en anglais). Pour un projet qui exige un hébergement au Canada ou un déploiement privé, c’est un élément de choix concret, à vérifier toutefois auprès de Cohere au moment de contractualiser. Pour découvrir comment l’IA s’insère dans un cursus de développeur, voir aussi la formation des développeurs à l’IA générative.

Questions fréquentes

Les réponses détaillées figurent dans la section FAQ de cette page : essai gratuit, SDK PHP, compatibilité avec le SDK d’OpenAI, rôle de Rerank et rôle système. Elles reprennent les valeurs de la documentation officielle de Cohere consultée en novembre 2026, qui peuvent évoluer ; revérifiez les limites et les identifiants de modèles avant de figer une architecture.