Documentación de la API

Archivarix Tube Search proporciona una API REST para acceso programático a metadatos de vídeos de YouTube archivados, subtítulos y resúmenes de IA. Esta página es la referencia completa de la API.

El acceso a la API requiere la suscripción MCP + API. Consulte Precios para más detalles.

Autenticación

Las claves de API se crean en su Perfil → pestaña API. Incluya la clave en cada solicitud usando uno de estos encabezados:

X-API-Key: tsk_SU_CLAVE_AQUI

o

Authorization: Bearer tsk_SU_CLAVE_AQUI

Las claves usan el prefijo tsk_. Mantenga su clave en secreto — otorga acceso completo a la API en nombre de su cuenta.

Endpoints

Búsqueda (Búsqueda de canales vía SSE)

La búsqueda de canales es un proceso de dos pasos: crear una sesión de búsqueda y luego consumir resultados mediante Server-Sent Events.

POST /api/search

Iniciar una nueva búsqueda de canal.

Cuerpo de la solicitud (JSON):

{
  "query": "@handle o URL del canal o URL/ID de vídeo"
}

Respuesta:

{
  "data": {
    "searchSessionId": "uuid",
    "sseEndpointUrl": "/api/search/uuid/stream",
    "channelId": "UCxxxxxx",
    "channelTitle": "Nombre del canal"
  }
}

GET /api/search/:sessionId/stream

Conéctese al flujo SSE para recibir resultados en tiempo real. Establezca el encabezado Accept: text/event-stream. Consulte la sección Protocolo SSE para los tipos de eventos.

POST /api/search/:sessionId/continue

Continuar una búsqueda paginada para cargar la siguiente página de resultados del archivo.

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

Verificar si una búsqueda de canal se está ejecutando en segundo plano.

Respuesta:

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

Búsqueda de texto completo

GET /api/fts

Buscar en todos los títulos y descripciones de vídeos indexados.

Parámetros de consulta:

Subtítulos

GET /api/subtitles/:videoId

Descargar subtítulos de un vídeo.

Parámetros de consulta:

POST /api/subtitles/:videoId/fetch

Obtener subtítulos bajo demanda vía yt-dlp o Wayback Machine. Inicia una tarea en segundo plano si los subtítulos aún no están disponibles.

POST /api/subtitles/bulk-download

Descargar subtítulos de múltiples vídeos a la vez.

Cuerpo de la solicitud (JSON):

{
  "videoIds": ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
  "query": "consulta opcional para resaltado"
}

Resúmenes de IA

POST /api/summary/generate

Generar un resumen de IA para un vídeo. Requiere subtítulos disponibles.

Cuerpo de la solicitud (JSON):

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

Respuesta (202 Accepted):

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

GET /api/summary/:videoId

Obtener el resumen de IA para un vídeo específico.

DELETE /api/summary/:videoId

Eliminar un resumen. Solo administradores.

GET /api/summary/browse

Explorar resúmenes con filtros.

Parámetros de consulta:

GET /api/summary/latest

Obtener los resúmenes generados más recientemente.

GET /api/summary/tags

Obtener etiquetas populares de todos los resúmenes.

GET /api/summary/languages

Obtener idiomas disponibles de resúmenes con conteos.

GET /api/summary/channels

Obtener canales que tienen resúmenes.

Estado del vídeo

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

Obtener el historial de cambios de estado de un vídeo (ej., live → deleted → re-uploaded).

Sistema

GET /api/health

Endpoint de verificación de estado. Devuelve el estado del servidor.

GET /api/features

Obtener indicadores de funcionalidades y límites para el usuario/nivel actual.

GET /api/tiers

Obtener datos de comparación de niveles (límites y funcionalidades por nivel).

Protocolo SSE

El flujo de búsqueda de canales envía Server-Sent Events. Cada evento tiene un tipo y datos JSON:

Límites de tasa

Las solicitudes API (nivel MCP + API) tienen los siguientes límites:

