Albert API — Référence consolidée

API d'inférence de l'État français, opérée par le département IAE de la DINUM (commun numérique OpenGateLLM). Partiellement compatible OpenAI : pour chat/completions et embeddings, réutiliser le SDK openai (ou tout client OpenAI) en changeant simplement base_url et la clé. Les autres surfaces — rerank, RAG, audio, OCR — n'existent pas dans le SDK OpenAI et s'appellent en HTTP direct.

Base URL : https://albert.api.etalab.gouv.fr Spec OpenAPI (fait foi) : https://albert.api.etalab.gouv.fr/openapi.json Doc humaine : https://doc.incubateur.net/alliance/albert-api

Comment utiliser cette skill

• Consommation d'abord. L'usage courant = appeler les modèles (chat, embeddings) et le RAG. Les écritures (créer collection, uploader documents, gérer des clés) ne se font que sur intention explicite de l'utilisateur.
• Compatibilité OpenAI, mais partielle. Pointer un client OpenAI sur https://albert.api.etalab.gouv.fr/v1 évite de réécrire du code pour chat/completions et embeddings, dont les schémas de requête/réponse suivent OpenAI (Albert ajoute des paramètres : search, search_args). Le SDK s'arrête là : rerank, audio/transcriptions, ocr et le RAG n'ont aucune méthode côté SDK — ne jamais générer de client.rerank(...), client.ocr(...) ou client.search(...), ces appels échouent avant même de partir. Les faire en HTTP direct (requests, httpx, curl).
• Ne jamais logger ni afficher le token. Le Bearer token est un secret. Ne pas l'écho dans les réponses, les logs, les exemples copiés. Le lire depuis une variable d'environnement (ALBERT_API_KEY).
• L'OpenAPI fait autorité. En cas de divergence entre ce fichier et la spec récupérée en live, suivre la spec. Son champ info.version change sans préavis (v0.4.7, puis latest, puis 0.6.0post1 à ce jour) : c'est le contenu qui fait foi, pas un semver — bin/check_drift.py détecte les écarts d'endpoints et d'enums.
• Ne pas inventer d'ID de modèle, et ne jamais coder un alias. Lister les modèles via GET /v1/models et utiliser le champ id, jamais une valeur du tableau aliases (cf. § Modèles).