Reference v2

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

Все эндпоинты, примеры и нюансы. Базовый URL — https://picex.ru/api

Введение

PICEX API возвращает чистый JSON. Все эндпоинты принимаютapplication/json и возвращают то же самое. Ответы кодированы в UTF-8, без trailing-слешей.

GET/api/health

Состояние сервиса. Без авторизации. Возвращает доступность под-сервисов и uptime.

Response

{
  "status": "ok",
  "uptime": 3621.2,
  "timestamp": "2026-05-02T00:00:00Z",
  "services": { "images": true, "videos": true, "ytdlp": true },
  "version": "2.0.0"
}

POST/api/images/scrape

Достаёт все изображения со страницы — теги <img>, srcset, lazy-load (data-src/data-bg/...), background-image, иконки, OG-теги, найденные в подключённых CSS-файлах.

Request

{
  "url": "https://example.com/gallery"
}

Response

{
  "images": [
    {
      "src": "https://example.com/hero.jpg",
      "size": {
        "width": 1920,
        "height": 1080,
        "format": "jpg",
        "size": 412000,
        "fileSize": "402.34 Кб",
        "buffer": { "type": "Buffer", "data": [...] }
      }
    }
  ]
}

POST/api/videos/scrape

Находит видео на странице: теги <video>/<source>, прямые ссылки на MP4/WEBM/MOV, HLS (.m3u8), DASH (.mpd), а также iframe-эмбеды (YouTube, Rutube, VK и т.д.).

Request

{
  "url": "https://example.com/article",
  "useYtdlp": false
}

Response

{
  "mode": "page",
  "videos": [
    {
      "src": "https://cdn.example.com/clip.mp4",
      "kind": "mp4",
      "contentType": "video/mp4",
      "size": { "bytes": 15240000, "fileSize": "14.53 Мб", "format": "mp4" },
      "useYtdlp": false
    }
  ]
}

POST/api/videos/ytdlp

Используем yt-dlp, который понимает 1500+ видео-платформ. Возвращает список доступных форматов с прямыми URL — клиент сам выбирает качество.

Request

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

Response

{
  "info": {
    "id": "...",
    "title": "...",
    "duration": 215,
    "uploader": "...",
    "thumbnail": "https://...",
    "formats": [
      { "formatId": "137", "ext": "mp4", "width": 1920, "height": 1080,
        "vcodec": "avc1.640028", "acodec": null, "bitrate": 4500,
        "filesize": 28000000, "url": "https://..." }
    ],
    "bestUrl": "https://..."
  }
}

Ошибки

Стандартные HTTP-коды плюс поле error и опционально detail.

400 — нет url или невалидный
404 — на странице не нашли подходящих медиа-файлов
500 — внутренняя ошибка парсинга (детали в "detail")
503 — yt-dlp недоступен на этом инстансе

Лимиты

На бесплатном плане — 50 запросов в месяц на IP. Для безлимита и SLA смотрите тарифы.

SDK

Скоро: официальные клиенты на TypeScript и Python. Пока — обёртка fetch хватает с головой.

const r = await fetch("https://picex.ru/api/images/scrape", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url })
});
const { images } = await r.json();