Getting Started

Bienvenue dans la documentation de l’API Magistral ! Ce guide vous aidera à démarrer rapidement avec notre API et à comprendre les concepts fondamentaux pour une intégration réussie.

Prérequis

Avant de commencer à utiliser l’API Magistral, assurez-vous d’avoir :

1. Un compte Magistral actif
2. Un token API valide (voir Authentication pour plus de détails)

Fonctionnement de l’API

Note

L’API Magistral est conçue pour traiter des requêtes de manière asynchrone, ce qui permet une meilleure scalabilité et des performances optimales pour vos traitements.

Processus de Traitement

1. Envoi de la Requête : Envoyez votre requête à l’endpoint approprié
2. Réception de l’ID : Recevez immédiatement un ID unique de traitement
3. Suivi du Traitement : Utilisez l’ID pour suivre l’état de votre requête
4. Réception des Résultats : Obtenez les résultats via la méthode de votre choix

Exemple de réponse avec ID de traitement

{
  "request_id": "req_abc123xyz789",
  "status": "processing",
  "estimated_time": "30s"
}

Réception des Résultats

Nous proposons trois méthodes différentes pour recevoir vos données une fois le traitement terminé :

1. Polling

Le polling consiste à interroger régulièrement notre API pour vérifier si le traitement est terminé :

JavaScript

Exemple de polling

async function checkStatus(requestId) {
  const response = await fetch(`https://api.magistral.com/v1/status/${requestId}`, {
    headers: {
      'Authorization': `Bearer ${VOTRE_TOKEN_API}`
    }
  });
  return await response.json();
}

Python

Exemple de polling

import requests

def check_status(request_id):
  response = requests.get(f"https://api.magistral.com/v1/status/{request_id}",
  headers = {
    "Authorization": f"Bearer {VOTRE_TOKEN_API}"
  })

  return response.json()

Shell

Exemple de polling

curl -X GET "https://api.magistral.com/v1/status/${requestId}" \
-H "Authorization: Bearer ${VOTRE_TOKEN_API}"

2. Webhook

Configurez un endpoint sur votre serveur pour recevoir automatiquement les résultats :

JavaScript

Configuration du webhook

const express = require('express');
const app = express();

app.post('/webhook', express.json(), (req, res) => {
  const result = req.body;
  console.log('Résultat reçu:', result);
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Serveur webhook en écoute sur le port 3000');
});

Python

Configuration du webhook

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    result = request.json
    print('Résultat reçu:', result)
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)

Shell

Test du webhook

# Pour tester votre webhook, vous pouvez utiliser cette commande
curl -X POST "http://votre-serveur.com/webhook" \
-H "Content-Type: application/json" \
-d '{"status": "completed", "result": "..."}'

3. Callback URL

Spécifiez une URL de callback directement dans votre requête :

Exemple avec callback URL

{
  "callback_url": "https://votre-serveur.com/callback",
  "data": {
    // Vos données de requête
  }
}