다중 플랫폼 비디오 링크 다운로드 가이드

이 문서는 Douyin, TikTok, Bilibili, Xiaohongshu, Weibo 등 플랫폼에서 비디오 링크를 가져온 후, 비디오 파일을 올바르게 다운로드하는 방법을 자세히 소개합니다. 핵심은 크로스 도메인, 핫링크 방지, 요청 헤더 검증 등 흔한 문제를 해결하는 것입니다.

공통 문제 개요

각 플랫폼에서 비디오 링크를 가져온 후, 직접 다운로드하면 보통 다음과 같은 문제를 만나게 됩니다:

문제 유형	설명	해결 방안
핫링크 방지 (Referer)	서버가 요청 출처를 검사하여 불법 출처를 거부	올바른 Referer 헤더 설정
크로스 도메인 (CORS)	브라우저 보안 정책이 크로스 도메인 요청을 차단	백엔드 프록시 / 서버 측 다운로드
User-Agent 검증	서버가 클라이언트 식별자를 검사	브라우저 UA 모방
Cookie 검증	일부 링크는 로그인 상태 필요	유효한 Cookie 포함
링크 유효 시간	비디오 링크에는 만료 시간이 있음	즉시 사용, 만료 시 재획득
IP 제한	일부 링크는 지역 접근 제한	해당 지역 프록시 사용

Douyin

비디오 링크 특징

Douyin 비디오 링크는 보통 다음과 같은 형태입니다:

txt

# 播放地址 (无水印)
https://www.douyin.com/aweme/v1/play/?video_id=xxx&line=0&file_id=xxx

# CDN 地址
https://v26-web.douyinvod.com/xxx/xxx.mp4

# 带水印下载地址
https://aweme.snssdk.com/aweme/v1/playwm/?video_id=xxx

다운로드 요구사항

요청 헤더	필수 여부	값
`Referer`	필수	`https://www.douyin.com/`
`User-Agent`	권장	브라우저 UA
`Cookie`	선택	일부 고화질 링크에 필요

서버 측 다운로드 예시

python
import httpx

async def download_douyin_video(video_url: str, save_path: str) -> bool:
    """
    下载抖音视频

    Args:
        video_url: 视频播放地址
        save_path: 保存路径

    Returns:
        是否下载成功
    """
    headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "Referer": "https://www.douyin.com/",  # 必须
        "Accept": "*/*",
        "Accept-Encoding": "identity",  # 避免压缩，方便流式下载
        "Range": "bytes=0-",  # 支持断点续传
    }

    async with httpx.AsyncClient(follow_redirects=True, timeout=60) as client:
        async with client.stream("GET", video_url, headers=headers) as response:
            if response.status_code in [200, 206]:
                with open(save_path, "wb") as f:
                    async for chunk in response.aiter_bytes(chunk_size=8192):
                        f.write(chunk)
                return True
    return False

프런트엔드 크로스 도메인 문제

Douyin 비디오 링크는 CORS를 지원하지 않으므로, 프런트엔드에서 직접 요청하면 브라우저에 의해 차단됩니다:

javascript
// ❌ 错误方式 - 会被 CORS 拦截
fetch('https://v26-web.douyinvod.com/xxx.mp4')
  .then(res => res.blob())  // CORS error!

// ✅ 正确方式 - 使用后端代理
fetch('/api/proxy/video?url=' + encodeURIComponent(videoUrl))
  .then(res => res.blob())
  .then(blob => {
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'video.mp4';
    a.click();
  });

주의사항

링크 유효 시간: Douyin 비디오 링크는 보통 24시간 내에 유효합니다
워터마크 없는 링크: play_addr를 사용하고 download_addr는 사용하지 마세요
고화질 링크: 일부 4K/원본 화질 비디오는 용량이 크므로, 한 번에 다운로드 실패를 피하기 위해 분할 다운로드를 권장합니다

TikTok

비디오 링크 특징

txt

# 播放地址
https://v16-webapp-prime.tiktok.com/video/tos/xxx.mp4

