Cobalt 视频下载完整指南：Docker 自建实例到 API 调用的实操教程-平芜编程栈

Cobalt 视频下载完整指南：Docker 自建实例到 API 调用的实操教程

【免费下载链接】cobaltbest way to save what you love项目地址: https://gitcode.com/GitHub_Trending/cob/cobalt

凌晨刷到一条很对味的教程视频，想把它转成 mp3 存进手机通勤时听——与其依赖那些行为不透明的在线站，不如自己跑一个。Cobalt 是一个开源的自托管视频下载服务，支持 YouTube、TikTok、Bilibili 等 20 多个平台，没有广告、没有追踪器，一条 Docker 命令就能把它部署到自己的服务器上，还开放 REST API 方便接进你自己的脚本。下面从部署、参数配置到接口调用，一步步带你把它跑通。

⚡ 5 分钟跑通一个 Cobalt 实例

部署首选官方 Docker 包，前提是机器上装好了 Docker 和 Docker Compose（容器编排工具）。我们最省事的路径就三步：

git clone https://gitcode.com/GitHub_Trending/cob/cobalt cd cobalt docker compose up -d

compose 文件可以直接拿仓库里的样例配置起步，唯一必须改的是把默认的WEB_URL/API_URL换成你自己的域名，否则前端会把请求发给别人的实例。包内置了 watchtower（容器自动升级工具），镜像一有新版容器就会自动拉取重启，省掉手动升级这一步。

如果只是本地开发调试，也可以手动装：先装 Node.js 18 以上和 git，git clone仓库后跑npm run setup（脚本会问你这次装 API 还是前端，两者要分开部署），再npm start就能跑起来。要支持需要登录态才能看的内容，在同目录放一份 cookies.json（样例见 cookies.example.json），再用环境变量COOKIE_PATH指向它。

🎛️ 下载参数怎么配：模式、画质与文件名

所有请求都打到同一个POST /api/json接口，靠 body 里的字段控制行为。最关键的几个开关如下。

三种互斥模式（默认就是视频+音频）：

模式	怎么触发	适用
视频+音频	默认，不用传	存原片
仅音频	`isAudioOnly: true`	只要音乐/人声（做课件转 mp3/opus 很省空间）
仅视频	`isAudioMuted: true`	只要画面素材，去掉音轨

画质与编码：vQuality可取 144 到 2160 或max，默认 720（手机端建议这个，省电省流）；YouTube 还能用vCodec选h264/av1/vp9，老手机选 h264 兼容性最稳。音频格式由aFormat指定，支持best、mp3、ogg、wav、opus，默认 mp3。

平台专属开关：TikTok 的isTTFullAudio能拿到视频用的原始完整音源（找 BGM 原曲时很顺手），tiktokH265控制是否优先 1080p 的 HEVC 版本；Twitter 的twitterGif决定 GIF 是否真转成 .gif 文件。

文件名由filenamePattern决定，四种风格，生成逻辑在 createFilename.js，标题、分辨率、编码器、音轨语言都会保留，素材入库后不用二次改名也能认出来：

取值	示例
`classic`（默认）	`youtube_MMK3L4W70g4_1920x1080_h264_mute.mp4`
`pretty`	`Loossemble - 'Sensitive' MV (1080p, h264, mute, youtube).mp4`
`basic`	标题 + (1080p, h264)，不带平台名
`nerdy`	标题 + (1080p, h264, ru, youtube, 视频ID)

运营做品牌素材归档时，把filenamePattern设成nerdy最省心——文件名里自带分辨率、编码和平台 ID，按项目文件夹一放，日后盘点不用回网站翻历史。

🔌 Cobalt API 调用与实例加固

整个服务本质就是一个 REST 接口，前端和 API 分开放，所以任何语言、任何脚本都能直接调，把它接进自己的自动化里也毫不费力。最精简的一次调用长这样：

curl -X POST http://localhost:9000/api/json \ -H "Accept: application/json" -H "Content-Type: application/json" \ -d '{"url": "https://www.youtube.com/watch?v=xxxxx", "vQuality": "1080"}'

成功时返回status: success加一个可下载的直链，链接参数带签名且有时效，直接当下载地址用就行。每个平台的具体抓取与转码逻辑都在 services 目录，一个平台一个文件，字段全集见 docs/api.md。

要把实例暴露到公网，重点调这几个环境变量（完整清单在 run-an-instance.md）：

变量	默认	说明
`API_PORT`	9000	API 端口
`WEB_PORT`	9001	前端端口
`API_URL`	必填	实例对外地址
`RATELIMIT_WINDOW`	60	限流时间窗（秒）
`RATELIMIT_MAX`	20	窗口内单 IP 最多请求数
`CORS_WILDCARD`	1	0=按白名单，1=全放开
`CORS_URL`	无	白名单域名