谷歌图片搜索 API:字段口径、外链防盗链与成本纪律

图片端点是六个端点里最贵的:每次成功请求 2 credits,是搜索端点的两倍;它的返回结构也最容易踩坑——你以为有title,它经常没有;你以为数组一定在,它可能整个缺席。这篇把字段口径、请求路径和成本纪律一次讲清,给一个能直接跑的采集脚本。先说两个最容易栽的点:端点路径是/google/image/search(单数 image),不是直觉上的 images;以及结果里只有rank、link、image_url三个字段是必填,其余全是可选,口径见 SerpBase 官方文档的图片端点字段表。字段口径每次成功请求 2 credits,失败自动退款(credits_charged为 0)。入参四个:q必填,hl/gl/page可选(默认 en/us/1)。返回顶层images数组是可选的——当解析到图片结果时才有,零结果时可能整个键都不存在。字段必要性文档原话rank必填“本响应内 1 起算位次”link必填“解析器返回的主链接”image_url必填“完整图片 URL”title可选“当解析到图片标题或 alt 文本时”position可选“rank 的别名,可用时”url / display_url / source_url可选视归一化与重定向情况thumbnail_url / thumbnail可选“当 Google 暴露缩略图时”source / domain可选“当解析到来源文本/域名时”文档还明确提醒:“部分 Google Images 载荷形态只暴露 rank/link,不暴露每个归一化别名”——所以解析器一律.get()兜底,别裸取。脚本importcsv,requests APIhttps://api.serpbase.dev/google/image/searchKEY你的 API Keydefimage_search(q:str,page:int1)-list:resprequests.post(API,headers{X-API-Key:KEY,Content-Type:application/json},json{q:q,hl:zh-CN,gl:cn,page:page},timeout30)dataresp.json()ifdata.get(status)!0:raiseRuntimeError(f{data.get(status)}:{data.get(error)})returndata.get(images,[])# 数组本身是可选的rows[]forkwin[机械键盘 产品图,静音键盘 白色]:foriteminimage_search(kw)[:10]:rows.append({关键词:kw,位次:item[rank],图片URL:item[image_url],标题:item.get(title,),# 可能为空来源:item.get(source,),域名:item.get(domain,),})withopen(images.csv,w,newline,encodingutf-8-sig)asf:wcsv.DictWriter(f,fieldnames[关键词,位次,图片URL,标题,来源,域名])w.writeheader()w.writerows(rows)print(f共{len(rows)}条 → images.csv)三条实践纪律先判 status 再碰 images。零结果查询可能返回status: 0且根本没有images键;用data.get(images, []),别写data[images]——那是线上脚本最常见的 KeyError。外链防盗链要当回事。image_url是第三方站点上的图片地址,直接img src热链到你自己页面,对方换域名、加 referer 校验或下架,你的页面就是一片碎图。稳妥做法是下载到自己存储再引用,并保留来源字段备查;商用前确认对方站点的使用条款。2 credits 一次,重复查询是最大的浪费。同一个 (q, hl, gl, page) 的结果短期内稳定,采集前先按这个四元组去重;缓存到本地磁盘,第二次访问零成本。20 个关键词一轮就是 40 credits,重复跑三遍就够吃掉免费额度的一半。成本账每关键词每次请求 2 credits:10 个关键词一轮 20 credits,100 次免费额度够跑五轮——但带着缓存跑,实际只会用掉 10 credits,剩下的是留给调试的。标准包按 $10/20k($0.50/1k)算,一次成功请求合一美分,监控类需求一天两轮也就几毛钱。FAQ为什么我的 title 全是空的?它本来就可选——大量真实页面没有 alt 文本,解析器无从填充。展示逻辑要能在无标题时正常工作,别把它当主字段用。link 和 image_url 哪个能直接放进 img 标签?image_url是完整图片地址,放 src 用它;link是解析器的主结果链接,可能是来源页面而不是图片文件本身。两者都建议先 HEAD 一下确认可达再落库。有 device 参数吗?没有。device 只属于搜索端点;图片端点入参就是 q/hl/gl/page 四个。返回的图片有版权风险吗?接口只返回公开可索引的结果,不改变图片本身的版权状态。批量商用前走自己的合规审查,保留来源域名字段就是为这个准备的。把脚本里的关键词换成你的监测对象,先跑一轮看title/source在你这个行业的填充率,再决定展示层怎么写。