获取已完成的以图搜图 SERP 任务列表

接口说明

Tasks Ready 接口用于获取已经执行完成但尚未被获取结果的任务列表。

如果你使用标准提交方式且未设置 postback_url，可以通过本接口获取所有已完成任务的 id，再使用对应的 Task GET 接口获取结果。

该接口适合以下场景：

• 轮询获取最近完成的任务 ID
• 在未启用回调时补齐结果采集流程
• 排查回调失败后未成功投递的任务

注意： 由于平台 API 的队列刷新存在轻微延迟，高并发场景下可能出现短暂不同步。 如果你的系统需要每分钟采集 1000 个任务，建议优使用 pingback/postback 回调机制，本接口更适合用于补拉回调失败任务的 ID。

请求信息

请求方式： GET接口路径： /v3/serp/google/search_by_image/tasks_ready

完整请求地址

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

计费与调用限制

• 拉取已完成任务列表不收费
• 每个未被拉取的任务会一直保留在列表中，直到结果被成功采集
• 每分钟最多可调用 20 次
• 每次最多返回近 3 天完成的 1000 个任务
• 以下任务不会出现在列表中：
• 已经被拉取过结果的任务
• 完成后 3 天仍未采集的任务

postback_url

如果创建任务时指定了 postback_url，该任务通常不会出现在已完成任务列表中。

只有在向你的服务器推送回调时失败，该任务才可能出现在列表中，例如：

• 你的服务器请求处理失败
• 返回的 HTTP 状态码 小于 200 或 大于 300

响应结构

接口返回 JSON 数据，顶层 tasks 数组，用于描述本次返回的任务集合。

顶层字段说明

字段	类型	说明
version	string	当前 API 版本
status_code	integer	接口总体状态码，可参考 /v3/appendix/errors
status_message	string	接口总体状态信息，可参考 /v3/appendix/errors
time	string	接口执行时间，单位秒
cost	float	本次请求总成本，USD；本接口通常为 0，扣费以响应头 X-SeerMarTech-Charge-CNY 为准
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务数组

tasks[] 字段说明

字段	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，可参考 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行时间，单位秒
cost	float	任务成本，USD；扣费以响应头 X-SeerMarTech-Charge-CNY 为准
result_count	integer	result 数组中的数量
path	array	当前接口路径
data	object	请求 URL 中传的参数
result	array	已完成任务列表

tasks[].result[] 字段说明

字段	类型	说明
id	string	已完成任务的任务 ID，UUID 格式
se	string	创建任务时指定的搜索引擎
se_type	string	搜索引擎类型；此接口固定为 search_by_image
date_posted	string	任务提交时间，UTC 格式
tag	string	用户自定义任务标识
endpoint_regular	string	获取 SERP Regular 结果的 URL；若该类型不支持则为 null
endpoint_advanced	string	获取 SERP Advanced 结果的 URL；若该类型不支持则为 null
endpoint_html	string	获取 SERP HTML 结果的 URL；若该类型不支持则为 null

调用示例

cURL

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

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)
 # 后续可根据 result 中的任务 id 调用对应 Task GET 接口
else:
 print(f"error. Code: {result.get('status_code')} Message: {result.get('status_message')}")

TypeScript

import axios from "axios";

// 获取已完成但尚未获取结果的任务列表
axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/serp/google/search_by_image/tasks_ready",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
}).then((response) => {
 const result = response.data;
 console.log(result);
}).catch((error) => {
 console.error(error);
});

响应示例

{
 "version": "0.1.20200923",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2642 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "tasks_ready",
 "se": "google",
 "se_type": "search_by_image"
 },
 "result": []
 }
 ]
}

使用说明

型流程如下：

1. 通过任务提交接口创建以图搜图任务
2. 等任务执行完成
3. 调用 /v3/serp/google/search_by_image/tasks_ready 获取已完成任务 ID
4. 使用返回的 endpoint_regular、endpoint_advanced 或 endpoint_html，或对应 Task GET 接口获取结果

状态码与异常处理

• 建议始终检查顶层 status_code 与 status_message
• 也要逐个检查 tasks[]的 status_code
• 完整错误码定义可参考 /v3/appendix/errors

建议在生产环境中实现完善的异常处理机制：

• 接口限流处理
• 空结果重试
• 回调失败补拉 -过 3 天未采集任务的底监控

实用场景

• 轮询已完成任务：在未回调的，持续获取最新完成的以图搜图任务 ID，保证结果采集链路完整。
• 补拉回调失败结果：当业务侧 postback_url 接收异常时，通过本接口找回遗漏任务，结果丢失。
• 构建任务消费队列：将已完成任务 ID 写消息队列，再异步调用 Task GET 接口，提高大批量任务处理效率。
• 监控采集时效：结合 date_posted 判断任务从提交到完成的时间跨度，评估采集链路性能。
• 业务标签追踪任务：利用 tag 字段将已完成任务与站点、客户、项目批次对应，方便做结果归档与审计。