Guide des API compatibles OpenAI — de l'endpoint local d'Ollama aux modèles avancés hébergés

« Compatible avec OpenAI » signifie qu’une API utilise le même format filaire que /v1/chat/completions d’OpenAI — tout SDK ou outil OpenAI fonctionne donc avec elle en modifiant uniquement le base_url. Ollama expose un endpoint compatible avec OpenAI pour les modèles exécutés localement sur votre machine. Kunavo en expose un pour les modèles de pointe hébergés — Claude, GPT ainsi que des modèles d’image, de vidéo et d’audio — derrière un seul jeton bearer. Ce guide présente le principe et explique comment passer de l’un à l’autre sans réécrire le code.

Ce que signifie « compatible avec OpenAI »

Le format Chat Completions d’OpenAI est devenu le standard de facto : un tableau messages en entrée, un choices[].message en sortie, des Server-Sent Events pour la diffusion en continu et tools pour les appels de fonctions. Tout endpoint qui respecte ce contrat est « compatible avec OpenAI » ; les SDK officiels openai (Python, Node et tous les ports communautaires) s’y connectent en définissant base_url.

Le modèle Ollama (local)

Ollama exécute des modèles ouverts en local et les sert à http://localhost:11434/v1 :

from openai import OpenAI

# Ollama exposes an OpenAI-compatible endpoint on localhost
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

resp = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Le même code avec des modèles de pointe hébergés (Kunavo)

Pointez exactement le même SDK vers Kunavo et choisissez un modèle de pointe. Seuls base_url, api_key et model changent — l’appel est identique octet par octet :

import os
from openai import OpenAI

# Same SDK, same call shape — only base_url, api_key and model change
client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key=os.environ["KUNAVO_API_KEY"],
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-haiku-4-5, gpt-5-5, gpt-5-6-terra...
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Obtenez une clé à /app/keys ; le démarrage rapide propose des exemples Node et curl.

Local ou hébergé — quand utiliser lequel

Configuration courante : Ollama sur localhost pour le développement hors ligne, Kunavo pour la qualité hébergée en production — une seule variable d’environnement permet de passer de l’un à l’autre. Pour le contrat champ par champ implémenté par les deux extrémités — paramètres, deltas de diffusion, tool_calls, objet usage et tableau de parité avec la surface v1 d’Ollama — consultez la référence /v1/chat/completions et sa section sur la compatibilité OpenAI d’Ollama.

Découvrir les modèles à l’exécution

Comme le /api/tags d’Ollama, Kunavo expose un catalogue au format OpenAI. Résolvez les slugs à l’exécution plutôt que de les coder en dur :

# Discover every enabled model (OpenAI-shaped, like Ollama's /api/tags)
curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

Au-delà du chat

La même clé permet d’atteindre les endpoints d’image (/v1/images/generations), de vidéo (/v1/video/generations) et d’audio — tous au format OpenAI. Consultez le guide de l’IA multimodale et la comparaison avec OpenRouter pour comprendre les différences entre Kunavo et les autres passerelles.

Une surface dépasse la définition habituelle de « compatible » et mérite d’être connue : POST /v1/responses. Codex CLI n’accepte un fournisseur personnalisé que via l’API Responses, raison pour laquelle la plupart des passerelles compatibles avec OpenAI ne peuvent pas le piloter — le coût de Codex par token explique comment y parvenir avec un bloc de configuration opérationnel. Pour calculer le prix d’une charge GPT incluant les entrées mises en cache, le calculateur de tarifs de l’API OpenAI utilise vos propres nombres de tokens.

Questions fréquentes