コンテンツへスキップ

APIドキュメント

3つのエンドポイントと、6つの言語の完全なコード例。Capzyの高性能なソルバークラスターと60秒以内で連携できます。

クイックスタート

ステップ 1
POST /createTask

CAPTCHAのタイプとサイトのパラメーターを送信すると、すぐにtaskIdが返されます。

ステップ 2
POST /getTaskResult

statusがreadyになるまで約1秒ごとにポーリングします。トークンはsolutionオブジェクトで返されます。

ステップ 3
POST /getBalance

残りのクレジットを確認します。失敗した解決はここに自動で返金されます。

ベースURLhttps://api.capzy.ai認証はリクエスト本文のclientKeyで行います

エンドポイント

POST/createTask新しいCAPTCHA解決タスクを作成
リクエスト
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
レスポンス
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultタスクの結果をポーリング
リクエスト
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
レスポンス
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceアカウント残高を確認
リクエスト
{ "clientKey": "capzy_..." }
レスポンス
{ "errorId": 0, "balance": 9.50 }
POST/reportScore任意:V3タスクについて、Googleが検証したスコアを報告します。ダッシュボードのV3品質ビューに使われます。報告はタスクごとに1回で、解決完了から24時間以内に送信する必要があります。
リクエスト
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
レスポンス
{ "errorId": 0 }
POST/reportCorrectCaptcha任意:解決が対象サイトで「受け入れられた」ことを報告します。座標を返すタイプ(Shopeeのスライダーなど)で特に有用です。この場合、Capzyは位置を返し、ドラッグはお客様のブラウザが行います。この報告は、実環境での精度を知る唯一の手がかりです。報告はタスクごとに1回、24時間以内で、料金には影響しません。
リクエスト
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
レスポンス
{ "errorId": 0 }
POST/reportIncorrectCaptcha任意:解決が対象サイトで「拒否された」ことを報告します。/reportCorrectCaptcha と同じ実環境での精度の追跡に使われます。報告はタスクごとに1回、24時間以内で、料金には影響しません。
リクエスト
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
レスポンス
{ "errorId": 0 }

対応タスクタイプ

読み込み中…

現在有効なタスクタイプを、CAPTCHAプロバイダー別にリアルタイムで一覧表示します。料金と平均解決時間は、クラスターのテレメトリーから自動で更新されます。

タスクタイプを読み込み中…

レート制限

制限はアカウント単位で適用され、お客様が所有するすべてのAPIキーの合計で計算されます。上限を超えると、クレジットを消費せずにエラーコードが返されます。

デフォルト
同時実行30 · 30リクエスト/秒

すべての新規アカウントはここから始まります

同時実行数の拡張
同時実行300+ · 100リクエスト/秒以上

想定される利用量を添えてサポートチケットを作成してください(別料金のティアはなく、解決あたりの料金は同じです)

同時実行タスク

解決キューに同時に入れておけるタスクの数です。タスクは createTask から完了(成功、失敗、タイムアウト)するまで上限にカウントされます。

レート制限

1秒あたりに実行できる createTask 呼び出しの数です。スライディングウィンドウ方式で、アカウント単位で適用されます。レートを超えると ERROR_RATE_LIMITED が返され、クレジットは差し引かれません。

エラーコード

/createTask / /getTaskResult が返すすべてのエラーと、その対処法です。失敗した解決は自動返金され、クレジットはすぐに残高に戻ります。

認証

APIキーまたはIPに関する問題。
  • ERROR_KEY_DOES_NOT_EXIST

    APIキーが認識されませんでした。

    対処法ダッシュボード → APIキーで値を再確認してください。キーは `capzy_` で始まります。ローテーションしたキーはすぐに無効になります。

    #
  • ERROR_IP_NOT_ALLOWED

    リクエスト元のIPが、APIキーの許可リストに含まれていません。

    対処法ダッシュボード → APIキーでキーの許可リストにIPを追加するか、IPの固定が不要であれば許可リスト自体を削除してください。

    #
  • ERROR_IP_BLOCKED

    無効なリクエストを送りすぎたため、お使いのIPは一時的にブロックされています。

    対処法10分間に100件以上の無効なリクエストを送信したIPはブロックされます(段階的に厳しくなります)。無効なリクエストの原因となっている不具合を修正してから、お待ちください。ブロックはティアに応じて1分から最大24時間で自動的に解除されます。

    #

検証

不正なタスクパラメーター、またはサイトキーに対して誤ったタイプ。
  • ERROR_INVALID_PARAMS

    リクエスト本文の形式が正しくないか、必須フィールドがありません。

    対処法`clientKey` がトップレベルにあり、`task` に `type` と必須の識別子(websiteURL/websiteKey/captchaIdなど)が含まれていることを確認してください。タイプ別の必須パラメーターは「タスクタイプ」セクションを参照してください。

    #
  • ERROR_BAD_SITEKEY

    `websiteKey` が、識別可能なCAPTCHAプロバイダーのいずれにも登録されていません。

    対処法対象ページからサイトキー全体をコピーしていることを確認してください(`data-sitekey`、`sitekey:`、または `grecaptcha.render` / `hcaptcha.render` のパラメーターを探してください)。

    #
  • ERROR_TASK_NOT_SUPPORTED

    送信したタスクの `type` は、Capzyが現在対応しているCAPTCHAタイプではありません。

    対処法有効なタイプの一覧は、下の「タスクタイプ」セクションを参照してください。一覧にないCAPTCHAが必要な場合は、チケットを作成していただければ優先的に対応します。

    #
  • ERROR_WRONG_TASK_TYPE

    タスクタイプが、サイトキーの実際のプロバイダーと一致しません。

    対処法サイトキーは事前に実際のプロバイダーと照合しています。エラーレスポンスには `recommended` フィールドが含まれるので、そのタスクタイプに切り替えてください(クレジットは請求されません)。

    #
  • ERROR_PROXY_REQUIRED

    このCAPTCHAはIPに紐づいています:トークンは解決したIPに結び付けられます。

    対処法(`*TaskProxyLess` ではなく)`*Task` のバリアントに切り替え、トークンを送信するIPと一致する `proxyAddress` を渡してください。対象:Cloudflare Challenge、CaptchaFox、AWS WAF、DataDome、PerimeterX、Kasada、Akamai、Imperva。

    #
  • ERROR_NO_PROXY

    このタスクタイプにはプロキシのフィールドが必要ですが、指定されていません。

    対処法タスク本文に `proxyType`、`proxyAddress`、`proxyPort`(必要に応じて `proxyLogin`/`proxyPassword`/`userAgent`)を含めてください。

    #
  • ERROR_PROXY_CONNECT_REFUSED

    指定されたプロキシが接続を拒否しました。

    対処法プロキシの認証情報、ホストへの到達性、IPが稼働しているかを確認してください。プロバイダー側の問題を切り分けるため、まずご自身のマシンから同じプロキシを試してください。

    #

