SeerMarTech API 文档

主题

Google 以图搜图 SERP 任务提交 ​

POST /v3/serp/google/search_by_image/task_post

接口说明 ​

POST /v3/serp/google/search_by_image/task_post

本接口用于提交 Google 以图搜图（Search By Image）SERP 任务，最多返回前 100 条搜索结果。搜索结果会根据指定的地区和语言生成。

本接口支持两种任务优级：

  • 1：普通优级，默认值
  • 2：高优级，执行速度更快，但会产生额外费用

请求限制 ​

  • 所有请求使用 UTF-8 编码的 JSON 格式。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 每次 POST 请求最多 100 个任务。 -过 100 个任务的部分将返回错误码 40006。
  • 任务提交成功后，可通过返回的任务 id 获取结果。
  • 也可以在请求中 pingback_url 或 postback_url，由本平台在任务完成后主动通知。

如果通知服务器在 10 秒未返回响应，连接将因时中断，任务会转移至任务就绪列表。

计费说明 ​

本接口按任务提交计费。高优级任务可能产生额外费用；启用 calculate_rectangles=true 时，单任务费用将乘以 2。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

###填参数

以下三种地区参数选择一：

  • location_code
  • location_name
  • location_coordinate

以下两种语言参数选择一：

  • language_code
  • language_name

同一组参数中只需提供一种，不需要同时提供。

参数类型填说明
image_urlstring是用于执行以图搜图的图片 URL。示例：https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg
location_codeinteger条件填搜索地区代码。未提供 location_name 或 location_coordinate 时填。使用此参数后，无需再提供另外两个地区参数。可通过 /v3/serp/wp/locations 获取可用地区及代码。示例：2840
language_codestring条件填搜索语言代码。未提供 language_name 时填。使用此参数后，无需再提供 language_name。可通过 /v3/serp/wp/languages 获取可用语言及代码。示例：en
pingback_urlstring否任务完成通知地址。本平台会向该地址发送 GET 请求。URL 中可以使用 $id 和 $tag 占位符，发送时会替换为任务 ID 和经过 URL 编码的标签值。特殊字符会被编码，例如 # 会编码为 %23。
postback_urlstring否任务结果回调地址。任务完成后，本平台会向该地址发送结果的 POST 请求，使用 GZIP 压缩。URL 中可以使用 $id 和 $tag 占位符。特殊字符会被 URL 编码。
postback_datastring条件填使用 postback_url 时填，用于指定回调数据类型。可选值：advanced、html。

可选参数 ​

参数类型默认值说明
priorityinteger1任务优级。1 表示普通优级，2 表示高优级。高优级任务会产生额外费用。
location_namestring—搜索地区的完整名称。未提供 location_code 或 location_coordinate 时填。示例：London,England,United Kingdom
language_namestring—搜索语言的完整名称。未提供 language_code 时填。示例：English
tagstring—用户自定义任务标识，最多 255 个字符。可用于任务与结果，提交的值会在响应的 data 对象中返回。
max_crawl_pagesinteger—要抓取的搜索结果页数，最大值为 100。该参数与 depth 参数相互补。
search_paramstring—搜索请求的附加参数。
calculate_rectanglesbooleanfalse是否计算高级结果中 SERP素的像素排名。像素排名表示结果摘要与屏幕左上角之间的距离。设置为 true 后，单任务费用将乘以 2。
browser_screen_widthinteger1920浏览器屏幕宽度。在 calculate_rectangles=true 时生效。
browser_screen_heightinteger1080浏览器屏幕高度。在 calculate_rectangles=true 时生效。
browser_screen_resolution_ratiointeger1浏览器屏幕分辨率比例。在 calculate_rectangles=true 时生效。
location_coordinatestring—搜索地区的 GPS 坐标，格式为 "纬度,经度,半径"。纬度和经度最多支持 7 位小数；半径最小值为 199.9 毫米，最大值为 199999 毫米。示例：53.476225,-2.243572,200
se_domainstring—搜索引擎域名。本平台会根据地区和语言自动选择合适的域名，也可以手动指定，例如 google.co.uk、google.com.au、google.de。

请求示例 ​

cURL ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/google/search_by_image/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"
    },
    {
      "language_name": "English",
      "location_name": "New York,New York,United States",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
      "priority": 2,
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/serp/google/search_by_image/task_post"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

payload = [
    {
        "language_code": "en",
        "location_code": 2840,
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
    },
    {
        "language_name": "English",
        "location_name": "United States",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
        "priority": 2,
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
    },
]

response = requests.post(url, headers=headers, json=payload)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

TypeScript ​

typescript
import axios from "axios";

const payload = [
  {
    language_code: "en",
    location_code: 2840,
    image_url:
      "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
  },
  {
    language_name: "English",
    location_name: "United States",
    image_url:
      "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
    priority: 2,
    tag: "some_string_123",
    pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/serp/google/search_by_image/task_post",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error.response?.data || error.message);
  });

响应结构 ​

接口返回 JSON 数据已提交任务的信息。

json
{
  "version": "0.1.20200923",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0926 sec.",
  "cost": 0.0015,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0926 sec.",
      "cost": 0.0015,
      "result_count": 0,
      "path": [
        "v3",
        "serp",
        "google",
        "search_by_image",
        "task_post"
      ],
      "data": {
        "api": "serp",
        "function": "task_post",
        "se": "google",
        "se_type": "search_by_image",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg",
        "language_name": "English",
        "location_name": "United States",
        "priority": 2,
        "device": "desktop",
        "os": "windows"
      },
      "result": null
    }
  ]
}

顶层字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger请求的通用状态码。成功通常为 20000。
status_messagestring请求的通用状态信息。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorintegertasks 数组中返回错误的任务数。
tasksarray已提交任务的详细信息。

tasks 数组字段 ​

字段类型说明
idstring任务唯一标识，采用 UUID 格式。可使用该 ID 查询任务结果。
status_codeinteger当前任务的状态码，通常处于 10000 至 60000 范围。
status_messagestring当前任务的状态信息。
timestring任务执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。提交任务时通常为 0。
patharray当前 API 请求的路径信息。
dataobject请求中提交的任务参数。
resultarray | null任务结果。提交任务接口返回时为 null，需要通过任务 ID 或回调获取后续结果。

错误处理 ​

请根据顶层和任务级别的 status_code 判断请求是否成功：

  • 顶层 status_code：表示整个批量请求的处理状态。
  • tasks[].status_code：表示单个任务的处理状态。
  • tasks_error：表示批量请求中失败的任务数量。
  • 单次请求 100 个任务时，出部分会返回错误码 40006。

实用场景 ​

  • 监测图片在 Google 以图搜图中的结果，评估品牌图片、产品图片或营销素材的搜索可见度。
  • 识别竞品图片的搜索页面，分析竞品素材被哪些网站引用以及潜在的外链来源。
  • 追踪原创图片的盗用，定期提交图片 URL 并对比搜索结果，支持版权维权和理。
  • 按不同国家和语言采集图片搜索结果，比较本地化图片差异，为 SEO 和多地区运营提供依据。
  • 计算 SERP素的像素位置，结合自定义屏幕尺寸评估图片搜索结果在不同设备上的可见程度。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API