用途
cobalt-downloader 是一个用于下载 YouTube 视频的技能,底层调用开源媒体下载器 Cobalt 的 API。Cobalt 能处理 YouTube 的反机器人措施,因此该技能适合在 yt-dlp 因机器人检测报错、业务系统无法管理 cookies、需要更可靠下载方式或已有自托管下载基础设施的场景中使用。
主要能力
- 向 Cobalt API 提交 YouTube 视频 URL,获取可直接下载的链接。
- 使用 curl 抓取视频或音频文件,并按视频 ID 命名保存到输出目录。
- 支持指定视频编码(h264、av1、vp9)、清晰度(144-2160 或 max)、音频格式(mp3、ogg、wav、opus)以及文件名模式(basic、pretty、nerdy)。
- 支持仅下载音频(isAudioOnly 设为 true)。
- 处理 Cobalt 的多种响应状态:stream(直接下载链接)、redirect(重定向下载)、picker(多个可选流)和 error(错误)。
使用方式
- 配置 Cobalt API 端点:可使用公共实例
https://api.cobalt.tools(有速率限制),或自托管实例(推荐生产使用)。自托管可通过 Docker 部署:
docker run -d -p 9000:9000 ghcr.io/imputnet/cobalt:latest
然后设置 COBALT_API="http://localhost:9000"。
- 通过
POST $COBALT_API/api/json发送 JSON 请求,包含 url、vCodec、vQuality、aFormat、filenamePattern 等参数,从响应中解析出下载链接。 - 使用
curl -L -o下载文件到./output/downloads/目录。 - 文档还提供仅音频模式的请求示例,以及 Docker Compose 自托管配置示例(包含 API_URL、API_NAME 环境变量)。
- 若 Cobalt 失败,可回退到 yt-dlp 命令继续下载。
适用场景
- yt-dlp 遭遇机器人检测错误时的替代下载方案。
- 无法维护 cookies 的业务系统。
- 需要自托管、可控且无速率限制的下载基础设施。
- 需要按指定编码、清晰度或音频格式批量获取 YouTube 媒体文件的流程。
限制与注意事项
- 公共实例存在速率限制;生产环境建议自托管。
- 无法下载私享或已删除的视频(content.video.unavailable),也无法下载直播流(content.video.live)。
- 网络问题可能导致 fetch.fail,可重试或回退 yt-dlp。
- 与 yt-dlp 相比,Cobalt 无需 cookies、可靠性较高、速度快,但自定义能力有限。
- 价格、收费、官方支持范围等资料暂未提供。