Conversation (chat completions)

POST /v1/chat/completions est le point d’accès des modèles de conversation. Le corps de la requête et la réponse suivent l’API Chat Completions d’OpenAI : les SDK d’OpenAI s’en servent sans réglage particulier.

POST https://api.realmoon.ai/v1/chat/completions

• Authentification : clé sk-moon-… avec la portée inference (voir Authentification).
• Corps : JSON (Content-Type: application/json).
• Réponse : un objet chat.completion, ou un flux SSE de morceaux chat.completion.chunk avec "stream": true.
• Facturation : à l’usage, sur le porte-monnaie du workspace de la clé (voir Coûts).

Exemple#Lien vers la section Exemple

curl https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "anthropic/claude-haiku-4.5",
        "messages": [
          {"role": "system", "content": "Tu réponds en une phrase."},
          {"role": "user", "content": "Qu’est-ce qu’une API ?"}
        ],
        "max_tokens": 300,
        "temperature": 0.3
      }'

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.realmoon.ai/v1", api_key=os.environ["MOONAI_API_KEY"])

response = client.chat.completions.create(
    model="anthropic/claude-haiku-4.5",
    messages=[
        {"role": "system", "content": "Tu réponds en une phrase."},
        {"role": "user", "content": "Qu’est-ce qu’une API ?"},
    ],
    max_tokens=300,
    temperature=0.3,
)
print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://api.realmoon.ai/v1', apiKey: process.env.MOONAI_API_KEY });

const response = await client.chat.completions.create({
  model: 'anthropic/claude-haiku-4.5',
  messages: [
    { role: 'system', content: 'Tu réponds en une phrase.' },
    { role: 'user', content: 'Qu’est-ce qu’une API ?' },
  ],
  max_tokens: 300,
  temperature: 0.3,
});
console.log(response.choices[0].message.content);

Paramètres#Lien vers la section Paramètres

Le corps est un objet JSON. Les paramètres du tableau sont transmis au modèle, sauf provider et transforms, vérifiés à part (voir Préférences de fournisseur) ; les autres sont retirés sans erreur (voir Paramètres ignorés). Un modèle peut refuser un paramètre qu’il ne connaît pas (400 unsupported_parameter).

Les réglages d’échantillonnage dépendent du modèle : un modèle peut en ignorer certains.

Préférences de fournisseur#Lien vers la section Préférences de fournisseur

Un même modèle peut être servi par plusieurs fournisseurs. L’objet provider restreint ou ordonne ce choix ; il ne l’élargit jamais.

• Les listes comptent 64 noms au plus.
• Une valeur par défaut (allow_fallbacks: true, zdr: false, data_collection: "allow", liste vide) est ignorée.
• Toute autre clé, ou une valeur invalide, est refusée avec 400 unsupported_parameter et param qui la nomme (par exemple provider.foo).
• Le prix maximal transmis n’est jamais plus haut que le prix du modèle dans /v1/models : une préférence ne fait jamais servir la requête plus cher que ce que la réserve couvre.
• Tous les modèles ne prennent pas ces préférences en charge. Sur un modèle qui ne les accepte pas, par exemple un modèle hébergé par Moon AI, une préférence active est refusée avec 400 unsupported_parameter (param: "provider").
• Les engagements data_collection et zdr sont ceux que déclarent les fournisseurs ; Moon AI ne les contrôle pas.

transforms: ["middle-out"] raccourcit le milieu d’une conversation trop longue pour la fenêtre de contexte du modèle. Toute autre valeur est refusée (400 unsupported_parameter, param: "transforms"), comme middle-out sur un modèle qui ne prend pas les préférences de fournisseur en charge.

Messages#Lien vers la section Messages

messages est un tableau d’objets message, du plus ancien au plus récent.

Un content en tableau contient des parties :

Toute autre partie est refusée avec 400 unsupported_content, en particulier :

• un fichier désigné par son identifiant (file_id) : envoyez son contenu dans file_data ;
• une vidéo ;
• de l’audio envoyé comme file : utilisez une partie input_audio ;
• de l’audio sur un modèle dont le prix de l’audio n’est pas connu.

Réponse#Lien vers la section Réponse

Sans flux, la réponse est un objet chat.completion.

{
  "id": "gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a",
  "object": "chat.completion",
  "created": 1793577600,
  "model": "anthropic/claude-haiku-4.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Une API est une interface qui permet à deux logiciels d’échanger des données."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42 }
}

La réponse ne donne jamais le coût, ni le fournisseur qui a servi le modèle : provider, system_fingerprint, native_finish_reason et les champs de coût de usage sont retirés.

En-têtes de réponse#Lien vers la section En-têtes de réponse

Flux#Lien vers la section Flux

Avec "stream": true, la réponse arrive en Server-Sent Events (Content-Type: text/event-stream) au format d’OpenAI. Le statut HTTP (200) et les en-têtes partent avec le premier octet.

