Accès programmatique à l'API REST d'Ollama

Après l'installation, Ollama fournit une API REST complète sur le port local 11434, couvrant la génération de texte, le chat, les embeddings vectoriels et la gestion des modèles, ainsi que deux protocoles compatibles : OpenAI et Anthropic.

Cet article explique les API principales une par une : structure des requêtes, traitement en flux, statistiques d'utilisation et gestion des erreurs, permettant à n'importe quel langage de s'intégrer aux modèles locaux.


Deux URL de base et méthodes d'authentification

L'API d'Ollama dispose de deux points de terminaison : local et cloud, avec des règles d'authentification différentes.

Ollama API 全景:调用方、服务端点、本地模型与 Cloud

Point de terminaisonURL de baseAuthentification
Service localhttp://localhost:11434/apiAucune authentification requise
Service local (protocole compatible)http://localhost:11434/v1Aucune authentification requise, api_key peut être renseigné arbitrairement
Ollama Cloudhttps://ollama.com/apiAuthorization: Bearer + API Key

Les services locaux ne nécessitent aucune authentification par défaut et fonctionnent immédiatement ; lorsque vous vous connectez directement à l'API cloud d'Ollama sur ollama.com, créez d'abord une clé API sur la page des paramètres du site officiel et incluez-la dans l'en-tête de la requête.


Génération de texte : /api/generate

generate est l'API de génération à tour unique la plus basique ; il suffit de passer le nom du modèle et le prompt :

Exemple

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3.5",
"prompt": "Présentez Python en une phrase",
  "stream": false
}'

Lorsque stream est défini sur false, un seul objet JSON est renvoyé :

{
  "model": "qwen3.5",
  "created_at": "2026-08-29T03:20:00.499127Z",
  "response": "Example是一个面向编程初学者的免费中文教程网站。",
  "done": true,
  "total_duration": 10706818083,
  "load_duration": 6338219291,
  "prompt_eval_count": 26,
  "prompt_eval_duration": 130079000,
  "eval_count": 42,
  "eval_duration": 4232710000
}

Les paramètres courants sont les suivants :

ParamètreDescription
modelObligatoire, nom du modèle
promptPrompt ; peut être laissé vide pour précharger le modèle
fluxPar défaut, true renvoie un flux en streaming ; lorsque false, renvoie le résultat complet en une seule fois
systemSpécifier temporairement une invite système, en remplaçant le paramètre défini dans Modelfile
optionsObjet des paramètres de génération, par ex. temperature, num_ctx (identiques aux paramètres du Modelfile)
format"json" ou un schéma JSON complet, force une sortie structurée
keep_aliveDurée pendant laquelle le modèle reste résident après la requête, par ex. "10m", -1 pour une résidence permanente, 0 pour un déchargement immédiat
rawLorsque true, ignore l’assemblage du template et utilise directement le prompt complet que vous fournissez
suffixTexte à ajouter après la sortie du modèle, pour les scénarios de complétion de texte
imagesTableau d’images Base64, utilisé avec les modèles multimodaux

Deux conseils pratiques : envoyer un prompt vide peut précharger le modèle en mémoire, ce qui élimine l’attente de chargement lors de la première requête ; définir keep_alive sur 0 avec un prompt vide peut décharger immédiatement le modèle et libérer la VRAM.

Exemple

# Précharger le modèle (aucun contenu généré)
curl http://localhost:11434/api/generate -d '{"model": "qwen3.5"}'

# Décharger immédiatement le modèle, libérer la VRAM
curl http://localhost:11434/api/generate -d '{"model": "qwen3.5", "keep_alive": 0}'

Génération de conversation : /api/chat

chat est une API de conversation multi-tours ; l'historique des messages est maintenu par l'appelant, ce qui est la différence essentielle avec generate.

Exemple

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3.5",
  "messages": [
{ "role": "user", "content": "Qu'est-ce que Python ?" },
{ "role": "assistant", "content": "Un site de tutoriels chinois pour débutants." },
{ "role": "user", "content": "Est-ce gratuit ? Réponds en une seule phrase" }
  ],
  "stream": false
}'

