API リファレンス

リクエストとレスポンス

このページは中国語版から機械翻訳されたもので、不正確な箇所がある可能性があります。中国語版を正としてください。

すべてのメソッドは HTTPS POST で JSON を送信し（/useragent のみ GET）、リクエストボディの clientKey で認証し、JSON を返します。errorId が 0 なら成功、1 なら失敗で errorCode が付きます。キャプチャの認識は 2 段階です。createTask でタスクを作成し、getTaskResult を 5 秒ごとに呼び出して結果を取得します。同期タイプは createTask が結果を直接返します。

リクエスト

curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'

エンドポイント：https://api.yescaptcha.com（グローバル）または https://cn.yescaptcha.com（中国）。詳しくはエンドポイントを参照してください。
リクエストボディは JSON で、Content-Type: application/json ヘッダーを付け、6 MB 以内にします。JSON にコメントは書けません。
すべてのリクエストに clientKey を含めます。ダッシュボードに表示される値をそのまま全体コピーしてください。

レスポンス

成功：

{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

失敗：

{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}

フィールド	説明
`errorId`	0 は成功、1 は失敗
`errorCode`	失敗時のエラーコード。意味と対処法はエラーコードを参照
`errorDescription`	失敗理由の説明文
`taskId`	タスク ID
`status`	`processing`（処理中）または `ready`（完了）
`solution`	認識結果。フィールドはタスクタイプによって異なります（各タスクタイプのページを参照）

結果の判定には errorId と errorCode を使い、errorDescription の文言は解析しないでください。変更される可能性があります。

同期と非同期

	非同期	同期
対象タイプ	token を返すタイプ（reCAPTCHA、hCaptcha、Turnstile、FunCaptcha）、Cloudflare チャレンジページ、`ImageToTextTask`、`ImageToTextTaskM1`	画像認識（名前が `Classification` で終わるもの）、`ImageToTextTaskOcrBase`、`ImageToTextTaskMuggle`
`createTask` の戻り値	`taskId`	`status: "ready"` と `solution`
結果の取得方法	`getTaskResult` を 5 秒ごとに呼び出す	追加の問い合わせは不要

各タイプがどちらに該当するかは、タスクタイプと料金の「返却方式」列で確認できます。

ポーリング

createTask が taskId を返したら、5 秒待ってから getTaskResult を呼び出します。
status: "processing" が返ったらさらに 5 秒待って再試行します。status: "ready" が返ったら、結果は solution に入っています。
errorId: 1 が返ったらこのタスクのポーリングを止め、errorCode に従って対処します。

同じ taskId への 5 秒以内の重複した問い合わせには、すぐに processing が返ります。間隔を短くしても結果は早くなりません。
タスクの処理時間は最長でおよそ 110 秒です（一部のタイプは 180〜220 秒）。超過すると ERROR_TASK_TIMEOUT が返り、ポイントは自動で返金されます。
結果はサーバー側で約 10 分間保持されます。その後 taskId は無効になり、問い合わせると ERROR_TASKID_INVALID が返ります。
結果の問い合わせは課金されません。課金されるのはタスク作成時のみです。

メッセージの言語

自動一時停止、無効パラメーターのキャッシュ、ポーリング停止に関するメッセージでは、errorDescription の言語がリクエストヘッダー Accept-Language に従います。zh で始まる場合は中国語、それ以外の言語は英語を返し、このヘッダーがない場合は中国語と英語の両方を返します。その他のエラーコードの説明には影響しません。

リクエストとレスポンス