主动触发一次异步记忆整理任务。
POST /api/v1/forward/dreams
Dream 可以直接整理一个 Memory Store,也可以整理指定 Identity 与 Template 的 Default Memory。接口返回后任务在后台执行,调用方可通过详情或列表接口查询状态。
请求头
| Header | 是否必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <PAT 或管理员 SAT>。 |
Content-Type | 是 | 固定为 application/json。 |
请求体参数
| 字段 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
inputs | object[] | 是 | — | 输入列表。必须包含且仅包含一个 memory_store 或 identity_template 主要输入,可以附加 sessions 输入。 |
model | string | object | null | 否 | auto | 模型 ID 或 Dream model 对象,可指定思考深度和上下文窗口。省略或传 null/空字符串时使用 auto。 |
instructions | string | 否 | "" | 自定义整理指令,UTF-8 编码后最多 4096 字节(多字节字符会占用多个字节)。 |
inputs 元素
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
type | string | 是 | 输入类型:memory_store、identity_template 或 sessions。 |
memory_store_id | string | 条件必填 | type=memory_store 时必填;指定当前调用方可访问的 Memory Store。 |
identity_id | string | 条件必填 | type=identity_template 时必填。 |
template_id | string | 条件必填 | type=identity_template 时必填。 |
session_ids | string[] | 条件必填 | type=sessions 时必填且不能为空;所有 sessions 输入合计最多 100 个 Session ID。 |
identity_template 输入不能同时携带 memory_store_id。
两种主要输入的处理方式见 Dream input。
model 对象
旧字符串请求仍受支持,例如 "model": "auto"。也可传对象:
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
id | string | 是 | 非空模型 ID。使用 列出模型 返回的可用且启用的 ID。 |
effort | string | 否 | 思考深度:none、low、medium、high、xhigh、max。除 none 外,必须在所选模型的 efforts 中;none 表示显式关闭思考。 |
context_window | integer | 否 | 上下文窗口 token 数,必须为正整数。模型有非空 available_context_windows 时必须选其中一个值;目录未声明档位时不做档位限制。 |
- 两个选项可独立省略;显式传 null、空 effort、零或负窗口等非法值返回 400。
- 整个
model省略、为 null 或空白字符串时按auto处理;对象必须包含非空id,{}不等价于 auto。 auto带选项时,模型目录必须存在可用且支持相应选项的条目。对象只支持上述三个字段;未知字段返回 400,error.param指向对应字段。- 上例仅演示格式;使用前查询当前身份可用的模型及参数。
示例请求
整理 Identity 与 Template 的 Default Memory:
示例响应
HTTP 201 Created
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| 返回值 | object | 新创建的 Dream 对象。 |
错误
| HTTP | Type | 触发条件 |
|---|---|---|
400 | invalid_request_error | 请求体或输入组合不合法、模型不可用、模型选项无效或含未知字段;error.code 可能为 invalid_dream_inputs、too_many_sessions、invalid_model 或 instructions_too_long。 |
401 | authentication_error | 认证信息缺失、无效或已过期。 |
403 | permission_error | 当前令牌不能管理 Dream;Identity SAT 不支持此接口。 |
404 | not_found_error | Memory Store 不存在或不可访问,或者指定的 Identity、Template、Default Memory 不存在;error.code 为 memory_store_not_found 或 dream_scope_not_found。 |
409 | invalid_request_error | 当前个人空间或 Workspace 已有 pending 或 running 状态的 Dream。 |
413 | invalid_request_error | 请求体超过大小限制。 |
429 | rate_limit_error | 请求频率或并发达到限制。 |
500/502/503 | api_error | 服务或内部依赖暂时不可用。 |