跳到主要内容

会话与消息

会话是某一个终端用户的一次对话。用户发出的每一条消息都会开启一个任务——助手的回答——它在会话的事件流上流式发送，并保存在会话的消息列表里。下面这些调用都使用终端用户的令牌。

创建会话​

curl -s "$NEWEYES_API_BASE/v1/sessions" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"output_format": "a2ui", "text": "What can I cook with leeks and potatoes?"}'
  • output_format 决定会话整个生命周期内回复的形式：
    • a2ui（默认）：回复是由你的应用用 A2UI 渲染器渲染的界面数据，界面之外说的话以纯文本给出。详见 A2UI 回复。
    • markdown：回复是格式化的 Markdown 文字。
  • capabilities 或 exclude_capabilities 决定助手在这个会话里能用哪些能力，同样在会话的整个生命周期里不变：只开列出的，或除了列出的全开。两个都不传就全部打开。见为会话选择能力。
  • text 可选。带上它，第一个任务会立刻开始，响应里会有它的 task_id 和 last_event_id。不带则创建一个空会话，空会话不需要余额。
  • attachments 随 text 一起，用法和后续消息相同（见下文）。

响应是会话本身：

字段含义
id会话标识。
type文字对话为 text，语音通话为 realtime。
statuscreated、queued、running、completed、failed、stopped 或 timeout。
output_formata2ui 或 markdown。
brief_status语音会话的纪要是否已就绪。
created_at、ended_at开始时间；结束时间，进行中为 null。
capabilities助手在这个会话里能用的能力。
task_id、last_event_id只在创建时返回：第一个任务，以及它在事件流上的起点。

发送消息​

curl -s "$NEWEYES_API_BASE/v1/sessions/$SESSION_ID/messages" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"text": "Make it vegetarian."}'
{ "object": "task", "task_id": "exec-5a2c…", "session_id": "9c1e…", "last_event_id": "1760860912345-0" }
  • text 是用户说的话：1 到 32,000 个字符。
  • 响应为 202 Accepted，带上它开启的任务。从 last_event_id 开始在事件流上跟踪它；或者发送 "stream": true，直接在这个请求上接收——详见事件流。
  • 一次一个任务。 任务运行期间发送新消息，会被拒绝并返回 409 session_busy。等任务的结束帧，或先停止它。
  • 语音会话不接受文字消息（409 session_not_taskable）。
  • 开启任务需要可用余额（否则返回 429 insufficient_credits）。

附带媒体​

一条消息最多可以附带 10 个图片或视频：

{
  "text": "Which of these two rooms gets more light?",
  "attachments": [
    { "file_id": "3d0f…" },
    { "file_data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…" }
  ]
}

每个附件是以下两者之一：

  • file_id：用户用 POST /v1/files 上传的文件。较大的内容（例如视频）请用这种方式。
  • file_data：文件内容的 base64，直接内嵌，最大 10 MB。可以带 data:…;base64, 前缀。

音频不能作为消息附件（422 unsupported_media_type）；请用 POST /v1/audio/transcriptions 转成文字后再发送。

回应界面操作​

在 a2ui 会话里，用户通过操作界面——点按钮、提交表单——发出的消息，会在 a2ui_action 里带上渲染器给出的操作。详见 A2UI 回复。

停止任务​

curl -s "$NEWEYES_API_BASE/v1/sessions/$SESSION_ID/stop" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN"

正在运行的任务会以 task.stopped 帧结束，帧里带着回复到目前为止的内容。响应给出被停止任务的 task_id；没有任务在运行时为 null。

读取对话​

curl -s "$NEWEYES_API_BASE/v1/sessions/$SESSION_ID/messages?limit=50" \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN"

列表按对话顺序排列，并分页。每一项都有 type：

type含义
user_message用户发出的内容：content 及其 attachments。
assistant_message一条回复：content、attachments（它生成的图片、视频、音频和文件）、suggestions，以及写下它的任务的 task_id。
status_update关于某个任务的通知，例如任务失败，带 error。
activity助手执行的一个步骤。仅在 verbose=true 时列出。
  • 附件的 url 是每次读取时重新签发的下载链接，在其 expires_at（一小时）后失效。重新读取列表即可得到新链接。
  • 较早的消息会随时间归档，归档可能改变消息的 id。请按 task_id 匹配回复，而不是按 id。游标在归档前后都能保持位置。
  • 语音会话列出的是它的转写内容。

列出、读取和删除会话​

调用作用
GET /v1/sessions用户的会话，按从新到旧。已删除的不会列出。
GET /v1/sessions/{session_id}一个会话。
DELETE /v1/sessions/{session_id}删除它：此后不再出现在列表或读取中。

语音会话在通话仍连接时不能删除（409 call_in_progress）。如果清理会话的存储数据失败，什么都不会被删除，调用返回 503：请重试。

会话只对拥有它的终端用户可见；读取其他用户的会话，结果为 404 session_not_found。