Aller au contenu
Miraca Miraca Miraca — Docs

Quickstart

L’API Miraca est OpenAI-compatible : si votre outil parle à OpenAI, il parle à Miraca.

1. Récupérer une clé + la base URL

Section intitulée « 1. Récupérer une clé + la base URL »

Depuis le portail développeur : générez une clé API. Vous obtenez :

  • Base URL : https://api.miraca.fr/v1
  • Clé : sk-...

Permissions de la clé

Section intitulée « Permissions de la clé »

À la création, vous choisissez ce que la clé peut faire. Douze permissions, combinables :

PermissionScopeDonne accès à
Chat / inférencechat/v1/chat/completions, /v1/models, embeddings
Bases : lecturekb:readlecture des bases de connaissance (liste, recherche, export)
Bases : écriturekb:writecréation / modification / suppression de bases et documents
Connecteur MCPmcple serveur MCP /v1/mcp (RAG exposé comme outils)
Recherche webweb_searchles outils web_search / web_fetch dans la boucle agentique
Connecteurs APIconnectionsutiliser les connecteurs API (/v1/connections, outils connection:…) et les serveurs MCP de l’organisation (outils mcp:…)
Exécution de codecodel’outil code (sandbox isolé) dans la boucle agentique
Tâches (gestion)tasksgérer les tâches programmées par /v1/tasks ; seul un propriétaire ou un administrateur peut la donner à une clé
Anonymiseur de documentsanonymize/v1/anonymize et /v1/deanonymize
Fichiers : suppressionfilessupprimer un fichier produit (DELETE /v1/files/{id})
Transcription audioaudio/v1/audio/transcriptions
Boîtes mailemailles outils email_* et /v1/mailboxes

Une clé sans liste de permissions est illimitée (rétrocompatibilité).

Une clé qui appelle une surface hors de ses permissions reçoit 403 (401 pour le chat et la transcription audio, refusés par la passerelle). Pour un connecteur (Claude, ChatGPT, n8n), une clé « Connecteur MCP » seule suffit et limite l’exposition. Les clés créées avant cette fonctionnalité restent sans restriction (toutes permissions).

2. Premier appel (curl)

Section intitulée « 2. Premier appel (curl) »
Fenêtre de terminal
curl https://api.miraca.fr/v1/chat/completions \
  -H "Authorization: Bearer $MIRACA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-small",
    "messages": [{"role": "user", "content": "Explique l'\''ESS en une phrase."}],
    "max_tokens": 500
  }'

3. SDK OpenAI (Python)

Section intitulée « 3. SDK OpenAI (Python) »
from openai import OpenAI


client = OpenAI(
    base_url="https://api.miraca.fr/v1",
    api_key="sk-...",
)


resp = client.chat.completions.create(
    model="mistral-small",
    messages=[{"role": "user", "content": "Bonjour !"}],
    max_tokens=500,
)
print(resp.choices[0].message.content)

4. SDK OpenAI (Node.js / TypeScript)

Section intitulée « 4. SDK OpenAI (Node.js / TypeScript) »
import OpenAI from "openai";


const client = new OpenAI({
  baseURL: "https://api.miraca.fr/v1",
  apiKey: process.env.MIRACA_API_KEY,
});


const resp = await client.chat.completions.create({
  model: "mistral-small",
  messages: [{ role: "user", content: "Bonjour !" }],
  max_tokens: 500,
});
console.log(resp.choices[0].message.content);

5. Modèle avec raisonnement interne

Section intitulée « 5. Modèle avec raisonnement interne »

mistral-small raisonne avant de répondre sur les tâches complexes. Ce raisonnement est exposé dans le champ reasoning_content du message (peut être null si le modèle n’a pas jugé utile de raisonner) :

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "La réponse finale.",
      "reasoning_content": "…réflexion interne… (null si absent)"
    }
  }]
}

Pour la sortie structurée (json_schema / json_object), le raisonnement est automatiquement désactivé — reasoning_content est toujours null et max_tokens n’a besoin de couvrir que le JSON final.

L’impact pratique sur max_tokens : les tokens de réflexion sont comptabilisés. Avec une valeur trop basse en mode chat, la réponse peut être vide ou tronquée. Voir Référence API — Raisonnement pour les détails.

Pour aller plus loin

Section intitulée « Pour aller plus loin »