# 无水印地址
https://www.tiktok.com/aweme/v1/play/?video_id=xxx

# 带水印地址
https://v16-webapp.tiktok.com/video/tos/xxx.mp4

다운로드 요구사항

Web端 비디오 링크

요청 헤더	필수 여부	값
`Referer`	필수	`https://www.tiktok.com/`
`User-Agent`	필수	브라우저 UA
`Cookie`	필수	`tt_chain_token` 필드 필요

중요: TikTok Web端에서 반환된 비디오 링크는 다운로드하려면 반드시 tt_chain_token Cookie를 포함해야 하며, 그렇지 않으면 403 오류가 반환됩니다.

App端 비디오 링크

요청 헤더	필수 여부	값
`User-Agent`	권장	임의의 UA
`Cookie`	불필요	App端 링크에는 이 제한이 없음

권장: App端 링크를 얻을 수 있다면 우선적으로 App端 링크를 사용하세요. Cookie 문제를 처리할 필요가 없습니다.

서버 측 다운로드 예시

Web端 다운로드 (tt_chain_token 필요)

python
import httpx

async def download_tiktok_video_web(
    video_url: str,
    save_path: str,
    tt_chain_token: str  # 必须提供
) -> bool:
    """
    下载 TikTok Web 端视频

    注意:
    - Web 端链接必须携带 tt_chain_token Cookie
    - tt_chain_token 可从浏览器或 API 响应中获取
    """
    headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36",
        "Referer": "https://www.tiktok.com/",
        "Accept": "video/webm,video/ogg,video/*;q=0.9,*/*;q=0.8",
        "Accept-Language": "en-US,en;q=0.5",
        "Cookie": f"tt_chain_token={tt_chain_token}",  # 必须
        "Sec-Fetch-Dest": "video",
        "Sec-Fetch-Mode": "no-cors",
        "Sec-Fetch-Site": "cross-site",
    }

    async with httpx.AsyncClient(follow_redirects=True, timeout=60) as client:
        async with client.stream("GET", video_url, headers=headers) as response:
            if response.status_code in [200, 206]:
                with open(save_path, "wb") as f:
                    async for chunk in response.aiter_bytes(chunk_size=8192):
                        f.write(chunk)
                return True
            elif response.status_code == 403:
                print("下载失败: tt_chain_token 无效或缺失")
    return False

python
async def download_tiktok_video_app(video_url: str, save_path: str) -> bool:
    """
    下载 TikTok App 端视频

    App 端链接无需 Cookie，直接下载即可
    """
    headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "Accept": "*/*",
    }

    async with httpx.AsyncClient(follow_redirects=True, timeout=60) as client:
        async with client.stream("GET", video_url, headers=headers) as response:
            if response.status_code in [200, 206]:
                with open(save_path, "wb") as f:
                    async for chunk in response.aiter_bytes(chunk_size=8192):
                        f.write(chunk)
                return True
    return False

tt_chain_token 획득 방법

tt_chain_token은 TikTok이 비디오 다운로드 인증에 사용하는 Cookie로, 획득 방법은 다음과 같습니다:

브라우저에서 획득: TikTok 웹사이트를 열고, F12 개발자 도구 -> Application -> Cookies -> tt_chain_token 찾기
API 응답에서 획득: 일부 TikTok API 응답의 Set-Cookie 헤더에 이 값이 포함될 수 있음
TikHub API 사용: API 반환 데이터에 사용 가능한 token이 이미 포함되어 있을 수 있음

python
# 示例：从响应头提取 tt_chain_token
def extract_tt_chain_token(response_headers: dict) -> str:
    """从响应头中提取 tt_chain_token"""
    cookies = response_headers.get("set-cookie", "")
    for cookie in cookies.split(";"):
        if "tt_chain_token=" in cookie:
            return cookie.split("tt_chain_token=")[1].split(";")[0]
    return ""

지역 제한

TikTok 비디오는 지역 제한이 있을 수 있으며, 일부 비디오는 특정 국가에서만 접근 가능합니다:

