API 文档
Base URL:https://edge.brownhorse.cn 所有接口返回 JSON,含 ok 字段。金额单位统一为「厘」(1 元 = 1000 厘)。
鉴权
用户接口支持两种方式:会话令牌(控制台登录后从 localStorage 取 edge_token)或 API Key(适合服务端自动化)。二选一,放在请求头:
Authorization: Bearer <token>
X-API-Key: <你的 apiKey,在控制台「我的 API Key」查看>
节点接入用独立的 X-Node-Key,注册节点后获得;管理接口用 X-Admin-Key,仅平台方持有。
能力市场
GET /api/caps
获取全部能力与实时单价。status=live 可下单,preview 内测中。
{
"ok": true,
"capabilities": [
{ "id": "ocr_print", "name": "印刷体文字识别", "unit": "页",
"price": 2, "priceYuan": 0.002, "status": "live", "model": "PP-OCRv4 (RKNN int8)" }
],
"currency": "厘", "perYuan": 1000
}
任务
POST /api/tasks
提交批处理任务。items 为数组,每个元素即一次能力调用;提交时按次数×单价预扣费用。
{
"capability": "ocr_print",
"items": [
{ "text": "第一页印刷体内容..." },
{ "image": "data:image/..." }
]
}
返回 task.id、cost(厘)、status=queued。单次最多 1000 条。
GET /api/tasks
列出我的全部任务,含状态、进度、费用。
GET /api/tasks/:id
任务详情,status=done 时 results 含全部结果,顺序与 items 一一对应。
POST /api/tasks/:id/cancel
取消排队中的任务,预扣费用原路退还。已进入执行的任务不可取消。
账户与账务
GET /api/me
当前用户信息,含余额 balanceYuan 与 apiKey。
GET /api/ledger
账务流水:grant 体验金 / recharge 充值 / consume 消费 / refund 退还。
POST /api/recharge/order
创建充值订单 {"amountYuan": 50}。测试模式立即到账;生产模式接微信支付后返回支付参数。
节点接入协议
节点运行在设备端,负责实际推理。平台负责编排与计量。协议如下:
1. 注册(幂等)
POST /api/node/register
{ "sn": "设备SN", "model": "H5", "space": "空间标识",
"capabilities": ["ocr_print","barcode"] }
→ 返回 { nodeKey, nodeId } // 同一 sn 重复注册返回同一 nodeKey
2. 心跳 + 状态上报
POST /api/node/heartbeat 头: X-Node-Key
{ "idle": true, "capabilities": ["ocr_print"] }
idle 表示设备当前可承接任务:true 可接单,false 不可接单。设备状态变化时立即上报,平台收到后将该节点未完成的切片任务放回队列、由其他节点续跑。心跳间隔建议 5–10 秒,超过 90 秒视为离线。
3. 拉取 / 执行 / 回传
GET /api/node/tasks → 取派给本节点的任务
POST /api/node/tasks/:id/start → 标记开始执行
POST /api/node/tasks/:id/result → 分批回传 {"results":[...]}
POST /api/node/tasks/:id/fail → 失败上报,费用退还客户
推理在设备端完成,平台接收结构化结果。任务派发或执行超过 10 分钟自动回收重派,最多重试 3 次。
服务说明
- 结果隔离:任务与结果按任务 ID 严格隔离,仅任务提交方可查看。
- 幂等与重试:register 幂等;任务回传按条累加,网络中断后可重传,不会重复扣费。
状态机
queued(排队)→ assigned(已派发)→ running(执行中)→ done(完成);异常分支 failed(失败退还)/ cancelled(取消退还)。
© 2026 BROWNHORSE
