API.md

API 文檔

基礎信息

• 基礎 URL: http://localhost:7860 (本地) 或 https://huggingface.co/spaces/YOUR_USERNAME/turnstile-solver (HuggingFace)
• 內容類型: application/json
• 認證: 無（可選配置）

端點列表

1. 健康檢查

檢查服務是否正常運行。

請求：

GET /health

響應 (200 OK)：

{
  "status": "healthy",
  "service": "Turnstile Solver"
}

示例：

curl http://localhost:7860/health

---

2. 本地求解

使用 Playwright 本地求解 Turnstile 驗證碼。

請求：

POST /solve
Content-Type: application/json

{
  "url": "https://example.com",
  "sitekey": "0x4AAAAAAAxxxxxx",
  "timeout": 30000
}

參數：

參數	類型	必需	說明
url	string	✓	包含 Turnstile 驗證碼的網頁 URL
sitekey	string	✓	Turnstile sitekey
timeout	integer	✗	超時時間（毫秒），默認 30000

響應 (200 OK)：

{
  "token": "0.xxxxxxxxxxxxx",
  "success": true,
  "message": "Turnstile 求解成功"
}

錯誤響應 (400/500)：

{
  "detail": "無法獲取 Turnstile token"
}

示例：

curl -X POST http://localhost:7860/solve \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "sitekey": "0x4AAAAAAAxxxxxx",
    "timeout": 30000
  }'

Python 示例：

import requests

response = requests.post(
    "http://localhost:7860/solve",
    json={
        "url": "https://example.com",
        "sitekey": "0x4AAAAAAAxxxxxx",
        "timeout": 30000
    }
)

data = response.json()
print(f"Token: {data['token']}")

---

3. 第三方服務求解

使用第三方服務（2captcha、Anti-Captcha、CapSolver）求解 Turnstile 驗證碼。

請求：

POST /solve-external
Content-Type: application/json

{
  "sitekey": "0x4AAAAAAAxxxxxx",
  "pageurl": "https://example.com",
  "provider": "2captcha",
  "api_key": "YOUR_API_KEY",
  "timeout": 180
}

參數：

參數	類型	必需	說明
sitekey	string	✓	Turnstile sitekey
pageurl	string	✓	包含驗證碼的頁面 URL
provider	string	✓	服務提供商：2captcha、anti-captcha、capsolver
api_key	string	✓	服務提供商的 API Key
timeout	integer	✗	超時時間（秒），默認 180

響應 (200 OK)：

{
  "token": "0.xxxxxxxxxxxxx",
  "success": true,
  "message": "使用 2captcha 求解成功"
}

錯誤響應 (400/500)：

{
  "detail": "不支持的服務提供商: invalid-provider"
}

示例：

curl -X POST http://localhost:7860/solve-external \
  -H "Content-Type: application/json" \
  -d '{
    "sitekey": "0x4AAAAAAAxxxxxx",
    "pageurl": "https://example.com",
    "provider": "2captcha",
    "api_key": "YOUR_API_KEY",
    "timeout": 180
  }'

Python 示例：

import requests

response = requests.post(
    "http://localhost:7860/solve-external",
    json={
        "sitekey": "0x4AAAAAAAxxxxxx",
        "pageurl": "https://example.com",
        "provider": "2captcha",
        "api_key": "YOUR_API_KEY",
        "timeout": 180
    }
)

data = response.json()
print(f"Token: {data['token']}")

---

4. 獲取服務提供商列表

獲取支持的第三方服務提供商信息。

請求：

GET /providers

響應 (200 OK)：

{
  "providers": [
    {
      "name": "2captcha",
      "url": "https://2captcha.com",
      "description": "2captcha 驗證碼求解服務",
      "pricing": "按求解次數計費"
    },
    {
      "name": "anti-captcha",
      "url": "https://anti-captcha.com",
      "description": "Anti-Captcha 驗證碼求解服務",
      "pricing": "按求解次數計費"
    },
    {
      "name": "capsolver",
      "url": "https://www.capsolver.com",
      "description": "CapSolver 驗證碼求解服務",
      "pricing": "按求解次數計費"
    }
  ]
}

示例：

curl http://localhost:7860/providers

---

錯誤處理

常見錯誤碼

狀態碼	說明	解決方案
200	成功	-
400	請求錯誤	檢查參數是否正確
500	服務器錯誤	檢查服務日誌

錯誤響應格式

{
  "detail": "錯誤信息"
}

常見錯誤

1. 無效的 sitekey

{
  "detail": "求解失敗: Invalid sitekey"
}

解決方案： 確認 sitekey 正確

2. 超時

{
  "detail": "求解失敗: Timeout"
}

解決方案： 增加 timeout 參數

3. API Key 無效

{
  "detail": "求解失敗: Invalid API key"
}

解決方案： 檢查 API Key 是否正確

---

速率限制

目前無速率限制，但建議：

• 本地求解：最多 10 req/min
• 第三方服務：根據服務提供商限制

---

認證

目前無認證機制。生產環境建議添加：

from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer

security = HTTPBearer()

@app.post("/solve")
async def solve_turnstile(request: TurnstileRequest, credentials = Depends(security)):
    # 驗證 token
    pass

---

超時設置

本地求解

• 最小值: 5000 ms (5 秒)
• 最大值: 120000 ms (2 分鐘)
• 默認值: 30000 ms (30 秒)

第三方服務

• 最小值: 30 秒
• 最大值: 600 秒 (10 分鐘)
• 默認值: 180 秒 (3 分鐘)

---

響應時間

本地求解

• 平均: 10-30 秒
• 最快: 5 秒
• 最慢: 2 分鐘

第三方服務

• 平均: 3-10 秒
• 最快: 1 秒
• 最慢: 10 分鐘

---

使用示例

JavaScript/Node.js

const response = await fetch('http://localhost:7860/solve', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    sitekey: '0x4AAAAAAAxxxxxx',
    timeout: 30000
  })
});

const data = await response.json();
console.log(data.token);

Python

import requests

response = requests.post(
    'http://localhost:7860/solve',
    json={
        'url': 'https://example.com',
        'sitekey': '0x4AAAAAAAxxxxxx',
        'timeout': 30000
    }
)

print(response.json()['token'])

Go

package main

import (
    "bytes"
    "encoding/json"
    "io/ioutil"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "url":     "https://example.com",
        "sitekey": "0x4AAAAAAAxxxxxx",
        "timeout": 30000,
    }

    body, _ := json.Marshal(payload)
    resp, _ := http.Post(
        "http://localhost:7860/solve",
        "application/json",
        bytes.NewBuffer(body),
    )

    defer resp.Body.Close()
    data, _ := ioutil.ReadAll(resp.Body)
    println(string(data))
}

cURL

curl -X POST http://localhost:7860/solve \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "sitekey": "0x4AAAAAAAxxxxxx",
    "timeout": 30000
  }'

---

最佳實踐

1. 使用適當的超時

   • 本地求解：30-60 秒
   • 第三方服務：180-300 秒

2. 實現重試機制

   for attempt in range(3):
       try:
           result = solve_turnstile()
           break
       except Exception as e:
           if attempt == 2:
               raise
   

3. 監控成功率

   • 記錄所有請求
   • 追蹤失敗原因
   • 定期分析

4. 使用連接池

   session = requests.Session()
   response = session.post(url, json=data)
   

5. 實現緩存

   • 緩存相同 sitekey 的結果
   • 減少重複求解

---

支持

• 文檔：https://github.com/your-repo/docs
• 問題：https://github.com/your-repo/issues
• 討論：https://github.com/your-repo/discussions