RealHand API 文档

AI 原生线下真人履约 API 服务平台。让 AI 程序能够调用真实人类完成线下任务。

BASE https://realhand.top/api/v1

鉴权说明

RealHand 采用三种鉴权方式，不同角色使用不同的凭据类型。

API Key X-API-Key: rh_xxx API 调用方 ▼

鉴权头

X-API-Key: rh_xxxxxxxxxxxxxxxxxxxx

在管理后台创建 API Key 后获得。每个 Key 有独立余额，可单独充值。

JWT Authorization: Bearer <token> 执行者 & 管理员 ▼

鉴权头

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

执行者通过 /api/executor/login 获取 Token，管理员通过 /api/admin/login 获取。

API 调用方接口

路径前缀：/api/v1 | 鉴权：X-API-Key

POST /api/v1/task/create 创建任务 ▼

请求头

X-API-Key: rh_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

请求参数

参数	类型	必填	说明
content	string	必填	任务内容描述
address	string	必填	任务执行地址
price	number	必填	单价（1-100元）
task_type	string	可选	store_verify / price_collect / address_confirm，默认 store_verify
require_photo	int	可选	需要照片数量，默认2
callback_url	string	可选	任务完成后回调通知地址
target_lat	number	可选	目标纬度（就近派单）
target_lng	number	可选	目标经度
deadline_minutes	int	可选	执行时限（10-1440分钟），默认240

响应示例

{
  "code": 200,
  "msg": "任务创建成功",
  "data": {
    "task_id": "a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "assigned",
    "price": 5,
    "expires_at": "2026-06-25T06:00:00.000Z",
    "deadline_minutes": 240
  }
}

GET /api/v1/task/query 查询任务状态 ▼

查询参数

参数	类型	必填	说明
task_id	string	必填	任务ID

响应示例

{
  "code": 200,
  "data": {
    "task_id": "a1b2c3d4-...",
    "status": "completed",
    "content": "请拍摄门店门头照片",
    "address": "北京市朝阳区建国路88号",
    "gps": { "lat": 39.9087, "lng": 116.3975, "accuracy": 10 },
    "photos": [
      { "url": "https://cdn.realhand.com/photos/xxx.jpg", "location": { "lat": 39.9087, "lng": 116.3975 } }
    ],
    "text_result": "门店正常营业",
    "verify_score": 95,
    "completed_at": "2026-06-25T02:30:00.000Z"
  }
}

任务状态

pending

待接单

assigned

已派单

executing

执行中

completed

已完成

rejected

已驳回

cancelled

已取消

POST /api/v1/task/:task_id/cancel 取消任务 ▼

路径参数

参数	类型	必填	说明
task_id	string	必填	任务ID

只能取消 assigned 或 executing 状态的任务，取消后自动退款。

响应示例

{ "code": 200, "msg": "任务已取消，已退款" }

GET /api/v1/task/list 任务列表 ▼

查询参数

参数	类型	必填	说明
status	string	可选	按状态筛选
page	int	可选	页码，默认1
limit	int	可选	每页数量，默认20

GET /api/v1/account/balance 账户余额 ▼

响应示例

{
  "code": 200,
  "data": {
    "balance": 95.0,
    "total_spent": 5.0,
    "total_tasks": 1
  }
}

快速接入示例

Python

import requests

API_BASE = "https://realhand.top/api/v1"
API_KEY = "rh_xxxxxxxxxxxxxxxxxxxx"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# 创建任务
resp = requests.post(f"{API_BASE}/task/create", headers=headers, json={
    "content": "请拍摄门店门头照片",
    "address": "北京市朝阳区建国路88号",
    "price": 5,
    "callback_url": "https://your-server.com/callback"
})
task_id = resp.json()["data"]["task_id"]
print(f"任务已创建: {task_id}")

# 查询任务状态
resp = requests.get(f"{API_BASE}/task/query", headers=headers, params={"task_id": task_id})
print(resp.json())

Node.js

const axios = require('axios');

const API_BASE = 'https://realhand.top/api/v1';
const API_KEY = 'rh_xxxxxxxxxxxxxxxxxxxx';

const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json'
};

async function createTask() {
  const resp = await axios.post(`${API_BASE}/task/create`, {
    content: '请拍摄门店门头照片',
    address: '北京市朝阳区建国路88号',
    price: 5,
    callback_url: 'https://your-server.com/callback'
  }, { headers });
  console.log('任务已创建:', resp.data.data.task_id);
  return resp.data.data.task_id;
}

createTask();

cURL

curl -X POST https://realhand.top/api/v1/task/create \
  -H "X-API-Key: rh_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "请拍摄门店门头照片",
    "address": "北京市朝阳区建国路88号",
    "price": 5,
    "callback_url": "https://your-server.com/callback"
  }'

执行者接口

路径前缀：/api/executor | 鉴权：Authorization: Bearer <token>

POST /api/executor/register 注册 ▼

请求参数

参数	类型	必填	说明
phone	string	必填	手机号（11位）
password	string	必填	密码
real_name	string	可选	真实姓名
id_card	string	可选	身份证号（自动实名认证）

响应示例

{ "code": 200, "msg": "注册成功", "data": { "executor_id": "e1b2c3d4-..." } }

