Documentation API

Intègre Louana dans tes applications via une API RESTful performante. Retrouve ci-dessous la théorie et tous les exemples pratiques.

01 · Authentification

Authorization: Bearer lou_votre_clé_api

02 · Chat API (Théorie)

POST /api/v1/chat

Endpoint principal pour discuter avec le modèle.

Requête Attendue

{ "message": "Bonjour Louana" }

Réponse du Serveur

{ "response": "Bonjour !" }

Bibliothèque d'exemples

01. Requête cURL (Terminal)

La méthode la plus rapide pour tester l'API directement depuis votre terminal, sans avoir à écrire la moindre ligne de code.

curl -X POST https://louana.echo-host.net/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Explique-moi le théorème de Pythagore"}'

02. Exemple Simple (JavaScript)

C'est la méthode la plus basique pour interroger l'API avec fetch(). Idéal pour un test rapide ou un script court. Elle inclut une vérification de base (!response.ok).

async function chatWithLouana(message, apiKey) {
  try {
    const response = await fetch("https://louana.echo-host.net/api/v1/chat", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ message }),
    });

    if (!response.ok) {
      console.error("Erreur API:", await response.json());
      return null;
    }
    return (await response.json()).response;
  } catch (error) {
    console.error("Erreur réseau:", error);
    return null;
  }
}

03. Gestion d'Erreurs Avancée

En production, l'API peut retourner des erreurs (quota dépassé, serveur surchargé). Ce script gère précisément les codes HTTP (400, 401, 429) et implémente un système de "Retry" (réessai automatique) en cas d'erreur 500.

async function chatWithError(message, apiKey) {
  const maxRetries = 3;
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const response = await fetch("https://louana.echo-host.net/api/v1/chat", {
        method: "POST",
        headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
        body: JSON.stringify({ message })
      });

      switch (response.status) {
        case 200: return await response.json();
        case 400: throw new Error("Message invalide");
        case 401: throw new Error("Clé API expirée");
        case 429: 
          const data = await response.json();
          throw new Error(`Quota dépassé: ${data.quotaUsed}/${data.quotaMax}`);
        case 500: throw new Error("Erreur serveur");
        default: throw new Error(`HTTP ${response.status}`);
      }
    } catch (error) {
      attempt++;
      if (attempt < maxRetries && error.message === "Erreur serveur") {
        await new Promise(r => setTimeout(r, 2000)); // Attente 2s
      } else if (attempt >= maxRetries) {
        throw error;
      }
    }
  }
}

04. Récupération des Statistiques

Utilise cet appel pour afficher à l'utilisateur son pourcentage d'utilisation, ses crédits restants et la date de réinitialisation de ses quotas.

async function getApiStats(apiKey) {
  const response = await fetch("https://louana.echo-host.net/api/v1/stats", {
    headers: { "Authorization": `Bearer ${apiKey}` },
  });

  if (!response.ok) throw new Error("Impossible de récupérer les stats");
  
  const stats = await response.json();
  const percentage = (stats.quotaUsed / stats.quotaMax) * 100;
  
  console.log(`Utilisation: ${percentage.toFixed(2)}%`);
  return stats;
}

05. Classe OOP (JavaScript)

Plutôt que de passer l'URL et la clé API à chaque fonction, encapsuler la logique dans une Classe permet de garder le contexte proprement tout au long du cycle de vie de l'application.

class LouanaAPI {
  constructor(apiKey, baseUrl = "https://louana.echo-host.net") {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
    this.stats = null;
  }

  async sendMessage(message) {
    const response = await fetch(`${this.baseUrl}/api/v1/chat`, {
      method: "POST",
      headers: { "Authorization": `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
      body: JSON.stringify({ message }),
    });
    return await response.json();
  }

  // Utilisation :
  // const api = new LouanaAPI("CLE_API");
  // await api.sendMessage("Hello");
}

06. Implémentation Python

L'équivalent exact de la classe JavaScript, mais pour les backends en Python. Utilise la librairie standard requests.

import requests

class LouanaAPI:
    def __init__(self, api_key, base_url="https://louana.echo-host.net"):
        self.headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
        self.base_url = base_url

    def send_message(self, message):
        response = requests.post(
            f"{self.base_url}/api/v1/chat", 
            headers=self.headers, 
            json={"message": message}
        )
        response.raise_for_status()
        return response.json()

07. Caching Local (Économie de Quotas)

Hérite de notre classe de base pour intercepter les requêtes. Si une question a déjà été posée il y a moins de 24h, on renvoie la réponse stockée en mémoire au lieu de consommer un crédit API.

class CachedLouanaAPI extends LouanaAPI {
  constructor(apiKey) {
    super(apiKey);
    this.cache = new Map();
    this.cacheExpiry = 24 * 60 * 60 * 1000; // 24 heures
  }

  async sendMessage(message) {
    const key = message.toLowerCase().trim();

    if (this.cache.has(key)) {
      const cached = this.cache.get(key);
      if (Date.now() - cached.timestamp < this.cacheExpiry) return cached.data;
    }

    const response = await super.sendMessage(message);
    this.cache.set(key, { data: response, timestamp: Date.now() });
    return response;
  }
}

08. Pagination / Traitement par Lot

Comment traiter un tableau complet de prompts. La fonction inclut un délai (delayMs) entre chaque requête pour éviter de déclencher les sécurités anti-spam (Rate Limiting) de l'API.

async function processBatchMessages(messages, apiKey, delayMs = 100) {
  const results = [];
  for (let i = 0; i < messages.length; i++) {
    try {
      const response = await chatWithLouana(messages[i], apiKey);
      results.push({ message: messages[i], response, status: "success" });
      
      // Pause entre chaque requête
      if (i < messages.length - 1) {
        await new Promise(r => setTimeout(r, delayMs));
      }
    } catch (error) {
      results.push({ message: messages[i], error: error.message, status: "error" });
    }
  }
  return results;
}

09. Stockage Frontend (Local Storage)

Méthodes utilitaires pour sauvegarder la clé API de l'utilisateur dans son navigateur. Attention : Ne faites ça que si l'utilisateur fournit sa propre clé. Ne mettez jamais la clé de votre entreprise en clair dans le frontend.

function saveApiKey(apiKey) {
  localStorage.setItem("louanaApiKey", apiKey);
}

function getApiKey() {
  return localStorage.getItem("louanaApiKey");
}

function clearApiKey() {
  localStorage.removeItem("louanaApiKey");
}

10. Monitoring en Tâche de Fond

Cette fonction tourne en boucle (par défaut chaque minute) pour surveiller la santé du quota. Elle alerte dans la console lorsque les 90% d'utilisation sont atteints.

async function monitorQuota(apiKey, checkInterval = 60000) {
  setInterval(async () => {
    try {
      const stats = await getApiStats(apiKey);
      if (!stats) return;

      const percentage = (stats.quotaUsed / stats.quotaMax) * 100;

      if (percentage >= 100) {
        console.error("❌ Quota atteint - API bloquée jusqu'à demain");
      } else if (percentage > 90) {
        console.warn("⚠️ Attention: Quota à 90%!");
      }
    } catch (error) {
      console.error("Erreur monitoring:", error);
    }
  }, checkInterval);
}