Champs pris en charge par l'objet message :

ChampDescription
rôleQuatre rôles : system / user / assistant / tool
contentContenu du message
imagesFacultatif, liste d'images base64 (modèles multimodaux)
thinkingFacultatif, le processus de raisonnement des modèles de réflexion (utilisé avec le paramètre think)
tool_callsFacultatif, la liste des outils que le modèle demande à appeler (voir la section sur l'appel d'outils pour une pratique concrète)

La bonne façon de mener une conversation multi-tours : ajoutez le message de l'assistant renvoyé par le modèle à chaque tour au tableau messages, puis envoyez-le avec la nouvelle question ; le modèle peut alors « se souvenir » de tout le contexte.

Étant donné que les messages sont entièrement gérés par vous, l'historique peut être conservé dans une base de données, compressé par résumé, ou restauré entre les sessions — le problème mentionné dans la partie 5 de « les sorties de ligne de commande perdent la mémoire » a désormais une solution d'ingénierie ici.


Embeddings vectoriels : /api/embed

L'API embed convertit le texte en vecteurs, servant d'atelier de matières premières pour le RAG et la recherche sémantique.

Exemple

# Texte unique
curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
"input": "EXAMPLE est un site de tutoriels de programmation"
}'


# Traitement par lots : passez un tableau à input, renvoie plusieurs vecteurs à la fois
curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
"input": ["premier texte", "deuxième texte", "troisième texte"]
}'

Les embeddings dans la réponse forment un tableau 2D, chaque vecteur étant déjà normalisé L2 (longueur unitaire), de sorte que la similarité cosinus peut être directement utilisée pour la comparaison.

Deux paramètres à noter : dimensions permet de spécifier la dimension du vecteur de sortie (lorsque le modèle le prend en charge, réduire dimensions permet d'économiser du stockage) ; truncate vaut true par défaut et tronque automatiquement le texte trop long, et le définir sur false lèvera une erreur lorsque le texte est trop long.


Streaming vs non-streaming : comment gérer les réponses

Les API de génération renvoient du streaming par défaut, au format NDJSON : chaque ligne est un objet JSON indépendant.

{"model":"qwen3.5","created_at":"...","response":"EXAMPLE","done":false}
{"model":"qwen3.5","created_at":"...","response":"(Example)","done":false}
{"model":"qwen3.5","created_at":"...","response":"是编程初学者的入门网站。","done":false}
{"model":"qwen3.5","created_at":"...","response":"","done":true,"done_reason":"stop"}

Le client lit ligne par ligne et concatène les champs de réponse pour former la réponse complète ; le processus de concaténation peut être affiché en temps réel sur l'interface.

Compromis entre les deux modes :

ModeAvantageCas d'utilisation
Streaming (par défaut)Temps d'obtention du premier token réduit, affichage en temps réelInterfaces de chat, génération de textes longs
Non-streaming stream:falseObtenir le résultat complet en une seule fois, simple à traiterTraitement par lots, sortie structurée, appels de scripts

En mode streaming, des erreurs peuvent survenir en cours de sortie ; à ce stade, le code d'état HTTP ne peut plus être modifié. L'erreur apparaîtra sous la forme d'une ligne {"error": "..."} à la fin du flux de données, et le client doit vérifier cette ligne lors de l'analyse.


Statistiques d'utilisation et gestion des erreurs

Chaque réponse de génération se termine par des champs de statistiques de performance, fournissant des données de première main pour évaluer la surcharge d'inférence.

ChampSignification
total_durationDurée totale de la requête (nanoseconds)
load_durationTemps de chargement du modèle (perceptible lors de la première requête)
prompt_eval_countNombre de tokens consommés par l'entrée
prompt_eval_durationTemps de traitement de l'entrée
eval_countNombre de tokens générés par la sortie
eval_durationTemps de génération de sortie

La formule de la vitesse de génération (token/s) : eval_count / eval_duration * 10^9 ; toutes les unités de temps sont des nanosecondes.

En matière de gestion des erreurs, l'API utilise les codes d'état HTTP standard pour exprimer les résultats :

Code d'étatSignification
200Succès
400Erreur de requête (paramètres manquants, JSON non valide, etc.)
404Le modèle n'existe pas (exécutez d'abord ollama pull ou vérifiez le nom)
429Limitation de débit en raison de requêtes trop fréquentes
500Erreur interne du serveur
502Erreur de passerelle (par ex., modèle cloud inaccessible)

