Documentation de l'API

Archivarix Tube Search fournit une API REST pour l'accès programmatique aux métadonnées de vidéos YouTube archivées, aux sous-titres et aux résumés IA. Cette page est la référence complète de l'API.

L'accès à l'API nécessite l'abonnement MCP + API. Consultez les Tarifs pour plus de détails.

Authentification

Les clés API sont créées dans votre Profil → onglet API. Incluez la clé dans chaque requête en utilisant l'un de ces en-têtes :

X-API-Key: tsk_VOTRE_CLE_ICI

ou

Authorization: Bearer tsk_VOTRE_CLE_ICI

Les clés utilisent le préfixe tsk_. Gardez votre clé secrète — elle accorde un accès complet à l'API au nom de votre compte.

Points de terminaison

Recherche (Recherche de chaînes via SSE)

La recherche de chaînes est un processus en deux étapes : créer une session de recherche, puis consommer les résultats via Server-Sent Events.

POST /api/search

Lancer une nouvelle recherche de chaîne.

Corps de la requête (JSON) :

{
  "query": "@identifiant ou URL de chaîne ou URL/ID de vidéo"
}

Réponse :

{
  "data": {
    "searchSessionId": "uuid",
    "sseEndpointUrl": "/api/search/uuid/stream",
    "channelId": "UCxxxxxx",
    "channelTitle": "Nom de la chaîne"
  }
}

GET /api/search/:sessionId/stream

Connectez-vous au flux SSE pour recevoir les résultats en temps réel. Définissez l'en-tête Accept: text/event-stream. Consultez la section Protocole SSE pour les types d'événements.

POST /api/search/:sessionId/continue

Continuer une recherche paginée pour charger la page suivante des résultats d'archive.

GET /api/search/background-status/:channelId

Vérifier si une recherche de chaîne est en cours en arrière-plan.

Réponse :

{
  "data": {
    "running": true,
    "searchSessionId": "uuid"
  }
}

Recherche en texte intégral

GET /api/fts

Rechercher dans tous les titres et descriptions de vidéos indexés.

Paramètres de requête :

Sous-titres

GET /api/subtitles/:videoId

Télécharger les sous-titres d'une vidéo.

Paramètres de requête :

POST /api/subtitles/:videoId/fetch

Récupérer les sous-titres à la demande via yt-dlp ou Wayback Machine. Lance une tâche en arrière-plan si les sous-titres ne sont pas encore disponibles.

POST /api/subtitles/bulk-download

Télécharger les sous-titres de plusieurs vidéos en une fois.

Corps de la requête (JSON) :

{
  "videoIds": ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
  "query": "requête optionnelle pour mise en surbrillance"
}

Résumés IA

POST /api/summary/generate

Générer un résumé IA pour une vidéo. Nécessite des sous-titres disponibles.

Corps de la requête (JSON) :

{
  "videoId": "dQw4w9WgXcQ",
  "private": false
}

Réponse (202 Accepted) :

{
  "data": {
    "status": "generating",
    "videoId": "dQw4w9WgXcQ"
  }
}

GET /api/summary/:videoId

Obtenir le résumé IA pour une vidéo spécifique.

DELETE /api/summary/:videoId

Supprimer un résumé. Administrateurs uniquement.

GET /api/summary/browse

Parcourir les résumés avec des filtres.

Paramètres de requête :

GET /api/summary/latest

Obtenir les résumés les plus récemment générés.

GET /api/summary/tags

Obtenir les tags populaires de tous les résumés.

GET /api/summary/languages

Obtenir les langues disponibles des résumés avec les compteurs.

GET /api/summary/channels

Obtenir les chaînes qui ont des résumés.

Statut de la vidéo

GET /api/videos/:videoId/status-history

Obtenir l'historique des changements de statut d'une vidéo (ex., live → deleted → re-uploaded).

Système

GET /api/health

Point de terminaison de vérification de santé. Renvoie le statut du serveur.

GET /api/features

Obtenir les indicateurs de fonctionnalités et les limites pour l'utilisateur/niveau actuel.

GET /api/tiers

Obtenir les données de comparaison des niveaux (limites et fonctionnalités par niveau).

Protocole SSE

Le flux de recherche de chaînes envoie des Server-Sent Events. Chaque événement a un type et des données JSON :

Limites de débit

Les requêtes API (niveau MCP + API) ont les limites suivantes :

Lorsqu'une limite est dépassée, l'API renvoie HTTP 429 avec le code d'erreur RATE_LIMITED.

Codes d'erreur

Toutes les erreurs renvoient du JSON avec un objet d'erreur :

{"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded"}}

Exemples

curl

# Lancer une recherche de chaîne
curl -X POST https://tube.archivarix.net/api/search \
  -H "X-API-Key: tsk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"query": "@MrBeast"}'

