API 概述

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

基准地址

Studio API 的基准地址为 /api/v1。

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

旧路径 /api/... 仍然有效（作为别名）。本文档示例中仍写着 /api/... 的部分也可以直接使用，但新编写的代码请使用 /api/v1。

请勿与平台的 v5 混淆

这不是同一个 API 的两个版本，而是不同的产品，监听器也不同。

	是什么	路径
Studio API	Studio 自身的 API（本文档）	`/api/v1`
平台 API	Studio 创建的应用在自己的源上调用的代理	`/api/v5`

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

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..."
}