跳到主要内容

批量上传并创建任务（超量自动拆分）

POST /api/openapi/uploadAndCreateTasks

功能说明​

  • 与一键上传并创建任务流程一致，但不限制单次上传总量
  • 数据量超过单任务拆分条数时，系统自动拆成多个任务，一次返回全部任务 ID
  • 每个任务独立计费、独立处理，可分别查询状态和下载结果

请求参数​

参数位置类型必填说明
fileform-dataFile是仅 .txt，≤ 1 GB
taskTypeform-dataString是业务类型，见任务类型列表
descriptionform-dataString是任务描述（通常为原始文件名）
countryCodeform-dataString是国家代码（如：US）
countryAreaCodeform-dataString手机号类必填区域代码（如：1）。邮箱/用户名类任务可不传；skipCountryFilter=true 时可不传
skipDedupform-dataBoolean否是否跳过去重，默认 false。仅白名单任务类型支持
skipCountryFilterform-dataBoolean否是否跳过国家/区号过滤，默认 false。仅白名单任务类型支持
countryAreaCode 说明

手机号类任务必须传入 countryAreaCode，缺失将直接返回错误「手机号类任务必须传入countryAreaCode（国家区号）」，不会创建任务。

邮箱类任务（email 及所有以 Email 结尾的类型）和 TG 用户名筛活跃（usernameActive）无需传入该参数。传了 skipCountryFilter=true 的请求也无需传入该参数。

skipDedup / skipCountryFilter

两个参数的含义、白名单限制与计费影响与一键上传并创建任务完全一致。 skipDedup=true 时，totalCount 与各分片任务的计费条数均包含重复号码；分片切割按文件顺序进行，重复号码可能落在不同任务中。

拆分规则​

  • 单任务拆分条数由平台与任务类型决定（一般为 100 万，部分渠道为 50 万），并且不超过产品配置的单任务最大条数
  • 有效数据按拆分条数切片，每片创建一个任务；例如拆分条数 100 万、上传 1000 万条有效数据，将创建 10 个任务
  • 末尾余量若不足产品最小条数，系统自动将其与前一分片合并后均分（前一个任务少一些、最后一个任务多一些），保证所有数据都被处理；例如拆分条数 100 万、余量 200 条时，最后两个任务各约 50 万条
  • 仅在极端产品配置下均分也无法满足最小条数时，末尾余量才会被舍弃，条数计入返回字段 discardedCount（不扣费）；正常情况下该字段恒为 0
  • 余额校验按全部有效数据总费用进行，余额不足时不会创建任何任务

返回示例​

{
    "code": 200,
    "msg": "文件上传并创建任务成功",
    "data": {
        "taskIds": [
            "TASK-20250120110901-1001",
            "TASK-20250120110902-1002",
            "TASK-20250120110903-1003"
        ],
        "taskCount": 3,
        "totalCount": 2500000,
        "splitSize": 1000000,
        "discardedCount": 0
    }
}

返回说明：

字段类型说明
taskIdsString[]本次创建的全部任务 ID
taskCountInteger创建的任务数量
totalCountInteger有效数据总条数（默认去重、过滤后；skipDedup=true 时含重复项）
splitSizeInteger单任务拆分条数上限
discardedCountInteger被舍弃的条数（正常恒为 0，仅极端配置下末尾余量无法重排时产生，不扣费）

错误返回示例​

{
    "code": 500,
    "msg": "余额不足，需要: 2500.00，当前余额: 1000.00，差额: 1500.00"
}
部分失败说明

若拆分过程中途失败（如个别分片文件创建失败），已创建的任务不会回滚（已扣费并进入处理队列），错误信息中会附带已成功创建的任务 ID，请据此对账：

{
    "code": 500,
    "msg": "拆分文件创建失败，已成功创建的任务ID：TASK-20250120110901-1001,TASK-20250120110902-1002"
}

与一键接口的选择​

场景建议接口
数据量不超过单任务上限一键上传并创建任务（返回单个任务 ID，解析更简单）
数据量可能超过单任务上限本接口（自动拆分，返回任务 ID 数组）

调用示例（Python）​

import requests
import hmac
import hashlib
import base64
import time

# 1. 生成签名
timestamp = str(int(time.time() * 1000))
data = f"{account}:{timestamp}"
signature = base64.b64encode(
    hmac.new(api_key.encode(), data.encode(), hashlib.sha256).digest()
).decode()
header_key = f"{timestamp}.{signature}"

# 2. 发送请求
files = {'file': open('data.txt', 'rb')}
data = {
    'taskType': 'wsExist',
    'description': 'data.txt',
    'countryCode': 'US',
    'countryAreaCode': '1'
}
headers = {
    'X-Api-Account': account,
    'X-Api-Key': header_key
}

response = requests.post(
    'https://api.ts-filter.com/api/openapi/uploadAndCreateTasks',
    files=files,
    data=data,
    headers=headers
)

# 3. 获取全部任务ID
result = response.json()
task_ids = result['data']['taskIds']
print(f"共创建 {result['data']['taskCount']} 个任务: {task_ids}")