> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 Dream

> 触发一次异步记忆整理任务。

`POST /api/v1/cloud/dreams`

创建一个 Dream，系统将异步整理指定的 Memory Store。返回 [Dream 对象](/cloud-agents/api/dreams/schemas#dream-对象)。

## 请求头

| 头部              | 必选 | 说明                 |
| --------------- | -- | ------------------ |
| `Authorization` | 是  | `Bearer <PAT>`     |
| `Content-Type`  | 是  | `application/json` |

## 请求体

| 字段             | 类型     | 必选 | 说明                                                   |
| -------------- | ------ | -- | ---------------------------------------------------- |
| `inputs`       | array  | 是  | 输入列表。必须包含一个 `memory_store` 类型输入，可选包含 `sessions` 类型输入 |
| `model`        | string | 否  | 模型选择：`auto`（默认）、`lite`、`ultimate`                    |
| `instructions` | string | 否  | 自定义整理指令，最长 4096 字符                                   |

### inputs 元素

| 字段                | 类型     | 说明                                          |
| ----------------- | ------ | ------------------------------------------- |
| `type`            | string | `"memory_store"` 或 `"sessions"`             |
| `memory_store_id` | string | 当 type 为 `memory_store` 时必填                 |
| `session_ids`     | array  | 当 type 为 `sessions` 时必填，最多 100 个 Session ID |

## 示例请求

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/cloud/dreams' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      { "type": "memory_store", "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4" },
      { "type": "sessions", "session_ids": ["sess_019e7a1b2c3d4e5f6a7b8c9d0e1f2a3b"] }
    ],
    "model": "auto",
    "instructions": "重点关注用户对代码风格的偏好修正"
  }'
```

## 示例响应

**HTTP 201 Created**

```json theme={null}
{
  "id": "drm_019e86b4a8f070a3b6c5d4e3f2a1b0c9",
  "type": "dream",
  "status": "pending",
  "inputs": [
    { "type": "memory_store", "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4" },
    { "type": "sessions", "session_ids": ["sess_019e7a1b2c3d4e5f6a7b8c9d0e1f2a3b"] }
  ],
  "outputs": [],
  "model": { "id": "auto" },
  "instructions": "重点关注用户对代码风格的偏好修正",
  "session_id": null,
  "usage": { "input_tokens": 0, "output_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0 },
  "error": null,
  "created_at": "2026-06-15T10:00:00Z",
  "ended_at": null,
  "archived_at": null
}
```

## 错误码

| HTTP | Type                    | 触发条件                                                                                          |
| ---- | ----------------------- | --------------------------------------------------------------------------------------------- |
| 400  | `invalid_request_error` | inputs 为空、缺少 memory\_store 输入、重复 memory\_store、sessions 超过 100 个、model 不在允许列表、instructions 超长 |
| 401  | `authentication_error`  | 缺少或无效的认证令牌                                                                                    |
| 404  | `not_found_error`       | memory\_store\_id 引用的 Memory Store 不存在或不可访问                                                   |
| 409  | `invalid_request_error` | 用户已有一个活跃的 Dream（pending 或 running）                                                            |

完整错误信封说明详见 [错误参考](/cloud-agents/api/conventions/errors)。