API 概述

Studio 服务器暴露的 REST API 与 Web UI 使用的完全相同。本文档面向希望直接调用该 API 的集成开发者。

基准地址

所有路径均以 Studio 服务器地址下的 /api 开头。

https://<studio-host>/api/...

通过请求头发送会话令牌。

Authorization: Bearer <token>

令牌缺失或过期时，服务器返回 401。Web UI 收到 401 后会清除已保存的令牌并返回登录界面。直接调用时也建议采用相同处理 —— 401 无法通过重试解决。

成功响应封装在 data 信封中。

{
  "data": { "id": "prj_01H...", "name": "라인 모니터" }
}

失败响应包含 errors 数组。第一项的 message 即为可读的错误消息。

{
  "errors": [
    { "code": "project_not_found", "message": "프로젝트를 찾을 수 없습니다." }
  ]
}

客户端同时检查 HTTP 状态码和 errors[0].message 更为稳妥。由于服务器有时不返回消息，Web UI 仅在这种情况下才使用自带的兜底文案。

代理执行任务期间的进度以流式方式返回。对话（/api/session/{id}/message、/api/ask）和通知（/api/notifications/stream）属于此类。

事件共有以下七种。

读取到 done 或 error 为止即可。

图片等附件以 base64 内联传输。

{
  "name": "설비사진.png",
  "mime": "image/png",
  "dataBase64": "iVBORw0KGgo..."
}