python
# 使用代理下载特定地区视频
proxies = {
    "http://": "http://us-proxy:8080",
    "https://": "http://us-proxy:8080",
}

async with httpx.AsyncClient(proxies=proxies) as client:
    # ...

주의사항

지역 제한: 일부 비디오는 미국/유럽 IP가 있어야 접근 가능
링크 유효 시간: 링크 유효 기간은 약 24시간
워터마크 없음: downloadAddr 필드를 우선 사용

Bilibili

비디오 링크 특징

B站 비디오 링크는 비교적 특수하며, 오디오와 비디오가 분리되어 있습니다:

txt

# 视频流 (DASH)
https://upos-sz-mirrorali.bilivideo.com/xxx/xxx.m4s

# 音频流 (DASH)
https://upos-sz-mirrorali.bilivideo.com/xxx/xxx.m4s

# FLV 格式 (旧版)
https://upos-sz-mirrorali.bilivideo.com/xxx/xxx.flv

다운로드 요구사항

요청 헤더	필수 여부	값
`Referer`	필수	`https://www.bilibili.com/`
`User-Agent`	권장	브라우저 UA
`Cookie`	고화질, 4K 필수	SESSDATA 등
`Range`	권장	분할 다운로드

서버 측 다운로드 예시

python
import httpx
import subprocess
from pathlib import Path

async def download_bilibili_video(
    video_url: str,
    audio_url: str,
    save_path: str,
    cookie: str = None
) -> bool:
    """
    下载 B站 视频 (需要合并音视频)

    Args:
        video_url: 视频流地址
        audio_url: 音频流地址
        save_path: 最终保存路径
        cookie: 可选，高清视频需要 SESSDATA
    """
    headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36",
        "Referer": "https://www.bilibili.com/",  # 必须，否则 403
        "Accept": "*/*",
        "Accept-Encoding": "identity",
        "Origin": "https://www.bilibili.com",
    }

    if cookie:
        headers["Cookie"] = cookie

    # 临时文件路径
    video_temp = save_path + ".video.m4s"
    audio_temp = save_path + ".audio.m4s"

    async with httpx.AsyncClient(follow_redirects=True, timeout=120) as client:
        # 下载视频流
        async with client.stream("GET", video_url, headers=headers) as response:
            if response.status_code not in [200, 206]:
                return False
            with open(video_temp, "wb") as f:
                async for chunk in response.aiter_bytes(chunk_size=8192):
                    f.write(chunk)

        # 下载音频流
        async with client.stream("GET", audio_url, headers=headers) as response:
            if response.status_code not in [200, 206]:
                return False
            with open(audio_temp, "wb") as f:
                async for chunk in response.aiter_bytes(chunk_size=8192):
                    f.write(chunk)

    # 使用 FFmpeg 合并音视频
    try:
        subprocess.run([
            "ffmpeg", "-y",
            "-i", video_temp,
            "-i", audio_temp,
            "-c:v", "copy",
            "-c:a", "copy",
            save_path
        ], check=True, capture_output=True)

        # 删除临时文件
        Path(video_temp).unlink()
        Path(audio_temp).unlink()
        return True
    except subprocess.CalledProcessError:
        return False

화질과 Cookie의 관계

화질	로그인 필요 여부	Cookie 요구사항
360P/480P	아니오	없음
720P	예	SESSDATA
1080P	예	SESSDATA + 대회원
4K/HDR	예	SESSDATA + 대회원

주의사항

반드시 병합: DASH 형식은 오디오와 비디오가 분리되어 있으므로 FFmpeg로 병합해야 함
Referer 필수: 올바른 Referer가 없으면 403 반환
링크 유효 시간: 약 2시간 유효
분할 다운로드: 대용량 파일은 Range 헤더를 사용한 분할 다운로드 권장

Xiaohongshu

비디오 링크 특징

txt

# 视频地址
https://sns-video-bd.xhscdn.com/xxx.mp4
https://sns-video-hw.xhscdn.com/xxx.mp4

# 图片地址
https://sns-img-bd.xhscdn.com/xxx.jpg

다운로드 요구사항

