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

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

📘 전체 인터랙티브 문서 (온라인 디버깅 포함): CAPTCHA 작업 조회 API →

신청 절차

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

기본 사용법

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

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

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
}'

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

두 번째 단계 (선택 사항): task_id로 결과 조회

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

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이 반환됩니다:

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

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

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

{
  "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를 반복 조회하면 동일한 실패 결과가 안정적으로 반환됩니다:

{
  "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에 대한 폴링을 중단하십시오. 이 실패는 요금을 부과하지 않습니다.

오류 응답 예시

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "task not found"
  }
}

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

Coding

추가 가이드

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

신청 절차

기본 사용법

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

두 번째 단계 (선택 사항): task_id로 결과 조회

요금 설명

오류 처리

오류 응답 예시

​신청 절차

​기본 사용법

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

​두 번째 단계 (선택 사항): task_id로 결과 조회

​요금 설명

​오류 처리

​오류 응답 예시

신청 절차

기본 사용법

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

두 번째 단계 (선택 사항): task_id로 결과 조회

요금 설명

오류 처리

오류 응답 예시