# 快速开始

> 5 分钟发出第一个 YesCaptcha 请求：注册、复制 clientKey、充值，再用 curl、Python 或 Node.js 识别一张图片验证码（ImageToTextTaskOcrBase，同步返回，每次 2 点）。

Source: https://docs.yescaptcha.com/zh/getting-started/quickstart/ · Last verified: 2026-10-15

这一页用最简单的任务类型 `ImageToTextTaskOcrBase`（识别图片里的英文和数字）发出第一个请求。它是同步的：一次 `createTask` 请求就返回结果，每次 2 点（0.002 元），不依赖第三方网站，适合用来确认账户和代码都没问题。

1.  **注册账户**
    
    打开 [yescaptcha.com](https://yescaptcha.com/) 注册并登录。
    
2.  **复制 clientKey**
    
    登录后在仪表盘（[yescaptcha.com/dashboard.html](https://yescaptcha.com/dashboard.html)）找到“您的密钥 ClientKey”，点复制，要完整复制。所有 API 请求都用它鉴权，不要泄露给别人；泄露了可以在同一个位置重置。
    
3.  **充值**
    
    余额必须大于 10 点才能创建任务。充值方式和 VIP 赠送见 [充值与 VIP](https://docs.yescaptcha.com/zh/account/recharge/)。
    
4.  **确认 clientKey 能用**
    
    `getBalance` 查询余额，不扣点：
    
    ```bash
    curl -s https://api.yescaptcha.com/getBalance \
      -H 'Content-Type: application/json' \
      -d '{"clientKey": "YOUR_CLIENT_KEY"}'
    ```
    
    返回 `{"errorId": 0, "balance": 12345, ...}` 就说明可以用了，`balance` 是剩余点数。返回 `ERROR_KEY_DOES_NOT_EXIST` 说明密钥复制错了。
    
5.  **识别一张图片**
    
    下载示例图片 [captcha.jpg](https://docs.yescaptcha.com/samples/captcha.jpg)（也可以用你自己的验证码图片），把 clientKey 放进环境变量后运行：
    
    ```bash
    export YESCAPTCHA_CLIENT_KEY=你的clientKey
    ```
    
    **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);
    ```
    
    运行：`bash quickstart.sh captcha.jpg`、`python quickstart.py captcha.jpg` 或 `node quickstart.mjs captcha.jpg`。Python 需要先 `pip install requests`；Node.js 需要 18 以上版本。
    
6.  **看结果**
    
    成功时返回：
    
    ```json
    {
      "errorId": 0,
      "status": "ready",
      "solution": { "text": "LMResm" },
      "taskId": "2376919c-1863-11ec-a012-94e6f7355a0b"
    }
    ```
    
    `errorId` 为 0 表示成功，识别出的文字在 `solution.text`。`errorId` 为 1 时看 `errorCode`，含义见 [错误码](https://docs.yescaptcha.com/zh/api/errors/)。
    

## 下一步

-   reCAPTCHA、hCaptcha 这类返回 token 的任务是**异步**的：`createTask` 先返回 `taskId`，再每 5 秒调用一次 `getTaskResult`。完整流程见 [请求与响应](https://docs.yescaptcha.com/zh/api/overview/)，例子见 [reCAPTCHA v2](https://docs.yescaptcha.com/zh/tasks/recaptcha-v2/)。
-   选任务类型：[任务类型与价格](https://docs.yescaptcha.com/zh/tasks/)。
-   一个可以直接复制进项目的客户端：[Python](https://docs.yescaptcha.com/zh/samples/python/)、[Node.js](https://docs.yescaptcha.com/zh/samples/nodejs/)。
-   不写代码：[浏览器插件](https://docs.yescaptcha.com/zh/extension/)。