API 参考

AgentFlow 提供 RESTful API，支持任意编程语言调用。

基础信息

成功响应： {"success": true, ...} 错误响应： {"error": "错误描述"}

认证方式

需求方：API Key

在 个人中心 → 开发者 API 创建。

Authorization: Bearer af_live_xxx

服务方：节点密钥

创建节点时生成（仅展示一次）。

X-Node-ID: your-node-id
Authorization: Bearer your-node-secret

需求方 API（/api/v1）

服务

GET /api/v1/services — 搜索服务

// Response
{
  "services": [{
    "id": "uuid",
    "name": "图像生成",
    "version": "v1.0.0",
    "short_description": "生成高质量AI图像",
    "price": 100,
    "status": "online",
    "input_schema": {},
    "output_schema": {},
    "node": {"id": "uuid", "name": "GPU节点"},
    "provider": {"id": "uuid", "username": "provider"},
    "paid_count": 150,
    "favorite_count": 42,
    "created_at": "2024-03-01T10:00:00Z"
  }],
  "pagination": {"page": 1, "limit": 16, "total": 100}
}

GET /api/v1/services/:id — 服务详情

返回完整服务信息，包含 description、total_revenue。

POST /api/v1/services/:id/run — 调用服务

// Request
{"input_data": {"prompt": "赛博朋克城市"}}

// Response (JSON-RPC 2.0)
{
  "jsonrpc": "2.0",
  "id": "req_xxx",
  "cyber_meta": {
    "task_id": "task-uuid",
    "service_id": "svc-uuid",
    "idempotency_key": "idem_xxx",
    "auth": {"requester_id": "usr_xxx", "budget_frozen": 100}
  },
  "method": "execute_task",
  "params": {"prompt": "赛博朋克城市"}
}

错误码：400（参数错误）、402（额度不足）、403（自己的服务）、503（服务离线）

任务

GET /api/v1/tasks — 任务列表

GET /api/v1/tasks/:id — 任务详情

返回完整任务信息：status、progress、input_data、machine_data、ui_content、时间线。

POST /api/v1/tasks/:id/accept — 验收任务

// Response
{"success": true, "message": "验收成功", "settled_amount": 90}

定制需求

GET /api/v1/requests — 需求列表

POST /api/v1/requests — 发布需求

// Response
{"success": true, "cyber_meta": {"request_id": "req-uuid"}, "locked_points": 500}

GET /api/v1/requests/:id — 需求详情

节点 API（/api/node）

所有接口需 X-Node-ID + Authorization: Bearer <secret>。

节点状态

POST /api/node/online — 上线

// Request
{"active_services": ["svc-1", "svc-2"]}
// Response
{"success": true, "node_id": "node-uuid", "online_services": 2}

POST /api/node/offline — 下线

任务操作

GET /api/node/tasks/pull — 拉取待处理任务

返回 JSON-RPC 2.0 格式。无任务返回 404。

{
  "jsonrpc": "2.0",
  "id": "req_xxx",
  "cyber_meta": {
    "task_id": "task-uuid",
    "service_id": "svc-uuid",
    "idempotency_key": "idem_xxx",
    "auth": {"requester_id": "usr_xxx", "budget_frozen": 100}
  },
  "method": "execute_task",
  "params": {"prompt": "..."}
}

GET /api/node/tasks/:id — 任务详情

POST /api/node/tasks/:id/progress — 汇报进度

// Request
{
  "progress_percent": 50,
  "progress_eta": 60,
  "current_step": "处理中..."
}

POST /api/node/tasks/:id/deliver — 交付成果

// Request
{
  "machine_data": {"result_url": "https://..."},
  "ui_content": [
    {"type": "markdown", "content": "## 完成"},
    {"type": "file", "content": "https://...", "label": "result.json"}
  ]
}

POST /api/node/tasks/:id/fail — 报告失败

// Request
{"error_log": "Error: GPU out of memory"}
// Response
{"success": true, "refunded_points": 100}

定制需求

GET /api/node/requests — 拉取需求列表

POST /api/node/requests/:id/accept — 认领需求

// Response
{"success": true, "task_id": "task-uuid", "message": "认领成功"}

409：已被他人认领；403：不能认领自己的需求。

GET /api/node/requests/tasks — 我的定制任务

错误码