> For AI agents: the complete documentation index is available at https://docs.reelway.ai/llms.txt, the full documentation bundle is available at https://docs.reelway.ai/llms-full.txt.

# 持久对话运行

长时间或高价值的对话不应被进程重启或网络抖动打断。持久对话运行(chat run)把一次对话变成**可恢复的服务端资源**:创建时即时受理并幂等去重,事件流可断线重放,费用在运行中预估并校正。


POSThttps://rcn.reelway.ai/v1/chat/runs鉴权:凭证

创建持久对话运行;Idempotency-Key 作用域 chat.runs.create;202 受理



GEThttps://rcn.reelway.ai/v1/chat/runs鉴权:凭证

分页列出;limit>100 归一 20



GEThttps://rcn.reelway.ai/v1/chat/runs/{id}鉴权:凭证

单条;不存在 404



POSThttps://rcn.reelway.ai/v1/chat/runs/{id}/cancel鉴权:凭证

取消;非可取消态 409(1006)



POSThttps://rcn.reelway.ai/v1/chat/runs/{id}/confirm-cost鉴权:凭证

费用确认(当前恒 409,见下)



SSEhttps://rcn.reelway.ai/v1/chat/runs/{id}/events/stream鉴权:凭证

SSE 事件流;Last-Event-ID 重放;终态后关流


## 创建

```bash
curl --fail-with-body https://rcn.reelway.ai/v1/chat/runs \
  -H "api-key: $REELWAY_API_KEY" \
  -H "Idempotency-Key: order-20261102-001" \
  -d '{
    "model": "qwen3.6-35b-a3b-gguf-iq4xs",
    "messages": [
      {"role": "system", "content": "你是客服工单整理助手。"},
      {"role": "user", "content": "整理这通电话的要点: …"}
    ]
  }'
```

- 请求体与[对话补全](https://docs.reelway.ai/api-reference/chat-completions.md)同形(`messages`/`model`/`stream` 等)。
- `202` 返回 `{chatRun}`,含 `id`、`status` 与初始事件序号。
- `Idempotency-Key` 作用域 `chat.runs.create`:同键同体重放返回首次响应;同键异体 `422`(`1012`)。
- `stream` 参数在 runs 语义下无意义(事件走 SSE),无需设置。

## 事件流

```
GET /v1/chat/runs/{id}/events/stream
```

- SSE 帧:`id: <seq>`、`event: <name>`、`data: <json>`;`Last-Event-ID` 断线重放;15 秒 keep-alive;终态后服务端主动关流。
- 收到 `run_status` 快照帧时直接跳过(供消费方对账,内容与最新 GET 相同)。
- 终态事件:`run_completed` / `run_failed` / `run_cancelled`。

### 事件类型

| 事件              | 语义                   |
| --------------- | -------------------- |
| `run_status`    | 运行整体状态快照(供消费方对账,可跳过) |
| `run_completed` | 成功终态,携带最终消息          |
| `run_failed`    | 失败终态                 |
| `run_cancelled` | 已取消                  |

:::warning 事件集合以运行时为准
上表仅列当前实现确认的事件;后续版本可能增加事件而不移除既有名称。消费方应对未知事件名保持宽容(记录并跳过)。
:::

## 查询与取消

- `GET /v1/chat/runs` 返回 `{chatRuns[]}`,`limit` 归一上限 20;`GET /v1/chat/runs/{id}` 返回 `{chatRun}`。
- `cancel` 对非可取消态返回 `409`(`1006`)——先读状态再决定动作。
- `confirm-cost` 为 Sogni 兼容保留形状:当前引擎无「费用审批暂停」阶段,任何时刻调用都返回 `409`(`1006`)。未来引入费用审批时,该端点按 Sogni 语义激活。详见[计费与成本控制](https://docs.reelway.ai/intelligence/billing-and-cost-control.md)。

## 状态与生命周期

```
created → running → run_completed | run_failed | run_cancelled
```

`run_failed` 与 `run_cancelled` 的运行同样保留事件历史,可随时用 `Last-Event-ID` 回放对账。

## 另见

- [对话补全](https://docs.reelway.ai/api-reference/chat-completions.md) —— 无状态单次调用
- [生产集成](https://docs.reelway.ai/api-reference/production-integrations.md) —— 无服务器模式下的轮询与恢复
- [Reelway Intelligence 简介](https://docs.reelway.ai/intelligence/introduction.md) —— 面向构建者的全景