Cuando se excede un límite, la API devuelve HTTP 429 con el código de error RATE_LIMITED.

Códigos de error

Todos los errores devuelven JSON con un objeto de error:

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

Ejemplos

curl

# Iniciar una búsqueda de canal
curl -X POST https://tube.archivarix.net/api/search \
  -H "X-API-Key: tsk_SU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"query": "@MrBeast"}'

# Recibir resultados (SSE)
curl -N https://tube.archivarix.net/api/search/SESSION_ID/stream \
  -H "X-API-Key: tsk_SU_CLAVE" \
  -H "Accept: text/event-stream"

# Continuar búsqueda paginada
curl -X POST https://tube.archivarix.net/api/search/SESSION_ID/continue \
  -H "X-API-Key: tsk_SU_CLAVE"

# Búsqueda de texto completo
curl "https://tube.archivarix.net/api/fts?q=video+eliminado&pageSize=20&sort=relevance" \
  -H "X-API-Key: tsk_SU_CLAVE"

# Descargar subtítulos (SRT)
curl https://tube.archivarix.net/api/subtitles/dQw4w9WgXcQ \
  -H "X-API-Key: tsk_SU_CLAVE"

# Obtener subtítulos bajo demanda
curl -X POST https://tube.archivarix.net/api/subtitles/dQw4w9WgXcQ/fetch \
  -H "X-API-Key: tsk_SU_CLAVE"

# Generar resumen de IA
curl -X POST https://tube.archivarix.net/api/summary/generate \
  -H "X-API-Key: tsk_SU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"videoId": "dQw4w9WgXcQ"}'

# Obtener un resumen
curl https://tube.archivarix.net/api/summary/dQw4w9WgXcQ \
  -H "X-API-Key: tsk_SU_CLAVE"

# Explorar resúmenes por etiqueta
curl "https://tube.archivarix.net/api/summary/browse?tag=music&limit=10" \
  -H "X-API-Key: tsk_SU_CLAVE"

# Verificación de estado
curl https://tube.archivarix.net/api/health

Python

import requests

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

# --- Búsqueda de canal ---
resp = requests.post(f"{BASE}/api/search",
    headers=headers,
    json={"query": "@MrBeast"})
session = resp.json()["data"]
search_id = session["searchSessionId"]

# Recibir resultados (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:])

# --- Búsqueda de texto completo ---
resp = requests.get(f"{BASE}/api/fts",
    headers=headers,
    params={"q": "video eliminado", "pageSize": 20, "sort": "relevance"})
print(resp.json())

# --- Descargar subtítulos ---
resp = requests.get(f"{BASE}/api/subtitles/dQw4w9WgXcQ",
    headers=headers,
    params={"format": "srt"})
with open("subtitles.srt", "w") as f:
    f.write(resp.text)

# --- Generar resumen de IA ---
resp = requests.post(f"{BASE}/api/summary/generate",
    headers=headers,
    json={"videoId": "dQw4w9WgXcQ"})
print(resp.json())  # {"data": {"status": "generating", ...}}

# --- Obtener resumen ---
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_SU_CLAVE";
const BASE = "https://tube.archivarix.net";
const headers = { "X-API-Key": API_KEY };

// --- Búsqueda de canal ---
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();

// Recibir resultados (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());

// --- Búsqueda de texto completo ---
const ftsResp = await fetch(
  `${BASE}/api/fts?q=video+eliminado&pageSize=20`,
  { headers }
);
const results = await ftsResp.json();

// --- Descargar subtítulos ---
const subResp = await fetch(
  `${BASE}/api/subtitles/dQw4w9WgXcQ?format=srt`,
  { headers }
);
const srtText = await subResp.text();

// --- Generar resumen de 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());

// --- Explorar resúmenes ---
const browseResp = await fetch(
  `${BASE}/api/summary/browse?tag=music&limit=10`,
  { headers }
);
console.log(await browseResp.json());