# 요청과 응답

> YesCaptcha API의 공통 규칙: POST JSON, clientKey 인증, errorId 응답 형식, 동기·비동기 작업, 5초마다 폴링, 110초 타임아웃, 결과 약 10분 보관, Accept-Language에 따른 안내 문구 언어.

Source: https://docs.yescaptcha.com/ko/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`가 함께 와요. 캡차 하나를 인식하는 데는 두 단계가 필요해요. `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/ko/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/ko/api/errors.md)를 참고하세요 |
| `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` 호출 | 따로 조회할 필요 없음 |

각 유형이 어느 쪽인지는 [작업 유형과 가격](https://docs.yescaptcha.com/ko/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/ko/api/create-task.md)
-   [getTaskResult 결과 가져오기](https://docs.yescaptcha.com/ko/api/get-task-result.md)
-   [동시 작업 수 제한과 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md): 오류가 너무 많으면 몇 분 동안 일시 중지돼요