招个AI · API 文档

认证方式

所有需要认证的接口通过 Cookie 或 Bearer Token 鉴权

方式一：Cookie 认证（浏览器）

登录后浏览器自动携带 portal_token Cookie，所有 API 请求自动鉴权。

方式二：Bearer Token（程序化调用）

调用 POST /api/auth/login 获取 token，后续请求添加 Header：

Authorization: Bearer <token>

Token 有效期 24 小时，过期后需重新登录获取。

接口列表

当前可用的 REST API 端点

9 个接口

方法	路径	说明	参数	响应	认证
POST	`/api/auth/login`	用户登录	`username, password`	`{ token, sub, tenant_id, role }`	不需要
POST	`/api/auth/register`	邀请码注册	`invite_code, username, password, name?`	`{ token, sub, tenant_id }`	不需要
POST	`/api/cloud/tasks/dispatch`	派发 AI 任务	`goal, engine?, risk_level?, task_id?`	`{ task_id, run_id, status }`	需要
GET	`/api/cloud/tasks`	查询任务列表	`—`	`{ tasks: [...], count, tenant_id }`	需要
GET	`/api/cloud/tasks/status?task_id=X`	查询任务状态	`task_id (query)`	`{ task_id, status, engine_result, ... }`	需要
GET	`/api/workers`	获取已开通 AI 员工列表	`—`	`{ workers: [...] }`	需要
POST	`/api/workers/hire`	开通（招聘）AI 员工	`job_pack_id`	`{ worker_id, name, status }`	需要
GET	`/api/market/packs`	获取岗位包列表	`—`	`{ packs: [...] }`	不需要
GET	`/api/v1/usage/summary?tenant_id=X&period=current_month`	获取 Token 用量统计	`tenant_id, period (query)`	`{ total_tokens, total_tasks, records }`	需要

快速示例

使用 curl 派发一个 AI 任务

# 1. 登录获取 Token
curl -X POST https://app.zgai.work/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your_user","password":"your_pass"}'

# 响应: {"token":"eyJ...","sub":"usr-xxx","tenant_id":"tnt-xxx"}

# 2. 派发任务
curl -X POST https://app.zgai.work/api/cloud/tasks/dispatch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJ..." \
  -d '{"goal":"整理本周项目文档","engine":"doc-organizer"}'

# 响应: {"task_id":"CLOUD-xxx","run_id":"...","status":"accepted"}

# 3. 查询任务状态
curl https://app.zgai.work/api/cloud/tasks/status?task_id=CLOUD-xxx \
  -H "Authorization: Bearer eyJ..."

错误码说明

HTTP 状态码	含义	处理建议
`400`	请求参数不合法	检查必填字段和格式
`401`	未认证或 Token 过期	重新登录获取 Token
`403`	无权访问该资源	确认账号权限和租户归属
`404`	资源不存在	检查 ID 或路径
`502`	上游服务不可用	稍后重试或联系管理员

API 接口文档

认证方式

接口列表

快速示例

错误码说明