요청 헤더	필수 여부	값
`Referer`	필수	`https://www.xiaohongshu.com/`
`User-Agent`	권장	브라우저 UA
`Cookie`	선택	일부 콘텐츠에 필요

서버 측 다운로드 예시

python
import httpx

async def download_xiaohongshu_video(video_url: str, save_path: str) -> bool:
    """
    下载小红书视频

    小红书对 Referer 检查较严格
    """
    headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "Referer": "https://www.xiaohongshu.com/",  # 必须
        "Accept": "*/*",
        "Origin": "https://www.xiaohongshu.com",
        "Sec-Fetch-Dest": "video",
        "Sec-Fetch-Mode": "cors",
        "Sec-Fetch-Site": "cross-site",
    }

    async with httpx.AsyncClient(follow_redirects=True, timeout=60) as client:
        async with client.stream("GET", video_url, headers=headers) as response:
            if response.status_code in [200, 206]:
                with open(save_path, "wb") as f:
                    async for chunk in response.aiter_bytes(chunk_size=8192):
                        f.write(chunk)
                return True
    return False

이미지 다운로드

Xiaohongshu 이미지도 핫링크 방지가 있습니다:

python
async def download_xiaohongshu_image(image_url: str, save_path: str) -> bool:
    """下载小红书图片"""
    headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "Referer": "https://www.xiaohongshu.com/",
        "Accept": "image/avif,image/webp,image/apng,image/*,*/*;q=0.8",
    }

    async with httpx.AsyncClient(follow_redirects=True) as client:
        response = await client.get(image_url, headers=headers)
        if response.status_code == 200:
            with open(save_path, "wb") as f:
                f.write(response.content)
            return True
    return False

주의사항

Referer 엄격: 반드시 xiaohongshu.com의 Referer를 포함해야 함
CDN 노드: bd(Baidu Cloud), hw(Huawei Cloud) 등 서로 다른 노드
워터마크 없음: API가 반환하는 링크는 보통 워터마크가 없음

Weibo

비디오 링크 특징

Weibo 비디오 링크 형식은 여러 가지입니다:

txt

# 标准视频
https://f.video.weibocdn.com/xxx.mp4

# 直播回放
https://live.video.weibocdn.com/xxx.flv

# 高清视频
https://video.weibo.com/media/play?fid=xxx

다운로드 요구사항

요청 헤더	필수 여부	값
`Referer`	필수	`https://weibo.com/` 또는 `https://m.weibo.cn/`
`User-Agent`	권장	브라우저 UA
`Cookie`	일부 필요	비공개 비디오에 필요

서버 측 다운로드 예시

python
import httpx

async def download_weibo_video(video_url: str, save_path: str) -> bool:
    """
    下载微博视频

    微博支持多个 Referer 域名
    """
    headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "Referer": "https://weibo.com/",  # 或 https://m.weibo.cn/
        "Accept": "*/*",
        "Accept-Encoding": "identity",
    }

    async with httpx.AsyncClient(follow_redirects=True, timeout=60) as client:
        async with client.stream("GET", video_url, headers=headers) as response:
            if response.status_code in [200, 206]:
                with open(save_path, "wb") as f:
                    async for chunk in response.aiter_bytes(chunk_size=8192):
                        f.write(chunk)
                return True
    return False

다중 화질 선택

Weibo 비디오는 보통 여러 화질을 제공합니다:

python
def select_best_quality(media_info: dict) -> str:
    """选择最高清晰度的视频链接"""
    # 清晰度优先级
    quality_priority = ["mp4_720p_mp4", "mp4_hd_mp4", "mp4_ld_mp4"]

    playback_list = media_info.get("playback_list", [])

    for quality in quality_priority:
        for item in playback_list:
            if item.get("quality_label") == quality:
                return item.get("play_info", {}).get("url")

    # 降级使用 stream_url
    return media_info.get("stream_url")

주의사항

Referer 도메인: weibo.com 및 m.weibo.cn 지원
다중 화질: 반환 데이터에 여러 화질 선택지가 있음
링크 유효성: 일부 링크는 유효 기간 제한이 있음

