> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# CAPTCHA 작업 조회 API (서버 비동기 작업) 연동 설명

> hCaptcha verification code recognition service API guide - Ace Data Cloud

본 문서는 CAPTCHA 비동기 작업 조회 인터페이스 `POST /captcha/tasks`를 소개합니다. 임의의 CAPTCHA 인터페이스(토큰 시리즈 또는 인식 시리즈)를 호출할 때 `async: true`를 전달하면, 인터페이스는 즉시 `task_id`를 반환하며, 서버는 즉시 작업을 인수받아 지속적으로 처리합니다. 해당 `task_id`를 사용하여 최종 결과를 조회할 수 있지만, 조회는 작업이 계속 실행되는 전제가 아닙니다. 다중 디코더 회전(multi-solver rotation) 등의 시나리오에 적합합니다: 작업을 제출한 후 즉시 `task_id`를 받아 다른 디코더를 조정하고, 나중에 결과를 읽으러 돌아옵니다.

> 📘 전체 인터랙티브 문서 (온라인 디버깅 포함): [CAPTCHA 작업 조회 API →](https://platform.acedata.cloud/documents/captcha-tasks)

## 신청 절차

이 인터페이스를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API 토큰을 받아야 하며, 이를 백업으로 보관하십시오. **하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다.**

## 기본 사용법

### 첫 번째 단계: 비동기 방식으로 작업 생성

임의의 CAPTCHA 인터페이스 요청 본문에 `async: true`를 전달하면, 인터페이스는 즉시 `task_id`(HTTP 201)를 반환하며, 대기하지 않습니다:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  "website_url": "https://www.google.com/recaptcha/api2/demo",
  "async": true
}'
```

```json theme={null}
{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

### 두 번째 단계 (선택 사항): task\_id로 결과 조회

진행 상황을 적극적으로 확인하려면, 이전 단계에서 반환된 `task_id`를 사용하여 `POST /captcha/tasks`를 조회할 수 있습니다(3\~5초마다 한 번씩 권장). 이 인터페이스는 작업 처리를 촉발하거나 진행하지 않으며; 준비된 결과를 읽을 때 기존의 일회성 정산 행동을 따릅니다:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'
```

처리 중에는 `status: processing`이 반환됩니다:

```json theme={null}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "processing"
}
```

처리가 완료되면 `status: ready`와 해당 결과 필드가 반환되며, 필드 구조는 동기 모드와 완전히 일치합니다:

* **토큰 시리즈** (hcaptcha, recaptcha2, recaptcha3)는 `token`을 반환합니다:

```json theme={null}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "started_at": 1784885653.0,
  "finished_at": 1784885665.4,
  "elapsed": 12.4,
  "token": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMB......"
}
```

* **인식 분류** (recognition/recaptcha2, recognition/hcaptcha)는 `solution`을 반환합니다; **recognition/image2text**는 `text`를 반환합니다.

`/captcha/tasks`는 모든 CAPTCHA 인터페이스(토큰 및 인식 시리즈)에 공통적으로 사용되며, 동일한 `task_id`로 폴링하면 됩니다.

서버는 생성 시점부터 지속적으로 처리하며, 최대 120초까지 진행됩니다. 마감 기한의 마지막 조회에서 결과를 얻지 못하면 HTTP 504를 지속화합니다. 이 상태는 최종 상태이며, 클라이언트는 폴링을 중단해야 합니다; 동일한 `task_id`를 반복 조회하면 동일한 실패 결과가 안정적으로 반환됩니다:

```json theme={null}
{
  "detail": "The captcha task timed out.",
  "code": "timeout",
  "success": false,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "failed",
  "started_at": 1784885653.0,
  "finished_at": 1784885765.4,
  "elapsed": 112.4
}
```

`status: ready`와 HTTP 504의 최종 상태 응답은 모두 타이밍 필드를 포함합니다.

* `started_at`, 작업 시작 처리 시간, Unix 타임스탬프(초, 부동 소수점).
* `finished_at`, 작업 결과 생성 시간, Unix 타임스탬프(초, 부동 소수점). 처리 중일 때는 이 필드를 반환하지 않습니다.
* `elapsed`, 작업 처리 소요 시간, 단위는 초(부동 소수점, 소수점 3자리 유지). 처리 중일 때는 이 필드를 반환하지 않습니다.

## 요금 설명

비동기 모드에서는 작업 생성 및 "처리 중" 상태 읽기에 요금이 부과되지 않습니다; **클라이언트가 최초로 성공적인 결과를 읽을 때 한 번 요금이 부과됩니다**(기존 행동 및 동기 모드 가격과 일치). 서버는 작업을 자율적으로 진행하지만, 백그라운드에서 먼저 완료되더라도 조기 요금이 부과되지 않습니다. 120초 마감 기한 내에 성공하지 못한 작업은 HTTP 504로 종료되며 요금이 부과되지 않습니다.

## 오류 처리

이 인터페이스를 호출할 때 오류가 발생하면, 해당 오류 코드와 정보가 반환됩니다. 예를 들어:

* `400 invalid_request`: 요청에 `task_id` 매개변수가 누락되었습니다.
* `401 invalid_token`: 인증되지 않음, 인증 토큰이 유효하지 않거나 누락되었습니다.
* `404 not_found`: `task_id`가 존재하지 않거나 현재 계정에 속하지 않습니다.
* `504 timeout`: 작업이 종료되었고 결과를 생성하지 않았습니다; 해당 `task_id`에 대한 폴링을 중단하십시오. 이 실패는 요금을 부과하지 않습니다.

### 오류 응답 예시

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "task not found"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.