L’API Ollama permet de piloter vos modèles locaux avec curl

Quand vous avez déjà un modèle chargé dans Ollama, la ligne de commande ne suffit pas toujours : vous pouvez vouloir récupérer une réponse dans un script ou relier votre prototype à une interface. L’API HTTP sert précisément à envoyer des requêtes au serveur local et à lire ses réponses structurées. Pour commencer, il faut connaître l’adresse, le nom exact du modèle et la différence entre une réponse complète et un flux de morceaux. Les exemples ci-dessous utilisent curl, sans bibliothèque supplémentaire.

Que permet l’API HTTP locale d’Ollama ?

L’API expose les fonctions du serveur Ollama sous forme de requêtes HTTP. Votre programme envoie des données, généralement en JSON, puis reçoit une réponse qu’il peut exploiter au lieu de demander à quelqu’un de copier-coller le texte depuis une fenêtre de discussion. C’est pratique pour tester un prompt, automatiser une tâche ou relier un prototype à une interface locale.

Pour une machine personnelle, l’adresse de base est http://localhost:11434. Le mot localhost désigne l’ordinateur sur lequel la commande s’exécute, et le nombre 11434 est le port utilisé par défaut. L’API locale ne demande pas de clé d’authentification. Les adresses et cette distinction avec l’API cloud sont précisées dans la documentation d’introduction à l’API Ollama. L’API cloud est un service différent : ne remplacez pas l’adresse locale par une adresse distante en supposant que les mêmes conditions d’accès s’appliquent.

Pour explorer les réglages de modèles, de pilotes et d’usages locaux, retrouvez aussi les sujets de la rubrique intelligence artificielle.

Quel endpoint choisir pour envoyer un prompt ?

Un endpoint est une adresse dédiée à une opération. Pour discuter avec un modèle et conserver un historique, le choix naturel est POST /api/chat. Le corps de la requête contient notamment model et messages. Chaque message associe un rôle à un contenu : les rôles documentés incluent system, user, assistant et tool. Un rôle system sert à donner un cadre, user porte la demande, et assistant désigne une réponse précédente.

Pour soumettre plutôt un prompt unique, POST /api/generate accepte un champ prompt. Cette option convient à une génération sans structure de conversation particulière. Les deux endpoints peuvent diffuser leur résultat progressivement : dans ce mode, la réponse arrive comme une suite d’objets JSON. Si votre script attend un seul objet lisible à la fin, ajoutez "stream": false. Le comportement de diffusion et les paramètres des endpoints sont détaillés dans la documentation officielle des endpoints API.

Les noms de modèles peuvent inclure un tag, par exemple nom:tag. Ce tag permet de désigner une variante ; si vous l’omettez, Ollama utilise le tag latest. Évitez de deviner le nom : listez les modèles présents dans l’installation avec ollama list, puis reprenez exactement le nom affiché. Un modèle disponible dans une autre installation ne sera pas automatiquement présent sur ce PC.

Comment tester un chat sans streaming avec curl ?

Lancez Ollama et vérifiez qu’un modèle est déjà installé. Remplacez llama3.2 ci-dessous par un nom réellement affiché chez vous. Envoyez ensuite une requête depuis un terminal :

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    {"role": "user", "content": "Donne-moi une astuce pour réduire le bruit de mon PC."}
  ],
  "stream": false
}'

Ici, curl effectue la requête HTTP, et -d transmet le corps JSON. L’exemple minimal fonctionne avec le serveur local sans en-tête d’authentification. Dans la réponse, cherchez message.content : c’est le texte généré. Le champ done indique que la génération est terminée. Les autres champs peuvent fournir des informations de durée et de comptage de jetons, utiles pour observer le traitement, mais les temps obtenus dépendent de votre machine, du modèle et du prompt.

Si vous préférez une génération simple plutôt qu’un chat, le principe est similaire :

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Explique en une phrase ce qu’est un SSD.",
  "stream": false
}'

Dans cette réponse, le texte se trouve dans response, au lieu de message.content. Gardez ce détail en tête lorsque vous écrivez le programme qui lira le JSON. Les endpoints ne renvoient pas tous les réponses sous la même clé.

Pour reprendre l’historique d’un chat, renvoyez les tours précédents dans messages à chaque appel. Une requête suivante peut contenir le message user initial, la réponse assistant reçue, puis un nouveau message user. L’API ne remplace pas la logique de votre interface : c’est votre application qui doit décider quelles conversations retenir, afficher ou oublier. Évitez d’inclure des informations sensibles sans raison.

Streaming ou réponse complète, que choisir ?

Le streaming envoie le résultat en plusieurs morceaux, plutôt que d’attendre la fin pour recevoir un seul objet. Il convient à une interface qui affiche la réponse au fur et à mesure, mais le programme client doit lire et assembler les éléments. Pour un premier test avec curl, une tâche automatisée ou un script qui analyse une réponse entière, "stream": false simplifie la lecture. Ce paramètre ne rend pas le modèle plus rapide : il change la forme de la réponse.

