C’est quoi une API ? Explication avec l’IA et premier curl

👁 119 lectures

Une API est un contrat entre deux programmes : le premier envoie une requete dans un format defini, le second renvoie une reponse, egalement structuree. Quand votre script demande a un modele d’IA de resumer un e-mail, il ne clique pas dans une fenetre de discussion. Il expedie sur Internet un paquet de texte au format JSON et recoit un JSON en retour. Ce guide constitue la premiere etape du parcours API IA de zero, ou chaque notion est illustree par des requetes reelles executees sur mon ordinateur.

Comprendre l’API : l’analogie du guichet administratif

Le moyen le plus simple de visualiser une API consiste a imaginer un guichet administratif qui n’accepte que des formulaires standardises. Vous ne voyez pas les bureaux a l’arriere-plan et vous ignorez qui traite votre dossier en coulisses. En revanche, vous connaissez trois elements indispensables :

• A quel guichet vous adresser - il s’agit de l’adresse, ou endpoint, par exemple https://openrouter.ai/api/v1/chat/completions ;
• Comment remplir le formulaire - c’est le format de requete precise dans la documentation technique : champs obligatoires et champs optionnels ;
• Comment prouver votre identite - c’est votre cle d’API, que vous joignez a chaque demande.

L’agent derriere le guichet vous retourne soit le dossier traite, soit une fiche indiquant un code d’erreur : signature manquante, quota quotidien depasse ou panne informatique. Dans une API, ces retours correspondent aux codes de statut HTTP detailles plus bas.

La difference entre une interface de chat et une API tient au public cible. Un chat (comme ChatGPT, Claude ou Gemini) est une application prete a l’emploi pour les humains. L’API donne un acces direct a ce meme modele pour vos programmes. Par API, le modele ne garde aucune memoire de vos echanges passes, n’affiche aucun bouton et ne conserve aucun historique. Vous pouvez neanmoins l’appeler un millier de fois depuis un tableur, un bot ou un script automatise la nuit. Vous ne payez pas d’abonnement fixe, mais uniquement les tokens consommes, c’est-a-dire des morceaux de texte expliques dans l’article Tokens IA : fonctionnement et calcul du cout.

Requete et reponse (request et response)

Chaque dialogue avec une API comporte deux volets. La requete (request) rassemble plusieurs informations :

1. La methode - l’action souhaitee. Avec les modeles d’IA, on utilise presque toujours POST pour transmettre du contenu.
2. L’adresse - l’endpoint associe a une fonction precise, comme generer du texte ou lister les modeles disponibles.
3. Les en-tetes (headers) - les metadonnees : la cle d’API (Authorization: Bearer ...) et le type de contenu (Content-Type: application/json).
4. Le corps (body) - les donnees brutes : le modele cible, la liste des messages et les parametres d’execution.

La reponse (response) renvoie un code de statut (par exemple 200 quand tout s’est bien passe) et un corps de texte incluant la reponse generee ainsi que le decompte des tokens utilises. Voici la reponse reelle recue le 4 octobre 2026 depuis le modele GPT-6 Luna via OpenRouter (abregee pour ne garder que les champs essentiels) :

{
  "id": "gen-1791114764-uKPpeyAgJg4GJmOQhMp4",
  "object": "chat.completion",
  "model": "openai/gpt-6-luna",
  "provider": "OpenAI",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Krakow zachwyca zabytkowym Rynkiem Glownym, klimatycznymi uliczkami i bogata historia."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 36,
    "total_tokens": 52,
    "cost": 0.0000196
  }
}

Lecture du resultat : le modele a repondu par une phrase descriptive (la requete de test a ete effectuee en polonais sur la ville de Cracovie : « Cracovie seduit par sa place du Grand Marche historique, ses ruelles pleines de charme et sa riche histoire » dans le champ content), s’est arrete normalement (finish_reason: stop), a consomme 16 tokens en entree et 36 en sortie. La requete complete a coute 0,0000196 USD (environ 0,0000175 EUR au cours BCE du 12/10/2026 ; source : https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml), soit moins de deux milliemes de centime.

