Документация API - Загрузчик

Загрузка Медиа

POST /download

Загрузка медиа с поддерживаемых платформ (YouTube, Instagram, TikTok, SoundCloud). Важно: Файл автоматически загружается в Telegram группу для получения telegram_file_id и сохранения в кэш. Если файл уже есть в кэше, возвращается информация из кэша без повторной загрузки.

Полный URL эндпоинта:

POST https://download.dreampartners.online/download

Request Body:

Parameter	Type	Required	Description
url	string	Yes	URL of the media to download

{
  "url": "https://youtube.com/watch?v=..."
}

Response (Success - Новый файл):

{
  "status": "success",
  "cached": false,
  "files": [
    {
      "path": "downloads/uuid/video.mp4",
      "filename": "video.mp4",
      "url": "https://download.dreampartners.online/files/...",
      "size": 1024000,
      "telegram_file_id": "BAACAgIAAxkBAAI...",
      "bot_link": "https://t.me/bot_username?start=file_123",
      "cache_id": 123,
      "normalized_url": "https://youtube.com/watch?v=...",
      "media_type": "video"
    }
  ],
  "task_id": "uuid",
  "normalized_url": "https://youtube.com/watch?v=...",
  "telegram_file_ids": ["BAACAgIAAxkBAAI..."],
  "cache_id": 123
}

Response (Error):

{
  "status": "error",
  "message": "Error description"
}

Тест API

Transcribe Audio/Video

POST /transcribe

Convert speech to text from audio or video files. Can accept URL or file upload.

Option 1: URL (JSON):

{
  "url": "https://youtube.com/watch?v=..."
}

Option 2: File Upload (Multipart):

Content-Type: multipart/form-data
Field: file (binary)

Response:

{
  "status": "success",
  "text": "Transcribed text here..."
}

Note: Transcription uses Google Speech Recognition API. Supports Russian and English languages.

Тест API

Генерация Саммари

POST /summary

Генерация краткого саммари из расшифрованного текста с использованием AI.

Полный URL эндпоинта:

POST https://download.dreampartners.online/summary

Request Body:

{
  "text": "Long text to summarize..."
}

Response:

{
  "status": "success",
  "summary": "1. Key point one\n2. Key point two..."
}

Тест API

History Management

GET /api/history

Get download history for current session.

Response:

{
  "status": "success",
  "history": [
    {
      "id": "uuid",
      "filename": "video.mp4",
      "url": "https://...",
      "size": 1024000,
      "added_at": "2025-01-20T10:00:00"
    }
  ]
}

Тест API

DELETE /api/history/{file_id}

Delete a file from history.

Response:

{
  "status": "success"
}

Тест API

Загрузка в Telegram

POST /api/telegram/upload

Получить ссылку на бота для открытия файла. Файл загружается в Telegram, получает file_id и сохраняется в базу данных. Возвращается ссылка вида https://t.me/bot_username?start=file_{cache_id}

Request Body:

{
  "file_id": "uuid-from-history"
}

Response (Успех):

{
  "status": "success",
  "bot_link": "https://t.me/bot_username?start=file_123",
  "cache_id": 123,
  "telegram_file_id": "BAACAgIAAxkBAAI...",
  "message": "Используйте эту ссылку для открытия файла в боте"
}

Примечание: Файл загружается в Telegram группу для получения file_id, затем сохраняется в базу данных. При открытии ссылки бот покажет файл с опциями конвертации. Если файл уже загружен в Telegram, возвращается существующая ссылка без повторной загрузки.

Тест API

Полный Цикл Обработки

POST /api/process

Полный цикл: Скачать → Расшифровать → Саммари. Выполняет все три операции последовательно.

Request Body:

{
  "url": "https://youtube.com/watch?v=..."
}

Response:

{
  "status": "success",
  "file": {
    "id": "uuid",
    "filename": "video.mp4",
    "url": "https://...",
    "size": 1024000
  },
  "transcription": "Полный текст расшифровки...",
  "summary": "1. Ключевой момент\n2. Второй момент..."
}

Важно: Этот endpoint выполняет все три операции последовательно. Процесс может занять некоторое время в зависимости от размера файла.

Тест API

Статус API

GET /health

Проверка статуса и доступности сервиса API. Используйте этот эндпоинт для мониторинга работоспособности сервиса.

Полный URL эндпоинта:

GET https://download.dreampartners.online/health

Ответ (Сервис онлайн):

{
  "status": "ok",
  "service": "download-api"
}

Коды ответов:

Код	Статус	Описание
200	OK	Сервис работает
503	Service Unavailable	Сервис временно недоступен

Совет: Используйте этот эндпоинт для проверок работоспособности и мониторинга. Возвращает 200 OK, когда сервис доступен.

Supported Platforms

✓ YouTube (youtube.com, youtu.be)
✓ Instagram (instagram.com)
✓ TikTok (tiktok.com, vt.tiktok.com)
✓ SoundCloud (soundcloud.com)

Example Usage

// Базовый URL API
const API_BASE_URL = 'https://download.dreampartners.online';

// Download video
const response = await fetch(`${API_BASE_URL}/download`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://youtube.com/watch?v=...'
  })
});

const data = await response.json();
if (data.status === 'success') {
  console.log('Files:', data.files);
  console.log('Download URL:', data.files[0].url);
  console.log('Telegram file_id:', data.files[0].telegram_file_id);
  console.log('Bot link:', data.files[0].bot_link);
}

import requests

# Базовый URL API
API_BASE_URL = 'https://download.dreampartners.online'

# Download video
response = requests.post(
    f'{API_BASE_URL}/download',
    json={'url': 'https://youtube.com/watch?v=...'}
)

data = response.json()
if data['status'] == 'success':
    print('Files:', data['files'])
    print('Download URL:', data['files'][0]['url'])
    print('Telegram file_id:', data['files'][0]['telegram_file_id'])
    print('Bot link:', data['files'][0]['bot_link'])
    print('Cache ID:', data.get('cache_id'))
    print('Is carousel:', data.get('is_carousel', False))

# Пример запроса через cURL
curl -X POST https://download.dreampartners.online/download \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=..."}'

# Проверка статуса API
curl https://download.dreampartners.online/health

Кэширование и Telegram File ID

Сервис автоматически кэширует все загруженные файлы:

Автоматическая загрузка в Telegram: При загрузке файл сразу отправляется в Telegram группу для получения telegram_file_id
Сохранение в кэш: URL нормализуется (убираются параметры, приводится к единому виду) и сохраняется в базу данных вместе с file_id
Проверка кэша: Перед загрузкой проверяется наличие файла в кэше. Если найден - возвращается информация из кэша без повторной загрузки
Bot Deep Links: Для каждого файла генерируется ссылка вида https://t.me/bot_username?start=file_{cache_id}, которая открывает файл в боте с опциями конвертации

Поля ответа при загрузке:

Поле	Тип	Описание
telegram_file_id	string	ID файла в Telegram (получается автоматически при загрузке)
bot_link	string	Ссылка для открытия файла в боте: `https://t.me/bot_username?start=file_{cache_id}`
cache_id	integer	ID записи в кэше базы данных
normalized_url	string	Нормализованный URL (используется для проверки кэша)
media_type	string	Тип медиа: `video`, `audio`, `photo`, `document`
cached	boolean	`true` если файл взят из кэша, `false` если загружен заново

Важно: Все файлы автоматически получают telegram_file_id при загрузке. Это позволяет использовать файлы в Telegram боте без повторной загрузки. Кэш работает на основе нормализованных URL, поэтому ссылки с разными параметрами (например, ?t=10) считаются одинаковыми.