数字伙伴服务端 API
使用 API Token 从服务端调用指定数字伙伴，并获得文本或 JSON 结构化结果。
服务端 API 使用与网页聊天相同的数字伙伴执行链路，但不要求调用方打开或登录聊天页面。Token 只能保存在受信任的服务端，不能写入浏览器或小程序代码。
创建 Token
在「设置 → API Tokens」创建 Personal Access Token。Token 只在创建时完整显示一次，请保存到服务端密钥管理系统。调用者仍受 Token 所属用户的工作区成员权限和数字伙伴访问权限约束。
发起调用
POST /api/agents/{agent_id}/invoke
Authorization: Bearer <Token>
X-Workspace-ID: <workspace_id>
Content-Type: application/json例如调用数字伙伴 1b98e86c-a994-4683-ae23-7eeffff69697：
curl https://aurababa.com/api/agents/1b98e86c-a994-4683-ae23-7eeffff69697/invoke \
-H "Authorization: Bearer $AURA_TOKEN" \
-H "X-Workspace-ID: $AURA_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"input": "分析这个视频并返回文章、章节、知识图谱和截图时间",
"response_format": "json_object",
"timeout_seconds": 120
}'response_format 支持 text（默认）和 json_object。选择 json_object 时，接口要求数字伙伴只返回一个 JSON 对象，并在响应前校验 JSON；具体字段由提示词约定，例如 article、chapters、knowledge_graph、screenshots。
响应与长任务
任务在等待时间内完成时返回 200：
{
"task_id": "…",
"session_id": "…",
"status": "completed",
"output": {
"article": {},
"chapters": [],
"knowledge_graph": {},
"screenshots": []
}
}timeout_seconds 可设为 1–120 秒。长视频任务未在等待时间内完成时返回 202，任务会继续执行。之后查询：
GET /api/agents/{agent_id}/invocations/{task_id}?response_format=json_object
Authorization: Bearer <Token>
X-Workspace-ID: <workspace_id>查询未完成时仍返回 202；完成或失败时返回 200，并通过 status、output 或 error 表示结果。调用端应保存 task_id，使用退避策略查询，避免因客户端超时重复创建长任务。
错误与限流
| HTTP 状态 | 含义 | 建议处理 |
|---|---|---|
400 | 请求、Agent ID、响应格式或超时参数无效 | 修正请求，不重试原请求 |
401 | Token 缺失、失效或已撤销 | 更新 Token |
403 | 无工作区或数字伙伴访问权限 | 检查 Token 所属用户权限 |
404 | 数字伙伴或任务不存在 | 检查 ID 与工作区 |
202 | 任务仍在处理 | 按 task_id 退避查询 |
429 | 超过平台 API 限流 | 遵循 Retry-After 后重试 |
500 | 入队或服务端处理失败 | 使用指数退避重试；先确认是否已获得 task_id |