PerimeterX（HUMAN）解決 API：_px3 Cookie を REST で取得

SolveHub API で PerimeterX / HUMAN のボット対策を解決：アプリ ID、対象サイト、プロキシ、ブラウザー Cookie。送信フィールドと返却 Cookie の使い方。

許可された QA 自動化とブラウザー連携向けです。テスト権限のあるサイトと業務フローでのみ使用してください。

ページ URL websiteURL、PerimeterX のアプリケーション ID websiteKey（pxAppId）、および HTTP プロキシが必須です。useragent は任意です。ページ上に表示される UUID や訪問者 ID をアプリケーション ID の代わりに使用しないでください。

リクエストフィールド

外側の type と task は必須です。以下の task.* パスはすべて task オブジェクト内にあります。フィールド名は大文字と小文字が区別されます。長さの制限は UTF-8 のバイト数で計算されます。

フィールド	型	必須	制限	説明
`type`	文字列	はい	`perimeterx` 固定	プラットフォームのタスクタイプ。
`task`	JSON オブジェクト	はい	≤ 7 MiB	このタイプのタスクパラメータ。
`task.type`	文字列	いいえ	指定する場合は `perimeterx` であること	旧リクエスト形式との互換用。新規導入では省略できます。
`task.websiteURL`	HTTP(S) URL	はい	≤ 2048 バイト	解決対象ページの完全な URL。アカウント名やパスワードは含めません。
`task.websiteKey`	文字列	はい	≤ 256 バイト	PerimeterX のアプリケーション ID、すなわち `pxAppId`。訪問者の UUID/vid では代用できません。
`task.useragent`	文字列	いいえ	≤ 512 バイト	カスタムのブラウザ User-Agent。後続のリクエストでは、実際に返された `solution.useragent` を優先して使用してください。
`task.proxyType`	文字列	はい	`http` のみ	プロキシプロトコル。指定する場合は `http` である必要があります。
`task.proxyAddress`	文字列	はい	≤ 256 バイト	プロキシの IP またはホスト名。`proxyPort` と同時に指定する必要があります。
`task.proxyPort`	文字列	はい	1–5 バイト、数値 1–65535	プロキシのポート。引用符で囲んだ数字の文字列である必要があります。
`task.proxyLogin`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合にユーザー名を指定します。アドレスとポートを指定せずに単独で指定することはできません。
`task.proxyPassword`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合にパスワードを指定します。アドレスとポートを指定せずに単独で指定することはできません。

作成リクエストの例

