Quickstart

This page sends a first request with the simplest task type, ImageToTextTaskOcrBase, which reads the letters and digits in an image. It is synchronous (a single createTask request returns the result), costs 2 points (¥0.002) per image and needs no third-party site, so it is a good way to check that your account and code work.

1. Create an account

   Sign up and log in at yescaptcha.com.

2. Copy your clientKey

   On the dashboard (yescaptcha.com/dashboard.html), find “Your ClientKey” and click copy. Copy the whole value. Every API request is authenticated with it, so keep it private; if it leaks, reset it in the same place.

3. Top up

   Your balance must be above 10 points to create tasks. Payment methods and VIP bonuses: Top-up and VIP.

4. Check that the clientKey works

   getBalance returns your balance and is free:

   curl -s https://api.yescaptcha.com/getBalance \
     -H 'Content-Type: application/json' \
     -d '{"clientKey": "YOUR_CLIENT_KEY"}'

   If you get {"errorId": 0, "balance": 12345, ...}, you are ready; balance is your remaining points. ERROR_KEY_DOES_NOT_EXIST means the key was copied incorrectly.

5. Read an image

   Download the sample image captcha.jpg (or use your own captcha image), put your client key in an environment variable and run one of the scripts:

   export YESCAPTCHA_CLIENT_KEY=your_client_key

   curl

   quickstart.sh

   #!/usr/bin/env bash
   # First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image)
   # Usage: YESCAPTCHA_CLIENT_KEY=your_client_key bash quickstart.sh captcha.png
   set -euo pipefail
   IMAGE="${1:-captcha.png}"
   BODY=$(base64 < "$IMAGE" | tr -d '\n')   # no "data:" prefix, no line breaks
   curl -s https://api.yescaptcha.com/createTask \
     -H 'Content-Type: application/json' \
     -d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\", \"task\": {\"type\": \"ImageToTextTaskOcrBase\", \"body\": \"${BODY}\"}}"
   echo

   Python

   quickstart.py

   """First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase
   (synchronous, 2 points per image).
   
   Usage:
       export YESCAPTCHA_CLIENT_KEY=your_client_key
       python quickstart.py captcha.png
   """
   import base64
   import os
   import sys
   
   import requests
   
   CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]
   image_path = sys.argv[1] if len(sys.argv) > 1 else "captcha.png"
   
   with open(image_path, "rb") as f:
       body = base64.b64encode(f.read()).decode()  # no "data:" prefix
   
   r = requests.post(
       "https://api.yescaptcha.com/createTask",
       json={
           "clientKey": CLIENT_KEY,
           "task": {"type": "ImageToTextTaskOcrBase", "body": body},
       },
       timeout=30,
   )
   data = r.json()
   if data.get("errorId"):
       raise SystemExit(f"{data.get('errorCode')}: {data.get('errorDescription')}")
   print("text:", data["solution"]["text"])

   Node.js

   quickstart.mjs

   // First request: read an alphanumeric image captcha with ImageToTextTaskOcrBase (synchronous, 2 points per image).
   // Usage: YESCAPTCHA_CLIENT_KEY=your_client_key node quickstart.mjs captcha.png
   import { readFileSync } from 'node:fs';
   
   const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;
   const body = readFileSync(process.argv[2] ?? 'captcha.png').toString('base64'); // no "data:" prefix
   
   const res = await fetch('https://api.yescaptcha.com/createTask', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ clientKey: CLIENT_KEY, task: { type: 'ImageToTextTaskOcrBase', body } }),
   });
   const data = await res.json();
   if (data.errorId) throw new Error(`${data.errorCode}: ${data.errorDescription}`);
   console.log('text:', data.solution.text);

   Run bash quickstart.sh captcha.jpg, python quickstart.py captcha.jpg or node quickstart.mjs captcha.jpg. Python needs pip install requests; Node.js needs version 18 or later.

6. Read the result

   On success you get:

   {
     "errorId": 0,
     "status": "ready",
     "solution": { "text": "LMResm" },
     "taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
   }

   errorId 0 means success, and the text is in solution.text. If errorId is 1, look up errorCode in Error codes.

Next steps

• Token tasks such as reCAPTCHA and hCaptcha are asynchronous: createTask returns a taskId, then you call getTaskResult every 5 seconds. The full flow is in Requests and responses; an example is reCAPTCHA v2.
• Choose a task type: Task types and pricing.
• A client you can copy into your project: Python, Node.js.
• No code: Browser extension.