SocialLoad API

Тот же движок, что работает в Telegram-боте, на сайте и в расширении для браузера. Загрузка асинхронная: запрос создаёт задачу и сразу отдаёт её номер, держать соединение открытым не нужно.

Базовый адрес https://usarbot.online/api/v1

Быстрый старт

Три шага: создать задачу, дождаться готовности, забрать файл.

# 1. Создаём задачу
curl -X POST https://usarbot.online/api/v1/download \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_ВАШ_КЛЮЧ" \
  -d '{"url": "https://www.instagram.com/p/Db_HLc5DQBQ/"}'

# Ответ
{"success": true, "job_id": "3f2a91c0d4e84b7c", "status": "queued", "progress": 12}

# 2. Проверяем состояние
curl https://usarbot.online/api/v1/download/3f2a91c0d4e84b7c \
  -H "X-API-Key: sk_live_ВАШ_КЛЮЧ"

# Когда готово
{"success": true, "status": "completed", "progress": 100,
 "download_url": "https://usarbot.online/api/v1/files/3f2a91c0d4e84b7c?token=…",
 "expires_at": "2026-08-15T04:12:00+00:00"}

# 3. Забираем файл по download_url

Ссылка download_url временная и подписанная — ключ для неё не нужен. Файл удаляется с сервера после expires_at.

Ключ доступа

Каждый запрос, кроме /status и /files/…, требует заголовок:

X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Ключ выдаётся в панели управления. Полностью он показывается один раз при создании — в базе хранится только его отпечаток, восстановить ключ невозможно, потерянный нужно выпустить заново.

Не кладите ключ в код страницы или мобильного приложения: оттуда его заберёт любой желающий. Запрос к API делайте со своего сервера.

Площадки

Заявлено только то, что движок действительно берёт.

Площадка	Выбор качества	Форматы
YouTube	144p – 2160p	`mp4` `mp3`
Instagram	лучшее доступное	`mp4` `mp3`
TikTok	лучшее доступное	`mp4` `mp3`
Threads	лучшее доступное	`mp4` `mp3`
X (Twitter)	лучшее доступное	`mp4` `mp3`
Facebook	лучшее доступное	`mp4` `mp3`
VK	лучшее доступное	`mp4` `mp3`
Reddit	лучшее доступное	`mp4` `mp3`
SoundCloud	только звук	`mp3`
Snapchat	лучшее доступное	`mp4` `mp3`
Dailymotion	лучшее доступное	`mp4` `mp3`
Rutube	лучшее доступное	`mp4` `mp3`
OK.ru	лучшее доступное	`mp4` `mp3`
Likee	лучшее доступное	`mp4` `mp3`
Bilibili	лучшее доступное	`mp4` `mp3`

Выбор качества есть только у YouTube. У остальных площадок сервис берёт лучшее доступное — если передать quality, он будет принят, но в ответе придёт пояснение notice.

Создать загрузку

POST/download

Поле	Тип	Описание
`url`	строка	Обязательно. Ссылка на запись.
`quality`	строка	`best` (по умолчанию), `audio`, либо `144p…2160p` для YouTube.
`format`	строка	`mp4` или `mp3`. `mp3` всегда означает только звук.
`webhook_url`	строка	Необязательно. Куда сообщить о готовности, только `https`.

Заголовок Idempotency-Key защищает от двойной отправки: повтор с тем же значением вернёт ту же задачу, а не создаст новую.

Ответ 202 — задача создана
{"success": true, "job_id": "3f2a91c0d4e84b7c", "status": "queued",
 "progress": 12, "platform": "instagram", "reused": false}

Ответ 200 — такой файл уже скачан недавно
{"success": true, "job_id": "3f2a91c0d4e84b7c", "status": "completed",
 "progress": 100, "reused": true, "download_url": "…"}

Состояние задачи

GET/download/{job_id}

Статус	Что значит
`queued`	Задача принята и ждёт свободного места
`processing`	Разбираем ссылку и готовим файл
`downloading`	Идёт скачивание
`converting`	Собираем результат, например несколько снимков в архив
`completed`	Готово, есть `download_url`
`failed`	Не получилось, причина в поле `error`
`cancelled`	Остановлено

