API 레퍼런스

요청과 응답

이 페이지는 중국어 버전을 기계 번역한 것이라 부정확한 내용이 있을 수 있어요. 중국어 버전을 기준으로 해 주세요.

모든 메서드는 HTTPS POST로 JSON을 보내고(/useragent만 GET), 요청 본문의 clientKey로 인증하며, 응답은 모두 JSON이에요. errorId가 0이면 성공이고, 1이면 실패이며 errorCode가 함께 와요. 캡차 하나를 인식하는 데는 두 단계가 필요해요. 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의 문구는 바뀔 수 있으니 파싱하지 마세요.

동기와 비동기

	비동기	동기
해당 유형	토큰을 반환하는 작업 유형(reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), Cloudflare 챌린지 페이지, `ImageToTextTask`, `ImageToTextTaskM1`	이미지 인식(이름이 `Classification`으로 끝나는 유형), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle`
`createTask` 반환값	`taskId`	`status: "ready"`와 `solution`
결과 받는 방법	5초마다 `getTaskResult` 호출	따로 조회할 필요 없음

각 유형이 어느 쪽인지는 작업 유형과 가격의 “반환 방식” 열에서 확인하세요.

폴링

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로 시작하면 중국어, 그 밖의 언어는 영어로 반환하고, 이 헤더가 없으면 중국어와 영어를 모두 반환해요. 다른 오류 코드의 설명은 영향을 받지 않아요.

다음 단계

createTask 작업 만들기
getTaskResult 결과 가져오기
동시 작업 수 제한과 자동 일시 중지: 오류가 너무 많으면 몇 분 동안 일시 중지돼요