POST /api/executor/login 登录 ▼

请求参数

参数	类型	必填
phone	string	必填
password	string	必填

响应示例

{
  "code": 200, "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "executor": {
      "id": "e1b2c3d4-...", "phone": "13900008888",
      "real_name": "张三", "is_verified": 1,
      "credit_score": 100, "wallet_balance": 0
    }
  }
}

PUT /api/executor/location 更新位置 ▼

请求参数

参数	类型	必填
lat	number	必填
lng	number	必填

GET /api/executor/tasks/nearby 查看附近任务 ▼

响应示例

{
  "code": 200,
  "data": {
    "tasks": [
      {
        "id": "a1b2c3d4-...", "content": "请拍摄门店门头照片",
        "address": "北京市朝阳区建国路88号", "task_type": "store_verify",
        "price": 5, "require_photo": 2,
        "target_lat": 39.9087, "target_lng": 116.3975
      }
    ]
  }
}

POST /api/executor/tasks/:taskId/accept 接单 ▼

前置条件：信用分 ≥ 60，且没有未完成的任务

POST /api/executor/tasks/:taskId/submit 提交任务结果 ▼

请求参数

参数	类型	必填
gps_lat	number	必填
gps_lng	number	必填
gps_accuracy	number	必填
text_result	string	必填

提交前需先通过 H5 上传照片。

响应示例

{
  "code": 200, "msg": "提交成功",
  "data": { "verify_score": 95, "earned": 5, "wallet_balance": 5 }
}

POST /api/executor/tasks/:taskId/cancel 取消任务 ▼

扣除 10 信用分，任务重新上架。只能取消自己执行的 assigned/executing 任务。

GET /api/executor/my-tasks 我的任务 ▼

查询参数

参数	类型	必填	说明
status	string	可选	按状态筛选

GET /api/executor/wallet 查看钱包 ▼

响应示例

{
  "code": 200, "data": {
    "wallet_balance": 50.0, "total_earned": 50.0,
    "total_tasks": 10, "credit_score": 98,
    "recent_withdrawals": [{ "amount": 20.0, "status": "pending" }]
  }
}

POST /api/executor/withdraw 申请提现 ▼

请求参数

参数	类型	必填	说明
amount	number	必填	提现金额（≥1元）
wx_account	string	必填	微信账号

管理后台接口

路径前缀：/api/admin | 鉴权：Authorization: Bearer <token>

POST /api/admin/login 管理员登录 ▼

请求参数

参数	类型	必填
username	string	必填
password	string	必填

响应示例

{ "code": 200, "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }

GET /api/admin/dashboard 仪表盘统计 ▼

响应示例

{
  "code": 200, "data": {
    "tasks": { "total": 100, "pending": 5, "executing": 3, "completed": 85, "today": 12 },
    "executors": { "total": 50, "active": 42, "online": 8 },
    "revenue": { "total": 500.0, "today": 60.0 },
    "api_keys": { "total": 3, "total_balance": 500.0 }
  }
}

GET /api/admin/tasks 任务列表 ▼

查询参数

参数	类型	必填
status	string	可选
page	int	可选
limit	int	可选

POST /api/admin/tasks/:id/reject 驳回任务 ▼

请求体

{ "reason": "提交内容不符合要求" }

状态改为 rejected，自动退款，扣除执行者 10 信用分。

POST /api/admin/tasks/:id/cancel 取消任务 ▼

请求体

{ "reason": "管理员取消" }

GET /api/admin/executors 执行者列表 ▼

POST /api/admin/executors/:id/ban 封禁执行者 ▼

请求体

{ "reason": "作弊行为" }

POST /api/admin/executors/:id/unban 解封执行者 ▼

POST /api/admin/executors/:id/reset-credit 重置信用分 ▼

请求体

{ "score": 100 }

GET /api/admin/api-keys API Key 列表 ▼

POST /api/admin/api-keys 创建 API Key ▼

请求体

{ "name": "AI助手API", "initial_balance": 100.0 }

POST /api/admin/api-keys/:id/recharge 充值 ▼

GET /api/admin/withdrawals?status=pending 待审批提现 ▼

POST /api/admin/withdrawals/:id/approve 审批通过 ▼

错误码

所有接口返回统一 JSON 格式：{ code, msg, data? }

200

成功

400

参数错误

401

未授权（API Key / Token 无效）

402

余额不足

403

无权限（信用分不足 / 被封禁）

404

资源不存在

409

冲突（手机号已注册 / 有未完成任务）

429

请求过于频繁

500

服务器内部错误

回调通知

创建任务时提供 callback_url，任务完成或取消后向该地址发送 POST 请求。

POST 任务完成回调 ▼

{
  "task_id": "a1b2c3d4-...",
  "status": "completed",
  "verify_score": 95,
  "result": {
    "text": "门店正常营业，门头照片已拍摄",
    "photos": ["https://cdn.realhand.com/photos/xxx.jpg"],
    "gps": { "lat": 39.9087, "lng": 116.3975 }
  }
}

POST 任务取消回调 ▼

{
  "task_id": "a1b2c3d4-...",
  "status": "cancelled",
  "reason": "执行者主动取消，任务重新上架"
}

RealHand API v1.0

技术支持通过管理后台提交工单