Документация API

Archivarix Tube Search предоставляет REST API для программного доступа к метаданным архивных видео YouTube, субтитрам и AI-саммари. Эта страница — полный справочник по API.

Доступ к API требует подписки уровня MCP + API. Подробности на странице Тарифы.

Аутентификация

API-ключи создаются в разделе Профиль → вкладка API. Включайте ключ в каждый запрос одним из заголовков:

X-API-Key: tsk_ВАШ_КЛЮЧ

или

Authorization: Bearer tsk_ВАШ_КЛЮЧ

Ключи используют префикс tsk_. Храните ключ в секрете — он предоставляет полный доступ к API от имени вашего аккаунта.

Эндпоинты

Поиск (Поиск каналов через SSE)

Поиск каналов — двухэтапный процесс: создание поисковой сессии, затем получение результатов через Server-Sent Events.

POST /api/search

Начать новый поиск канала.

Тело запроса (JSON):

{
  "query": "@handle или URL канала или URL/ID видео"
}

Ответ:

{
  "data": {
    "searchSessionId": "uuid",
    "sseEndpointUrl": "/api/search/uuid/stream",
    "channelId": "UCxxxxxx",
    "channelTitle": "Название канала"
  }
}

GET /api/search/:sessionId/stream

Подключение к SSE-потоку для получения результатов в реальном времени. Укажите заголовок Accept: text/event-stream. Типы событий описаны в разделе Протокол SSE.

POST /api/search/:sessionId/continue

Продолжить постраничный поиск — загрузить следующую страницу результатов из архивов.

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

Проверить, выполняется ли фоновый поиск по каналу.

Ответ:

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

Полнотекстовый поиск

GET /api/fts

Поиск по всем индексированным заголовкам и описаниям видео.

Параметры запроса:

Субтитры

GET /api/subtitles/:videoId

Скачать субтитры для видео.

Параметры запроса:

POST /api/subtitles/:videoId/fetch

Получить субтитры по запросу через yt-dlp или Wayback Machine. Запускает фоновую задачу, если субтитры ещё недоступны.

POST /api/subtitles/bulk-download

Скачать субтитры для нескольких видео одновременно.

Тело запроса (JSON):

{
  "videoIds": ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
  "query": "необязательный запрос для подсветки"
}

AI-саммари

POST /api/summary/generate

Сгенерировать AI-саммари для видео. Требуются доступные субтитры.

Тело запроса (JSON):

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

Ответ (202 Accepted):

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

GET /api/summary/:videoId

Получить AI-саммари для конкретного видео.

DELETE /api/summary/:videoId

Удалить саммари. Только для администраторов.

GET /api/summary/browse

Просмотр саммари с фильтрами.

Параметры запроса:

GET /api/summary/latest

Получить последние сгенерированные саммари.

GET /api/summary/tags

Получить популярные теги по всем саммари.

GET /api/summary/languages

Получить доступные языки саммари с количеством.

GET /api/summary/channels

Получить каналы, для которых есть саммари.

Статус видео

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

Получить историю изменения статуса видео (например, live → deleted → re-uploaded).

Система

GET /api/health

Проверка состояния сервера.

GET /api/features

Получить флаги функций и лимиты для текущего пользователя/тарифа.

GET /api/tiers

Получить сравнение тарифов (лимиты и возможности по уровням).

Протокол SSE

Поток поиска каналов отправляет Server-Sent Events. Каждое событие имеет тип и JSON-данные:

Лимиты запросов

API-запросы (тариф MCP + API) имеют следующие лимиты:

При превышении лимита API возвращает HTTP 429 с кодом ошибки RATE_LIMITED.

Коды ошибок

Все ошибки возвращают JSON с объектом ошибки:

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

Примеры

curl

# Начать поиск канала
curl -X POST https://tube.archivarix.net/api/search \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"query": "@MrBeast"}'

# Получить результаты (SSE)
curl -N https://tube.archivarix.net/api/search/SESSION_ID/stream \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ" \
  -H "Accept: text/event-stream"

# Продолжить постраничный поиск
curl -X POST https://tube.archivarix.net/api/search/SESSION_ID/continue \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ"

# Полнотекстовый поиск
curl "https://tube.archivarix.net/api/fts?q=deleted+video&pageSize=20&sort=relevance" \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ"

# Скачать субтитры (SRT)
curl https://tube.archivarix.net/api/subtitles/dQw4w9WgXcQ \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ"

# Скачать субтитры (VTT)
curl "https://tube.archivarix.net/api/subtitles/dQw4w9WgXcQ?format=vtt" \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ"

# Получить субтитры по запросу
curl -X POST https://tube.archivarix.net/api/subtitles/dQw4w9WgXcQ/fetch \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ"

# Сгенерировать AI-саммари
curl -X POST https://tube.archivarix.net/api/summary/generate \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"videoId": "dQw4w9WgXcQ"}'

# Получить саммари
curl https://tube.archivarix.net/api/summary/dQw4w9WgXcQ \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ"

# Просмотр саммари по тегу
curl "https://tube.archivarix.net/api/summary/browse?tag=music&limit=10" \
  -H "X-API-Key: tsk_ВАШ_КЛЮЧ"

# Проверка состояния
curl https://tube.archivarix.net/api/health

Python

import requests

API_KEY = "tsk_ВАШ_КЛЮЧ"
BASE = "https://tube.archivarix.net"
headers = {"X-API-Key": API_KEY}

# --- Поиск канала ---
resp = requests.post(f"{BASE}/api/search",
    headers=headers,
    json={"query": "@MrBeast"})
session = resp.json()["data"]
search_id = session["searchSessionId"]

# Получение результатов (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:])

# --- Полнотекстовый поиск ---
resp = requests.get(f"{BASE}/api/fts",
    headers=headers,
    params={"q": "удалённое видео", "pageSize": 20, "sort": "relevance"})
print(resp.json())

# --- Скачивание субтитров ---
resp = requests.get(f"{BASE}/api/subtitles/dQw4w9WgXcQ",
    headers=headers,
    params={"format": "srt"})
with open("subtitles.srt", "w") as f:
    f.write(resp.text)

# --- Генерация AI-саммари ---
resp = requests.post(f"{BASE}/api/summary/generate",
    headers=headers,
    json={"videoId": "dQw4w9WgXcQ"})
print(resp.json())  # {"data": {"status": "generating", ...}}

# --- Получение саммари ---
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_ВАШ_КЛЮЧ";
const BASE = "https://tube.archivarix.net";
const headers = { "X-API-Key": API_KEY };

// --- Поиск канала ---
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();

// Получение результатов (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());

// --- Полнотекстовый поиск ---
const ftsResp = await fetch(
  `${BASE}/api/fts?q=deleted+video&pageSize=20`,
  { headers }
);
const results = await ftsResp.json();

// --- Скачивание субтитров ---
const subResp = await fetch(
  `${BASE}/api/subtitles/dQw4w9WgXcQ?format=srt`,
  { headers }
);
const srtText = await subResp.text();

// --- Генерация AI-саммари ---
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());

// --- Просмотр саммари ---
const browseResp = await fetch(
  `${BASE}/api/summary/browse?tag=music&limit=10`,
  { headers }
);
console.log(await browseResp.json());