Playground API

网页界面的 Playground 完全通过这些接口工作，脚本也可以用它们做同样的事：保存对话、流式获取回复、运行工具并答复批准请求。发给模型的所有内容（系统提示词、文件文字、图片描述、之前的工具调用）都在服务端组装，客户端只需说明要添加什么、加在哪里。

这些接口属于管理 API（见管理 API）：

• 基础地址：http://127.0.0.1:10600/api/v1/playground。
• 认证：设置了 server.access_token 时使用 Authorization: Bearer <工具访问密钥>（见访问与安全），不是模型 API 密钥。
• 错误：JSON 响应体 {"code": "...", "message": "...", "detail": {}}，状态码为 400（invalid_input）、404（not_found）或 409（conflict）。
• 运行中服务的 /docs 和 /openapi.json 列出了全部字段（见 API 概览）。

示例中用 ACCESS_KEY 表示工具访问密钥：

export ACCESS_KEY=your-tool-access-key
BASE=http://127.0.0.1:10600/api/v1/playground

接口一览复制锚点链接

对话复制锚点链接

对话是一棵消息树。每条消息记录它所跟随的消息（parent_id，第一条为 null），因此编辑或重试会在原消息旁边新增一个兄弟节点，而不是替换它。current_leaf 是当前显示路径的最后一条消息；从第一条消息到它的路径就是发给模型的内容。

对话对象复制锚点链接

GET /conversations 和 PATCH 返回摘要（不含 current_leaf 和 messages）；POST /conversations、GET /conversations/{id} 和 POST .../branch 返回完整对话。

工具开关名为 read、apply_patch、shell、terminal、web_search 和 web_fetch，其他名称返回 400。当 playground.tools 或对话的 tools_on 包含某个工具、且 tools_off 不包含它时，对话使用该工具。

创建复制锚点链接

curl -X POST $BASE/conversations \
  -H "Authorization: Bearer $ACCESS_KEY" -H "Content-Type: application/json" \
  -d '{"model": "your-model", "tools_on": ["read"], "approval": "ask"}'

修改复制锚点链接

PATCH /conversations/{id} 只修改给出的字段：

修改不会改变 updated_at：只有新消息会让对话在列表中上移。

删除复制锚点链接

DELETE /conversations/{id} 删除对话、其消息和只属于它的附件，停止它的后台命令，并清除它的 始终允许 答复。

消息复制锚点链接

提示复制锚点链接

发送消息复制锚点链接

POST /conversations/{id}/messages 添加一个问题并流式返回回复。

模型和推理强度会成为对话的当前值。以流的方式读取响应：

curl -N -X POST $BASE/conversations/$CID/messages \
  -H "Authorization: Bearer $ACCESS_KEY" -H "Content-Type: application/json" \
  -d '{"parent_id": null, "content": "What is in the workspace?"}'

事件流复制锚点链接

响应类型为 text/event-stream。每个事件是一行 data:，内容为一个 JSON 对象，用 type 表示事件类型：

reasoning 和 delta 在最后一个步骤类型相同时追加到该步骤，否则开始新步骤。没有其他内容时（工具运行中或等待批准），每 2 秒发送一行注释 : ping；以 : 开头的行直接跳过即可。

一个包含一次工具调用的回复大致如下（消息已省略部分字段）：

data: {"type": "user", "message": {"id": "94bc…", "parent_id": null, "role": "user", "content": "What is in the workspace?", "status": "complete", …}}

data: {"type": "assistant", "message": {"id": "5828…", "parent_id": "94bc…", "role": "assistant", "content": "", "model": "your-model", "status": "streaming", …}}

data: {"type": "delta", "text": "Let me look."}

data: {"type": "tool", "step": {"type": "tool", "id": "call_1", "name": "read", "arguments": "", "status": "pending", "output": "", "exit_code": null, "ms": 0, "meta": {}, "approval": "", "round": 0}}

data: {"type": "tool", "step": {"type": "tool", "id": "call_1", "name": "read", "arguments": "{\"path\": \".\"}", "status": "running", …}}

data: {"type": "tool", "step": {"type": "tool", "id": "call_1", "name": "read", "arguments": "{\"path\": \".\"}", "status": "done", "output": "Directory /home/me/.hoshimi/workspace:\n(empty)", "meta": {"path": "/home/me/.hoshimi/workspace", "entries": 0}, …}}

data: {"type": "delta", "text": "The workspace is empty."}

data: {"type": "done", "message": {"id": "5828…", "content": "Let me look.\n\nThe workspace is empty.", "status": "complete", "steps": [ … ], …}}

流的结束方式：

• 问题保存之前发现的错误（没有模型、parent_id 或附件不存在）直接以 400 或 404 返回，而不是流。
• 之后模型或站点返回的错误会让回复以 error 结束，流仍以 done 收尾。
• 关闭连接会停止回复：正在运行的工具被要求停止，等待中的批准被取消，回复连同已生成的内容保存为 stopped。之后不会再有 done。

重试复制锚点链接

POST /conversations/{id}/messages/{message_id}/retry 流式生成另一条回复，事件与发送相同，只是没有 user。message_id 可以是一条回复（新回复与它并列），也可以是一个还没有回复的问题（为它生成第一条回复）。

步骤复制锚点链接

调用过工具或被补充说明过的回复会按顺序保存其 steps。每个步骤都有 type 和 round（从 0 开始，每轮工具调用加一）：

工具步骤的 status：

output 是发给模型的内容（最多 32,000 个字符）。meta 是页面在旁边显示的信息：

运行中被停止的调用还会带有 "cancelled": true。对话再次发给模型时，每一轮会还原为：该轮的补充消息、一条带 tool_calls 的 assistant 消息，以及每次调用对应的 tool 消息；没有开启工具时，调用及其结果以文字形式发送。