Le format JSON en 2 minutes

Le JSON (JavaScript Object Notation) est un format textuel de donnees lisible a la fois par les humains et par tous les langages de programmation. Cinq notions de base suffisent :

• { } - un objet, representant un ensemble de couples « cle: valeur », par exemple {"model": "openai/gpt-6-luna"} ;
• [ ] - une liste (ou tableau), par exemple la suite des messages d’une discussion ;
• "texte" - une chaine de caracteres imperativement encadree de guillemets doubles (les apostrophes simples provoquent une erreur) ;
• les nombres sans guillemets : 0.7, 1024 - avec un point decimal, jamais de virgule ;
• true, false, null - vrai, faux, absence de valeur.

Une requete adressee a un modele de langage forme un objet contenant le champ model et la liste messages. Chaque message precise un role (system pour donner une consigne generale, user pour votre message, assistant pour les reponses precedentes) ainsi qu’un contenu (ici traduit de notre test original realise en polonais) :

{
  "model": "openai/gpt-6-luna",
  "messages": [
    {"role": "user", "content": "Ecris une seule phrase sur Cracovie."}
  ]
}

L’erreur la plus frequente chez les debutants consiste a laisser une virgule apres le dernier element d’un objet ou d’une liste. La syntaxe JSON l’interdit strictement et le serveur retournera une erreur 400. Si vous souhaitez que le modele reponde lui-meme en JSON valide, consultez le guide Structured outputs : forcer l’IA a repondre en JSON.

Methodes HTTP : GET, POST et leurs usages

En pratique, vous utiliserez principalement deux methodes : GET pour explorer les ressources disponibles et POST pour executer des generations.

Codes d’erreur et statuts HTTP : 401, 429, 500

Le code d’etat est un nombre a trois chiffres place en entete de reponse. Le premier chiffre indique l’origine de l’evenement : 2xx signale un succes, 4xx pointe une erreur dans votre requete, et 5xx reflete une panne du serveur distant.

Voici le retour obtenu lors d’un test sans en-tete Authorization aupres d’OpenRouter :

$ curl -s https://openrouter.ai/api/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"openai/gpt-6-luna","messages":[{"role":"user","content":"salut"}]}'
{"error":{"message":"No cookie auth credentials found","code":401}}

Et voici deux erreurs capturees par mon script Python : une cle invalide, puis un modele imaginaire. Remarque utile : face a un nom de modele inexistant, OpenRouter renvoie un code 400 et non 404 ; evitez donc de figer votre logique de gestion d’erreurs sur un seul statut.

401: verifiez la cle API (Error code: 401 - {'error': {'message': 'User not found.', 'code': 401}})

400: corrigez la requete (Error code: 400 - {'error': {'message': 'openai/gpt-7-nie-istnieje is not a valid model ID', 'code': 400}})

Pour decouvrir comment intercepter ces exceptions en code et reessayer automatiquement apres une erreur 429, lisez l’article Premiere requete API en Python.

Premier appel avec curl dans le terminal

curl est un utilitaire en ligne de commande concu pour transferer des donnees via HTTP. Il est disponible par defaut sous Windows 10 et 11 (sous le nom curl.exe), macOS et Linux, sans aucune installation prealable. Commencons par un appel GET sans cle d’authentification pour lister les modeles disponibles sur OpenRouter :