curl -N https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "anthropic/claude-haiku-4.5",
        "messages": [{"role": "user", "content": "Écris un haïku sur la Lune."}],
        "stream": true
      }'

stream = client.chat.completions.create(
    model="anthropic/claude-haiku-4.5",
    messages=[{"role": "user", "content": "Écris un haïku sur la Lune."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

const stream = await client.chat.completions.create({
  model: 'anthropic/claude-haiku-4.5',
  messages: [{ role: 'user', content: 'Écris un haïku sur la Lune.' }],
  stream: true,
});
for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
  if (chunk.usage) console.log('\n', chunk.usage);
}

Format des événements#Lien vers la section Format des événements

Chaque événement est une ligne data: suivie d’un objet JSON, puis une ligne vide. Le dernier événement est data: [DONE]. Les lignes qui commencent par : sont des commentaires.

data: {"id":"gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a","object":"chat.completion.chunk","created":1793577600,"model":"anthropic/claude-haiku-4.5","choices":[{"index":0,"delta":{"role":"assistant","content":"Lune"},"finish_reason":null}]}

data: {"id":"gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a","object":"chat.completion.chunk","created":1793577600,"model":"anthropic/claude-haiku-4.5","choices":[{"index":0,"delta":{"content":" pâle au-dessus des toits"},"finish_reason":null}]}

: keep-alive

data: {"id":"gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a","object":"chat.completion.chunk","created":1793577600,"model":"anthropic/claude-haiku-4.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"gen-6f1c2b7e9a4d4c0e8b3a5d2f1e0c9b8a","object":"chat.completion.chunk","created":1793577600,"model":"anthropic/claude-haiku-4.5","choices":[],"usage":{"prompt_tokens":16,"completion_tokens":21,"total_tokens":37}}

data: [DONE]

• Le morceau qui porte usage arrive toujours, même sans stream_options : vérifiez que choices n’est pas vide avant de le lire.
• Des commentaires : keep-alive arrivent pendant que le modèle réfléchit, pour garder la connexion ouverte. Les SDK les ignorent.
• Quand Moon Blur a remplacé une valeur, elle est remise dans le texte, le raisonnement et les arguments d’outils, même quand un jeton est coupé entre deux morceaux.
• Si le flux est coupé de notre côté ou chez le fournisseur, un dernier événement data: {"error": {"message": "upstream stream interrupted", "type": "server_error", "code": "upstream_error"}} signale que la réponse est incomplète. Les SDK le lèvent comme une erreur pendant l’itération.
• Le flux dure une heure au plus, et il est coupé si le modèle n’envoie rien pendant 5 minutes.
• Le coût est réglé à la fin du flux. Si votre client ferme la connexion avant, la requête est réglée sur le coût que le fournisseur annonce pour ce qu’il a produit, ou garde une partie de sa réserve (voir Règlement).

Outils (function calling)#Lien vers la section Outils (function calling)

Seuls les outils de type function, exécutés par votre programme, sont acceptés. Un outil d’un autre type (exécuté par le fournisseur, comme une recherche web) est refusé avec 400 unsupported_parameter et param: "tools".

curl https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "anthropic/claude-haiku-4.5",
        "messages": [{"role": "user", "content": "Quel temps fait-il à Lyon ?"}],
        "tools": [{
          "type": "function",
          "function": {
            "name": "meteo",
            "description": "Météo actuelle d’une ville",
            "parameters": {
              "type": "object",
              "properties": {"ville": {"type": "string"}},
              "required": ["ville"]
            }
          }
        }],
        "tool_choice": "auto"
      }'

import json

tools = [{
    "type": "function",
    "function": {
        "name": "meteo",
        "description": "Météo actuelle d’une ville",
        "parameters": {
            "type": "object",
            "properties": {"ville": {"type": "string"}},
            "required": ["ville"],
        },
    },
}]
messages = [{"role": "user", "content": "Quel temps fait-il à Lyon ?"}]

first = client.chat.completions.create(model="anthropic/claude-haiku-4.5", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)

messages.append(first.choices[0].message)
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps({"ville": args["ville"], "ciel": "dégagé", "temperature": 18})})

final = client.chat.completions.create(model="anthropic/claude-haiku-4.5", messages=messages, tools=tools)
print(final.choices[0].message.content)

const tools = [{
  type: 'function',
  function: {
    name: 'meteo',
    description: 'Météo actuelle d’une ville',
    parameters: {
      type: 'object',
      properties: { ville: { type: 'string' } },
      required: ['ville'],
    },
  },
}];
const messages = [{ role: 'user', content: 'Quel temps fait-il à Lyon ?' }];

const first = await client.chat.completions.create({ model: 'anthropic/claude-haiku-4.5', messages, tools });
const call = first.choices[0].message.tool_calls[0];
const args = JSON.parse(call.function.arguments);

