> 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.

# 生产集成

本页汇总把 Reelway 接入生产系统时需要一次性想清楚的事:钱从哪里扣、用哪条路径接、会碰到哪些上限、哪些错误必须有代码处理。

## 生产负载的计费

- 所有付费操作从**账户余额**扣除;余额查询 `GET /v4/account/balance`,流水 `GET /v1/transactions/list`。
- 扣费发生在**受理时**(按预估),完成后校正为实际用量;失败与无产物不计费。
- 为每个生产系统使用独立的[子 Key](https://docs.reelway.ai/api-reference/api-keys.md),并为其设置限额,把单点泄露或失控重试的损失限制在可控范围内(触顶返回 `402` / `1013`)。
- 分销场景下,下级账户的余额与费率在分销商侧管理,见[分销体系](https://docs.reelway.ai/pricing/reseller.md)。

## 选择集成路径

### 无服务器模式(REST)

适合函数计算、队列消费者等没有长连接的环境:

1. `POST /v1/creative-agent/workflows`(或 `POST /v1/chat/runs`)并携带 `Idempotency-Key`;
2. 持久化返回的资源 `id`;
3. 以 `GET …/{id}/events?after=<seq>` 轮询,或在能保持连接的组件中订阅 `GET …/{id}/events/stream`(SSE,支持 `Last-Event-ID` 重放);
4. 终态事件后下载产物。

优点:函数重试天然安全(幂等键);无需维护 WebSocket。代价:进度粒度以事件为单位。预览创意工作流执行器 M1 为占位
### 长连接 SDK 模式(WebSocket)

适合常驻服务与交互式前端:

1. `SogniClient.createInstance({ appId, network, apiKey })` 建立 artist 通道;
2. 用 `projects.create()` 提交,监听 `progress` / `completed` / `failed` 事件;
3. 进程重启后调用 `GET /api/v1/artist/projects/sync` 拉取恢复快照(`activeProjects` + `unclaimedCompletedProjects`),或直接读 `GET /v2/projects/{id}`。

优点:实时进度与预览、即时取消。注意:**同一账号 + 同一 `appId` 的新连接会以关闭码 `4015` 接管旧连接**,多实例部署时请为每个实例使用不同的 `appId`。

## 限制

### 渲染容量

- 单次 `jobRequest` 的 `numberOfImages` 受模型与网络限制;视频模型通常为 1。
- `network: 'fast'` 优先派发到就绪节点;`relaxed` 允许更长排队换取更低优先级成本。队列规则见[公平使用队列](https://docs.reelway.ai/pricing/fair-use-queue.md)。
- 单帧上限:artist 通道 1 MiB;图像与媒体请通过预签名 URL 上传,不要内联到帧中。

### 创意工作流

- 请求体 ≤ 1 MiB;严格解码(未知字段 `400` / `1010`);
- 事件列表接口 `…/events` 单次最多返回 500 条,请用 `after` 分页;
- 事件流 15 秒 keep-alive,终态事件后服务端主动关流。

### 连接

- 服务端每 25 秒 ping、60 秒 pong 窗口,超时断开;SDK 自动重连,自实现客户端需响应 ping。
- 并发会话超上限返回 `409`(`4027`)。

## 必须处理的错误

| 错误                           | 来源                     | 处理                                        |
| ---------------------------- | ---------------------- | ----------------------------------------- |
| `401` / `101`                | 凭证无效或已吊销               | 停止重试;轮换 Key。WebSocket 表现为关闭码 `4021`       |
| `402` / `1005`               | 余额不足                   | 暂停提交,告警充值;已在途任务不受影响                       |
| `402` / `1013`               | 单 Key 限额触顶             | 提高限额或切换 Key                               |
| `429` / `126`                | 创建限频                   | 按 `Retry-After`(60 秒)退避,指数回退              |
| `400` / `1002` `1014`        | 模型不在目录 / 无价格行          | 刷新目录(`GET /v1/model-catalog`,支持 ETag);换规格 |
| `400` / `1010`               | 未知字段                   | 升级 SDK 后对照文档逐字段核对请求体                      |
| `409` / `1006`               | 状态机非法迁移                | 先读当前状态再决定动作;不要盲目重试                        |
| `422` / `1012`               | 幂等键异体                  | 为新请求生成新键                                  |
| `422` / `1007` `1008`        | DAG 环 / `dependsOn` 缺失 | 修正工作流定义                                   |
| `jobError` 帧 `5000` / `5001` | 节点执行失败 / 节点断线          | 任务不计费;可按原参数重新提交                           |

OpenAI 兼容推理面(`api.reelway.ai/v1`)的错误为 OpenAI 形状(`error.type` / `error.code` / `error.message`),请复用你为 OpenAI 写的错误处理。

## 上线清单

- [ ] 为该系统创建独立子 Key 并设置限额;Key 仅存在于服务端密钥管理中
- [ ] 所有付费 `POST` 携带 `Idempotency-Key`,并把键与业务请求一同持久化
- [ ] 实现 `429` 指数退避(下限取 `Retry-After`)与 `401` 立即停止
- [ ] 产物 URL 48 小时过期:完成后立即转存到自有存储
- [ ] 多实例部署时 `appId` 按实例唯一;重启后以 `projects/sync` 或 `GET /v2/projects/{id}` 恢复
- [ ] 监控 `GET /v4/account/balance`,设置余额阈值告警
- [ ] 订阅 `GET /v1/announcements/active` 获取平台公告(模型上下线、维护窗口)