heyfworld/vidbee-api

•Updated 4 months ago

Image

1.2K

heyfworld/vidbee-api repository overview

⁠VidBee API

The backend API server for VidBee⁠ — a modern, open-source video downloader that supports 1000+ websites. Powered by yt-dlp⁠ and FFmpeg⁠, this image provides a ready-to-run download API with real-time SSE events, download history, and an OpenAPI/Swagger UI.

Batteries included — yt-dlp, FFmpeg, and SQLite are all bundled. Just run the container and point the VidBee web UI⁠ at it.

⁠Quick Start

⁠Docker Compose (recommended)

# docker-compose.yml
services:
  vidbee-api:
    image: heyfworld/vidbee-api:latest
    container_name: vidbee-api
    environment:
      VIDBEE_API_HOST: 0.0.0.0
      VIDBEE_API_PORT: 3100
      VIDBEE_DOWNLOAD_DIR: /data/downloads
      VIDBEE_HISTORY_STORE_PATH: /data/vidbee/vidbee.db
    ports:
      - "3100:3100"
    volumes:
      - ./data/downloads:/data/downloads
      - ./data/vidbee:/data/vidbee
    restart: unless-stopped

docker compose up -d

⁠Docker Run

docker run -d \
  --name vidbee-api \
  --restart unless-stopped \
  -p 3100:3100 \
  -e VIDBEE_API_HOST=0.0.0.0 \
  -e VIDBEE_API_PORT=3100 \
  -e VIDBEE_DOWNLOAD_DIR=/data/downloads \
  -e VIDBEE_HISTORY_STORE_PATH=/data/vidbee/vidbee.db \
  -v ./data/downloads:/data/downloads \
  -v ./data/vidbee:/data/vidbee \
  heyfworld/vidbee-api:latest

API is now available at http://localhost:3100.

⁠Full Stack (API + Web)

To run VidBee with both the API and web UI together:

# docker-compose.yml
services:
  api:
    image: heyfworld/vidbee-api:latest
    environment:
      VIDBEE_API_HOST: 0.0.0.0
      VIDBEE_API_PORT: 3100
      VIDBEE_DOWNLOAD_DIR: /data/downloads
      VIDBEE_HISTORY_STORE_PATH: /data/vidbee/vidbee.db
    ports:
      - "3100:3100"
    volumes:
      - ./data/downloads:/data/downloads
      - ./data/vidbee:/data/vidbee
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:3100/health > /dev/null || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped

  web:
    image: heyfworld/vidbee-web:latest
    depends_on:
      api:
        condition: service_healthy
    ports:
      - "3000:3000"
    restart: unless-stopped

docker compose up -d

Open http://localhost:3000 for the web UI, http://localhost:3100/docs for Swagger API docs.

⁠Environment Variables

Variable	Default	Description
`VIDBEE_API_HOST`	`0.0.0.0`	Host address the API binds to
`VIDBEE_API_PORT`	`3100`	Port the API listens on
`VIDBEE_DOWNLOAD_DIR`	Current working directory	Directory where downloaded files are saved
`VIDBEE_HISTORY_STORE_PATH`	`<VIDBEE_DOWNLOAD_DIR>/.vidbee/vidbee.db`	Path to the SQLite database for download history
`VIDBEE_MAX_CONCURRENT`	Unlimited	Maximum number of concurrent downloads

⁠Volumes

Mount Point	Description
`/data/downloads`	Downloaded video/audio files
`/data/vidbee`	SQLite database (download history)

⁠API Endpoints

Endpoint	Description
`GET /health`	Health check — returns `{ "ok": true }`
`GET /docs`	Swagger UI for interactive API exploration
`GET /openapi.json`	OpenAPI specification
`GET /events`	SSE stream for real-time download progress
`POST /rpc/*`	oRPC endpoints for downloads, queue management, and history
`GET /images/proxy?url=`	Image proxy for video thumbnails (SSRF-protected)

⁠Verify

# Health check
curl -s http://localhost:3100/health
# {"ok":true}

# Check Swagger docs
curl -sI http://localhost:3100/docs

# Inspect download history database
docker exec vidbee-api ls -la /data/vidbee/

⁠Architectures

This image supports linux/amd64 and linux/arm64.

⁠Source

Built from nexmoe/VidBee⁠ — the official open-source VidBee repository.

⁠Notes

This image contains only the API server. For the web UI, use heyfworld/vidbee-web⁠.
yt-dlp and FFmpeg are pre-installed inside the container. No external dependencies are required.
The SQLite database is stored at the path specified by VIDBEE_HISTORY_STORE_PATH. Mount a volume to persist download history across container restarts.

Tag summary

Recent tags

Content type

Image

Digest

sha256:f67843d99…

Size

656.3 MB

Last updated

4 months ago

docker pull heyfworld/vidbee-api