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

Интегрируйте TrendingCaptions в ваши приложения с помощью REST API. Обрабатывайте видео и добавляйте AI-субтитры программно.

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

Все API-запросы требуют аутентификации с помощью Bearer-токена. Получите API-ключ в Telegram Боте.

Authorization: Bearer YOUR_API_KEY

⚡ Ограничение запросов

API-запросы ограничены до 20 запросов в минуту на API-ключ. При превышении лимита возвращается статус 429 с заголовком Retry-After.

🌐 Базовый URL

https://api.trendingcaptions.app

📋 Эндпоинты

GET /api/templates

Возвращает все доступные шаблоны субтитров, сгруппированные по типу письма (латиница, кириллица, греческий).

curl -X GET "https://api.trendingcaptions.app/api/templates" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.trendingcaptions.app/api/templates', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const templates = await response.json();

Пример ответа

{
  "latin": [
    { "name": "popin", "description": "Energetic 'Expert' style using Montserrat ExtraBold..." },
    { "name": "karaoke", "description": "Interactive style with word-by-word highlighting..." },
    { "name": "minimal", "description": "Clean and modern style with semantic highlighting..." }
  ],
  "cyrillic": [...],
  "greek": [...]
}

GET /api/statuses

Возвращает все возможные статусы обработки видео и их описания.

curl -X GET "https://api.trendingcaptions.app/api/statuses" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.trendingcaptions.app/api/statuses', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const statuses = await response.json();

new Видео загружено и поставлено в очередь на обработку

processing Видео транскрибируется и рендерится

done Обработка завершена, готово к скачиванию

error Ошибка обработки (кредиты возвращены)

Пример ответа

{
  "new": {
    "description": "Video has been uploaded and queued for processing. Initial state."
  },
  "processing": {
    "description": "Video passed validation and is currently being processed (transcription, rendering)."
  },
  "done": {
    "description": "Video processing completed successfully. The video is ready for download."
  },
  "error": {
    "description": "Video processing failed. This could be due to validation errors (format, size) or system errors. Credits are refunded."
  }
}

POST /api/videos

Загрузка видео для добавления субтитров. Поддерживает два метода загрузки: JSON (base64) и multipart/form-data. Возвращает ID рендера для отслеживания прогресса.

📤 Методы загрузки

Content-Type: application/json — отправка видео как base64-строки в теле JSON.

Content-Type: multipart/form-data — отправка файла напрямую. Рекомендуется для больших файлов.

Параметры JSON

Параметр	Тип	Описание
video_base64 обязательный	string	Видео в формате base64
template_id необязательный	string	Название шаблона (по умолчанию: `karaoke`)

Поля Form-Data

Поле	Тип	Описание
video обязательный	file	Видеофайл (mp4, mov, webm)
template_id необязательный	string	Название шаблона (по умолчанию: `karaoke`)

⚠️ Ограничения размера

Максимальный размер входного видео — 100 МБ. Видео должно быть в формате 9:16. Выходной файл оптимизирован для Telegram (≤50 МБ).

# Загрузка видео через form-data (рекомендуется)
curl -X POST "https://api.trendingcaptions.app/api/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "video=@your_video.mp4" \
  -F "template_id=popin"

# Кодирование видео в base64 и отправка как JSON
VIDEO_B64=$(base64 -i your_video.mp4)

curl -X POST "https://api.trendingcaptions.app/api/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"video_base64\": \"$VIDEO_B64\", \"template_id\": \"popin\"}"

// Загрузка файла через FormData (рекомендуется)
const file = document.getElementById('videoInput').files[0];
const formData = new FormData();
formData.append('video', file);
formData.append('template_id', 'popin');

const response = await fetch('https://api.trendingcaptions.app/api/videos', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: formData
});

const { renderId } = await response.json();
console.log('Render ID:', renderId);

// Конвертация файла в base64 и отправка как JSON
const file = document.getElementById('videoInput').files[0];
const reader = new FileReader();
reader.onload = async () => {
  const base64 = reader.result.split(',')[1];
  
  const response = await fetch('https://api.trendingcaptions.app/api/videos', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_base64: base64,
      template_id: 'popin'
    })
  });
  
  const { renderId } = await response.json();
  console.log('Render ID:', renderId);
};
reader.readAsDataURL(file);

Пример ответа (202 Accepted)

{
  "status": "new",
  "renderId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Video uploaded and processing started."
}

GET /api/videos/:id

Проверка статуса обработки видео. Возвращает ссылку для скачивания при завершении.

curl -X GET "https://api.trendingcaptions.app/api/videos/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

// Опрос статуса до завершения
async function pollStatus(renderId) {
  const response = await fetch(
    `https://api.trendingcaptions.app/api/videos/${renderId}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const result = await response.json();
  
  if (result.status === 'done') {
    console.log('Download URL:', result.downloadUrl);
  } else if (result.status === 'error') {
    console.error('Processing failed');
  } else {
    setTimeout(() => pollStatus(renderId), 5000);
  }
}

Пример ответа (status: done)

{
  "renderId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "done",
  "description": "Video processing completed successfully. The video is ready for download.",
  "downloadUrl": "https://...presigned-url...?X-Amz-Expires=3600"
}

❌ Ответы с ошибками

Статус	Описание
`400`	Неверное тело запроса или отсутствуют обязательные поля
`401`	Отсутствует или неверный API-ключ
`403`	Пользователь не найден, нет кредитов или неактивная подписка
`404`	Рендер не найден
`413`	Видео превышает лимит 100 МБ
`429`	Превышен лимит запросов (20 запросов/мин)