生产集成

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

生产负载的计费

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

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

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

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

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

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

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

错误	来源	处理
`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 写的错误处理。