DEVELOPER DOCS

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