YouTube

비디오 링크 특징

YouTube 비디오 링크는 보통 다음과 같은 형태입니다:

txt

# 标准视频流地址
https://rr1---sn-xxx.googlevideo.com/videoplayback?expire=xxx&ei=xxx&ip=xxx&id=xxx&itag=xxx&source=youtube&...

# 自适应流地址 (DASH)
https://manifest.googlevideo.com/api/manifest/dash/...

# 直播流地址 (HLS)
https://manifest.googlevideo.com/api/manifest/hls_variant/...

다운로드 요구사항

엄격한 IP 제한: YouTube 비디오 스트림 주소는 IP 지리 위치에 대해 매우 엄격한 검증을 하며, 미국 캘리포니아주 로스앤젤레스 지역 IP를 사용해야만 성공적으로 다운로드할 수 있습니다. 그렇지 않으면 403 Forbidden 오류가 반환됩니다.

요청 헤더	필수 여부	값
`User-Agent`	필수	브라우저 UA
`Referer`	권장	`https://www.youtube.com/`
`Origin`	권장	`https://www.youtube.com`
프록시 IP	필수	미국 캘리포니아주 로스앤젤레스 IP

IP 지역 제한 설명

YouTube의 비디오 스트림 주소는 생성 시 요청자의 IP 주소에 바인딩되며, 다운로드 시 반드시 동일한 지역의 IP를 사용해야 합니다:

txt

# 视频流 URL 中包含 IP 绑定参数
https://rr1---sn-xxx.googlevideo.com/videoplayback?
    expire=1234567890        # 过期时间
    &ei=xxx                  # 加密标识
    &ip=1.2.3.4             # 绑定的 IP 地址 (关键!)
    &id=xxx
    &itag=137               # 视频质量标识
    &source=youtube
    &...

왜 반드시 로스앤젤레스 IP여야 하나요?

YouTube의 대부분 CDN 노드는 미국 서부 해안에 위치함
비디오 스트림 URL 생성 시 요청 IP에 따라 가장 가까운 CDN이 선택됨
다운로드 시 IP 지역이 일치하지 않으면 403 오류가 발생함
로스앤젤레스는 YouTube의 주요 데이터센터 위치로, 호환성이 가장 좋음

서버 측 다운로드 예시

python
import httpx

async def download_youtube_video(
    video_url: str,
    save_path: str,
    proxy: str = None  # 必须是美国加州洛杉矶代理
) -> bool:
    """
    下载 YouTube 视频

    重要:
    - 必须使用美国加利福尼亚州洛杉矶地区的代理 IP
    - 其他地区 IP 会返回 403 Forbidden
    - 视频流 URL 有时效性，通常 6 小时内有效
    """
    headers = {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36",
        "Referer": "https://www.youtube.com/",
        "Origin": "https://www.youtube.com",
        "Accept": "*/*",
        "Accept-Language": "en-US,en;q=0.9",
        "Accept-Encoding": "identity",  # 避免压缩
        "Range": "bytes=0-",  # 支持断点续传
        "Sec-Fetch-Dest": "video",
        "Sec-Fetch-Mode": "no-cors",
        "Sec-Fetch-Site": "cross-site",
    }

    # 代理配置 - 必须是洛杉矶 IP
    proxies = None
    if proxy:
        proxies = {
            "http://": proxy,
            "https://": proxy,
        }

    async with httpx.AsyncClient(
        follow_redirects=True,
        timeout=120,
        proxies=proxies
    ) as client:
        async with client.stream("GET", video_url, headers=headers) as response:
            if response.status_code in [200, 206]:
                with open(save_path, "wb") as f:
                    async for chunk in response.aiter_bytes(chunk_size=8192):
                        f.write(chunk)
                return True
            elif response.status_code == 403:
                print("下载失败: IP 地区不符合要求，请使用美国加州洛杉矶的代理")
            elif response.status_code == 410:
                print("下载失败: 视频链接已过期，请重新获取")
    return False

오디오/비디오 분리 처리

