把一段YouTube或TikTok链接丢给编码或研究型智能体,最直觉的做法是:跑一遍 yt-dlp,下载MP4,把视频字节塞给支持视觉的模型。听起来顺理成章,真放到生产环境里,这条流水线在智能体读到第一句话之前就已经断了。
断点不止一处。多数前沿编码智能体根本不吃原始视频文件:Anthropic的Claude接受图片(单次请求最多600张、上限128 MB),但没有原生视频或音频输入;OpenAI的Responses API同样只收图片和文档,不收任意社交视频链接。就算某个模型家族原生支持视频,只要流水线要同时喂Claude、GPT、DeepSeek或RAG向量库,仍然需要一层确定性的、可缓存的文本与帧数据。
成本也是硬伤。token和带宽随视频时长线性上涨,一段30分钟的高分辨率视频做密集抽帧,能烧掉几十万token,而答案的九成可能就藏在口播文本和三张幻灯片里。再加上平台CDN链接绑定IP、寿命极短,把 googlevideo.com 或 tiktokcdn.com 的裸链接直接递给外部大模型API,返回的是 403 Forbidden——媒体签名绑在当初协商播放会话的那个IP上。
VidCrawl 的做法叫“渐进式视频披露”:第一层保持纯确定性、零LLM token,把轻量分镜网格连同带时间戳的文本一起送出,只有当文本本身留下歧义时,才去取那个精确时间点的高分辨率像素。
第一个坑:测试视频永远绿,真实视频全红
早期在 Hetzner(AS24940)服务器上测试时,YouTube冒烟测试对着 dQw4w9WgXcQ 一路通过,真实用户贴进 1E3tv_3D95g、UF8uR6Z6KLc 或 aircAruvnKk 这类真实视频,立刻失败。从被标记的云ASN发起请求,YouTube 的 /youtubei/v1/player 和 watch HTML 会返回 playabilityStatus.status = "LOGIN_REQUIRED",理由是“登录以确认你不是机器人”。而同一个数据中心IP请求 dQw4w9WgXcQ,照样返回 OK。
如果CI或 /healthz 健康检查测的正是 dQw4w9WgXcQ,监控会一直显示绿色,而生产环境里90%以上的真实URL在失败。第二个错误是把失败掩盖掉:当 playabilityStatus.status === "LOGIN_REQUIRED" 时返回 ok: true 和零条转写片段。VidCrawl 的处理是把 dQw4w9WgXcQ 从实时可靠性测试集中剔除(改用 1E3tv_3D95g 这类非白名单URL),并且只要 /player 返回 LOGIN_REQUIRED,就抛出带类型的 YOUTUBE_BOT_CHALLENGED(502)错误,而不是回一个空壳成功。
拆开路由:四条网络路径各干各的
把整段视频下载都走住宅代理,单位经济性直接崩掉。VidCrawl 把每次YouTube抓取拆成四条路径:
- 直连服务器IP,POST /youtubei/v1/next(WEB客户端),拿 visitorData、attributedDescription、外链和章节标记,零代理字节,省掉约1.2 MB的watch HTML;
- 粘性住宅代理,POST /youtubei/v1/player,在确定性粘性端口上轮换 VISIONOS / ANDROID_VR / IOS 客户端,每次调用约20-40 KB压缩JSON;
- 直连服务器IP,GET i.ytimg.com/sb/... 取最高可用的L3/L2分镜图,3x3或5x5的雪碧图切片,零代理字节;
- 直连服务器IP,GET timedtext?fmt=json3,拿到干净的 tStartMs + dDurationMs 片段,零代理字节。
三个实现细节值得记下。其一,确定性粘性代理端口:对 DataImpulse(gw.dataimpulse.com:823)来说,10000..19999 端口映射到粘性住宅会话,把 ${videoId}:${attempt} 哈希到某个粘性端口,能让 /player 协商和后续任何绑定IP的媒体或音频抓取走同一个出口IP,同时在不同视频和重试之间轮换。其二,用 json3 字幕而不是直接抓WebVTT:YouTube自动生成的 .vtt 轨道是两行滚动显示窗口,每条cue都重复上一行,下游转写里会出现重复句子;改用 &fmt;=json3(带 srv3 和XML兜底)能拿到以 tStartMs 和 dDurationMs 为键的离散 events[].segs[].utf8 条目。其三,fetch({ proxy }) 需要Bun运行时:Bun原生支持 fetch(url, { proxy }),Node会忽略 RequestInit 上的 proxy 参数、回退到直连出口,所以配置了 VIDCRAWL_PROXY_URL 时VidCrawl会在运行时检查Bun,避免流量意外直漏。
在一段18分22秒的YouTube样本(WWDC 2025 Impressions: Liquid Glass!,1E3tv_3D95g)上,第一层产出26 KB Markdown(465条转写片段、9个章节),外加5张分镜图共237 KB(112个切片,每10秒采样一次)。智能体可以在请求任何一张全分辨率帧之前,先读完整个演讲、扫完每一次视觉转场。
第二个坑:为了两张截图下载几百MB的MP4
当分镜网格里出现看不清的14px IDE缓冲区、图表坐标轴或设置界面时,智能体调用 POST /v1/frames,带上 timestamps_sec(1到20个时间戳)和 max_width(320px到1920px)。为了不为了两张截图去下载几百MB的MP4,引擎会把 /player 里最好的MP4 DASH流缓存15分钟,优先720p(compareFrameStreams 按短边打分,避免竖屏720x1280的Shorts卡在巨大的1080x1920分片上),同时缓存 initRange 和 indexRange。
随后做精确的字节区间切片:先取容器头(0..indexRange.end,上限 MAX_HEADER_BYTES = 2 MB),用TypeScript解析ISO-BMFF的 sidx(Segment Index Box,0x73696478),校验version 0和version 1的引用条目,按 timescale 累加时间戳直到 targetSec 落进 [startSec, endSec);然后只取 initRange 加那一个5秒GOP片段 [byteStart, byteEnd](上限 MAX_MEDIA_BYTES = 16 MB),每一跳都强制 redirect: "manual",确保重定向永远出不了 googlevideo.com,并复用 /player 用过的那个 stickyProxyUrl;最后在内存里用 ffmpeg 和 sharp 解码,把 [initBuf, segBuf] 拼接后送进 ffmpeg(select=gte(n,${targetFrameIdx}) -frames:v 1),按 max_width 缩放,编码成JPEG(quality: 88)。
如果流头或 sidx 片段拿不到,/v1/frames 会显式回退到 storyboard_crop:用 sharp 从分镜JPEG里裁出最接近的那块,并把来源字段标成 "storyboard_crop" 而不是 "ffmpeg_seek"。
短视频是另一套麻烦
TikTok、Instagram Reels、X 这类短视频不暴露YouTube式的 sidx 字节区间,也没有静态的 i.ytimg.com 分镜图,关键文字经常是烧进画面的字幕而不是口播。TikTok走两级流水线:第一级零 yt-dlp,抓页面HTML解析 webapp.video-detail.itemInfo.itemStruct,有 subtitleInfos 就直接取原生ASR的WebVTT轨道;第二级用最低码率的H.264加直连优先回退,构建3x3联系表(960x1704,每格320x568,经ffmpeg)或跑Whisper ASR时选最低码率的 h264/avc 流而不是 bytevc1(TikTok上它经常丢音频),下载先走服务器IP直连,只有CDN返回HTTP 403时才回退住宅代理——生产出口下约17%的TikTok片段会碰到这种情况。Instagram Reels 和 X 帖子走同一条有界流水线(50 MB / 600s),返回完全相同的JSON结构。
300条URL的实测
可靠性不靠猜。VidCrawl 从Hetzner出口跑了一套确定性的300条URL评测(每个平台集60条公开URL,并发3,总耗时16.9分钟)。失败模式都显式且未截断:YouTube上2条 VIDEO_UNAVAILABLE、1条回退到 storyboard_crop;Shorts上1条抓取 UPSTREAM_TIMEOUT、3条取帧 UPSTREAM_TIMEOUT;TikTok上3条回退到 storyboard_crop。模型完成前失败的请求,一律自动不计费。
接入方式有两种:远程HTTP MCP,或在本地跑 npx -y @vidcrawl/mcp。MCP服务器暴露五个工具,对应渐进披露的工作流——vidcrawl_scrape(1积分,元数据、章节、转写、分镜图、Markdown)、vidcrawl_frames(1积分,最多20张精确时间戳的JPEG)、vidcrawl_search(1积分,每抓一条结果加1)、vidcrawl_agent(3/5/10积分,跨1到10个URL做有界视觉加口播综合,带[MM:SS]引用)、vidcrawl_account(0积分,查余额和端点价格)。
计费按调用而不是按时长:每次 /v1/scrape、/v1/frames、/v1/search 都是1积分,不管片段是15秒还是2小时;/v1/agent 按投入程度收3、5或10积分。新账户送100免费积分、无需绑卡,一次性积分包从 $9 / 1,000积分 和 $29 / 4,000积分 起,积分不过期。
热门跟贴