| # API 文檔 |
|
|
| ## 基礎信息 |
|
|
| - **基礎 URL**: `http://localhost:7860` (本地) 或 `https://huggingface.co/spaces/YOUR_USERNAME/turnstile-solver` (HuggingFace) |
| - **內容類型**: `application/json` |
| - **認證**: 無（可選配置） |
|
|
| ## 端點列表 |
|
|
| ### 1. 健康檢查 |
|
|
| 檢查服務是否正常運行。 |
|
|
| **請求：** |
| ```http |
| GET /health |
| ``` |
|
|
| **響應 (200 OK)：** |
| ```json |
| { |
| "status": "healthy", |
| "service": "Turnstile Solver" |
| } |
| ``` |
|
|
| **示例：** |
| ```bash |
| curl http://localhost:7860/health |
| ``` |
|
|
| --- |
|
|
| ### 2. 本地求解 |
|
|
| 使用 Playwright 本地求解 Turnstile 驗證碼。 |
|
|
| **請求：** |
| ```http |
| 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)：** |
| ```json |
| { |
| "token": "0.xxxxxxxxxxxxx", |
| "success": true, |
| "message": "Turnstile 求解成功" |
| } |
| ``` |
|
|
| **錯誤響應 (400/500)：** |
| ```json |
| { |
| "detail": "無法獲取 Turnstile token" |
| } |
| ``` |
|
|
| **示例：** |
| ```bash |
| curl -X POST http://localhost:7860/solve \ |
| -H "Content-Type: application/json" \ |
| -d '{ |
| "url": "https://example.com", |
| "sitekey": "0x4AAAAAAAxxxxxx", |
| "timeout": 30000 |
| }' |
| ``` |
|
|
| **Python 示例：** |
| ```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 驗證碼。 |
|
|
| **請求：** |
| ```http |
| 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)：** |
| ```json |
| { |
| "token": "0.xxxxxxxxxxxxx", |
| "success": true, |
| "message": "使用 2captcha 求解成功" |
| } |
| ``` |
|
|
| **錯誤響應 (400/500)：** |
| ```json |
| { |
| "detail": "不支持的服務提供商: invalid-provider" |
| } |
| ``` |
|
|
| **示例：** |
| ```bash |
| 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 示例：** |
| ```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. 獲取服務提供商列表 |
|
|
| 獲取支持的第三方服務提供商信息。 |
|
|
| **請求：** |
| ```http |
| GET /providers |
| ``` |
|
|
| **響應 (200 OK)：** |
| ```json |
| { |
| "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": "按求解次數計費" |
| } |
| ] |
| } |
| ``` |
|
|
| **示例：** |
| ```bash |
| curl http://localhost:7860/providers |
| ``` |
|
|
| --- |
|
|
| ## 錯誤處理 |
|
|
| ### 常見錯誤碼 |
|
|
| | 狀態碼 | 說明 | 解決方案 | |
| |--------|------|--------| |
| | 200 | 成功 | - | |
| | 400 | 請求錯誤 | 檢查參數是否正確 | |
| | 500 | 服務器錯誤 | 檢查服務日誌 | |
|
|
| ### 錯誤響應格式 |
|
|
| ```json |
| { |
| "detail": "錯誤信息" |
| } |
| ``` |
|
|
| ### 常見錯誤 |
|
|
| **1. 無效的 sitekey** |
| ```json |
| { |
| "detail": "求解失敗: Invalid sitekey" |
| } |
| ``` |
|
|
| **解決方案：** 確認 sitekey 正確 |
|
|
| **2. 超時** |
| ```json |
| { |
| "detail": "求解失敗: Timeout" |
| } |
| ``` |
|
|
| **解決方案：** 增加 timeout 參數 |
|
|
| **3. API Key 無效** |
| ```json |
| { |
| "detail": "求解失敗: Invalid API key" |
| } |
| ``` |
|
|
| **解決方案：** 檢查 API Key 是否正確 |
|
|
| --- |
|
|
| ## 速率限制 |
|
|
| 目前無速率限制，但建議： |
| - 本地求解：最多 10 req/min |
| - 第三方服務：根據服務提供商限制 |
|
|
| --- |
|
|
| ## 認證 |
|
|
| 目前無認證機制。生產環境建議添加： |
|
|
| ```python |
| 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 |
|
|
| ```javascript |
| 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 |
|
|
| ```python |
| import requests |
| |
| response = requests.post( |
| 'http://localhost:7860/solve', |
| json={ |
| 'url': 'https://example.com', |
| 'sitekey': '0x4AAAAAAAxxxxxx', |
| 'timeout': 30000 |
| } |
| ) |
| |
| print(response.json()['token']) |
| ``` |
|
|
| ### Go |
|
|
| ```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 |
|
|
| ```bash |
| 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. **實現重試機制** |
| ```python |
| for attempt in range(3): |
| try: |
| result = solve_turnstile() |
| break |
| except Exception as e: |
| if attempt == 2: |
| raise |
| ``` |
|
|
| 3. **監控成功率** |
| - 記錄所有請求 |
| - 追蹤失敗原因 |
| - 定期分析 |
|
|
| 4. **使用連接池** |
| ```python |
| 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 |
|
|