Le corps de la réponse d'erreur est fixé à la structure {"error": "error description"} ; les clients peuvent simplement extraire le champ error de manière uniforme.


Présentation de l'API de gestion des modèles

L'API fournit un équivalent pour chaque opération de gestion de modèle disponible en ligne de commande, adapté à la création de tableaux de bord d'administration ou de scripts d'automatisation.

Point de terminaisonMéthodeObjectif
/api/tagsGETLister les modèles locaux (y compris le nombre de paramètres, le niveau de quantification)
/api/showPOSTAfficher les détails du modèle, les capacités, le template
/api/pullPOSTRécupérer un modèle, renvoie la progression du téléchargement en streaming
/api/pushPOSTPousser le modèle vers la bibliothèque de modèles
/api/copyPOSTCopier le modèle (source / destination)
/api/deleteDELETESupprimer un modèle
/api/createPOSTCréer un modèle (y compris la quantification, correspondant aux capacités de Modelfile)
/api/psGETAfficher les modèles actuellement chargés et l'utilisation de la VRAM
/api/versionGETInterroger la version d'Ollama

En prenant /api/tags comme exemple, la réponse contient les détails des spécifications pour chaque modèle :

{
  "models": [
    {
      "name": "qwen3.5:latest",
      "size": 6600000000,
      "details": {
        "family": "qwen3.5",
        "parameter_size": "9B",
        "quantization_level": "Q4_K_M"
      }
    }
  ]
}

Des champs tels que quantization_level et parameter_size peuvent être directement utilisés pour construire une interface de sélection de modèle.


Interface compatible OpenAI

Pour que les applications OpenAI existantes passent aux modèles locaux, il suffit généralement de modifier une seule base_url.

Exemple

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5",
"messages": [{ "role": "user", "content": "Présentez Python en une phrase" }]
  }'

La compatibilité couvre cinq points de terminaison :

Point de terminaisonDescription
/v1/chat/completionsComplétions de chat, prenant en charge le streaming, la vision, les outils et le mode JSON
/v1/completionsComplétions de texte
/v1/responsesAPI Responses (mode sans état)
/v1/embeddingsPlongements vectoriels
/v1/modelsListe des modèles

Faites attention à deux différences courantes :

Premièrement, le protocole OpenAI n'a pas de concept num_ctx. Lorsque vous devez changer le contexte, créez d'abord un modèle avec PARAMETER num_ctx, puis appelez-le sous un nouveau nom (vous pouvez utiliser le Modelfile de la partie 7 ou emprunter un nom avec cp).

Deuxièmement, certains champs ne sont pas encore pris en charge : tool_choice, logit_bias, n, logprobs, etc. Avant de migrer, il est recommandé de consulter la liste de prise en charge du manuel.


Interface compatible Anthropic

Ollama fournit également une couche de compatibilité avec l'API Anthropic Messages, permettant à des outils tels que Claude Code d'utiliser directement des modèles locaux.

Exemple

curl http://localhost:11434/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "qwen3.5",
    "max_tokens": 1024,
"messages": [{ "role": "user", "content": "Présentez Python en une phrase" }]
  }'

Lors de l'intégration d'outils comme Claude Code, il vous suffit de définir deux variables d'environnement :

Exemple

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3.5

Notez les limites de capacités : les fonctionnalités Anthropic telles que tool_choice forcé, la mise en cache des prompts, l'interface par lots et l'entrée PDF ne sont pas encore prises en charge ; le nombre de tokens est approximatif.

Autres extensions