# リクエストとレスポンス

> YesCaptcha API の共通ルール。POST JSON、clientKey による認証、errorId のレスポンス形式、同期・非同期タスク、5 秒ごとのポーリング、110 秒のタイムアウト、結果の保持期間（約 10 分）、Accept-Language によるメッセージ言語。

Source: https://docs.yescaptcha.com/ja/api/overview/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/overview/

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

## リクエスト

```bash
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`（中国）。詳しくは[エンドポイント](https://docs.yescaptcha.com/ja/getting-started/endpoints.md)を参照してください。
-   リクエストボディは JSON で、`Content-Type: application/json` ヘッダーを付け、6 MB 以内にします。JSON にコメントは書けません。
-   すべてのリクエストに `clientKey` を含めます。ダッシュボードに表示される値をそのまま全体コピーしてください。

> **注意:** Python の requests では `json=data` を使い、`data=data` は使わないでください。後者はフォームとして送信されるため、`ERROR_TASK_ABSENT` または `ERROR_REQUIRED_FIELDS` が返ります。

## レスポンス

成功：

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

失敗：

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

| フィールド | 説明 |
| --- | --- |
| `errorId` | 0 は成功、1 は失敗 |
| `errorCode` | 失敗時のエラーコード。意味と対処法は[エラーコード](https://docs.yescaptcha.com/ja/api/errors.md)を参照 |
| `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 秒ごとに呼び出す | 追加の問い合わせは不要 |

各タイプがどちらに該当するかは、[タスクタイプと料金](https://docs.yescaptcha.com/ja/tasks.md)の「返却方式」列で確認できます。

## ポーリング

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

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

## メッセージの言語

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

## 次のステップ

-   [createTask でタスクを作成](https://docs.yescaptcha.com/ja/api/create-task.md)
-   [getTaskResult で結果を取得](https://docs.yescaptcha.com/ja/api/get-task-result.md)
-   [同時実行数の上限と自動一時停止](https://docs.yescaptcha.com/ja/api/rate-limits.md)：エラーが多すぎると数分間一時停止されます