Опрашивайте раз в 1–2 секунды. Отдельно можно остановить задачу: POST /download/{job_id}/cancel

Сведения о записи

POST/metadata

Название, автор, обложка, длительность — без скачивания.

{"success": true, "platform": "youtube", "title": "…", "author": "…",
 "duration": 213, "quality_selection": "choice",
 "formats": [{"quality": "720p", "format": "mp4", "size_mb": 24.1},
             {"quality": "1080p", "format": "mp4", "size_mb": 48.7}]}

Список форматов возвращается только там, где он известен заранее — сейчас это YouTube. Для остальных площадок formats пустой, а quality_selection равен best. Выдуманных значений в ответе нет.

Упрощённый метод — без ключа

POST/shortcuts/download ключ не нужен

Для iOS Shortcuts и других простых клиентов: ждёт готовности прямо в запросе и возвращает ссылку одним действием.

Ключ здесь не требуется намеренно. Команду на iPhone люди пересылают друг другу, и секрет внутри неё утёк бы в первый же день. Вместо ключа действуют ограничения по адресу — они ниже описаны.

Готово сразу — код 200
{"success": true, "status": "completed", "stage": "completed", "progress": 100,
 "job_id": "106de71c16a048389e24c66099a385f6", "platform": "instagram",
 "title": "Video by tursunkulov.muhammad", "size_mb": 1.9, "files": 1,
 "download_url": "https://usarbot.online/api/v1/files/106de…?token=c40a2…",
 "expires_at": "2026-08-15T06:00:22+00:00"}

Файл тяжёлый — код 202, досмотрим отдельно
{"success": true, "status": "downloading", "stage": "downloading", "progress": 62,
 "job_id": "e2e25f0864a740af89920de431c6c423", "platform": "youtube",
 "poll_url": "https://usarbot.online/api/v1/shortcuts/status/e2e25f0864a7…"}

Ожидание настраивается полем wait (0–50 секунд, по умолчанию 25). Оба ответа нужно уметь обрабатывать.

Проверка готовности — тоже без ключа

GET /shortcuts/status/{job_id} ключ не нужен

Опрашивайте раз в секунду, пока status не станет completed. Пропуском служит сам номер задачи: это 32 случайных знака, известных только тому, кто её создал.

Ограничения без ключа

Что ограничено	Сколько
Запросов с одного адреса	8 за 10 минут
Загрузок в сутки	60
Одновременных загрузок	2
Размер файла	до 500 МБ
Ожидание в запросе	до 50 секунд

Адрес не хранится — считается только его отпечаток. Если передать X-API-Key, действуют лимиты ключа: они заметно выше.

Лимиты ключа

GET/usage

Показывает остаток кредитов, потолки и число активных загрузок.

Команда на iPhone

Ничего регистрировать не нужно — ключ для этого не требуется. Пошагово, в приложении «Быстрые команды»:

Создайте новую команду и добавьте действие Получить содержимое URL.
В поле URL впишите https://usarbot.online/api/v1/shortcuts/download
Раскройте Показать больше и выберите метод POST.
В Тело запроса выберите JSON.
Добавьте поле: ключ url, тип Текст, значение — Вход быстрой команды.
Добавьте действие Получить значение словаря, ключ download_url.
Добавьте Получить содержимое URL с этим значением — это скачает файл.
Добавьте Сохранить в фотоальбом либо Сохранить файл.
В настройках команды (значок ⓘ) включите Показывать в меню «Поделиться», тип входа — URL.

Теперь в любой соцсети нажмите «Поделиться» и выберите свою команду.

Если файл большой

Тогда вместо download_url придёт job_id. Добавьте в команду ожидание:

Действие Повторить, количество повторов — 60.
Внутри: Получить содержимое URL с адресом https://usarbot.online/api/v1/shortcuts/status/ + job_id, метод GET.
Действие Получить значение словаря, ключ progress — можно показать процент.
Условие Если значение по ключу status равно completed → взять download_url и выйти из цикла.
Иначе — действие Подождать 1 секунду.

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

Примеры кода