YouTube 고화질 비디오(1080p+)는 DASH 형식을 사용하며, 오디오와 비디오가 분리되어 있습니다:

python
import subprocess
from pathlib import Path

async def download_youtube_video_with_audio(
    video_url: str,
    audio_url: str,
    save_path: str,
    proxy: str = None
) -> bool:
    """
    下载 YouTube 视频并合并音频

    YouTube 1080p 及以上清晰度的视频，音频和视频是分离的
    需要分别下载后使用 FFmpeg 合并
    """
    video_temp = save_path + ".video.mp4"
    audio_temp = save_path + ".audio.m4a"

    # 下载视频流
    success = await download_youtube_video(video_url, video_temp, proxy)
    if not success:
        return False

    # 下载音频流
    success = await download_youtube_video(audio_url, audio_temp, proxy)
    if not success:
        return False

    # 使用 FFmpeg 合并
    try:
        subprocess.run([
            "ffmpeg", "-y",
            "-i", video_temp,
            "-i", audio_temp,
            "-c:v", "copy",
            "-c:a", "aac",
            save_path
        ], check=True, capture_output=True)

        # 删除临时文件
        Path(video_temp).unlink()
        Path(audio_temp).unlink()
        return True
    except subprocess.CalledProcessError as e:
        print(f"FFmpeg 合并失败: {e}")
        return False

프록시 설정 예시

python
# 推荐的代理配置 - 必须是洛杉矶地区
LA_PROXIES = [
    "http://user:pass@la-proxy1.example.com:8080",  # 洛杉矶代理 1
    "http://user:pass@la-proxy2.example.com:8080",  # 洛杉矶代理 2
    "socks5://user:pass@la-socks.example.com:1080", # SOCKS5 代理
]

# 验证代理 IP 是否在洛杉矶
async def verify_proxy_location(proxy: str) -> bool:
    """验证代理 IP 是否在洛杉矶地区"""
    async with httpx.AsyncClient(proxies={"https://": proxy}) as client:
        response = await client.get("https://ipapi.co/json/")
        data = response.json()

        city = data.get("city", "")
        region = data.get("region", "")
        country = data.get("country_code", "")

        # 检查是否在加州洛杉矶
        is_la = (
            country == "US" and
            region == "California" and
            "Los Angeles" in city
        )

        if is_la:
            print(f"✓ 代理 IP 位于: {city}, {region}, {country}")
        else:
            print(f"✗ 代理 IP 位于: {city}, {region}, {country} (不符合要求)")

        return is_la

화질 식별자(itag) 대응표

itag	해상도	형식	오디오 포함 여부
18	360p	MP4	예
22	720p	MP4	예
137	1080p	MP4	아니오 (병합 필요)
248	1080p	WebM	아니오 (병합 필요)
271	1440p	WebM	아니오 (병합 필요)
313	2160p	WebM	아니오 (병합 필요)
140	-	M4A 오디오	오디오만
251	-	WebM 오디오	오디오만

주의사항

IP 제한이 매우 엄격함: 반드시 미국 캘리포니아주 로스앤젤레스 IP를 사용해야 하며, 다른 지역(미국의 다른 주 포함)은 실패할 수 있음
링크 유효 시간: 비디오 스트림 URL은 보통 6시간 내에 유효
오디오/비디오 분리: 720p 이상의 화질은 오디오와 비디오를 각각 다운로드한 후 병합해야 함
속도 제한: YouTube는 다운로드 속도에 제한이 있으므로, 대용량 파일은 분할 다운로드 권장

프런트엔드 다운로드 방식

CORS 제한으로 인해 프런트엔드에서는 대부분 플랫폼의 비디오를 직접 다운로드할 수 없습니다. 가능한 방식은 다음과 같습니다:

방식 1: 백엔드 프록시(권장)