レート制限

同時実行数 / 1秒あたり / 返金率の上限。
  • ERROR_MAX_TASKS_REACHED

    アカウントのティアの同時実行タスク数の上限に達しました。

    対処法処理中のタスクが完了するのを待ってから、追加で送信してください。デフォルトのRegularティアは同時実行30件です。アップグレードはサポートにお問い合わせください。

    #
  • ERROR_RATE_LIMITED

    レート制限を超える速度で /createTask を送信しています。

    対処法速度を落として再試行してください。デフォルトのRegularティアは、スライディングウィンドウで30リクエスト/秒です。レートを超えてもクレジットは消費されません。

    #
  • ERROR_NO_SLOT_AVAILABLE

    クラスターの処理能力が一時的に飽和しています。

    対処法数秒後に再試行してください(一時的な状態です)。数分続く場合は status.capzy.ai を確認してください。

    #
  • ERROR_SYSTEM_MAINTENANCE

    Capzyは定期メンテナンス中です。

    対処法メンテナンス時間の終了後に再試行してください。事前のお知らせはステータスページに掲載します。

    #

解決結果

ソルバーが返した結果。失敗した解決は自動返金されます。
  • ERROR_TIMEOUT

    タスクがタイプ別のタイムアウト上限内に完了しませんでした。

    対処法自動返金され、請求は発生しません。タイムアウトのほとんどは一時的なものです。特定のCAPTCHAで継続的にタイムアウトする場合は、タスクのUUIDを添えてチケットを作成してください。

    #
  • ERROR_CAPTCHA_UNSOLVABLE

    ソルバーがこのチャレンジの再試行回数を使い切りました。

    対処法自動返金され、請求は発生しません。よくある原因:古いサイトキー、websiteURLが埋め込み先のドメインと一致しない、対象サイトがCAPTCHAを無効にした。

    #
  • ERROR_NULL_RESULT

    ソルバーは完了しましたが、トークンが返されませんでした。

    対処法自動返金されます。通常は、解決中に対象サイトがCAPTCHAを削除したことを示します。再試行し、解決しない場合はチケットを作成してください。

    #
  • ERROR_INTERNAL

    解決パイプライン内で予期しないエラーが発生しました。

    対処法自動返金されます。再試行してください(まれなエラーです)。短時間に繰り返し発生する場合は、タスクのUUIDを添えてチケットを作成してください。

    #
  • ERROR_ZERO_BALANCE

    アカウント残高が、タスクの費用に対して不足しています。

    対処法ダッシュボード → 請求からクレジットをチャージしてください。失敗した解決は自動返金されるため、お支払いは成功したトークンの分だけです。

    #

スコアの報告

/reportScore(V3の品質フィードバック)に固有のエラー。
  • ERROR_TASK_NOT_FOUND

    /reportScore:taskIdがお客様のアカウントに属していないか、削除されています。

    対処法スコアの報告は、お客様が所有するタスクを参照し、解決完了から24時間以内に行う必要があります。

    #
  • ERROR_TASK_NOT_READY

    /reportScore:タスクはまだ処理中か、すでに失敗しています。

    対処法スコアを付けられるのは `ready` のタスクのみです。/getTaskResult が ready を返すまで待ってから報告してください。

    #
  • ERROR_REPORT_TOO_LATE

    /reportScore:解決完了から24時間以上が経過しています。

    対処法スコアは、siteverifyを呼び出してから数分以内に報告してください。そのタイミングのデータが、V3品質ダッシュボードにとって最も有用です。

    #
06

コードプレイグラウンド

主要なすべての言語で動作する完全なサンプル。コピーしてAPIキーを貼り付け、実行するだけです。

solve.py
import requests, time

API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"

# Create task
task = requests.post(f"{API}/createTask", json={
    "clientKey": KEY,
    "task": {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": "https://example.com",
        "websiteKey": "0x4AAA..."
    }
}).json()

task_id = task["taskId"]

# Poll for result
while True:
    result = requests.post(f"{API}/getTaskResult", json={
        "clientKey": KEY,
        "taskId": task_id
    }).json()

    if result["status"] == "ready":
        token = result["solution"]["token"]
        print(f"Solved: {token[:50]}...")
        break
    elif result["status"] == "failed":
        print(f"Failed: {result.get('errorDescription')}")
        break

    time.sleep(1)
出力のプレビュー成功(200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

60秒以内に連携。

登録時に$0.10分の無料クレジット。クレジットカードは不要です。

無料のAPIキーを取得 →