curl -X POST https://usarbot.online/api/v1/download \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SOCIALLOAD_KEY" \
  -d '{"url": "https://www.tiktok.com/@user/video/123", "quality": "best"}'

const KEY = process.env.SOCIALLOAD_KEY;

async function download(url) {
  const start = await fetch("https://usarbot.online/api/v1/download", {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": KEY },
    body: JSON.stringify({ url }),
  }).then(r => r.json());

  if (!start.success) throw new Error(start.error.message);

  while (true) {
    const job = await fetch(`https://usarbot.online/api/v1/download/${start.job_id}`,
      { headers: { "X-API-Key": KEY } }).then(r => r.json());
    if (job.status === "completed") return job.download_url;
    if (job.status === "failed") throw new Error(job.error.message);
    await new Promise(done => setTimeout(done, 1500));
  }
}

import os, time, requests

KEY = os.environ["SOCIALLOAD_KEY"]
API = "https://usarbot.online/api/v1"
headers = {"X-API-Key": KEY}

def download(url: str) -> str:
    start = requests.post(f"{API}/download", json={"url": url},
                          headers=headers, timeout=30).json()
    if not start["success"]:
        raise RuntimeError(start["error"]["message"])

    while True:
        job = requests.get(f"{API}/download/{start['job_id']}",
                           headers=headers, timeout=30).json()
        if job["status"] == "completed":
            return job["download_url"]
        if job["status"] == "failed":
            raise RuntimeError(job["error"]["message"])
        time.sleep(1.5)

<?php
$key = getenv('SOCIALLOAD_KEY');
$api = 'https://usarbot.online/api/v1';

function call($url, $method = 'GET', $body = null) {
    global $key;
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json', "X-API-Key: $key"],
        CURLOPT_POSTFIELDS     => $body ? json_encode($body) : null,
    ]);
    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $response;
}

$start = call("$api/download", 'POST', ['url' => 'https://www.instagram.com/p/XXXX/']);
do {
    sleep(2);
    $job = call("$api/download/{$start['job_id']}");
} while (in_array($job['status'], ['queued', 'processing', 'downloading', 'converting']));

echo $job['download_url'];

Webhooks

Передайте webhook_url при создании задачи — и вместо опроса сервис сам сообщит о событиях:

Событие	Когда
`download.started`	Задача взята в работу
`download.completed`	Файл готов
`download.failed`	Не получилось

Каждый запрос подписан заголовком X-SocialLoad-Signature вида sha256=… — это HMAC тела запроса на общем секрете. Проверяйте подпись, прежде чем доверять содержимому. При ошибке 5xx запрос повторяется трижды с нарастающей паузой.

Лимиты и кредиты

Ограничения

Тариф	Запросов/мин	Одновременно	Кредитов/сутки
free	20	1	50
starter	60	2	500
developer	120	3	2000
pro	300	5	10000
business	600	8	40000
enterprise	1200	16	без лимита

Стоимость операций

Операция	Кредитов
Сведения о записи	1
Фото	1
Только звук	2
До 480p	2
720p	3
1080p	5
1440p и 4K	10

Повторная загрузка того же файла кредитов не стоит. Если загрузка сорвалась — кредиты возвращаются.

Ошибки

Ответ при ошибке всегда одного вида:

{"success": false,
 "error": {"code": "UNSUPPORTED_PLATFORM",
           "message": "Эта платформа не поддерживается"}}

Код HTTP	Что произошло
400	Ссылка неверная, площадка не поддерживается или параметры не те
401	Ключ не передан или не найден
403	Ключ отключён или просрочен
404	Задача не найдена или ссылка устарела
409	Достигнут предел одновременных загрузок
413	Файл больше допустимого для тарифа
429	Слишком часто либо закончились кредиты
502	Площадка не отдала файл
503	Сервис перегружен

Подробности ошибок сервера наружу не отдаются — в ответе только код и понятное описание. Каждый ответ содержит заголовок X-Request-Id: назовите его при обращении в поддержку.

Версия API 1.0.0 · OpenAPI · интерактивная документация · на главную

Скачивайте только тот контент, на который у вас есть права.