javascript
// 前端请求后端代理接口
async function downloadVideo(videoUrl, platform, filename) {
  const proxyUrl = `/api/download/video?url=${encodeURIComponent(videoUrl)}&platform=${platform}`;

  const response = await fetch(proxyUrl);
  const blob = await response.blob();

  // 创建下载链接
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename || 'video.mp4';
  document.body.appendChild(a);
  a.click();
  document.body.removeChild(a);
  URL.revokeObjectURL(url);
}

방식 2: 새 창에서 열기(일부 플랫폼에서 사용 가능)

javascript
// 部分平台链接可以直接在新窗口打开下载
function openVideoInNewTab(videoUrl) {
  window.open(videoUrl, '_blank');
}

방식 3: download 속성 사용(동일 출처 시나리오)

html
<!-- 仅适用于同源或允许 CORS 的资源 -->
<a href="video.mp4" download="video.mp4">下载视频</a>

백엔드 프록시 다운로드 방식

FastAPI 프록시 예시

python
from fastapi import FastAPI, Query, Response
from fastapi.responses import StreamingResponse
import httpx

app = FastAPI()

# 各平台的请求头配置
PLATFORM_HEADERS = {
    "douyin": {
        "Referer": "https://www.douyin.com/",
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    },
    "tiktok": {
        "Referer": "https://www.tiktok.com/",
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    },
    "bilibili": {
        "Referer": "https://www.bilibili.com/",
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    },
    "xiaohongshu": {
        "Referer": "https://www.xiaohongshu.com/",
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    },
    "weibo": {
        "Referer": "https://weibo.com/",
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    },
}


@app.get("/api/download/video")
async def proxy_video(
    url: str = Query(..., description="视频 URL"),
    platform: str = Query(..., description="平台标识"),
):
    """
    视频代理下载接口

    解决前端跨域和防盗链问题
    """
    headers = PLATFORM_HEADERS.get(platform, {})

    async def video_stream():
        async with httpx.AsyncClient(follow_redirects=True, timeout=120) as client:
            async with client.stream("GET", url, headers=headers) as response:
                async for chunk in response.aiter_bytes(chunk_size=8192):
                    yield chunk

    return StreamingResponse(
        video_stream(),
        media_type="video/mp4",
        headers={
            "Content-Disposition": "attachment; filename=video.mp4",
            "Access-Control-Allow-Origin": "*",  # 允许跨域
        }
    )


@app.get("/api/download/image")
async def proxy_image(
    url: str = Query(..., description="图片 URL"),
    platform: str = Query(..., description="平台标识"),
):
    """图片代理下载接口"""
    headers = PLATFORM_HEADERS.get(platform, {})

    async with httpx.AsyncClient(follow_redirects=True) as client:
        response = await client.get(url, headers=headers)

        return Response(
            content=response.content,
            media_type=response.headers.get("content-type", "image/jpeg"),
            headers={
                "Access-Control-Allow-Origin": "*",
            }
        )

진행률이 있는 다운로드 예시

python
import httpx
from tqdm import tqdm

async def download_with_progress(url: str, save_path: str, headers: dict) -> bool:
    """带进度条的下载"""
    async with httpx.AsyncClient(follow_redirects=True, timeout=120) as client:
        async with client.stream("GET", url, headers=headers) as response:
            total = int(response.headers.get("content-length", 0))

            with open(save_path, "wb") as f:
                with tqdm(total=total, unit="B", unit_scale=True, desc="下载中") as pbar:
                    async for chunk in response.aiter_bytes(chunk_size=8192):
                        f.write(chunk)
                        pbar.update(len(chunk))

            return True
    return False

요약

각 플랫폼 다운로드 핵심 포인트 빠른 참고표

플랫폼	Referer	Cookie 요구사항	특수 처리	링크 유효 시간
Douyin	`https://www.douyin.com/`	선택	없음	24시간
TikTok Web	`https://www.tiktok.com/`	필수 `tt_chain_token`	지역 프록시 필요	1-6시간
TikTok App	불필요	불필요	사용 권장	김
B站	`https://www.bilibili.com/`	고화질은 SESSDATA 필수	오디오/비디오 분리 시 병합 필요	2시간
Xiaohongshu	`https://www.xiaohongshu.com/`	선택	없음	김
Weibo	`https://weibo.com/`	일부 필요	다중 화질	김
YouTube	`https://www.youtube.com/`	불필요	반드시 로스앤젤레스 IP + 오디오/비디오 분리	6시간

