Google 以图搜图 SERP 已完成任务列表

GET /v3/serp/google/search_by_image/tasks_ready

接口说明

GET /v3/serp/google/search_by_image/tasks_ready

本接口用于获取已完成但尚未领取的 Google 以图搜图 SERP 任务列表。

当您使用标准任务提交方式且未设置 postback_url 时，可以通过本接口获取已完成任务的 id，再调用对应的任务结果获取接口领取结果。

> 本接口返回任务标识及结果领取地址，不直接返回 SERP 结果数据。

使用限制

获取已完成任务列表不会产生费用。
每个任务会持续保留在列表中，直到被成功领取。
每分钟最多调用 20 次。
每次调用最多返回过去 3 天完成的 1000 个任务。
已经领取的任务不会再次出现在列表中。
完成后 3 天仍未领取的任务将从列表中移除。
如果任务设置了 postback_url，正常不会出现在本接口返回结果中。
只有当回调请求失败，且您的服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在领取列表中。
如果系统每分钟需要收集 1000 个任务，建议优使用回调通知机制；本接口适合用于补偿查询回调失败的任务。

由于系统架构原因，已完成任务队列可能存在短暂更新延迟。高并发场景下请勿依赖本接口进行实时任务收集。

请求

请求头

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求示例

cURL

bash

curl --location --request GET \
  "https://api.seermartech.cn/v3/serp/google/search_by_image/tasks_ready" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

Python

python

import requests

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

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

response = requests.get(url, headers=headers)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

async function getReadyTasks() {
  try {
    const response = await axios.get(
      "https://api.seermartech.cn/v3/serp/google/search_by_image/tasks_ready",
      {
        headers: {
          Authorization: "Bearer smt_live_YOUR_KEY",
          "Content-Type": "application/json",
        },
      }
    );

    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
    } else {
      console.error(
        `请求失败，错误码：${result.status_code}，错误信息：${result.status_message}`
      );
    }
  } catch (error) {
    console.error("网络请求失败：", error);
  }
}

getReadyTasks();

响应

接口返回 JSON 数据 tasks 数组已完成任务的信息。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	请求级状态码。完整错误码请参考错误码文档
`status_message`	string	请求级说明信息
`time`	string	请求执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量
`tasks`	array	已完成任务列表

`tasks` 数组字段

字段	类型	说明
`id`	string	已完成任务的唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态说明
`time`	string	任务执行耗时，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量
`path`	array	任务请求路径
`data`	object	创建任务时传的请求参数
`result`	array	任务结果信息数组

`result` 数组字段

字段	类型	说明
`id`	string	已完成任务的唯一标识，UUID 格式
`se`	string	创建任务时指定的搜索引擎，例如 `google`
`se_type`	string	搜索引擎类型。本接口返回 `search_by_image`
`date_posted`	string	任务提交时间，UTC 格式
`tag`	string	用户自定义任务标识
`endpoint_regular`	string / null	获取 SERP 标准结果的接口地址。如果当前端点不支持标准结果，则为 `null`
`endpoint_advanced`	string / null	获取 SERP 高级结果的接口地址。如果当前端点不支持高级结果，则为 `null`
`endpoint_html`	string / null	获取 SERP HTML 结果的接口地址。如果当前端点不支持 HTML 结果，则为 `null`

响应示例

json

{
  "version": "0.1.20200923",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2642 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": " ಸೆ123e4567-e89b-12d3-a456-426614174000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.234 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "google",
        "search_by_image",
        "tasks_ready"
      ],
      "data": {
        "api": "serp",
        "function": "tasks_ready",
        "se": "google",
        "se_type": "search_by_image"
      },
      "result": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "se": "google",
          "se_type": "search_by_image",
          "date_posted": "2024-01-15 08:30:00 +00:00",
          "tag": "image-search-batch-001",
          "endpoint_regular": "/v3/serp/google/search_by_image/task_get/123e4567-e89b-12d3-a456-426614174000",
          "endpoint_advanced": "/v3/serp/google/search_by_image/task_get/123e4567-e89b-12d3-a456-426614174000",
          "endpoint_html": null
        }
      ]
    }
  ]
}

> 示例中的任务标识和时间供说明使用，响应以本平台返回为准。

状态码与计费

status_code = 20000 表示请求成功。
顶层 status_code 表示本次接口请求的处理结果。
tasks[].status_code 表示单个任务的处理结果。
状态码和错误信息请参考错误码文档。
本接口不收取任务列表查询费用。
任务结果获取接口是否产生费用，以对应接口说明及响应头 X-SeerMarTech-Charge-CNY 为准。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

实用场景

轮询已完成任务：定时获取已完成的以图搜图任务 ID，并批量领取结果，降低任务处理链路的复杂度。
补偿失败回调任务：筛选未成功发送到业务服务器的任务，因回调失败造成 SERP 数据遗漏。
构建批量图片分析流程：在批量提交图片搜索任务后，集中获取已完成任务并后续识别、分类或分析流程。
监控任务处理状态：根据 tasks_count、tasks_error 和任务状态码监控批次执行，及时发现异常任务。
业务批次：利用 tag 将完成任务与图片素材、客户项目或 SEO 监测批次，便于结果归档和追踪。

Google 以图搜图 SERP 已完成任务列表 ​

接口说明 ​

使用限制 ​

请求 ​

请求头 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

响应示例 ​

状态码与计费 ​

实用场景 ​