首页

RealHand API 文档

AI 实地核验 API。让 AI Agent 和企业系统调用真人完成地址真实性核验，并获得 GPS、水印照片、审核结论和结构化报告。

BASE https://realhand.top/api/v1
1
鉴权说明
RealHand 对客户 API 采用 API Key 鉴权。每个 Key 有独立余额和任务记录。
API Key X-API-Key: rh_xxx API 调用方 ▼
鉴权头
X-API-Key: rh_xxxxxxxxxxxxxxxxxxxx

API Key 由 RealHand 为试点客户开通。请不要把 API Key 放在公开前端页面或公开代码仓库。

2
API 调用方接口
路径前缀：/api/v1 | 鉴权：X-API-Key
POST /api/v1/task/create 创建任务 ▼
请求头
X-API-Key: rh_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
请求参数
参数类型必填说明
contentstring必填任务内容描述，最多 2000 字
addressstring必填任务执行地址，最多 300 字
pricenumber必填单价，1-100 的数字（元）
task_typestring可选address_verify / store_verify，默认 address_verify
require_photoint可选需要照片数量，1-9 张，地址核验建议 3 张
callback_urlstring可选任务完成后回调通知地址，仅支持 http/https URL
target_latnumber可选目标纬度（-90 到 90），需和 target_lng 同时填写
target_lngnumber可选目标经度（-180 到 180），需和 target_lat 同时填写
deadline_minutesint可选执行时限，10-1440 的整数分钟，默认 240
响应示例
{
  "code": 200,
  "msg": "任务创建成功",
  "data": {
    "task_id": "a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "assigned",
    "price": 10,
    "expires_at": "2026-06-25T06:00:00.000Z",
    "deadline_minutes": 240
  }
}
POST /api/v1/task/batch-create 批量创建任务 ▼
请求参数
参数类型必填说明
contentstring必填统一核验要求，最多 2000 字
addressesstring[]必填地址数组，一次最多 50 个，单个地址最多 300 字
pricenumber必填单地址价格，1-100 的数字（元）
task_typestring可选address_verify / store_verify，默认 address_verify
require_photoint可选每个地址需要的照片数量，1-9 张
callback_urlstring可选任务完成后回调通知地址，仅支持 http/https URL
deadline_minutesint可选执行时限，10-1440 的整数分钟，默认 240
请求示例
{
  "task_type": "address_verify",
  "content": "请核验该地址是否真实存在，拍摄入口、地址标识和周边环境。",
  "addresses": [
    "佛山市禅城区祖庙路33号",
    "佛山市南海区桂城街道灯湖东路"
  ],
  "require_photo": 3,
  "price": 10,
  "deadline_minutes": 240
}
响应示例
{
  "code": 200,
  "msg": "批量任务创建成功",
  "data": {
    "count": 2,
    "task_ids": [
      "a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "b2c3d4e5-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    ],
    "total_price": 20,
    "deadline_minutes": 240
  }
}
GET /api/v1/task/query 查询任务状态 ▼
查询参数
参数类型必填说明
task_idstring必填任务ID
响应示例
{
  "code": 200,
  "data": {
    "task_id": "a1b2c3d4-...",
    "status": "completed",
    "content": "请到现场核验该地址是否真实存在，拍摄入口和周边环境",
    "address": "北京市朝阳区建国路88号",
    "report_url": "https://realhand.top/api/v1/task/a1b2c3d4-.../report",
    "gps": { "lat": 39.9087, "lng": 116.3975, "accuracy": 10 },
    "photos": [
      { "url": "https://realhand.top/uploads/photos/wm_xxx.jpg", "location": { "lat": 39.9087, "lng": 116.3975 } }
    ],
    "text_result": "现场地址存在，入口和周边环境可识别",
    "review_status": "approved",
    "review_note": "地址真实性核验通过",
    "verify_score": 95,
    "completed_at": "2026-06-25T02:30:00.000Z"
  }
}
任务状态
pending
待接单
assigned
已派单
executing
执行中
completed
已完成
rejected
已驳回
cancelled
已取消
GET /api/v1/task/:task_id/report HTML 核验报告 ▼
路径参数
参数类型必填说明
task_idstring必填任务ID

使用同一 API Key 访问。报告可用于存档、转发、打印或保存 PDF。

报告包含
核验地址
地址、任务编号、任务状态
交付清单
照片、GPS 记录、人工审核、报告链接
现场证据
照片、水印、上传位置和时间
审核结果
现场结论、审核备注、服务边界
请求示例
GET /api/v1/task/a1b2c3d4-.../report
X-API-Key: rh_xxxxxxxxxxxxxxxxxxxx
POST /api/v1/task/:task_id/cancel 取消任务 ▼
路径参数
参数类型必填说明
task_idstring必填任务ID

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

响应示例
{ "code": 200, "msg": "任务已取消，已退款" }
GET /api/v1/task/list 任务列表 ▼
查询参数
参数类型必填说明
statusstring可选按状态筛选
pageint可选页码，默认1
limitint可选每页数量，默认20

返回的 total 会按同一 status 条件统计，可用于分页和状态同步。

响应示例
{
  "code": 200,
  "data": {
    "tasks": [
      {
        "id": "a1b2c3d4-...",
        "content": "请到现场核验该地址是否真实存在，拍摄入口和周边环境",
        "address": "北京市朝阳区建国路88号",
        "status": "completed",
        "review_status": "approved",
        "review_note": "地址真实性核验通过",
        "price": 10,
        "verify_score": 95,
        "report_url": "https://realhand.top/api/v1/task/a1b2c3d4-.../report",
        "created_at": "2026-06-25T01:30:00.000Z",
        "completed_at": "2026-06-25T02:30:00.000Z"
      }
    ],
    "total": 1
  }
}
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号",
    "task_type": "address_verify",
    "require_photo": 3,
    "price": 10,
    "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号',
    task_type: 'address_verify',
    require_photo: 3,
    price: 10,
    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号",
    "task_type": "address_verify",
    "require_photo": 3,
    "price": 10,
    "callback_url": "https://your-server.com/callback"
  }'
3
错误码
所有接口返回统一 JSON 格式：{ code, msg, data? }
200
成功
400
参数错误
401
未授权（API Key 无效）
402
余额不足
403
无权限（信用分不足 / 被封禁）
404
资源不存在
409
冲突（手机号已注册 / 有未完成任务）
429
请求过于频繁
500
服务器内部错误
4
回调通知
创建任务时提供 callback_url，任务完成或取消后向该地址发送 POST 请求。
POST 任务完成回调 ▼ 
{
  "task_id": "a1b2c3d4-...",
  "status": "completed",
  "verify_score": 95,
  "review_status": "pending",
  "report_url": "https://realhand.top/api/v1/task/a1b2c3d4-.../report",
  "result": {
    "text": "门店正常营业，门头照片已拍摄",
    "photos": ["https://realhand.top/uploads/photos/wm_xxx.jpg"],
    "gps": { "lat": 39.9087, "lng": 116.3975, "accuracy": 10 }
  }
}
POST 任务取消回调 ▼ 
{
  "task_id": "a1b2c3d4-...",
  "status": "cancelled",
  "reason": "任务取消，等待重新处理"
}

RealHand API v1.0

如需开通 API Key、充值或试点支持，请联系 RealHand 对接人。