Chat completions

L’endpoint POST /v1/chat/completions est le point d’entrée principal pour la génération de texte. Le corps de requête et la réponse s’inspirent du modèle OpenAI Chat Completions : messages, paramètres de décodage, response_format, streaming et outils (tools / tool_calls).

Quel type de modèle ?

Pour POST /v1/chat/completions, vous devez utiliser un modèle de type text-generation (voir Types de modèles).

⚠️ Les anciens tutoriels mélangaient parfois des modèles image-text-to-text / image-to-text avec le chat texte. En production, utilisez plutôt ces modèles pour l’OCR ou les endpoints adaptés, et gardez text-generation pour le chat standard.

Avant de commencer

1) Définir votre clé API

export ALBERT_API_KEY="votre_jeton"

2) Choisir un modèle text-generation

curl

curl -sS "https://albert.api.etalab.gouv.fr/v1/models" \
  -H "Authorization: Bearer $ALBERT_API_KEY"

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://albert.api.etalab.gouv.fr/v1",
    api_key=os.environ["ALBERT_API_KEY"],
)

models = client.models.list().data
model = [m for m in models if m.type == "text-generation"][0].id
print("Modèle chat trouvé :", model)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://albert.api.etalab.gouv.fr/v1",
  apiKey: process.env.ALBERT_API_KEY,
});

const models = (await client.models.list()).data;
const model = models.find((m) => m.type === "text-generation")?.id;
console.log("Modèle chat trouvé :", model);

Unstreamed chat

curl

curl -sS "https://albert.api.etalab.gouv.fr/v1/chat/completions" \
  -H "Authorization: Bearer $ALBERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "REMPLACER_PAR_MODELE_TEXT_GENERATION",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, de façon concise."},
      {"role": "user", "content": "Explique ce qu’est une API compatible OpenAI en deux phrases."}
    ],
    "stream": false
  }'

Python

resp = client.chat.completions.create(
    model=model,
    messages=[
        {"role": "system", "content": "Tu réponds en français, de façon concise."},
        {"role": "user", "content": "Explique ce qu’est une API compatible OpenAI en deux phrases."},
    ],
    stream=False,
)

print(resp.choices[0].message.content)

JavaScript

const resp = await client.chat.completions.create({
  model,
  messages: [
    { role: "system", content: "Tu réponds en français, de façon concise." },
    { role: "user", content: "Explique ce qu’est une API compatible OpenAI en deux phrases." },
  ],
  stream: false,
});

console.log(resp.choices[0].message.content);

Streaming (SSE)

Pour activer le streaming, passez stream=True. Le SDK OpenAI renvoie une suite de chunks (deltas) jusqu’à la fin du flux.

curl

curl -N "https://albert.api.etalab.gouv.fr/v1/chat/completions" \
  -H "Authorization: Bearer $ALBERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "REMPLACER_PAR_MODELE_TEXT_GENERATION",
    "messages": [{"role": "user", "content": "Raconte une phrase sur la météo."}],
    "stream": true
  }'

Python

stream = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Raconte une phrase sur la météo."}],
    stream=True,
)

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

JavaScript

const stream = await client.chat.completions.create({
  model,
  messages: [{ role: "user", content: "Raconte une phrase sur la météo." }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices?.[0]?.delta;
  if (delta?.content) process.stdout.write(delta.content);
}
process.stdout.write("\n");

Voir aussi le guide Streaming.

Format de réponse (response_format)

• {"type": "json_object"} : JSON valide (mode “JSON”). Vous devez aussi demander explicitement du JSON côté prompt (system / user) pour éviter des sorties longues inutiles.
• {"type": "json_schema", "json_schema": { ... }} : sorties structurées guidées par un schéma JSON (approche proche des Structured Outputs).

Outils et tool_calls

Le champ tools permet forcer le modèle à gérer des fonctions au format JSON Schema. Le mécanisme tools / tool_choice est décrit dans Function calling.

Multimodal (image + texte) via chat/completions

Albert API peut accepter des entrées multimodales via POST /v1/chat/completions en passant, dans un message user, un content structuré (liste) combinant :

• {"type": "text", "text": "..."}
• {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}

Choisissez un modèle dont le type est généralement image-text-to-text (ou image-to-text selon l’instance).

curl

IMG_BASE64=$(base64 -w 0 "archi_mistral.png")

curl -sS "https://albert.api.etalab.gouv.fr/v1/chat/completions" \
  -H "Authorization: Bearer $ALBERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"REMPLACER_PAR_MODELE_MULTIMODAL\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": [
          {\"type\": \"text\", \"text\": \"Décris l'image et lis le texte visible (si présent). Réponds en français.\"},
          {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,${IMG_BASE64}\"}}
        ]
      }
    ],
    \"max_tokens\": 500
  }"

Python

import base64
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://albert.api.etalab.gouv.fr/v1",
    api_key=os.environ["ALBERT_API_KEY"],
)

with open("archi_mistral.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode("utf-8")

r = client.chat.completions.create(
    model="REMPLACER_PAR_MODELE_MULTIMODAL",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Décris l'image et lis le texte visible (si présent). Réponds en français."},
                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_b64}"}},
            ],
        }
    ],
    max_tokens=500,
)
print(r.choices[0].message.content)

JavaScript

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://albert.api.etalab.gouv.fr/v1",
  apiKey: process.env.ALBERT_API_KEY,
});

const imgB64 = fs.readFileSync("archi_mistral.png").toString("base64");

const r = await client.chat.completions.create({
  model: "REMPLACER_PAR_MODELE_MULTIMODAL",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Décris l'image et lis le texte visible (si présent). Réponds en français." },
        { type: "image_url", image_url: { url: `data:image/png;base64,${imgB64}` } },
      ],
    },
  ],
  max_tokens: 500,
});

console.log(r.choices[0].message.content);

⚠️ À vérifier — Champs additionnels exacts et valeurs par défaut : se référer au schéma CreateChatCompletion dans la page de l’endpoint Chat : page de l’endpoint Chat