메인 콘텐츠로 건너뛰기
본 문서에서는 Recaptcha2 이미지 인식 API 연동 방법을 소개합니다. 사용자가 인식한 내용과 Recaptcha2 인증 이미지 입력을 통해 클릭해야 할 작은 이미지의 좌표를 반환하여 인증을 완료합니다.

​
신청 절차

API를 사용하려면 먼저 Recaptcha2 이미지 인식 API 해당 페이지에서 서비스를 신청해야 합니다. 페이지에 들어가면 “Acquire” 버튼을 클릭합니다. 아래 그림과 같습니다: 로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 이동하여 등록 및 로그인을 요청합니다. 로그인 후에는 자동으로 현재 페이지로 돌아옵니다. 첫 신청 시 무료 사용량이 제공되며, 이 API를 무료로 사용할 수 있습니다.

​
기본 사용법

먼저 기본 사용 방법을 이해해야 합니다. 우리는 웹사이트에서 Recaptcha2 인증 이미지를 캡처해야 합니다. 여기서 예시 웹사이트의 URL은 https://www.google.com/recaptcha/api2/demo입니다. 구체적인 페이지는 아래 그림과 같습니다:

우리는 인증 체크박스를 클릭해야 인증 이미지가 나타납니다. 위 그림에서 노란 화살표가 가리키는 부분의 텍스트가 아래의 question 값입니다. 먼저 간단하게 image 필드를 전달해야 하며, 이는 위 그림에서 빨간 화살표가 가리키는 구체적인 Recaptcha2 인증 이미지입니다. 또한 이미지는 표준 크기(100x100, 300x300, 450x450)로 조정해야 하며, 그래야 서비스가 이미지 유형을 판단할 수 있습니다. 이미지 압축은 사용자가 직접 해야 하며, 본 문서에서는 압축 웹사이트를 추천합니다. 이 웹사이트에서 이미지의 크기와 용량을 압축할 수 있으며, 압축된 결과는 아래 그림과 같습니다: 또한 인증 이미지와 관련된 인식 내용 매개변수 question을 입력해야 합니다. 아래의 내용 표를 참고할 수 있습니다:

​
중국어 내용 표

{
  "/m/0pg52": "出租车",
  "/m/01bjv": "巴士",
  "/m/02yvhj": "校车",
  "/m/04_sv": "摩托车",
  "/m/013xlm": "拖拉机",
  "/m/01jk_4": "烟囱",
  "/m/014xcs": "人行横道",
  "/m/015qff": "红绿灯",
  "/m/0199g": "自行车",
  "/m/015qbp": "停车计价表",
  "/m/0k4j": "汽车",
  "/m/015kr": "桥",
  "/m/019jd": "船",
  "/m/0cdl1": "棕榈树",
  "/m/09d_r": "山",
  "/m/01pns0": "消防栓",
  "/m/01lynh": "楼梯"
}

​
영어 내용 표

{
  "/m/0pg52": "taxis",
  "/m/01bjv": "bus",
  "/m/02yvhj": "school bus",
  "/m/04_sv": "motorcycles",
  "/m/013xlm": "tractors",
  "/m/01jk_4": "chimneys",
  "/m/014xcs": "crosswalks", // pedestrian crossings 也是一样的
  "/m/015qff": "traffic lights",
  "/m/0199g": "bicycles",
  "/m/015qbp": "parking meters",
  "/m/0k4j": "cars",
  "/m/015kr": "bridges",
  "/m/019jd": "boats",
  "/m/0cdl1": "palm trees",
  "/m/09d_r": "mountains or hills",
  "/m/01pns0": "fire hydrant",
  "/m/01lynh": "stairs"
}
위의 내용을 통해 매개변수 question을 소화전과 관련된 /m/01pns0으로 설정할 수 있습니다. 구체적인 내용은 다음과 같습니다:

여기서 우리는 Request Headers를 설정했습니다. 포함된 내용은 다음과 같습니다:
  • accept: 어떤 형식의 응답 결과를 받고 싶은지, 여기서는 application/json으로 작성하여 JSON 형식으로 설정합니다.
  • authorization: API 호출을 위한 키로, 신청 후 직접 드롭다운에서 선택할 수 있습니다.
또한 Request Body를 설정했습니다. 포함된 내용은 다음과 같습니다:
  • image: Base64 인코딩된 인증 이미지.
  • question: 문제 ID, 표를 참조하여 /m/로 시작합니다.
선택 후 오른쪽에 해당 코드가 생성된 것을 확인할 수 있습니다. 아래 그림과 같습니다:

“Try” 버튼을 클릭하면 테스트를 진행할 수 있으며, 위 그림과 같이 다음과 같은 결과를 얻을 수 있습니다: 
{
  "solution": {
    "size": 300,
    "label": "/m/01pns0",
    "confidences": [
      0,
      0.0007,
      1,
      0.0003,
      0.0046,
      1,
      0,
      1,
      0
    ],
    "objects": [
      2,
      5,
      7
    ],
    "type": "multi"
  }
}
반환된 결과는 여러 필드로 구성되어 있으며, 설명은 다음과 같습니다:
  • solution: 이번 Recaptcha2 인증 이미지 작업 처리 후의 검증 결과.
    • size: Recaptcha2 인증 이미지의 크기.
    • label: Recaptcha2 인증 이미지에서 인식된 내용.
    • confidences: Recaptcha2 인증 이미지 인식 영역의 신뢰도, 영역은 0부터 시작합니다.
    • objects: Recaptcha2 인증 이미지 인식 후 인식 내용에 부합하는 영역, 영역은 0부터 시작합니다.
    • type: 이번 Recaptcha2 인증 이미지 작업의 유형, 여러 영역일 경우 multi입니다.
우리는 Recaptcha2 인증 이미지의 검증 결과를 얻었으며, 먼저 인증 이미지를 영역으로 나누어야 합니다. 아래 그림과 같습니다:

영역은 0부터 시작하며, 결과의 objects에서 2, 5, 7을 얻었습니다. 우리는 해당 인증 이미지를 클릭하여 이 세 영역을 통해 인증을 통과할 수 있습니다. 또한 해당 연동 코드를 생성하려면 직접 복사하여 사용할 수 있습니다. 예를 들어 CURL의 코드는 다음과 같습니다: 
curl -X POST 'https://api.acedata.cloud/captcha/recognition/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "question": "/m/01pns0",
  "image": "iVBORw0KGgoAAAANSUhEUgAAASoAAAEsCAIAAAD7AWllAAAAAX..."
}'
Python의 연동 코드는 다음과 같습니다: 
import requests

url = "https://api.acedata.cloud/captcha/recognition/recaptcha2"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "question": "/m/01pns0",
    "image": "iVBORw0KGgoAAAANSUhEUgAAASoAAAEsCAIAAAD7AWllAAAAAX..."
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
오류 처리

API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:
  • 400 token_mismatched：잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다.
  • 400 api_not_implemented：잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다.
  • 401 invalid_token：권한 없음, 잘못되었거나 누락된 인증 토큰입니다.
  • 429 too_many_requests：요청이 너무 많음, 비율 제한을 초과했습니다.
  • 500 api_error：내부 서버 오류, 서버에서 문제가 발생했습니다.

​
오류 응답 예시

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
결론

이 문서를 통해 Recaptcha2 이미지 인식 API를 사용하여 사용자가 인식할 내용을 입력하고 Recaptcha2 인증 이미지와 함께 마지막으로 클릭해야 할 작은 이미지의 좌표를 반환하여 인증을 완료하는 방법을 이해하셨습니다. 이 문서가 API를 더 잘 연결하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.