做内容分析、视觉搜索、视频监控的时候单看文字 SERP 不够。Google Images 和 Videos 端点返回的是结构化的媒体数据。这篇文章把这两个端点怎么用、真实场景和工程细节过一遍。Images 端点/google/images的参数跟 Search 一样简洁q查询词hl语言gl国家page页码调用defimages_search(query,hlen,glus,page1,timeout10):returnrequests.post(https://api.serpbase.dev/google/images,json{q:query,hl:hl,gl:gl,page:page},headers{X-API-Key:API_KEY,Content-Type:application/json},timeouttimeout,).json()返回里images数组每条长这样{rank:1,title:...,link:https://...,image_url:https://...,thumbnail_url:https://...,source:example.com,domain:example.com,display_url:example.com}几个关键字段image_url原图 URL可能很大注意下载thumbnail_url缩略图UI 列表用source图片来源站点domain来源域名去重 / 黑白名单用Images 端点的真实场景我做过几个实际项目场景 1电商图片监控监控某品牌在 Google Images 上的曝光情况每天查一次品牌相关 query统计图片数量、来源分布、是否有未授权使用。defbrand_image_monitor(brand,queries):results{}forqinqueries:bodyimages_search(f{brand}{q})itemsbody.get(images)or[]foritinitems:domainit.get(domain)orifbrand.lower()in(it.get(title)or).lower():results.setdefault(domain,0)results[domain]1returnresults场景 2素材聚合做内容创作工具需要根据 query 聚合图片素材defcollect_assets(query,n20):bodyimages_search(query)itemsbody.get(images)or[]return[{thumb:it.get(thumbnail_url)orit.get(image_url),full:it.get(image_url),source:it.get(domain),url:it.get(link),}foritinitems[:n]ifit.get(image_url)]注意版权风险正规产品要做来源标注和授权校验。场景 3竞品视觉对比监控竞品在视觉营销上的变化每周查竞品主推产品的图片分析首图风格、文案布局、配色。Videos 端点/google/videos跟 Images 类似defvideos_search(query,hlen,glus,page1,timeout10):returnrequests.post(https://api.serpbase.dev/google/videos,json{q:query,hl:hl,gl:gl,page:page},headers{X-API-Key:API_KEY,Content-Type:application/json},timeouttimeout,).json()返回字段{rank:1,title:...,link:https://youtube.com/...,source:YouTube,duration:10:23,time:2 days ago,published_at:...,thumbnail_url:https://...,display_url:youtube.com}source区分平台YouTube / Bilibili / 抖音 / Vimeoduration是时长文本“10:23” 这种格式。Videos 端点的真实场景场景 1教程视频聚合用户问如何学 Python让模型从 Google Videos 召回教程视频deftutorial_search(topic,langzh-CN):bodyvideos_search(f{topic}tutorial 教程,hllang,glcn)itemsbody.get(videos)or[]return[{title:it.get(title),url:it.get(link),source:it.get(source),duration:it.get(duration),thumbnail:it.get(thumbnail_url),published_at:it.get(published_at),}foritinitems[:10]]场景 2品牌视频监控监控某品牌在 YouTube、Bilibili 等平台的视频提及量。场景 3竞品视频分析抓竞品新发的产品视频分析标题、时长、缩略图风格。工程细节时长解析duration是 “10:23” 或 “1:23:45” 这种格式要解析成秒数defparse_duration(text):ifnottext:returnNonepartstext.split(:)iflen(parts)2:# mm:ssreturnint(parts[0])*60int(parts[1])iflen(parts)3:# hh:mm:ssreturnint(parts[0])*3600int(parts[1])*60int(parts[2])returnNone缩略图下载UI 显示缩略图时直接用thumbnail_url别下image_url原图可能几十 MB。如果要做本地缓存缩略图建议下到 CDN 别放在业务服务器importhashlibdefcached_thumb(url):keyhashlib.md5(url.encode()).hexdigest().jpgcdn_pathf/thumbs/{key}ifnotexists(cdn_path):download_to_cdn(url,cdn_path)returncdn_path媒体类型过滤Images 返回的image_url不一定是图片可能是 .svg、.webp、甚至是 HTML 页面。下游处理时要校验 Content-TypeHEADERS{User-Agent:Mozilla/5.0}defis_valid_image(url):try:rrequests.head(url,headersHEADERS,timeout5,allow_redirectsTrue)ctr.headers.get(Content-Type,)returnct.startswith(image/)exceptrequests.RequestException:returnFalse去重Images 同一个图片可能被多个站点转载image_url不一样但内容一样。要做感知哈希pHash去重importimagehashfromPILimportImagedefphash(url):imgImage.open(download(url))returnimagehash.phash(img)# 重复检测seen_hashes{}foritinitems:hphash(it[image_url])ifhinseen_hashes:# 重复continueseen_hashes[h]itpHash 计算慢、占内存建议异步批量处理不要在主流程里同步算。让 LLM 总结视频内容Videos 端点只返回 metadata不返回视频内容本身。要让模型理解视频得额外接一个视频转写服务Whisper、YouTube 字幕等。常见的做法是分两步SERP API 召回视频 URL用 yt-dlp / youtube-transcript-api 拉字幕把字幕喂给 LLM 做总结fromyoutube_transcript_apiimportYouTubeTranscriptApidefget_video_summary(video_url):video_idextract_youtube_id(video_url)ifnotvideo_id:returnNonetry:transcriptYouTubeTranscriptApi.get_transcript(video_id,languages[zh-Hans,en])exceptException:returnNonetext .join(seg[text]forsegintranscript)returnllm_summarize(text)这一步延迟比较大10–30s生产里要异步处理不能让用户等。一些坑缩略图 URL 不稳定Google Images 的thumbnail_url经常 304 失效下游要缓存。Videos 端点的source不全部分平台没列出来按 URL 域名判断更准。时区差异published_at是 UTC转本地时区要小心。图片版权聚合出来的图片直接给用户用有版权风险正规场景要做来源标注。duration 解析YouTube 短片是 “0:30” 这种但有时候是 “30”秒解析要兼容。收尾Images 和 Videos 端点把媒体搜索这块的脏活做掉了。下面以 serpbase 的接口为例文档三个端点Search / Images / Videos外壳一致写客户端只要维护一套代码。一个完整项目视觉内容分析 Agent把 Images / Videos 端点 LLM 拼起来能做一个视觉内容分析 Agent。流程用户输入 query ↓ Images 端点召回 20 张图 ↓ LLM 分析图片用 GPT-4V / Claude 3 ↓ 聚合输出代码大概长这样importasyncioimportaiohttpasyncdeffetch_images(session,query,hl,gl):asyncwithsession.post(https://api.serpbase.dev/google/images,json{q:query,hl:hl,gl:gl,page:1},headers{X-API-Key:API_KEY,Content-Type:application/json},timeoutaiohttp.ClientTimeout(total10),)asresp:returnawaitresp.json()asyncdefvisual_analysis(query,hlzh-CN,glcn):asyncwithaiohttp.ClientSession()assession:bodyawaitfetch_images(session,query,hl,gl)itemsbody.get(images)or[]# 只取前 10 张避免超出 GPT-4V 限制thumbs[it.get(thumbnail_url)foritinitems[:10]ifit.get(thumbnail_url)]analysisawaitgpt4v_analyze(query,thumbs)return{query:query,image_count:len(items),analysis:analysis,sources:list({it.get(domain)foritinitemsifit.get(domain)}),}GPT-4V 一次性能吃 10 张缩略图分析风格、主题、配色、构图。生产里要做异步批处理不然延迟很大。一些工程经验缩略图 URL 经常失效Google 重定向缓存必须做。大批量图片召回要限流每分钟 60 张左右别把 SERP API 配额打完。视频内容分析最好有 fallback拿不到字幕就退到只分析 metadata。多语言搜索的 hl/gl 参数要根据用户地区传不要用默认值。真实工程细节异步并发控制Images 召回 LLM 分析的 pipeline 通常是 IO 密集的用 asyncio aiohttp 比较合适。但 LLM 调用延迟高5–10s需要单独的并发控制gpt_semasyncio.Semaphore(3)# LLM 调用最多 3 个并发img_semasyncio.Semaphore(5)# SERP API 最多 5 个并发asyncdefguarded_fetch(session,query):asyncwithimg_sem:returnawaitfetch_images(session,query,zh-CN,cn)asyncdefguarded_analyze(query,thumbs):asyncwithgpt_sem:returnawaitgpt4v_analyze(query,thumbs)缓存策略媒体搜索的结果变化相对慢图片不会突然换但热门 query 的结果变化快fromcachetoolsimportTTLCache img_cacheTTLCache(maxsize2000,ttl1800)# 30 分钟video_cacheTTLCache(maxsize2000,ttl1800)defcached_images_search(query,hl,gl):keyf{query}|{hl}|{gl}ifkeyinimg_cache:returnimg_cache[key]resultimages_search(query,hl,gl)img_cache[key]resultreturnresult错误重试importasyncioimportrandomasyncdefwith_retry_async(coro_factory,max_retry2):foriinrange(max_retry1):try:returnawaitcoro_factory()except(asyncio.TimeoutError,aiohttp.ClientError)ase:ifimax_retry:raiseawaitasyncio.sleep(0.5*(2**i)random.uniform(0,0.2))监控每张图召回的延迟P50、P95缩略图下载成功率Google Images 缩略图经常 304LLM 视觉分析的成功率有些图模型拒识缓存命中率把这些指标接到 Prometheus/Grafana告警阈值按历史调。收尾最后一次Images / Videos 端点让视觉内容也能被 LLM 看到。配合 GPT-4V / Claude 3能做很多以前做不了的事图片风格分析、视频内容总结、视觉品牌监控。下面以 serpbase 的接口为例文档三个端点Search / Images / Videos外壳一致写客户端只要维护一套代码。配合 LLM 视觉模型能搭出很多有意思的应用。