# Recevoir les résultats (SSE)
curl -N https://tube.archivarix.net/api/search/SESSION_ID/stream \
  -H "X-API-Key: tsk_VOTRE_CLE" \
  -H "Accept: text/event-stream"

# Continuer la recherche paginée
curl -X POST https://tube.archivarix.net/api/search/SESSION_ID/continue \
  -H "X-API-Key: tsk_VOTRE_CLE"

# Recherche en texte intégral
curl "https://tube.archivarix.net/api/fts?q=video+supprimee&pageSize=20&sort=relevance" \
  -H "X-API-Key: tsk_VOTRE_CLE"

# Télécharger les sous-titres (SRT)
curl https://tube.archivarix.net/api/subtitles/dQw4w9WgXcQ \
  -H "X-API-Key: tsk_VOTRE_CLE"

# Récupérer les sous-titres à la demande
curl -X POST https://tube.archivarix.net/api/subtitles/dQw4w9WgXcQ/fetch \
  -H "X-API-Key: tsk_VOTRE_CLE"

# Générer un résumé IA
curl -X POST https://tube.archivarix.net/api/summary/generate \
  -H "X-API-Key: tsk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"videoId": "dQw4w9WgXcQ"}'

# Obtenir un résumé
curl https://tube.archivarix.net/api/summary/dQw4w9WgXcQ \
  -H "X-API-Key: tsk_VOTRE_CLE"

# Parcourir les résumés par tag
curl "https://tube.archivarix.net/api/summary/browse?tag=music&limit=10" \
  -H "X-API-Key: tsk_VOTRE_CLE"

# Vérification de santé
curl https://tube.archivarix.net/api/health

Python

import requests

API_KEY = "tsk_VOTRE_CLE"
BASE = "https://tube.archivarix.net"
headers = {"X-API-Key": API_KEY}

# --- Recherche de chaîne ---
resp = requests.post(f"{BASE}/api/search",
    headers=headers,
    json={"query": "@MrBeast"})
session = resp.json()["data"]
search_id = session["searchSessionId"]

# Recevoir les résultats (SSE)
with requests.get(f"{BASE}/api/search/{search_id}/stream",
    headers={**headers, "Accept": "text/event-stream"},
    stream=True) as r:
    for line in r.iter_lines(decode_unicode=True):
        if line.startswith("data:"):
            print(line[5:])

# --- Recherche en texte intégral ---
resp = requests.get(f"{BASE}/api/fts",
    headers=headers,
    params={"q": "vidéo supprimée", "pageSize": 20, "sort": "relevance"})
print(resp.json())

# --- Télécharger les sous-titres ---
resp = requests.get(f"{BASE}/api/subtitles/dQw4w9WgXcQ",
    headers=headers,
    params={"format": "srt"})
with open("subtitles.srt", "w") as f:
    f.write(resp.text)

# --- Générer un résumé IA ---
resp = requests.post(f"{BASE}/api/summary/generate",
    headers=headers,
    json={"videoId": "dQw4w9WgXcQ"})
print(resp.json())  # {"data": {"status": "generating", ...}}

# --- Obtenir un résumé ---
resp = requests.get(f"{BASE}/api/summary/dQw4w9WgXcQ",
    headers=headers)
summary = resp.json()["data"]
print(summary["title"], summary["tags"])

JavaScript (Node.js / Browser)

const API_KEY = "tsk_VOTRE_CLE";
const BASE = "https://tube.archivarix.net";
const headers = { "X-API-Key": API_KEY };

// --- Recherche de chaîne ---
const searchResp = await fetch(`${BASE}/api/search`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ query: "@MrBeast" }),
});
const { data: { searchSessionId } } = await searchResp.json();

// Recevoir les résultats (SSE)
const es = new EventSource(
  `${BASE}/api/search/${searchSessionId}/stream`
);
es.addEventListener("search:video", (e) => {
  const video = JSON.parse(e.data);
  console.log(video.title, video.videoId);
});
es.addEventListener("search:complete", () => es.close());

// --- Recherche en texte intégral ---
const ftsResp = await fetch(
  `${BASE}/api/fts?q=video+supprimee&pageSize=20`,
  { headers }
);
const results = await ftsResp.json();

// --- Télécharger les sous-titres ---
const subResp = await fetch(
  `${BASE}/api/subtitles/dQw4w9WgXcQ?format=srt`,
  { headers }
);
const srtText = await subResp.text();

// --- Générer un résumé IA ---
const sumResp = await fetch(`${BASE}/api/summary/generate`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ videoId: "dQw4w9WgXcQ" }),
});
console.log(await sumResp.json());

// --- Parcourir les résumés ---
const browseResp = await fetch(
  `${BASE}/api/summary/browse?tag=music&limit=10`,
  { headers }
);
console.log(await browseResp.json());