{
  "type": "perimeterx",
  "task": {
    "websiteURL": "https://example.com/protected",
    "websiteKey": "PX_EXAMPLE_APP_ID",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}

cURL での呼び出し

例に含まれるキー、サイト情報、プロキシを実際の値に置き換えてください。Idempotency-Key は同一の業務リクエストに対して変更しないでください。

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-perimeterx-0001' \
  --data-binary @- <<'JSON'
{
  "type": "perimeterx",
  "task": {
    "websiteURL": "https://example.com/protected",
    "websiteKey": "PX_EXAMPLE_APP_ID",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}
JSON

作成レスポンスと照会

作成に成功すると HTTP 202 が返され、status の初期値は通常 queued です。taskId を保存し、約 2–3 秒ごとに GET /v1/tasks/{taskId} を呼び出して照会します。このタイプの処理のソフトタイムリミットは 210 秒 です。ソフトタイムリミットを超えると uncertain になる場合があります。受理済みタスクの結果は引き続き確認できるため、クライアントは新しい冪等キーで安易に再作成しないでください。

結果フィールド

solution は status=completed の場合にのみ読み取ってください。下表はよく使われるフィールドを示しています。実際のフィールドは該当タスクのレスポンスを正とします。

フィールド	型	読み取り方法
`solution.cookies`	オブジェクト	ブラウザセッションの Cookie。名前は対象ページによって決まり、`_px3`、`_pxvid`、`_pxhd` を含む場合があります。
`solution.useragent`	文字列	後続のリクエストで同じプロキシとあわせて再利用する User-Agent。
`solution.value`	文字列、任意	空文字列が返される結果もあるため、Cookie の代わりに成功の判定に使うことはできません。

結果は主に solution.cookies と solution.useragent です。Cookie の名前は対象サイトの設定によって変わり、_px3、_pxvid を含む場合があります。結果イメージ：{"cookies":{"_px3":"EXAMPLE_COOKIE"},"useragent":"Mozilla/5.0 ..."}。後続のリクエストでは、解決時のプロキシと返された User-Agent を再利用してください。

完了レスポンスの例（プラットフォームのフィールドと結果は分かれています。価格と時刻はイメージです）：

{
  "taskId": "00000000-0000-4000-8000-000000000001",
  "type": "perimeterx",
  "status": "completed",
  "priceMicros": 1000,
  "traceId": "00000000-0000-4000-8000-000000000002",
  "solution": {
    "value": "",
    "cookies": {
      "_px3": "EXAMPLE_COOKIE",
      "_pxvid": "EXAMPLE_VISITOR"
    },
    "useragent": "Mozilla/5.0 ..."
  },
  "createdAt": "2026-10-05T00:00:00Z",
  "finishedAt": "2026-10-05T00:00:30Z"
}

Python での作成と照会

この例では requests を使用します。プレースホルダーのサイト、プロキシ、環境変数を実際の値に置き換えてください。作成リクエストでネットワーク例外が発生した場合は、同じ冪等キーと同じリクエストボディで再試行し、キーを変更しないでください。タスクが uncertain になった場合は、taskId を保持して照会を続けるか、サポートに連絡してください。

import os
import time
import requests

base = os.environ["SOLVEHUB_URL"].rstrip("/")
headers = {
    "Authorization": f"Bearer {os.environ['SOLVEHUB_API_KEY']}",
    "Idempotency-Key": "your-business-request-perimeterx-001",
}
payload = {
    "type": "perimeterx",
    "task": {
        "websiteURL": "https://example.com/protected",
        "websiteKey": "PX_EXAMPLE_APP_ID",
        "proxyType": "http",
        "proxyAddress": "203.0.113.10",
        "proxyPort": "8080",
    },
}
response = requests.post(f"{base}/v1/tasks", headers=headers, json=payload, timeout=20)
response.raise_for_status()
task_id = response.json()["taskId"]

deadline = time.monotonic() + 15 * 60
while time.monotonic() < deadline:
    response = requests.get(f"{base}/v1/tasks/{task_id}", headers=headers, timeout=20)
    response.raise_for_status()
    task = response.json()
    if task["status"] == "completed":
        solution = task["solution"]
        print(solution.get("cookies", {}), solution.get("useragent"))
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("errorCode", task["status"]))
    if task["status"] == "uncertain":
        print("タスクは確認待ち（uncertain）です：", task_id)
        break
    time.sleep(3)
else:
    print("ローカルのポーリング期限に達しました。後ほど元のタスクを引き続き照会してください：", task_id)

失敗とトラブルシューティング

websiteKey はアプリケーション ID pxAppId である必要があります。訪問者の UUID/vid を送信しないでください。proxyPort は文字列です。後続のアクセスでは、同じプロキシ、完全な Cookie セット、solution.useragent を再利用してください。

作成リクエストでよくあるエラーは 400 INVALID_TASK、402 INSUFFICIENT_BALANCE、429 TASK_LIMIT_EXCEEDED、503 TYPE_UNAVAILABLE です。作成済みタスクが失敗した場合の公開エラーコードは TASK_FAILED または TASK_TIMEOUT で、uncertain には TASK_UNCERTAIN が対応します。詳細はプラットフォーム API リファレンスを参照してください。

よくある質問

websiteKey には何を指定しますか？ 対象サイトの PerimeterX アプリケーション ID pxAppId を指定します。ページの訪問者 UUID や vid では代用できません。
プロキシは省略できますか？ このタイプでは省略できません。proxyType は http 固定で、proxyAddress と文字列の proxyPort を同時に指定する必要があります。proxyLogin、proxyPassword は、プロキシに認証が必要な場合にのみ指定します。
SOCKS5 プロキシを使いたい場合は？ このタイプは HTTP プロキシのみ対応です。socks5 が必要な場合は perimeterx_cookies タイプを使用してください（現在デフォルトで無効。GET /v1/prices で確認してください）。
返された Cookie が使えないのはなぜですか？ まず、送信した対象ページ、アプリケーション ID が現在のものであること、および Cookie セットが完全であることを確認してください。後続のリクエストでは、解決時のプロキシの送信元と返された solution.useragent を再利用してください。Cookie の名前は対象ページの設定によって決まるため、_px3 だけに依存しないでください。

処理時間はタスク作成の受理確認後に起算し、待ち行列の時間は差し引きません。ノードの現在のタイムアウトは約180秒、プラットフォームのソフト期限は通信と結果確認を含め210秒です。

対応 User-Agent