messages.push(first.choices[0].message);
messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify({ ville: args.ville, ciel: 'dégagé', temperature: 18 }) });

const final = await client.chat.completions.create({ model: 'anthropic/claude-haiku-4.5', messages, tools });
console.log(final.choices[0].message.content);

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_01",
      "type": "function",
      "function": { "name": "meteo", "arguments": "{\"ville\":\"Lyon\"}" }
    }
  ]
}

• Tous les modèles ne savent pas appeler des outils.
• Les arguments (function.arguments) arrivent sous forme de chaîne JSON. Quand Moon Blur a masqué une valeur, elle est remise dans les arguments, qui restent du JSON valide.
• finish_reason vaut tool_calls quand le modèle attend le résultat de vos fonctions.

Images et fichiers#Lien vers la section Images et fichiers

Un modèle qui lit les images accepte des parties image_url dans un message user.

curl https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "anthropic/claude-haiku-4.5",
        "messages": [{
          "role": "user",
          "content": [
            {"type": "text", "text": "Décris cette image."},
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
          ]
        }]
      }'

import base64

with open("photo.jpg", "rb") as f:
    data_url = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="anthropic/claude-haiku-4.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Décris cette image."},
            {"type": "image_url", "image_url": {"url": data_url}},
        ],
    }],
)
print(response.choices[0].message.content)

import fs from 'node:fs';

const dataUrl = 'data:image/jpeg;base64,' + fs.readFileSync('photo.jpg').toString('base64');

const response = await client.chat.completions.create({
  model: 'anthropic/claude-haiku-4.5',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'Décris cette image.' },
      { type: 'image_url', image_url: { url: dataUrl } },
    ],
  }],
});
console.log(response.choices[0].message.content);

• Une image à une adresse https:// est lue par le fournisseur du modèle, pas par Moon AI.
• Sur les modèles d’OpenAI, une image sans detail (ou avec auto) est envoyée avec detail: "high".
• Pour la plupart des modèles, un PDF envoyé dans une partie file est lu par le modèle s’il sait lire les fichiers ; sinon, son texte en est extrait avant l’envoi.
• La réserve d’une requête tient compte de ses pièces jointes. Une image d’un modèle dont le traitement des images n’est pas connu, un fichier PDF ou un audio peuvent être retenus jusqu’à la taille de la fenêtre de contexte : la réserve peut être élevée, mais elle est rendue après la réponse (voir Coûts).

Moon Blur ne lit que le texte : les images, fichiers et sons partent tels quels.

Raisonnement#Lien vers la section Raisonnement

Les modèles de raisonnement acceptent reasoning_effort ou l’objet reasoning selon leur famille. Quand le modèle renvoie son raisonnement, il arrive dans un champ du message ou du morceau de flux (reasoning ou reasoning_content, selon le modèle). Les jetons de raisonnement sont des jetons de sortie : ils sont comptés dans usage et dans la limite de sortie.

Longueur de la réponse#Lien vers la section Longueur de la réponse

• Avec max_tokens (ou max_completion_tokens), le modèle ne produit pas plus que cette valeur, raisonnement compris. Un budget reasoning.max_tokens plus grand est ramené à cette valeur.
• Sans max_tokens, la réponse dispose d’au moins 4 096 jetons de sortie (moins si la limite du modèle est plus basse). Si le solde ou un plafond de dépense ne couvre pas cette taille, la requête est refusée (402) plutôt que servie en quelques mots. Au-delà, la limite monte jusqu’à celle du modèle (16 384 jetons au plus), tant qu’une petite part de ce qu’il reste au solde et aux plafonds la couvre, pour laisser de la place aux requêtes simultanées. Elle laisse aussi la place de l’entrée dans la fenêtre de contexte.
• Pour un modèle de raisonnement d’OpenAI appelé directement, la limite est envoyée sous le nom max_completion_tokens.

Fixer max_tokens rend la réserve plus petite et plus prévisible. C’est recommandé quand beaucoup de requêtes partent en même temps.

Paramètres ignorés#Lien vers la section Paramètres ignorés

Ces paramètres sont retirés avant l’envoi, sans erreur : store, metadata, service_tier, modalities, audio, prediction, web_search_options, plugins, stream_options (le serveur demande lui-même l’usage en fin de flux) et tout paramètre absent du tableau des paramètres. Le paramètre store ne peut donc pas demander au fournisseur de garder vos requêtes.

Erreurs#Lien vers la section Erreurs

Les erreurs de clé et de débit, communes à toute l’API, sont dans Erreurs. Les refus du modèle sont relayés sans le nom de son fournisseur, ses liens ni ses identifiants internes.

Voir aussi#Lien vers la section Voir aussi

• Modèles : les identifiants et les prix.
• Solde et coût d’une requête : lire le coût d’une conversation.
• Limites : débit, durées et nouvelles tentatives.