soft_id 参数可让您跟踪哪个应用程序、客户端或集成生成了每个验证码解决方案。这对于管理多个客户的机构、嵌入 CaptchaAI 的软件供应商以及附属合作伙伴至关重要。
什么是软ID？
Without soft_id:
All solves tracked as one pool
No way to know which project/client generated usage
With soft_id:
Solve #1 ──▶ soft_id=PROJECT_A ──▶ Tracked separately
Solve #2 ──▶ soft_id=PROJECT_B ──▶ Tracked separately
Solve #3 ──▶ soft_id=CLIENT_123 ──▶ Tracked separately
基本用法
将 soft_id 添加到任何解决请求中：
import requests
API_KEY = "YOUR_API_KEY"
SOFT_ID = "1234" # Your registered soft_id
resp = requests.post("https://ocr.captchaai.com/in.php", data={
"key": API_KEY,
"method": "userrecaptcha",
"googlekey": "SITE_KEY",
"pageurl": "https://example.com",
"soft_id": SOFT_ID,
"json": 1,
})
适用于所有验证码类型：
# Turnstile with soft_id
resp = requests.post("https://ocr.captchaai.com/in.php", data={
"key": API_KEY,
"method": "turnstile",
"sitekey": "SITE_KEY",
"pageurl": "https://example.com",
"soft_id": SOFT_ID,
"json": 1,
})
# Image CAPTCHA with soft_id
resp = requests.post("https://ocr.captchaai.com/in.php", data={
"key": API_KEY,
"method": "base64",
"body": base64_image,
"soft_id": SOFT_ID,
"json": 1,
})
使用案例
1. 代理客户追踪
class AgencySolver:
"""Track CAPTCHA usage per client."""
def __init__(self, api_key, agency_soft_id):
self.api_key = api_key
self.soft_id = agency_soft_id
self.base = "https://ocr.captchaai.com"
def solve(self, method, client_tag=None, **params):
data = {
"key": self.api_key,
"method": method,
"soft_id": self.soft_id,
"json": 1,
}
data.update(params)
resp = requests.post(f"{self.base}/in.php", data=data)
task_id = resp.json()["request"]
# Log client attribution locally
if client_tag:
self._log_usage(client_tag, method, task_id)
return self._poll(task_id)
def _poll(self, task_id, timeout=120):
import time
start = time.time()
while time.time() - start < timeout:
time.sleep(5)
resp = requests.get(f"{self.base}/res.php", params={
"key": self.api_key, "action": "get",
"id": task_id, "json": 1,
})
data = resp.json()
if data["request"] != "CAPCHA_NOT_READY":
return data["request"]
raise TimeoutError("Solve timeout")
def _log_usage(self, client_tag, method, task_id):
import csv
import datetime
with open("client_usage.csv", "a", newline="") as f:
writer = csv.writer(f)
writer.writerow([
datetime.datetime.utcnow().isoformat(),
client_tag, method, task_id,
])
# Track usage per client
solver = AgencySolver("YOUR_API_KEY", agency_soft_id="1234")
# Client A's solves
solver.solve("userrecaptcha",
client_tag="client_acme",
googlekey="KEY", pageurl="https://acme.com",
)
# Client B's solves
solver.solve("turnstile",
client_tag="client_beta",
sitekey="KEY", pageurl="https://beta.com",
)
2. 软件供应商集成
如果您构建使用 CaptchaAI 的工具，请包含您的 soft_id，以便使用归因于您的应用程序：
class MyScraper:
"""Scraping tool with embedded CaptchaAI integration."""
SOFT_ID = "5678" # Registered when joining partner program
def __init__(self, user_api_key):
self.api_key = user_api_key
def solve_captcha(self, method, **params):
data = {
"key": self.api_key,
"method": method,
"soft_id": self.SOFT_ID, # Always include vendor ID
"json": 1,
}
data.update(params)
resp = requests.post(
"https://ocr.captchaai.com/in.php", data=data,
)
return resp.json()
3. 多项目归因
# Different soft_ids per project
PROJECTS = {
"price_monitor": "1001",
"lead_gen": "1002",
"qa_testing": "1003",
}
def solve_for_project(project_name, method, **params):
soft_id = PROJECTS.get(project_name, "0000")
data = {
"key": API_KEY,
"method": method,
"soft_id": soft_id,
"json": 1,
}
data.update(params)
return requests.post("https://ocr.captchaai.com/in.php", data=data)
本地使用跟踪
通过本地的 soft_id 跟踪求解器的使用情况以进行计费和分析：
import csv
import datetime
from collections import defaultdict
class UsageTracker:
"""Track CAPTCHA solve usage for billing and analytics."""
def __init__(self, log_file="captchaai_usage.csv"):
self.log_file = log_file
self._init_log()
def _init_log(self):
try:
with open(self.log_file, "r"):
pass
except FileNotFoundError:
with open(self.log_file, "w", newline="") as f:
writer = csv.writer(f)
writer.writerow([
"timestamp", "soft_id", "client",
"method", "task_id", "status",
])
def record(self, soft_id, client, method, task_id, status="submitted"):
with open(self.log_file, "a", newline="") as f:
writer = csv.writer(f)
writer.writerow([
datetime.datetime.utcnow().isoformat(),
soft_id, client, method, task_id, status,
])
def get_summary(self, days=30):
"""Summarize usage by client over the last N days."""
cutoff = datetime.datetime.utcnow() - datetime.timedelta(days=days)
usage = defaultdict(lambda: defaultdict(int))
with open(self.log_file, "r") as f:
reader = csv.DictReader(f)
for row in reader:
ts = datetime.datetime.fromisoformat(row["timestamp"])
if ts > cutoff:
usage[row["client"]][row["method"]] += 1
return dict(usage)
# Usage
tracker = UsageTracker()
tracker.record("1234", "client_acme", "userrecaptcha", "TASK123")
summary = tracker.get_summary(days=30)
for client, methods in summary.items():
print(f"{client}: {dict(methods)}")
故障排除
| 问题 | 原因 | 处理方式 |
|---|---|---|
| soft_id 未跟踪 | 参数名称错误 | 使用 soft_id（下划线，而不是连字符） |
| 仪表板中没有归因 | soft_id 未注册 | 通过合作伙伴计划注册您的 soft_id |
| 需要多个soft_id | 每个应用程序一个/integration | 单独注册每个应用程序 |
| 使用情况与本地日志不匹配 | 本地跟踪遗漏错误 | 记录成功和失败 |
常问问题
如何获得 soft_id？
通过CaptchaAI的合作伙伴或开发者计划注册。您将收到您的应用程序的唯一 soft_id。
soft_id 会影响求解行为吗？
不可以。soft_id 仅用于跟踪和归属。它不会改变求解速度、准确性或定价。
我可以通过一个 API 密钥使用多个 soft_id 吗？
是的。每个请求可以包含不同的 soft_id。不同的项目或客户使用不同的 ID。
相关指南
跟踪您的集成使用情况 –加入CaptchaAI合作伙伴计划.