批准复制锚点链接

status 为 waiting 的 tool 事件需要答复。用该步骤的 id 发送：

curl -X POST $BASE/conversations/$CID/approvals/call_1 \
  -H "Authorization: Bearer $ACCESS_KEY" -H "Content-Type: application/json" \
  -d '{"decision": "allow"}'

成功返回 204；没有等待中的对应调用时返回 404。调用最多等待 10 分钟，之后视为拒绝。随后流中会发送该调用的下一个状态。哪些调用需要等待取决于审批模式（见 Playground 工具）。

补充说明复制锚点链接

POST /conversations/{id}/steer，请求体 {"content": "..."}，向正在进行的回复发送消息而不停止它。返回 202 和 {"id": "steer_…"}。

• 模型在下一轮开始时（当前调用完成后）读取它；随后流中发送一个 steer 事件，其步骤带有这个 id。
• 在模型收尾时发送的消息会让回复再继续一轮来回应它。
• 没有回复能接收时返回 409：没有回复在运行、运行中的回复没有工具，或回复刚刚结束。此时请把它作为新消息发送。
• 消息为空时返回 400。

回复停止或失败时仍在排队的消息不会被读取。

后台命令复制锚点链接

GET /conversations/{id}/terminals 列出该对话的工具启动的后台命令（exec_command 会话），包括仍在运行的，以及已退出但模型尚未读取其输出的：

{
  "terminals": [
    {"id": 1, "command": "npm run dev", "cwd": "/home/me/.hoshimi/workspace", "started_at": 1792684330.35, "running": true, "exit_code": null}
  ]
}

DELETE /conversations/{id}/terminals/{session_id} 停止其中一个及其启动的所有进程（204；不属于该对话时返回 404）。删除对话或服务停止时，它们也会停止。

附件复制锚点链接

先上传文件，再把它的 id 放进 attachment_ids 发送。请求体就是文件本身：

curl -X POST "$BASE/attachments?name=photo.png&width=1024&height=768" \
  -H "Authorization: Bearer $ACCESS_KEY" -H "Content-Type: image/png" \
  --data-binary @photo.png

curl -X POST "$BASE/attachments?name=notes.md" \
  -H "Authorization: Bearer $ACCESS_KEY" -H "Content-Type: text/plain; charset=utf-8" \
  --data-binary @notes.md

Content-Type 决定保存方式：image/png、image/jpeg、image/webp 或 image/gif 作为图片保存；任意 text/* 类型，或 application/json、xml、yaml、x-yaml、javascript、x-sh、sql、toml，作为 UTF-8 文本保存。其他类型或空请求体返回 400。服务端按收到的内容保存：缩小图片和提取 PDF 文字都由网页界面在上传前完成。文件文字发给模型时最多 200,000 个字符。

响应为附件对象：id、kind、name、mime、size、width、height。

• GET /attachments/{id} 按图片自身的类型返回图片，文件以 text/plain 返回。
• DELETE /attachments/{id} 在发送前撤回附件（204）；已被消息携带的附件返回 400。
• 从未发送的附件会在一天后删除。

上下文与压缩复制锚点链接

GET /conversations/{id}/context 返回屏幕上的对话相对于模型上下文窗口的占用情况：

POST /conversations/{id}/compact 立即压缩对话，可附带 instructions（总结应关注的内容）。它依次推送 checkpoint（保存后的检查点消息，步骤状态为 running）和 done（最终保存的结果）。done 的 status 为 error 表示失败，对话保持原样；断开连接也会同样停止。有回复正在运行时返回 409，没有可压缩的内容（上次压缩后没有新回复）时返回 400。下一个问题以检查点的 ID 作为 parent_id 发送。

回复也会自行压缩对话（回复开始时、两轮工具调用之间，以及站点以过长为由拒绝某一轮时），表现为 compaction 事件和 compaction 步骤。从压缩点起，模型收到的是此前全部内容的总结（作为一条用户消息，后接一条确认），复制为 API 请求 可以看到。

标题、分支、请求与会话复制锚点链接

• POST /conversations/{id}/title 让模型根据第一轮问答为对话命名，并等待模型完成。使用 playground.title_model，未设置则用对话自身的模型。临时对话、已由模型命名的对话和你自己设置了标题的对话保持不变；模型调用失败时标题也不变。返回对话摘要。
• POST /conversations/{id}/branch，请求体 {"message_id": "..."}，新建一个对话，包含截至该消息的路径（使用新的 ID），沿用标题、模型、推理强度、工具和审批模式，并设置 branched_from。返回 201 和完整对话。
• GET /conversations/{id}/messages/{message_id}/request 返回某条回复背后的 Chat Completions 请求体（对问题则是将用来回答它的请求）：model、messages、stream: true，设置了推理强度时有 reasoning_effort，开启了工具时有 tools 和 tool_choice。使用了工具的回复返回的是第一轮的请求。这就是网页界面的 复制为 API 请求。
• GET /session 返回 {"conversation_id": "..."}，即上次打开的对话（没有，或该对话是临时对话或已删除时为 null）。PUT /session 用同样的请求体设置它（新对话时为 null）；ID 不存在时返回 400。网页界面启动时会重新打开它。

一次性聊天与模型列表复制锚点链接

• POST /chat/completions 接受 OpenAI Chat Completions 请求（见 OpenAI 兼容 API），响应与 /v1/chat/completions 相同，但使用工具访问密钥而不是模型 API 密钥，并以 playground 来源记录在用量中。请求中没有 system 或 developer 消息时，先发送 playground.system_prompt。不会保存为对话。
• GET /models 返回与 GET /v1/models 相同的列表。

通过对话生成的回复、标题和图片描述分别以 playground、playground-title 和 playground-vision 来源记录。