查询放大结果接口与批量轮询的写法

接口形态

查询用 GET /api/task/{任务ID}，任务 ID 可以逗号分隔一次查多个——官方示例直接展示了这个形态：

curl <接口地址>/api/task/tid1,tid2,tid3,tid100 \
  -H 'X-API-KEY: 你的密钥'

import requests

r = requests.get(
    url=f"{root}/api/task/tid1,tid2,tid3,tid100",
    headers={"X-API-KEY": "你的密钥"})

（root 为接口根地址，从用户中心 API 页复制。）

批量查询是内置能力

一次 GET 带一串 ID，返回对应多条任务的状态——这对批量场景非常友好：提交时记下所有任务 ID，之后一个循环每轮一个请求查完全部，而不是每张图一个请求，限流压力小得多。

返回里看什么

每条任务返回里关注三个字段语义：

拿到结果地址后直接下载落盘，别把结果地址当永久链接存库——上传图有 24/72 小时保存期，结果地址同样有生命周期，见图片保存期。

轮询节奏建议

• 起查间隔 30~60 秒——处理本身要几分钟到几十分钟（见排队时长），秒级轮询纯浪费；
• 指数退避——前几轮 30 秒，几轮后拉长到 2~5 分钟；
• 失败任务别无限轮询——确认失败态后走重试接口，见失败任务的 API 重试；
• 收敛条件——全部任务到达「已完成」或「失败」终态即退出循环。

最小轮询骨架

import time

ids = "tid1,tid2,tid3"          # 你创建任务时记下的 ID
while True:
    r = requests.get(f"{root}/api/task/{ids}",
                     headers=HEADERS)
    tasks = r.json()
    if all(t.get("status") in ("finished", "failed")
           for t in tasks):     # 字段名以实际返回为准
        break
    time.sleep(60)

字段名以你实际拿到的返回体为准，先打一次日志看清结构再写死解析。

相关阅读：创建任务的参数说明、Python 全流程示例。