🔍 douyin-insight
AI-powered short video analyzer for Douyin (抖音), TikTok, and more.
One command to download, extract frames, and analyze video content using free multimodal LLMs.
pip install douyin-insight
export GROQ_API_KEY=gsk_... # Free at groq.com
dyi analyze https://v.douyin.com/xxxxx/
✨ Features
- 📥 Smart Download — Douyin, TikTok, and 1000+ sites (via yt-dlp)
- 🎞️ Intelligent Frame Extraction — Uniform sampling or scene-change detection
- 🧠 Multi-Provider AI Analysis — 4 free LLM providers out of the box
- 📊 Structured Output — Markdown, JSON, or custom prompts
- 🔌 Extensible — Bring your own OpenAI-compatible endpoint
- 🐍 Python API — Use as a library in your own projects
🚀 Quick Start
Installation
pip install douyin-insight
# Optional: better video download support
pip install "douyin-insight[yt-dlp]"
Requires: Python 3.9+ and ffmpeg installed.
Get a Free API Key
| Provider | Free Tier | Get Key |
|---|---|---|
| Groq (recommended) | 1000 req/min | console.groq.com |
| Google Gemini | 15 req/min | aistudio.google.com |
| Zhipu/GLM | Unlimited | open.bigmodel.cn |
| NVIDIA NIM | Free tier | build.nvidia.com |
Usage
# Set your API key (one-time)
export GROQ_API_KEY=gsk_...
# Analyze a Douyin video
dyi analyze https://v.douyin.com/xxxxx/
# Analyze a TikTok video
dyi analyze https://www.tiktok.com/@user/video/123456
# Analyze a local video file
dyi analyze ./my_video.mp4
# More frames for longer videos
dyi analyze https://v.douyin.com/xxxxx/ --frames 16
# Scene-based frame extraction (better for varied content)
dyi analyze video.mp4 --strategy scene
# Output as JSON
dyi analyze video.mp4 --json
# Save to file
dyi analyze video.mp4 -o analysis.md
# Use a specific provider
dyi analyze video.mp4 --provider zhipu --api-key "your-key"
# Custom analysis prompt
dyi analyze video.mp4 --prompt "Count the number of people in each frame"
🐍 Python API
from douyin_insight import VideoAnalyzer
# Initialize with any supported provider
analyzer = VideoAnalyzer(
api_key="gsk_...",
provider="groq", # or "gemini", "zhipu", "nvidia"
frame_count=8,
)
# Analyze from URL
result = analyzer.analyze("https://v.douyin.com/xxxxx/")
print(result.analysis)
print(result.to_markdown())
print(result.to_json())
# Analyze local file
result = analyzer.analyze_local("video.mp4")
# Custom prompt
result = analyzer.analyze(
"https://v.douyin.com/xxxxx/",
prompt="What products are shown in this video? List brand names and prices if visible.",
)
# Access metadata
print(result.video_info) # duration, resolution, codec
print(result.frames) # list of extracted frame paths
print(result.provider) # which LLM was used
Lower-Level API
from douyin_insight import download_video, extract_frames
# Download only
video_path = download_video("https://v.douyin.com/xxxxx/")
# Extract frames only
frames = extract_frames(video_path, count=12, strategy="scene")
# Returns: [Path('frame_000_1.2s.jpg'), Path('frame_001_5.4s.jpg'), ...]
🔧 Configuration
Environment Variables
| Variable | Provider |
|---|---|
GROQ_API_KEY |
Groq (Llama 4 Scout) |
GOOGLE_API_KEY |
Google Gemini |
ZHIPU_API_KEY |
Zhipu GLM-4V |
NVIDIA_API_KEY |
NVIDIA NIM |
DYI_API_KEY |
Generic (use with --provider) |
Proxy Support
dyi analyze https://v.douyin.com/xxxxx/ --proxy http://127.0.0.1:7890
analyzer = VideoAnalyzer(api_key="...", proxy="http://127.0.0.1:7890")
🏗️ Architecture
URL → Download → Extract Frames → Vision LLM → Structured Analysis
│ │ │
Douyin/TikTok ffmpeg Groq/Gemini/
yt-dlp/direct uniform/scene Zhipu/NVIDIA
📋 Requirements
- Python 3.9+
- ffmpeg (for frame extraction)
- One free API key from any supported provider
🤝 Contributing
git clone https://github.com/qq1455519358-sys/douyin-insight
cd douyin-insight
pip install -e ".[dev]"
pytest
📄 License
MIT
🙏 Credits
Metadata
Release files for douyin-insight 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| douyin_insight-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for douyin_insight-0.1.0-py3-none-any.whl |
Release files / douyin_insight-0.1.0-py3-none-any.whl
| Download URL | douyin_insight-0.1.0-py3-none-any.whl |
|---|---|
| Size | 16.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c2c2aa831e67cf97574e6d45b32fc97aa797a116506e62264b8df9f91c9038c8
|
|
BLAKE2b-256 checksum How to use checksums |
7c3463d9232b4ba2c0ddb71305a770fec15c0020765f36e28a49689dc7ddec98
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for douyin-insight 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.