# Bắt đầu nhanh

> Gửi yêu cầu YesCaptcha đầu tiên trong 5 phút: đăng ký, sao chép clientKey, nạp tiền, rồi nhận dạng một ảnh captcha bằng curl, Python hoặc Node.js (ImageToTextTaskOcrBase, trả kết quả đồng bộ, 2 điểm mỗi lần).

Source: https://docs.yescaptcha.com/vi/getting-started/quickstart/ · 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/getting-started/quickstart/

Trang này gửi yêu cầu đầu tiên bằng loại tác vụ đơn giản nhất là `ImageToTextTaskOcrBase` (nhận dạng chữ cái và chữ số trong ảnh). Loại này chạy đồng bộ: chỉ một yêu cầu `createTask` là có kết quả, mỗi lần 2 điểm (≈ $0.30 / 1k), không phụ thuộc trang web bên thứ ba, nên rất phù hợp để kiểm tra tài khoản và code đã hoạt động đúng chưa.

1.  **Đăng ký tài khoản**
    
    Mở [yescaptcha.com](https://yescaptcha.com/), đăng ký rồi đăng nhập.
    
2.  **Sao chép clientKey**
    
    Sau khi đăng nhập, vào bảng điều khiển ([yescaptcha.com/dashboard.html](https://yescaptcha.com/dashboard.html)), tìm mục «ClientKey của bạn» rồi bấm sao chép. Hãy sao chép đầy đủ.
    
    > **Chú ý:** Mọi yêu cầu API đều được xác thực bằng clientKey, ai có nó cũng có thể dùng số dư của bạn. Đừng gửi cho người khác, cũng đừng ghi vào code công khai; nếu bị lộ, bạn có thể đặt lại ở cùng vị trí đó.
    
3.  **Nạp tiền**
    
    Số dư phải lớn hơn 10 điểm thì mới tạo được tác vụ. Các cách nạp tiền và điểm thưởng VIP xem tại [Nạp tiền và VIP](https://docs.yescaptcha.com/vi/account/recharge.md).
    
4.  **Kiểm tra clientKey có dùng được không**
    
    `getBalance` truy vấn số dư và không trừ điểm:
    
    ```bash
    curl -s https://api.yescaptcha.com/getBalance \
      -H 'Content-Type: application/json' \
      -d '{"clientKey": "YOUR_CLIENT_KEY"}'
    ```
    
    Nếu trả về `{"errorId": 0, "balance": 12345, ...}` nghĩa là đã dùng được, `balance` là số điểm còn lại. Nếu trả về `ERROR_KEY_DOES_NOT_EXIST` nghĩa là bạn đã sao chép sai khóa.
    
5.  **Nhận dạng một ảnh**
    
    Tải ảnh mẫu [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg) (bạn cũng có thể dùng ảnh captcha của riêng mình), đặt clientKey vào biến môi trường rồi chạy:
    
    ```bash
    export YESCAPTCHA_CLIENT_KEY=your_client_key
    ```
    
    **curl**
    
    quickstart.sh
    
    ```bash
    #!/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
    
    ```python
    """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
    
    ```js
    // 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);
    ```
    
    Chạy: `bash quickstart.sh captcha.jpg`, `python quickstart.py captcha.jpg` hoặc `node quickstart.mjs captcha.jpg`. Python cần chạy `pip install requests` trước; Node.js cần phiên bản 18 trở lên.
    
6.  **Xem kết quả**
    
    Khi thành công sẽ trả về:
    
    ```json
    {
      "errorId": 0,
      "status": "ready",
      "solution": {
        "text": "LMResm"
      },
      "taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
    }
    ```
    
    `errorId` bằng 0 nghĩa là thành công, văn bản nhận dạng được nằm trong `solution.text`. Khi `errorId` bằng 1, hãy xem `errorCode`, ý nghĩa xem tại [Mã lỗi](https://docs.yescaptcha.com/vi/api/errors.md).
    

## Bước tiếp theo

-   Các tác vụ trả về token như reCAPTCHA, hCaptcha là **bất đồng bộ**: `createTask` trả về `taskId` trước, sau đó cứ mỗi 5 giây gọi `getTaskResult` một lần. Quy trình đầy đủ xem tại [Yêu cầu và phản hồi](https://docs.yescaptcha.com/vi/api/overview.md), ví dụ xem tại [reCAPTCHA v2](https://docs.yescaptcha.com/vi/tasks/recaptcha-v2.md).
-   Chọn loại tác vụ: [Loại tác vụ và giá](https://docs.yescaptcha.com/vi/tasks.md).
-   Client có thể sao chép thẳng vào dự án: [Python](https://docs.yescaptcha.com/vi/samples/python.md), [Node.js](https://docs.yescaptcha.com/vi/samples/nodejs.md).
-   Không cần viết code: [Tiện ích trình duyệt](https://docs.yescaptcha.com/vi/extension.md).