Pour ajuster le temps pendant lequel un modèle reste chargé après une requête, l’API propose keep_alive. La valeur par défaut indiquée dans la documentation des endpoints est de cinq minutes. Vous pouvez laisser ce réglage tranquille au premier essai, puis l’examiner si le chargement répété du modèle devient gênant ou si vous cherchez à libérer de la mémoire. Le temps de chargement dépend notamment du matériel et du modèle ; ne promettez donc pas un délai fixe à partir de ce réglage.

Un autre mode de connexion peut vous convenir si votre application utilise déjà une bibliothèque compatible avec l’API OpenAI. Ollama documente une base locale en /v1 pour cette compatibilité, distincte de ses endpoints natifs /api. Pour choisir entre deux interfaces graphiques ou de gestion, comparez les usages décrits dans LM Studio et Ollama plutôt que de modifier votre requête au hasard.

Comment vérifier la réponse et diagnostiquer un échec ?

Procédez par petites vérifications :

1. Confirmez que le serveur répond à http://localhost:11434 depuis la même machine.
2. Contrôlez que le modèle demandé est installé et que son nom correspond exactement à celui affiché par ollama list.
3. Vérifiez les guillemets, virgules et crochets du JSON, puis gardez "stream": false pour un résultat unique.
4. Lisez le corps de réponse et repérez la clé adaptée à l’endpoint : message.content pour le chat, response pour generate.

Une erreur avant toute réponse suggère d’abord un problème d’adresse, de port ou de serveur arrêté. Si vous recevez une réponse HTTP avec un message d’erreur, examinez le corps JSON : il peut indiquer un nom de modèle incorrect ou un paramètre rejeté. Ne traitez pas toute réponse comme du texte généré ; un client robuste vérifie le statut HTTP et gère les erreurs avant de lire le contenu attendu.

La sécurité mérite une vérification séparée. Ollama indique qu’il écoute par défaut sur 127.0.0.1 et que l’adresse d’écoute peut être changée par OLLAMA_HOST. Cela signifie que l’accès au réseau local est un réglage distinct de l’appel sur localhost, pas une étape obligatoire du tutoriel. Ne redirigez pas le port 11434 depuis votre routeur et ne l’exposez pas directement sur Internet : l’API locale n’exige pas de clé. La FAQ officielle décrit l’adresse d’écoute et les variables associées dans sa section sur l’exposition réseau : FAQ officielle sur le réseau Ollama.

Si plusieurs services doivent communiquer avec Ollama, définissez précisément le périmètre réseau et ajoutez une couche de contrôle adaptée plutôt que de considérer l’absence d’authentification locale comme une protection à distance. L’utilisation avec Docker implique également des questions d’adresses et de ports propres au conteneur ; gardez-les séparées du test local présenté ici. Pour un cas dédié aux conteneurs, consultez lancer Ollama avec Docker.

Enfin, les modèles téléchargés occupent de l’espace disque indépendamment de la taille de vos requêtes API. Si vous faites des essais et souhaitez récupérer de la place, vous pouvez retirer un modèle inutilisé avec la commande adaptée. L’API est opérationnelle lorsque curl obtient une réponse JSON, que le champ de texte correspond à l’endpoint choisi et que le service reste accessible uniquement dans le périmètre voulu.

Questions fréquentes

Faut-il une clé API pour appeler Ollama sur le même PC ?

Non. Les requêtes à un serveur Ollama local ne demandent pas d’en-tête d’authentification. Cette absence de clé ne signifie pas que le service est protégé contre tout accès : gardez-le limité à votre machine et ne publiez pas son port sur Internet. L’API hébergée d’Ollama est un service distinct et requiert une clé.

Pourquoi curl reçoit-il une erreur de connexion ?

Vérifiez d’abord qu’Ollama tourne, que l’adresse est bien http://localhost:11434 et qu’un modèle a été téléchargé sous le nom demandé. Une erreur de connexion indique souvent que le serveur ne répond pas à cette adresse ; une erreur retournée après connexion peut plutôt signaler un modèle introuvable ou une requête JSON mal formée.

Comment garder une conversation entre deux requêtes ?

Avec /api/chat, renvoyez les messages précédents dans le tableau messages à chaque appel, puis ajoutez-y la nouvelle réponse de l’assistant et le message suivant de l’utilisateur. Le serveur traite le contenu fourni dans la requête ; votre application doit donc conserver cet historique si elle veut maintenir le fil. Pensez à limiter la longueur de l’historique.

Peut-on employer un client compatible avec l’API OpenAI ?

Oui, Ollama fournit aussi une interface compatible avec une partie de l’API OpenAI. Son adresse locale de base est http://localhost:11434/v1. Cette voie peut simplifier l’intégration d’un projet existant, mais les capacités prises en charge ne sont pas nécessairement identiques à celles du service d’origine. Vérifiez les fonctions requises avant de remplacer un fournisseur.