{"data":[{"id":"inclusionai/ling-3.1-flash","canonical_slug":"inclusionai/ling-3.1-flash-20261002","hugging_face_id":null,"name":"inclusionAI: Ling 3.1 Flash","created":1790950024,"description":"Ling 3.1 Flash is a hybrid reasoning mixture-of-experts model from inclusionAI, with 25B active parameters out of 560B total.","context

La reponse retourne un objet contenant une liste data qui recensait 466 modeles le 4 octobre. Passons a une requete POST complete envoyee au modele. Une cle d’API prealable est requise (voir le pas-a-pas detaille dans l’article Cle API : comment l’obtenir et la securiser). Sous Git Bash, Linux ou macOS :

#!/usr/bin/env bash
# Premiere requete curl (Git Bash, Linux, macOS). Au prealable : export OPENROUTER_API_KEY=sk-or-v1-...
# Note : prompt de test traduit du test original realise en polonais ("Napisz jedno zdanie o Krakowie.")
curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-luna",
    "messages": [{"role": "user", "content": "Ecris une seule phrase sur Cracovie."}]
  }'

Sous PowerShell, les guillemets du format JSON provoquent regulierement des erreurs d’echappement. Il est plus simple d’enregistrer la structure dans un fichier requete.json que curl charge directement. Pensez a taper curl.exe pour eviter tout conflit avec les alias historiques de PowerShell :

# Windows PowerShell : contenu de la requete stocke dans requete.json
# Au prealable dans la meme session : $env:OPENROUTER_API_KEY = "sk-or-v1-..."
curl.exe -s https://openrouter.ai/api/v1/chat/completions `
  -H "Authorization: Bearer $env:OPENROUTER_API_KEY" `
  -H "Content-Type: application/json" `
  -d "@requete.json"

J’ai teste ces deux methodes sous Windows 11 (Git Bash avec curl 8.22 et PowerShell). Dans les deux cas, le modele a retourne une phrase sur Cracovie pour un cout unitaire d’environ 0,00002 USD (environ 0,000018 EUR selon le taux de reference BCE du 12/10/2026 de 1 EUR = 1,1181 USD ; source : https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml). Les fichiers d’exemple sont regroupes dans le kit api-starter.

Prochaines etapes

1. Creez votre compte et generez une cle : Cles API chez OpenAI, Anthropic, Google AI Studio et OpenRouter.
2. Ecrivez votre premier script d’appel : Premiere requete a une API d’IA en Python.
3. Estimez vos depenses : Comprendre les tokens d’IA et calculer leur cout.
4. Passez a l’etape superieure avec l’automatisation : Creer des agents IA de zero.

Questions frequentes

C’est quoi une API en termes simples ?

C’est un mecanisme standardise qui permet a deux logiciels de communiquer : l’un envoie une demande formulee selon des regles precises, et l’autre transmet la reponse attendue sans devoiler son code interne.

Que signifie le sigle API ?

Application Programming Interface, soit interface de programmation d’application. Le mot interface designe le pont technique entre deux programmes, a l’image d’un tableau de bord pour un utilisateur humain.

Faut-il savoir coder pour utiliser une API ?

Pas pour executer un premier test : un terminal et une commande curl copiee-collee suffisent. Pour construire un flux de travail durable, des bases en Python ou l’usage d’outils no-code comme n8n ou Zapier facilitent les appels automatiques.

Quelle est la difference entre une API et ChatGPT ?

ChatGPT est une application grand public assortie d’un abonnement mensuel, d’une interface graphique et d’un historique. L’API d’OpenAI offre un acces technique reserve aux programmes, facture a l’usage par token sans memoire automatique. L’abonnement a ChatGPT ne donne pas acces aux API : il s’agit de comptes et de facturations distincts.

Qu’est-ce qu’une API REST ?

Il s’agit du style d’architecture web le plus repandu : chaque ressource possede son URL dediee, les actions sont determinees par des verbes HTTP (GET, POST, DELETE) et les echanges s’effectuent majoritairement en JSON. Les API de modeles d’IA actuelles adoptent ce standard.

Sources et verification

Les requetes de test ont ete executees le 4 octobre 2026 sous Windows 11 via OpenRouter. Cout cumule de l’ensemble des requetes de cet article : moins de 0,0001 USD (moins de 0,00009 EUR au taux BCE du 12/10/2026).

• OpenRouter - Demarrage rapide (Quickstart)
• OpenRouter - Referentiel des codes d’erreur
• MDN Web Docs - Codes de statut de reponse HTTP
• json.org - Specification du format JSON
• Anthropic - Documentation des erreurs d’API (dont le code 529)

// lire la suiteHiggsfield plugins : Blender, Premiere Pro, After Effects en 2026GuidesWaking Up : guide et plan pour votre premier moisGuidesPremier agent IA dans n8n : répondre aux emails étape par étapeGuides

Kinetyra