Complétions de chat

Point de terminaison : POST /v1/chat/completions. Le format des requêtes et des réponses correspond exactement à celui de l’API OpenAI Chat Completions, y compris pour le flux continu et les champs facultatifs tool_calls / reasoning_tokens.

Appel de base

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": "You are a senior staff engineer."},
        {"role": "user", "content": "Pros and cons of postgres LISTEN/NOTIFY for a job queue?"},
    ],
    max_tokens=800,
)
print(resp.choices[0].message.content)

Paramètres

Tous les paramètres OpenAI standard sont acceptés. Certains ne sont pertinents que pour certains fournisseurs : le traducteur transmet ceux pris en charge par chaque fournisseur en amont.

Diffusion en continu

Définissez stream=True. Kunavo émet des événements envoyés par le serveur au format exact d’OpenAI : chaque fragment est un chat.completion.chunk avec choices[0].delta.content. La charge utile finale d’utilisation arrive avec data: [DONE].

stream = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Explain B-trees in one paragraph."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Appels d’outils / de fonctions

Les appels d’outils fonctionnent avec tous les fournisseurs. Définissez les outils sous forme de schéma JSON ; le modèle renvoie tool_calls dans son message ; vous l’exécutez, puis renvoyez les résultats sous forme de messages role: "tool".

tools = [{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto",
)

# Inspect tool calls the model wants to make
for call in resp.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)

Sortie JSON (response_format)

response_format demande une sortie JSON. Les garanties dépendent de la famille de modèles, car la requête de chaque famille est traduite selon un mécanisme amont différent :

import json

resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Jane Doe <jane@example.com> wants the Pro plan."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "signup",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan": {"type": "string", "enum": ["free", "pro", "enterprise"]},
                },
                "required": ["name", "email", "plan"],
                "additionalProperties": False,
            },
        },
    },
)
signup = json.loads(resp.choices[0].message.content)  # constrained to the schema

Quatre points à connaître sur Claude :

• Le schéma est transmis à Anthropic presque tel que vous l’avez écrit. Anthropic exige additionalProperties: false sur les objets ; Kunavo l’ajoute donc à tout objet qui répertorie ses propriétés et ne le définit pas — c’est ce que produit le model_json_schema() de Pydantic. Anthropic rejette toujours, avec une erreur 400 précisant le problème : un objet laissé ouvert (additionalProperties défini sur une valeur autre que false, ou sans propriétés répertoriées et avec additionalProperties non défini) et oneOf — utilisez anyOf. La page d’Anthropic sur les sorties structurées répertorie les autres cas.
• strict et name sont ignorés : Anthropic applique chaque schéma qu’il accepte, avec ou sans mode strict.
• Un schéma ne peut pas être combiné avec un dernier message assistant (un préremplissage) ; Anthropic renvoie une erreur 400.
• Lorsque max_tokens est épuisé au milieu d’un objet, le JSON est tronqué et finish_reason vaut "length".

Entrée visuelle / multimodale

Les modèles dotés de la capacité vision acceptent des blocs de contenu image. Utilisez une URL HTTPS ou un URI de données base64 data:.

# Pass an image URL or a base64 data URI as part of a multimodal message
resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {
                "url": "https://example.com/cat.jpg"
            }},
        ],
    }],
)
print(resp.choices[0].message.content)

Les modèles compatibles avec la vision du catalogue incluent Claude Opus 5.5 — consultez la liste des modèles pour voir les autres.

Pour une image HTTPS, Kunavo télécharge lui-même le fichier et le transmet au modèle en ligne, car certains fournisseurs en amont ignorent une simple URL d’image. Limites : 16 images par requête, 5 MB par image, 20 MB au total, 10 secondes par téléchargement. Si une image ne peut pas être récupérée, une erreur la nommant est renvoyée au lieu de l’ignorer.

Raisonnement

Le rôle d’un paramètre de raisonnement sur ce point de terminaison dépend de la famille, car la requête de chacune est traduite vers une API en amont différente :

# GPT models: reasoning_effort is forwarded as the Responses API's
# reasoning.effort. Reasoning tokens are part of completion_tokens.
resp = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{"role": "user", "content": "Plan a 3-week MLOps migration."}],
    reasoning_effort="high",
)
details = resp.usage.completion_tokens_details   # absent when no reasoning ran
print(details.reasoning_tokens if details else 0)

Mise en cache des prompts

Un long prompt système, un document de référence, un bloc de quelques exemples : tout préfixe stable peut être mis en cache en amont et réutilisé lors des appels suivants à une fraction du prix d’entrée. Les accès au cache apparaissent dans l’objet d’utilisation sous prompt_tokens_details.cached_tokens.

Les modèles GPT mettent automatiquement le contenu en cache : aucune modification de la requête n’est nécessaire. cached_tokens est un sous-ensemble de prompt_tokens et est facturé à un tarif réduit de lecture du cache.

Claude ne met en cache que jusqu’à un point de rupture cache_control, et pour un prompt long, ce point de terminaison définit les points de rupture à votre place : sur le prompt système, sur les définitions d’outils et sur le dernier message dès que la conversation contient un tour de l’assistant. Pour choisir vous-même le préfixe, ajoutez cache_control à un bloc de contenu, comme ci-dessous ; Kunavo conserve vos points de rupture et n’ajoute les siens qu’aux positions que vous avez laissées libres :

# Claude caches prefixes you mark with cache_control. Attach it to a content
# block; later calls reusing that prefix read it at ~10% of the input price.
resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LONG_DOCUMENT,            # the stable, reused prefix
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Summarize the document above."},
        ],
    }],
)
print(resp.usage.prompt_tokens_details.cached_tokens)

Objet d’utilisation

Chaque réponse (ainsi que le dernier fragment du flux) inclut un objet usage :

Compatibilité d’Ollama avec OpenAI — /v1/chat/completions

Ollama expose ses modèles locaux via une API compatible avec OpenAI à l’adresse http://localhost:11434/v1, en implémentant le même contrat /chat/completions décrit sur cette page. Les deux sont donc interchangeables côté client : tout ce qui fonctionne avec l’API v1 d’Ollama fonctionne avec celle de Kunavo en changeant l’URL de base et le modèle.

from openai import OpenAI

# Before — Ollama's OpenAI-compatible API, local models
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",                       # ignored locally
)
resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

# After — the same call against hosted frontier models.
# Two lines changed. Everything below them is untouched.
client = OpenAI(
    base_url="https://api.kunavo.com/v1",   # <- was localhost:11434/v1
    api_key=os.environ["KUNAVO_API_KEY"],
)
resp = client.chat.completions.create(
    model="claude-sonnet-5",  # <- was llama3.2
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

Les éléments qui posent généralement problème lors du passage d’un fournisseur à un autre ne posent pas problème ici, car le format sur le réseau est identique :

Étapes suivantes

• Messages API native d’Anthropic
• Référence de génération d’images
• Fonctionnement de la facturation (tarifs des jetons, majoration)
• L’API d’Ollama compatible avec OpenAI — et le passage aux modèles hébergés
• Parcourir tous les modèles de chat