흔한 오류 점검

오류 코드	가능한 원인	해결 방안
403 Forbidden	Referer 오류 또는 누락	Referer 헤더 확인
403 Forbidden	TikTok의 tt_chain_token 누락	Cookie 추가 또는 App端 링크 사용
403 Forbidden	YouTube IP 지역 불일치	미국 캘리포니아주 로스앤젤레스 프록시 사용
404 Not Found	링크 만료	링크 재획득
410 Gone	YouTube 링크 만료	비디오 스트림 URL 재획득
CORS Error	브라우저 크로스 도메인 제한	백엔드 프록시 사용
시간 초과	네트워크 문제 또는 파일이 너무 큼	타임아웃 증가, 분할 다운로드

모범 사례

항상 Referer 설정: 대부분 플랫폼의 필수 조건입니다
백엔드 프록시 사용: 프런트엔드 CORS 문제를 해결하는 최선의 방법입니다
링크 유효 시간 처리: 링크를 즉시 사용하고, 만료되면 재획득하세요
이어받기 지원: 대용량 파일은 Range 헤더를 사용해 분할 다운로드하세요
오류 재시도: 네트워크가 불안정할 때 재시도 메커니즘을 구현하세요

문의하기

이 문서의 안내에 따라 작업했음에도 비디오를 성공적으로 다운로드할 수 없다면, 고객센터에 문의하여 도움을 받으세요:

공식 문서: https://docs.tikhub.io/
Discord 커뮤니티: https://discord.gg/Pu2uKkFu6u
온라인 고객센터(Chaport): 공식 웹사이트 오른쪽 아래의 온라인 상담 창을 이용

고객센터에 문의할 때는 더 빠른 도움을 위해 아래 정보를 제공해 주세요:

플랫폼 이름: Douyin/TikTok/B站/Xiaohongshu/Weibo/YouTube
비디오 링크: 원본 비디오 페이지 URL
오류 정보: 전체 오류 코드와 오류 설명
요청 헤더 설정: 사용한 Referer, Cookie 등의 정보
프록시 정보: 프록시를 사용한 경우 프록시 지역을 제공해 주세요

다중 플랫폼 비디오 링크 다운로드 가이드

목차

공통 문제 개요

Douyin

비디오 링크 특징

다운로드 요구사항

서버 측 다운로드 예시

프런트엔드 크로스 도메인 문제

주의사항

TikTok

비디오 링크 특징

다운로드 요구사항

Web端 비디오 링크

App端 비디오 링크

서버 측 다운로드 예시

Web端 다운로드 (tt_chain_token 필요)

App端 다운로드 (Cookie 제한 없음)

tt_chain_token 획득 방법

지역 제한

주의사항

Bilibili

비디오 링크 특징

다운로드 요구사항

서버 측 다운로드 예시

화질과 Cookie의 관계

주의사항

Xiaohongshu

비디오 링크 특징

다운로드 요구사항

서버 측 다운로드 예시

이미지 다운로드

주의사항

Weibo

비디오 링크 특징

다운로드 요구사항

서버 측 다운로드 예시

다중 화질 선택

주의사항

YouTube

비디오 링크 특징

다운로드 요구사항

IP 지역 제한 설명

서버 측 다운로드 예시

오디오/비디오 분리 처리

프록시 설정 예시

화질 식별자(itag) 대응표

주의사항

프런트엔드 다운로드 방식

방식 1: 백엔드 프록시(권장)

방식 2: 새 창에서 열기(일부 플랫폼에서 사용 가능)

방식 3: download 속성 사용(동일 출처 시나리오)

백엔드 프록시 다운로드 방식

FastAPI 프록시 예시

진행률이 있는 다운로드 예시

요약

각 플랫폼 다운로드 핵심 포인트 빠른 참고표

흔한 오류 점검

모범 사례

문의하기