图片端点是六个端点里最贵的:每次成功请求 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 API="https://api.serpbase.dev/google/image/search"KEY="你的 API Key"defimage_search(q:str,page:int=1)->list:resp=requests.post(API,headers={"X-API-Key":KEY,"Content-Type":"application/json"},json={"q":q,"hl":"zh-CN","gl":"cn","page":page},timeout=30)data=resp.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="",encoding="utf-8-sig")asf:w=csv.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在你这个行业的填充率,再决定展示层怎么写。
