--- url: https://docs.reelway.ai/api-reference/index.md --- > 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. # 你的下一个想法,有 API。 Reelway 提供两组互补的 HTTP 接口面,分别服务于「通用推理」与「创意生成」两类负载: | 接口面 | 基址 | 适用 | | ---------------- | ------------------------------------------------------------------------ | ------------------------------------------------ | | **OpenAI 兼容推理面** | `https://api.reelway.ai/v1` | 对话补全、LLM 模型列表;任何 OpenAI SDK 只需改 `baseURL` 即可直接使用 | | **Sogni 兼容创作面** | `https://rcn.reelway.ai`(REST)/ `wss://rcn.reelway.ai/socket`(WebSocket) | 图像/视频生成项目、媒体上传、资产库、个人 LoRA、创意工作流、持久对话运行、账户与余额 | 两组接口共用同一套 API Key(在[控制台 → API Keys](https://dashboard.reelway.ai/console/keys) 创建)。 ## 第一次调用 **curl** ```bash # 查询余额:验证 Key 可用 curl --fail-with-body https://rcn.reelway.ai/v4/account/balance \ -H "api-key: $REELWAY_API_KEY" # OpenAI 兼容对话补全 curl --fail-with-body https://api.reelway.ai/v1/chat/completions \ -H "Authorization: Bearer $REELWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen3.6-35b-a3b-gguf-iq4xs", "messages": [{"role": "user", "content": "用一句话介绍 Reelway。"}] }' ``` **JavaScript** ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.reelway.ai/v1', apiKey: process.env.REELWAY_API_KEY, }); const completion = await client.chat.completions.create({ model: 'qwen3.6-35b-a3b-gguf-iq4xs', messages: [{ role: 'user', content: '用一句话介绍 Reelway。' }], }); console.log(completion.choices[0].message.content); ``` ## 选择下一步 ### 入门 - [快速开始](https://docs.reelway.ai/api-reference/getting-started.md) —— 基址、认证、版本、错误、限流、幂等与计费,适用于每一个端点 - [API Keys](https://docs.reelway.ai/api-reference/api-keys.md) —— 创建、复制、吊销与安全使用 - [生产集成](https://docs.reelway.ai/api-reference/production-integrations.md) —— 重试、恢复、超时与必须处理的错误 ### 生成 - [生成配方](https://docs.reelway.ai/api-reference/direct-generation.md) —— `jobRequest` 帧提交图像与视频项目:t2i / t2v / i2v / flf2v / r2v - [项目状态 API](https://docs.reelway.ai/api-reference/project-status.md) —— `GET /v2/projects/{id}`、`GET /v1/projects/{id}`、`GET /v1/jobs/list` - [媒体工具与语音](https://docs.reelway.ai/api-reference/media-utilities.md) —— 上传预签名 URL、资产库状态机、CosyVoice 3 语音合成 - [个人 LoRA](https://docs.reelway.ai/api-reference/personal-loras.md) —— `POST /v1/loras/personal` 导入与目录 ### 对话与智能体 - [对话补全](https://docs.reelway.ai/api-reference/chat-completions.md) —— `POST /v1/chat/completions`(OpenAI 兼容,支持流式) - [直接工具执行](https://docs.reelway.ai/api-reference/tool-execution.md) —— `POST /v1/creative-agent/tools/execute` - [LLM 模型](https://docs.reelway.ai/api-reference/llm-models.md) —— `GET /v1/models` - [持久对话运行](https://docs.reelway.ai/api-reference/chat-runs.md) —— `POST /v1/chat/runs` 与 SSE 事件流 - [创意工作流](https://docs.reelway.ai/api-reference/workflows.md) —— `POST /v1/creative-agent/workflows` 多步 DAG 编排 - [工作流模板](https://docs.reelway.ai/api-reference/templates.md) —— `compose_workflow_template` 托管工具 - [回放记录](https://docs.reelway.ai/api-reference/replay.md) —— `POST /v1/replay/records` ### 媒体与账户 - [媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md) —— `GET /v1/image|media/uploadUrl|downloadUrl` - [余额与用量](https://docs.reelway.ai/api-reference/account-and-usage.md) —— `GET /v4/account/balance`、`GET /v1/transactions/list` ### 网络 - [节点分析](https://docs.reelway.ai/api-reference/worker-analytics.md) —— 节点车队观测与模型需求 - [模型与网络需求](https://docs.reelway.ai/api-reference/model-discovery.md) —— `GET /v1/model-catalog`、`GET /v1/model-demand` ### 资源 - [SDK 与资源](https://docs.reelway.ai/api-reference/sdks.md) —— `@reelway/client`、llms.txt、示例仓库 :::info 版本号混用是正常的 与 Sogni 一致,路径中同时存在 `/v1`、`/v2`、`/v4` 前缀(例如 `GET /v2/projects/{id}` 与 `GET /v4/account/balance`)。版本号附着于单个端点而非整个 API,请按本参考中给出的路径原样调用。 ::: --- url: https://docs.reelway.ai/api-reference/getting-started.md --- > 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. # 快速开始 本页内容适用于参考中的每一个端点:API 在哪里、如何认证、错误与限流如何表现、费用如何结算。通读一遍,然后开始构建。 ## 简介 Reelway 提供两个基址,按负载类型分流: | 基址 | 承载 | 说明 | | --------------------------- | ------------ | ------------------------------------------------------------------------------------ | | `https://api.reelway.ai/v1` | OpenAI 兼容推理面 | `POST /v1/chat/completions`、`GET /v1/models`。由推理网关承载,支持流式(SSE)响应与分销计费 | | `https://rcn.reelway.ai` | Sogni 兼容创作面 | 其余全部 REST 端点(`/v1`、`/v2`、`/v4`、`/api/v1-4`)与 WebSocket `wss://rcn.reelway.ai/socket` | `rcn` 即 **Reelway Collaboration Network**,是生成任务实际派发到 GPU 节点的网络入口。 ### 这里有什么 - **生成**:通过 WebSocket `jobRequest` 帧提交图像/视频项目,实时接收进度与结果;通过 `GET /v2/projects/{id}` 等端点查询投影。 - **对话与智能体**:OpenAI 兼容对话补全、持久对话运行(`/v1/chat/runs`)、多步创意工作流(`/v1/creative-agent/workflows`)与同步托管工具。 - **媒体**:预签名上传/下载 URL、可复用资产库(`/v1/assets`)、个人 LoRA 导入。 - **账户与网络**:余额、流水、模型目录与网络需求。 ### 快速开始 **curl** ```bash export REELWAY_API_KEY="rw_…" # 在 https://dashboard.reelway.ai/console/keys 创建 # 1. 验证 Key:查询余额(标准信封) curl --fail-with-body https://rcn.reelway.ai/v4/account/balance \ -H "api-key: $REELWAY_API_KEY" # 2. 列出可用生成模型(公开,无需凭证) curl https://rcn.reelway.ai/v1/model-catalog # 3. OpenAI 兼容对话补全(流式) curl -N https://api.reelway.ai/v1/chat/completions \ -H "Authorization: Bearer $REELWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"qwen3.6-35b-a3b-gguf-iq4xs","stream":true,"messages":[{"role":"user","content":"你好"}]}' ``` **JavaScript(SDK)** ```js import { SogniClient } from '@reelway/client'; // 默认端点即 https://rcn.reelway.ai 与 wss://rcn.reelway.ai/socket,无需配置 const client = await SogniClient.createInstance({ appId: 'my-app', // 每个客户端实例唯一;同账号同 appId 的新连接会接管旧连接 network: 'fast', apiKey: process.env.REELWAY_API_KEY, }); const project = client.projects.create({ modelId: 'z_image_turbo_bf16', positivePrompt: '赛博朋克雨夜街道,霓虹倒影,电影级构图', numberOfImages: 1, }); project.on('progress', (p) => console.log('进度', p)); const urls = await project.waitForCompletion(); console.log(urls); ``` ## 认证 所有需要凭证的端点都接受 API Key。将 Key 放在请求头中,**绝不要放在 URL 里**: ```bash curl --fail-with-body https://rcn.reelway.ai/v1/account/me \ -H "api-key: $REELWAY_API_KEY" ``` ### 两种凭证形态 | 凭证 | 头形态 | 说明 | | ----------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **API Key** | `api-key: ` 或 `Authorization: Bearer ` | 在[控制台](https://dashboard.reelway.ai/console/keys)创建,服务端按 SHA-256 查表,状态为 `active` 时放行。详见 [API Keys](https://docs.reelway.ai/api-reference/api-keys.md) | | **会话 JWT** | `Authorization: ` 或 `Authorization: Bearer ` | 由 `POST /v1/account/login` 签发,`refreshToken` 轮换;主要供 Web 应用与 SDK 的账号登录模式使用 | 两种形态可混用于同一个 `Authorization` 头:服务端按值中是否含两个 `.` 分流为 JWT 或 Key。 **WebSocket 握手**使用同一套凭证:`api-key` 头(或 JWT),外加查询串 `?appId=`(必填)。GPU 节点另需 `client-type: worker` 与 `app-id` 头,详见[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md)。 :::warning 凭证口径(端点表中的「鉴权」列) - **公开**:无凭证要求(模型目录、模型需求、健康检查等) - **凭证**:需 API Key 或 JWT,缺失或无效返回 `401`(错误码 `101`) - **账户**:凭证之上还要求账户行存在(余额、流水、`/v1/account/me`) - **可选**:携带凭证时按账户过滤,不带亦放行 ::: ## 版本 版本号附着于单个端点而非整个 API。同一账户相关的能力会出现 `GET /v1/account/me`、`GET /v2/account/me`、`GET /v4/account/balance` 这样的组合,请按参考中给出的路径原样调用。新版本的端点在旧版本保持可用的前提下增加;弃用会提前在本站公告。 ## 错误 ### 错误信封 绝大多数端点使用**标准信封**: ```json // 成功 { "status": "success", "data": { … } } // 失败 { "status": "error", "errorCode": 1005, "message": "余额不足", "details": { … }, "retryAfter": 60 } ``` 三类例外,其响应体没有信封: | 类别 | 端点 | 形状 | | --------- | -------------------------------------------- | -------------------------------------------------------------- | | OpenAI 形状 | `POST /v1/chat/completions`、`GET /v1/models` | 与 OpenAI 一致;错误为 `{ "error": { "message", "type", "code" } }` | | 裸 JSON | `GET /healthz`、socket REST 目录三件套与 estimate | 直接返回对象/数组 | | 事件流 | `…/events/stream` | `text/event-stream`:`id: `、`event: `、`data: ` | ### 错误码 | errorCode | HTTP | 含义 | 处理建议 | | --------- | ------- | ---------------------------- | ------------------------------------------------------------ | | `101` | 401 | 未认证 / 凭证无效 | 检查 Key 状态与请求头形态 | | `108` | 409 | 用户名已占用 | 换一个用户名 | | `126` | 429 | 创建类操作限频 | 按 `Retry-After` 退避 | | `179` | 403 | 需要订阅 | 升级方案 | | `4027` | 409 | 并发会话超上限 | 关闭多余连接后重试 | | `1001` | 422 | 工具 / 排行榜类型未实现 | 查阅对应页面的可用值 | | `1002` | 400 | 模型不在目录 | 以 `GET /v1/model-catalog` 为准 | | `1003` | 400 | 预估费用超上限 | 降低规格或分批 | | `1004` | 200/500 | 存储故障 | 重试;持续失败请联系支持 | | `1005` | 402 | 余额不足 | [充值](https://docs.reelway.ai/pricing/index.md) | | `1006` | 409 | 状态机非法迁移 | 先读取当前状态 | | `1007` | 422 | 工作流 DAG 存在环或指向更晚的 step | 修正 `dependsOn` | | `1008` | 422 | `dependsOn` 引用了不存在的 step | 修正 step id | | `1009` | 400 | `media_references` 非 http(s) | 先上传得到 URL | | `1010` | 400 | 请求体含未知字段(严格解码) | 删除多余字段 | | `1011` | 400 | 两段式创建的常规路径响应 | 见[创意工作流](https://docs.reelway.ai/api-reference/workflows.md) | | `1012` | 422 | 同一幂等键携带了不同的请求体 | 换新键 | | `1013` | 402 | 单 Key 限额触顶 | 调整 Key 限额或换 Key | | `1014` | 400 | 该模型 × 分辨率桶没有价格行 | 换规格;属平台配置问题可反馈 | ### 400 与 `errorCode: 1010` 创意工作流、持久对话运行等付费端点对请求体做**严格解码**:任何未在文档中列出的字段都会导致整体拒绝,而不是被忽略。升级 SDK 或复制示例后请逐字段核对。 ## 限流 触发限流时返回 `429`,同时携带 `Retry-After` 响应头与信封内的 `retryAfter` 字段(秒,当前为 `60`)。请实现指数退避,并把 `Retry-After` 作为退避下限。WebSocket 侧单帧上限 1 MiB(artist)/ 8 MiB(worker),服务端每 25 秒 ping、60 秒 pong 窗口;超时连接会被关闭,SDK 会自动重连。 ## 幂等 ### 请求头 在会产生付费副作用的创建请求上携带 `Idempotency-Key`(或 `X-Idempotency-Key`),长度不超过 200 字符。同键同体的重放返回首次响应;同键不同体返回 `422`(错误码 `1012`)并附 `Retry-After`。 ### 支持的端点 | 端点 | 幂等作用域 | | ----------------------------------- | ------------------ | | `POST /v1/creative-agent/workflows` | `workflow.create` | | `POST /v1/chat/runs` | `chat.runs.create` | | `POST /v1/world-builds` | `world.start` | 其余端点要么本身幂等(`GET`、`DELETE`),要么以资源 id 天然去重。 ## 计费 - **余额**:`GET /v4/account/balance` 返回账户余额;`GET /v1/transactions/list` 返回流水分页(`limit`/`offset`,整页 50 条时返回 `next`)。 - **扣费时点**:生成项目与工作流在**受理时按预估扣费**,完成后按实际用量校正;失败或无产物的任务不计费。 - **价格来源**:按「模型 × 分辨率桶」的价格规则计价;缺少价格行时返回 `400`(`1014`),不会静默免费。 - **单 Key 限额**:每个 API Key 可设置消费上限,触顶返回 `402`(`1013`),与账户余额不足(`1005`)区分。 - **分销体系**:二级分销商可为下级账户充值、设置费率并查看毛利报表,详见[方案与定价](https://docs.reelway.ai/pricing/index.md)。 :::tip 余额不足时发生什么 提交被拒绝于扣费之前,不会产生部分计费;已在途的任务不受影响。充值后直接重试即可。 ::: ## 下一步 - [API Keys](https://docs.reelway.ai/api-reference/api-keys.md) —— 创建与管理 Key - [生成配方](https://docs.reelway.ai/api-reference/direct-generation.md) —— 提交第一个图像或视频项目 - [生产集成](https://docs.reelway.ai/api-reference/production-integrations.md) —— 恢复、重试与错误处理清单 --- url: https://docs.reelway.ai/api-reference/api-keys.md --- > 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. # API Keys API Key 让你的代码代表你的 Reelway 账户行动。每个账户最多同时持有 **99 把在用的 Key**,每把有自己的名称与用量,因此每个应用、智能体、服务器或节点车队都可以拥有独立的 Key;吊销其中一把,其余不受影响。 在[控制台 → API Keys](https://dashboard.reelway.ai/console/keys)页面管理 Key(需登录会话)。只有登录会话可以创建或吊销 Key;**API Key 本身不能管理 Key,包括它自己**。 ## Key 的两类 | 类型 | 说明 | | --------- | ------------------------------------------------------------------------ | | **主 Key** | 每个账户自动持有一把。可随时在控制台**再次查看与复制**明文;不可吊销(吊销请求返回 404 语义)。适合个人开发与控制台内的快捷调用 | | **子 Key** | 通过「创建 Key」按钮生成。明文**仅在创建时弹窗显示一次**,之后无法再取回;可随时吊销。生产环境、智能体、节点与第三方集成请使用子 Key | 已吊销的 Key 仍保留在列表中(带吊销标记)便于审计,但不再占用 99 把的在用配额。 :::tip 节点请使用独立 Key GPU 节点(worker)在 WebSocket 握手时同样使用账户 API Key。为每台节点或每个车队单独创建一把子 Key,便于按节点吊销与排障。连接前可用 `POST /v1/client/key` 预检 Key 是否有效(见[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md))。 ::: ## 创建 Key ### 登录控制台 前往 [reelway.ai/console/keys](https://dashboard.reelway.ai/console/keys)。登录由 `auth.reelway.ai` 统一鉴权完成。 ### 创建并命名 点击「创建 Key」,填写名称(建议以用途命名,如 `agent-prod`、`worker-5090-01`)。 ### 立即保存明文 Key 明文仅显示一次。立即放入密钥管理器或环境变量;关闭弹窗后只能重新创建。 ## 发送 Key 在请求头中发送 Key,**绝不要放在 URL 里**: ```bash curl --fail-with-body https://rcn.reelway.ai/v4/account/balance \ -H "api-key: $REELWAY_API_KEY" ``` REST 端点接受 `api-key: ` 或 `Authorization: Bearer ` 两种写法;OpenAI 兼容推理面(`api.reelway.ai/v1`)推荐 `Authorization: Bearer`,以便与 OpenAI SDK 的默认行为一致。`@reelway/client` SDK 以 `apiKey` 参数接收 Key 并代为放入请求头与 WebSocket 握手头。 URL 会进入浏览器历史、代理日志与分析系统,因此 WebSocket 连接也请使用 `api-key` **握手头**而非 `?apiKey=` 查询串。 把 Key 留在服务端。不要放进浏览器打包产物、移动端二进制、提示词、代码仓库、截图或支持消息。 ## 限额与用量 - **单 Key 限额**:平台可为 Key 设置消费配额;提交的预估费用超过剩余配额时,请求在扣费前被拒绝,返回 `402`(错误码 `1013`),与账户余额不足(`1005`)区分。 - **用量查看**:控制台的 Key 列表展示每把 Key 的用量;账户维度的余额与流水见[余额与用量](https://docs.reelway.ai/api-reference/account-and-usage.md)。 - Key 的限额与用量仅在控制台可见;API Key 自身不能读取这些信息。 :::info 当前未提供的能力 按 Key 的模型白名单、IP 白名单、到期时间与暂停/恢复,当前版本**未提供**。需要隔离时请使用独立的子 Key 并按需吊销。 ::: ## 吊销与轮换 - **吊销**是永久的。Key 立即失效,使用它的 SDK 会话与节点连接在下一次鉴权时被拒绝(WebSocket 关闭码 `4021`)。其余 Key 不受影响。 - **轮换**采用「先建后吊」:创建新 Key → 部署到使用处 → 确认流量切换 → 吊销旧 Key。两把 Key 并存期间没有数量之外的限制。 **如果 Key 泄露**,立即吊销,创建新 Key 替换,然后在控制台检查该 Key 的用量是否存在陌生记录。 ## 错误 | 场景 | HTTP | 错误码 | 说明 | | --------------- | ---- | ------ | ----------------------------------------------------------- | | Key 缺失、格式错误、已吊销 | 401 | `101` | 响应信封 `message` 说明原因;WebSocket 以 `4021` 关闭 | | 单 Key 限额触顶 | 402 | `1013` | 调整限额或换用其他 Key | | 账户余额不足 | 402 | `1005` | 与 Key 无关,见[方案与定价](https://docs.reelway.ai/pricing/index.md) | OpenAI 兼容推理面上,鉴权失败返回 OpenAI 形状的 `401` 错误对象(`error.type` / `error.message`),而非标准信封。 另见[快速开始](https://docs.reelway.ai/api-reference/getting-started.md#%E8%AE%A4%E8%AF%81)了解认证在整个 API 中如何工作,以及[生产集成](https://docs.reelway.ai/api-reference/production-integrations.md#%E5%BF%85%E9%A1%BB%E5%A4%84%E7%90%86%E7%9A%84%E9%94%99%E8%AF%AF)了解其他需要处理的错误。 --- url: https://docs.reelway.ai/api-reference/direct-generation.md --- > 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 的生成能力通过两条路径暴露。**生产路径**是 Sogni 兼容的 WebSocket 通道:客户端(或 SDK)发送 `jobRequest` 帧,服务端把任务派发到 GPU 节点并实时推送进度与结果。**REST 路径**是创意智能体工作流(`POST /v1/creative-agent/workflows`),以多步 DAG 描述生成任务,适合无长连接的服务端集成。 | 路径 | 入口 | 适用 | 状态 | | ---------------------- | ----------------------------------- | ----------------- | ----------------------------------------------- | | WebSocket `jobRequest` | `wss://rcn.reelway.ai/socket` | 实时进度、预览、取消;SDK 默认 | | | 创意工作流 REST | `POST /v1/creative-agent/workflows` | 无状态服务端、多步编排、幂等重放 | | 本页的配方全部基于目录中的真实模型 ID,目录以 `GET /v1/model-catalog` 为准。 ## 通过 SDK 提交(推荐) `@reelway/client` 封装了握手、帧编解码、重连与事件分发。所有配方共享同一初始化: ```js import { SogniClient } from '@reelway/client'; const client = await SogniClient.createInstance({ appId: 'recipes-demo', // 同账号同 appId 的新连接会接管旧连接 network: 'fast', // fast | relaxed apiKey: process.env.REELWAY_API_KEY, }); ``` ### 文生图(t2i) ```js const project = client.projects.create({ modelId: 'z_image_turbo_bf16', // 或 'qwen_image_2512_fp8' positivePrompt: '黄昏下的江南水乡,倒影,胶片质感', negativePrompt: '模糊, 低质量', numberOfImages: 2, steps: 8, guidance: 3.5, seed: 42, }); project.on('progress', ({ progress }) => console.log(`${(progress * 100).toFixed(0)}%`)); const urls = await project.waitForCompletion(); // 48 小时有效的签名 URL ``` ### 文生视频(t2v) ```js const project = client.projects.create({ modelId: 'minimax-h3-fl2va-fp8_t2v_turbo', positivePrompt: '一只橘猫在雨后的屋顶上伸懒腰,镜头缓慢推进,环境音', numberOfImages: 1, }); const [videoUrl] = await project.waitForCompletion(); ``` ### 图生视频(i2v) 参考图作为首帧(SDK 直传 `Blob`/`Buffer`,内部自动完成预签名上传): ```js const project = client.projects.create({ modelId: 'minimax-h3-fl2va-fp8_i2v', positivePrompt: '人物转身微笑,自然光', referenceImage: fs.readFileSync('./first-frame.png'), // 首帧 }); ``` ### 首尾帧(flf2v) ```js const project = client.projects.create({ modelId: 'minimax-h3-fl2va-fp8_flf2v', positivePrompt: '从白天过渡到夜晚的城市天际线', referenceImage: fs.readFileSync('./first-frame.png'), referenceImageEnd: fs.readFileSync('./last-frame.png'), }); ``` ### 参考视频(r2v) 以参考图像为锚保持主体一致,`contextImages` 提供额外参考: ```js const project = client.projects.create({ modelId: 'minimax-h3-ref2va-fp8_r2v', positivePrompt: '同一位角色在咖啡馆里阅读', referenceImage: fs.readFileSync('./character.png'), contextImages: [fs.readFileSync('./outfit.png')], }); ``` :::tip 档位选择 每个 H3 任务都有 `base` / `_balanced` / `_turbo` 三档:`_turbo` 步数最少、最快;`_balanced` 折中;`base` 质量优先。r2v 另有 `_2stage` 两段式变体。详见[MiniMax H3](https://docs.reelway.ai/models/minimax-h3.md)。 ::: ## 直接使用 WebSocket 帧 不使用 SDK 时,按[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md)中的 artist 通道规范操作。关键帧: WSwss://rcn.reelway.ai/socket?appId=&forceWorkerId=fast鉴权:api-key 握手头 artist 通道;握手后首帧为 authenticated **上行 `jobRequest`**(线协议 `{type, data: base64(JSON)}`);图像输入先经 `GET /v1/image/uploadUrl?type=<槽位>&jobId=` 上传,槽位枚举含 `startingImage`、`referenceImage`、`referenceImageEnd`、`contextImage1..16`、`keyframeImage1..8`: ```json { "jobID": "0b0f6c0e-7d4b-4d3c-9c6f-0c7a7e3f2a11", "numberOfImages": 1, "previews": 0, "outputFormat": "mp4", "tokenType": "auto", "network": "fast", "keyFrames": [ { "modelID": "minimax-h3-fl2va-fp8_t2v_turbo", "positivePrompt": "一只橘猫在雨后的屋顶上伸懒腰", "negativePrompt": "", "stylePrompt": "", "steps": 4, "guidanceScale": 3.5, "seed": 20251102 } ] } ``` `keyFrames[0].modelID` 必填。服务端依次下发 `projectQueue` → `jobState(queued|assigned|initiatingModel|jobStarted)` → `jobProgress` → `jobResult`(含 `resultUrl`)或 `jobError`。取消用 `jobError`(`artistCanceled` 语义),回执 `artistCancelConfirmation`。 ## 通过创意工作流 REST 提交 POSThttps://rcn.reelway.ai/v1/creative-agent/workflows鉴权:凭证 两段式创建 + 幂等;输入 ≤1 MiB;严格解码 ```bash curl --fail-with-body https://rcn.reelway.ai/v1/creative-agent/workflows \ -H "api-key: $REELWAY_API_KEY" \ -H "Idempotency-Key: recipe-t2v-$(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "steps": [ { "id": "video", "tool": "generate_video", "input": { "model": "minimax-h3-fl2va-fp8_t2v_turbo", "prompt": "一只橘猫在雨后的屋顶上伸懒腰" } } ] }' ``` - 响应 `201` 返回工作流形状(含 `steps[]` 与状态);订阅 `GET …/{id}/events/stream`(SSE)获取进度与产物。 - 请求体**严格解码**,任何未知字段返回 `400`(`1010`)。 - 同一 `Idempotency-Key` 重放返回首次响应;同键不同体返回 `422`(`1012`)。 - DAG 校验:`dependsOn` 指向不存在的 step → `422`(`1008`);存在环或指向更晚的 step → `422`(`1007`)。 完整端点族见[创意工作流](https://docs.reelway.ai/api-reference/workflows.md)。 ## 费用与失败 - 项目在**受理时按预估扣费**,完成后按实际用量校正;`jobError` 或无产物的任务不计费。 - 模型不在目录 → `400`(`1002`);该模型 × 分辨率桶没有价格行 → `400`(`1014`);余额不足 → `402`(`1005`)。 - 产物 `resultUrl` 为 **48 小时**有效的签名 URL;需要长期保存请及时下载,或用 `GET /v1/image|media/downloadUrl` 重新签发(见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md))。 --- url: https://docs.reelway.ai/api-reference/production-integrations.md --- > 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=` 轮询,或在能保持连接的组件中订阅 `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` 获取平台公告(模型上下线、维护窗口) --- url: https://docs.reelway.ai/api-reference/project-status.md --- > 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. # 项目状态 API WebSocket 通道实时推送进度,但在无长连接的场景(函数计算、定时对账、进程重启后恢复)你需要用 REST 读取项目状态。本页的端点都以**账户凭证**鉴权,只返回凭证所有者的项目。 ## 实时投影:`GET /v2/projects/{id}` GEThttps://rcn.reelway.ai/v2/projects/{id}鉴权:凭证 所有者实时状态投影,处理中与完成后均可读 ```bash curl --fail-with-body https://rcn.reelway.ai/v2/projects/0b0f6c0e-7d4b-4d3c-9c6f-0c7a7e3f2a11 \ -H "api-key: $REELWAY_API_KEY" ``` ### 响应 ```json { "status": "success", "data": { "id": "0b0f6c0e-7d4b-4d3c-9c6f-0c7a7e3f2a11", "status": "processing", "finished": false, "workerJobs": [ { "imgID": "6f1c…", "status": "jobStarted", "performedSteps": 2 } ], "completedWorkerJobs": [ { "imgID": "a93d…", "status": "jobCompleted", "performedSteps": 4, "worker": { "name": "node-5090-01" }, "seedUsed": 20251102, "NSFW": false } ], "jobCountCompletedByState": { "jobCompleted": 1, "jobError": 0 } } } ``` | 字段 | 说明 | | -------------------------- | ----------------------------------------------------------------- | | `status` / `finished` | 项目级状态与是否终态 | | `workerJobs[]` | 在途作业:`imgID`、当前 `status`、已执行步数 | | `completedWorkerJobs[]` | 已终态作业:`status` 为 `jobCompleted` 或 `jobError`;含执行节点名、实际种子与 NSFW 标记 | | `jobCountCompletedByState` | 按终态聚合计数 | 产物下载 URL 不在投影中:凭 `imgID` 调用 `GET /v1/image/downloadUrl` 或 `GET /v1/media/downloadUrl`(见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md))。 ## 完成后读取:`GET /v1/projects/{id}` GEThttps://rcn.reelway.ai/v1/projects/{id}鉴权:凭证 仅完成后可读;处理中返回 404 与 `/v2` 同形,但沿用 Sogni v1 口径:**项目处理中返回 `404`**,只有完成后才返回 `200`。SDK 用这一差异区分「尚未完成」与「不存在」。新集成请直接使用 `/v2`。 ### 从 v1 迁移 把 `GET /v1/projects/{id}` 替换为 `GET /v2/projects/{id}`,并把「`404` 等于处理中」的逻辑改为读取 `data.finished`。 ## 历史列表:`GET /v1/jobs/list` GEThttps://rcn.reelway.ai/v1/jobs/list鉴权:凭证 近 7 天任务历史,分页 | 查询参数 | 说明 | | ----------- | -------------- | | `limit` | 1–100,默认 50 | | `since` | 毫秒时间戳,只返回其后的任务 | | `state` | 按状态过滤 | | `mediaOnly` | 仅返回有媒体产物的任务 | 响应 `data.jobs[]`、`data.offset`、`data.limit`。历史窗口为 **7 天**;更久的记录请在完成时自行归档。 ## 恢复快照:`GET /api/v1/artist/projects/sync` GEThttps://rcn.reelway.ai/api/v1/artist/projects/sync鉴权:凭证 进程重启后的恢复快照 返回 `activeProjects`(仍在途)与 `unclaimedCompletedProjects`(已完成但客户端尚未确认领取)。SDK 在重连后自动调用;自实现客户端在重启后调用一次,即可继续追踪在途项目并领取遗漏的结果。 ## 轮询与 HTTP 错误 - 推荐轮询间隔 2–5 秒;终态(`finished: true`)后停止。 - `404`:`/v2` 下表示项目不存在或不属于该凭证;`/v1` 下还可能表示处理中。 - `401`(`101`):凭证无效。 - `429`:按 `Retry-After` 退避。 ## 保留与兼容 - 投影在项目完成后持续可读;产物签名 URL 有效期 48 小时,需长期保存请转存。 - `/v1` 与 `/v2` 响应形状保持 Sogni 兼容,`@sogni-ai/sogni-client` 的既有解析逻辑可直接复用。 --- url: https://docs.reelway.ai/api-reference/media-utilities.md --- > 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. # 媒体工具与语音 本页覆盖生成主流程之外的「周边能力」:如何把源媒体稳定地供给给任务、如何在提交前预估费用、如何合成语音,以及 H3 的两段式参考视频变体。 ## 供给源媒体 \{#资产库} 一次性输入用[预签名 URL](https://docs.reelway.ai/api-reference/media.md) 即可;需要**复用、去重与配额管理**时使用资产库。资产库在同一对象存储之上提供四步状态机: GEThttps://rcn.reelway.ai/v1/assets/capabilities鉴权:凭证 enabled(是否已配置对象存储)/ maxSizeBytes / hashAlgorithm=sha256 GEThttps://rcn.reelway.ai/v1/assets鉴权:凭证 近 500 条资产 + 配额 limits POSThttps://rcn.reelway.ai/v1/assets/prepare鉴权:凭证 按 sha256 去重;签发 uploadUrl 或直接复用 POSThttps://rcn.reelway.ai/v1/assets/{id}/finalize鉴权:凭证 服务端复验 sha256 + size 后置 ready POSThttps://rcn.reelway.ai/v1/assets/{id}/bind鉴权:凭证 把 ready 资产绑定到项目槽位 DELETEhttps://rcn.reelway.ai/v1/assets/{id}鉴权:凭证 注销资产,尽力删除对象 ### prepare `POST /v1/assets/prepare`,body `{ "sha256", "bytes", "contentType", "name" }`。同账户已有相同 `sha256` 且状态 `ready` 的资产时直接返回该资产并标 `reused: true`,**跳过上传**;否则创建 `uploading` 档并返回 `uploadUrl`。单文件上限 100 MiB。 ### PUT 把文件体 PUT 到 `uploadUrl`。 ### finalize `POST /v1/assets/{id}/finalize`。服务端复验哈希与大小:对象未上传 → `400`;校验不符 → `400` 且资产置 `failed`。通过后置 `ready`。 ### bind `POST /v1/assets/{id}/bind`,body `{ "projectId", "type" }`(`type` 为槽位,如 `startingImage`)。资产非 `ready` 返回 `423`。绑定写入 `asset_bindings`,随后该项目的 `jobRequest` 即可引用。 ### 配额 | 项 | 限制 | | ---- | -------------------------- | | 资产条目 | 500 | | 总容量 | 5 GiB | | 单文件 | `maxSizeBytes`(当前 100 MiB) | | 闲置回收 | 7 天未绑定的资产可被回收 | | 每日拷贝 | 1 GiB | | 每日绑定 | 1000 次 | 实际值以 `GET /v1/assets` 返回的 `limits` 为准。 ## 提交前预估费用 GEThttps://rcn.reelway.ai/socket/api/v1/job/estimate/{tokenType}/{model}/…鉴权:凭证 裸 JSON;媒体估价包在 quote.project 下 SDK 的 `estimateVideoCost()` 等方法调用此端点。预览当前返回结构完整但数值为零的诚实零报价;价格规则接入后返回真实预估 实际扣费以受理时的价格规则为准(模型 × 分辨率桶);缺少价格行时提交返回 `400`(`1014`),不会静默免费。 ## 语音合成与参考音频克隆 目录模型 `cosyvoice3-tts-0.5b`(CosyVoice 3,0.5B)提供**零样本声音克隆** TTS:给定一段参考音频与目标文本,合成同音色语音。作为 `audio` 媒体类型的项目提交: ```js const project = client.projects.create({ modelId: 'cosyvoice3-tts-0.5b', positivePrompt: '欢迎使用 Reelway,祝你创作愉快。', // 要合成的文本 referenceAudio: fs.readFileSync('./voice.wav'), // 克隆音色参考 }); const [audioUrl] = await project.waitForCompletion(); // 经 /v1/media/downloadUrl 签发 ``` 参数细节见[CosyVoice 3 TTS](https://docs.reelway.ai/models/cosyvoice3-tts.md)。 ## MiniMax H3 两段式参考视频 `minimax-h3-ref2va-fp8_r2v_2stage` 与 `_balanced_2stage` 以两段推理换取更强的主体一致性与更长的有效时长,代价是更高的耗时与费用。输入与普通 r2v 相同(参考图 + 提示词),直接替换 `modelId` 即可。详见[MiniMax H3](https://docs.reelway.ai/models/minimax-h3.md#%E4%B8%A4%E6%AE%B5%E5%BC%8F%E5%8F%82%E8%80%83%E8%A7%86%E9%A2%91)。 ## 当前未提供的媒体工具 背景移除、3D 重建、对象选择(分割)与视频超分当前**不在模型目录中**,API 不提供对应端点。目录更新以 `GET /v1/model-catalog` 与[模型指南](https://docs.reelway.ai/models/index.md)为准。 --- url: https://docs.reelway.ai/api-reference/personal-loras.md --- > 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. # 个人 LoRA 个人 LoRA 库允许账户把自有权重(以 URL `source` 登记的**元数据档**)作为私有 LoRA 管理,并在生成请求的 `loras` 参数中引用。每账户保留**近 200 条**记录。 GEThttps://rcn.reelway.ai/v1/loras/personal鉴权:凭证 近 200 条,{loras[]} GEThttps://rcn.reelway.ai/v1/loras/personal/catalog鉴权:凭证 就绪导入条目 {loras[{id, name, baseModelId}]} GEThttps://rcn.reelway.ai/v1/loras/personal/{id}鉴权:凭证 单条;不存在返回 404 POSThttps://rcn.reelway.ai/v1/loras/personal鉴权:凭证 导入;202 受理 DELETEhttps://rcn.reelway.ai/v1/loras/personal/{id}鉴权:凭证 注销;不存在返回 404 ## 导入 ```bash curl --fail-with-body -X POST https://rcn.reelway.ai/v1/loras/personal \ -H "api-key: $REELWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source": "https://example.com/weights.safetensors", "name": "my-style-lora", "baseModelId": "qwen_image_2512_fp8" }' ``` ### `202` 表示什么 导入是**受理即返回**:响应 `202` 含 LoRA 条目形状。条目状态 `status` 随导入器推进:当前实现为**占位导入器**——条目立即置 `ready`,但**没有权重落盘**;真实拉取(从 `source` URL 拉取权重文件)待后续版本接入。 预览导入器为占位实现:条目立即 ready 但无权重落盘;契约稳定,M2 接入真实拉取 ### 导入错误 | HTTP | 错误码 | 场景 | | ---- | ------ | ---------------- | | 400 | `1010` | 请求体含未知字段(严格解码) | | 401 | `101` | 凭证无效 | | 409 | `1006` | 同 `source` 已存在 | | 422 | — | `source` 非有效 URL | ## 查看、目录与删除 - `GET /v1/loras/personal` 返回近 200 条 `{loras[]}`:`id` / `name` / `source` / `baseModelId` / `status` / `createdAt` / `updatedAt`。 - `GET /v1/loras/personal/catalog` 仅返回 `ready` 条目的精简形状,用于生成前的可引用性检查。 - `DELETE /v1/loras/personal/{id}` 注销条目;不存在返回 `404`。 ## 在生成中使用 生成请求的 `keyFrames[0].loras` 与 SDK `projects.create` 的 `loras` 参数引用就绪条目: ```js const project = client.projects.create({ modelId: 'qwen_image_2512_fp8', positivePrompt: '一杯手冲咖啡,水彩风格', loras: [{ id: 'my-style-lora', strength: 0.8 }], }); ``` :::warning 使用前提 当前节点配置未挂载个人 LoRA 权重,生成侧对 `loras` 的支持尚未打通;引用就绪条目暂不改变渲染行为。以本页状态徽标与本站公告为准。 ::: 另见[目录与网络需求](https://docs.reelway.ai/api-reference/model-discovery.md)查看平台目录;节点侧的 ComfyUI LoRA 目录见 `GET /v1/worker/config/comfy/loras`(当前返回空目录)。 --- url: https://docs.reelway.ai/api-reference/chat-completions.md --- > 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. # 对话补全 POSThttps://api.reelway.ai/v1/chat/completions鉴权:Authorization: Bearer OpenAI 兼容;支持流式(SSE)与 OpenAI 函数工具 Reelway 的对话补全端点与 OpenAI Chat Completions API 同形:任何 OpenAI SDK 只需修改 `baseURL` 即可接入,计费走 Reelway 余额(受理时扣费,失败不计费)。 ## 请求体 | 字段 | 类型 | 必填 | 说明 | | -------------------------------------- | -------------- | --------- | --------------------------------------------------------------------------------------------------------- | | `messages` | array | 是 | 非空 OpenAI 消息数组;`developer` 角色归一为 `system` | | `model` | string | 否 | LLM 模型 id(见[LLM 模型](https://docs.reelway.ai/api-reference/llm-models.md));缺省 `qwen3.6-35b-a3b-gguf-iq4xs` | | `stream` | boolean | 否 | `true` 时返回 OpenAI 风格 SSE 分片,以 `data: [DONE]` 结束 | | `max_tokens` / `max_completion_tokens` | integer | 否 | 最大输出 token;后者为 OpenAI SDK 别名 | | `temperature` / `top_p` | number | 采样参数,透传后端 | | | `tools` / `tool_choice` | array / string | 否 | OpenAI 函数工具数组与选择策略 | | `app_source` | string | 否 | 调用方标签(≤128 字,超长截断);亦可用 `X-App-Source` 头 | | `token_type` / `billing_mode` | string | 否 | Sogni 兼容形状字段;统一余额计费下不改变计费路径 | 未知字段返回 `400`(`1010`,严格解码)。 :::info Sogni 兼容字段 `token_type`、`billing_mode` 在 Sogni 用于双代币与订阅计费分流;Reelway 为统一余额计费,这些字段仅作形状兼容被接受,不改变计费路径。`sogni_tools` 创意工具族为 Sogni 特有能力,Reelway 未提供。 ::: ## 请求示例 **curl** ```bash curl --fail-with-body https://api.reelway.ai/v1/chat/completions \ -H "Authorization: Bearer $REELWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen3.6-35b-a3b-gguf-iq4xs", "messages": [ { "role": "user", "content": "用一句话介绍 Reelway。" } ] }' ``` **OpenAI SDK** ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.reelway.ai/v1', apiKey: process.env.REELWAY_API_KEY, }); const completion = await client.chat.completions.create({ model: 'qwen3.6-35b-a3b-gguf-iq4xs', messages: [{ role: 'user', content: '用一句话介绍 Reelway。' }], }); console.log(completion.choices[0].message.content); ``` ## 响应 - 非流式:OpenAI `chat.completion` 对象(`choices[0].message.content` 等)。 - 流式:OpenAI `chat.completion.chunk` SSE 分片,`data: [DONE]` 结束;网关已配置不缓冲流式响应。 - 错误:OpenAI 形状 `{ "error": { "message", "type", "code" } }`;鉴权失败 `401`,限流 `429`(附 `Retry-After`),余额/限额类拒绝 `402`(`1005` / `1013` 信封语义)。 ## 与持久对话运行的关系 本端点为**无状态**调用:每次请求独立计费,对话历史由调用方维护。需要可恢复、带事件流的长时间对话(含幂等重放)请用 `POST /v1/chat/runs`,见[持久对话运行](https://docs.reelway.ai/api-reference/chat-runs.md)。 --- url: https://docs.reelway.ai/api-reference/tool-execution.md --- > 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. # 直接工具执行 POSThttps://rcn.reelway.ai/v1/creative-agent/tools/execute鉴权:凭证 同步执行托管工具,返回最终消息与可选产物 创意智能体的六个**同步托管工具**通过单一端点执行:不需要建立长连接,适合无状态服务端与函数计算。 ## 请求体 | 字段 | 类型 | 必填 | 说明 | | ----------------------------- | ------ | -- | ---------------------------------------- | | `tool` | string | 是 | 托管工具名;`tool_name` 作为别名被接受 | | `arguments` | 各工具定义 | 是 | 所选工具的完整参数对象 | | `app_source` | string | 否 | 调用方标签(≤128 字符,超长截断);亦可用 `X-App-Source` 头 | | `token_type` / `billing_mode` | string | 否 | Sogni 兼容形状字段;统一余额计费下不改变计费结果 | 未知字段返回 `400`(`1010`)。`arguments` 必须为对象;未实现或未知工具返回 `422`(`1001`)。 ## 六个托管工具 | 工具 | 用途 | | --------------------------- | --------------------------- | | `enhance_prompt` | 把粗略提示词扩写为模型就绪的图像/视频/语音提示词 | | `compose_script` | 起草脚本、分镜、预告片与短视频文案 | | `compose_lyrics` | 撰写歌词与建议的音乐参数 | | `compose_instrumental` | 撰写纯音乐结构与建议参数 | | `compose_workflow` | 把创意简报编译为工作流 `input` 计划与费用预估 | | `compose_workflow_template` | 起草或编辑带参数的工作流模板与示例计划 | 预览六个工具当前为占位实现(mock 语义):响应契约稳定,内容质量随真实引擎接入提升 ## 请求示例 ```bash curl --fail-with-body https://rcn.reelway.ai/v1/creative-agent/tools/execute \ -H "api-key: $REELWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tool": "enhance_prompt", "arguments": { "prompt": "一只戴墨镜的柴犬", "target_output": "video_prompt" } }' ``` ## 响应 标准信封:`data` 含工具输出(`message` 文本与结构化字段,按工具定义)。未实现工具返回 `422`(`1001`);参数缺漏返回 `400`。 ## 另见 - [创意工作流](https://docs.reelway.ai/api-reference/workflows.md) —— `compose_workflow` 输出的执行载体 - [工作流模板](https://docs.reelway.ai/api-reference/templates.md) —— `compose_workflow_template` 输出的持久化方式 --- url: https://docs.reelway.ai/api-reference/llm-models.md --- > 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. # LLM 模型 GEThttps://api.reelway.ai/v1/models鉴权:Authorization: Bearer OpenAI 形状,无信封 推理面(`api.reelway.ai/v1`)按网关配置返回当前可用的 LLM 模型列表,响应为 **OpenAI 形状**(无标准信封)。 ## 请求 ```bash curl https://api.reelway.ai/v1/models \ -H "Authorization: Bearer $REELWAY_API_KEY" ``` ## 响应 ```json { "object": "list", "data": [ { "id": "qwen3.6-35b-a3b-gguf-iq4xs", "object": "model", "owned_by": "reelway" } ] } ``` 字段遵循 OpenAI `Model` 对象规范(`id`、`object`、`created`、`owned_by`)。 ## 说明 - 列表内容随推理面配置变化(模型上下线、维护窗口);调用方应以运行时查询为准,不要硬编码。上下文长度与输出上限以模型卡片为准,本端点不返回这些元数据。 - Sogni 兼容面(`rcn.reelway.ai`)的 `GET /v1/models` 当前返回**空列表**——该端点为 Sogni SDK 兼容保留,LLM 能力一律走推理面。引用生成模型请用 `GET /v1/model-catalog`(见[模型与网络需求](https://docs.reelway.ai/api-reference/model-discovery.md))。 ## 错误 | HTTP | 形状 | 说明 | | ---- | --------------- | ------------- | | 401 | OpenAI error 对象 | Bearer 凭证无效 | | 500 | OpenAI error 对象 | 网关配置或上游故障;可重试 | 另见[对话补全](https://docs.reelway.ai/api-reference/chat-completions.md)了解如何调用;生成模型(图像/视频/语音)与 LLM 是两类目录,互不混用。 --- url: https://docs.reelway.ai/api-reference/chat-runs.md --- > 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: `、`event: `、`data: `;`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) —— 面向构建者的全景 --- url: https://docs.reelway.ai/api-reference/workflows.md --- > 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. # 创意工作流 创意工作流把一次创作任务表达为**多步 DAG**:每个 step 调用一个托管工具,`dependsOn` 表达依赖,服务端按依赖顺序执行并发布事件。与单次工具执行相比,工作流是持久资源:幂等创建、断线可恢复、事件可回放。 POSThttps://rcn.reelway.ai/v1/creative-agent/workflows鉴权:凭证 两段式创建 + 幂等;输入 ≤1 MiB;严格解码 GEThttps://rcn.reelway.ai/v1/creative-agent/workflows鉴权:凭证 分页 offset/limit;{workflows[], total} GEThttps://rcn.reelway.ai/v1/creative-agent/workflows/{id}鉴权:凭证 单工作流(含 steps);不存在 404 GEThttps://rcn.reelway.ai/v1/creative-agent/workflows/{id}/events?after=鉴权:凭证 事件列表,单次上限 500 条 SSEhttps://rcn.reelway.ai/v1/creative-agent/workflows/{id}/events/stream鉴权:凭证 SSE;Last-Event-ID 重放;终态后关流 POSThttps://rcn.reelway.ai/v1/creative-agent/workflows/{id}/cancel鉴权:凭证 取消 POSThttps://rcn.reelway.ai/v1/creative-agent/workflows/{id}/confirm-cost鉴权:凭证 费用确认(当前恒 409,1006) POSThttps://rcn.reelway.ai/v1/creative-agent/workflows/{id}/resume鉴权:凭证 恢复(当前恒 409,无挂起态) POSThttps://rcn.reelway.ai/v1/creative-agent/workflows/{id}/reseed鉴权:凭证 按 step 覆写种子,产生一次新 run 预览执行器 M1 为占位:契约稳定,内容质量随真实引擎接入提升 ## 创建与消费 - `POST` body 为 DAG 定义 `{steps: [{id, tool, input, dependsOn?}]}`;`Idempotency-Key` 作用域 `workflow.create`,同键异体 `422`(`1012`);未知字段 `400`(`1010`)。 - 事件形状 `{seq, name, payload, createdAt}`;`after` 分页;SSE 断线用 `Last-Event-ID` 重放。 - 终态后产物经 `GET /v1/image|media/downloadUrl` 签发(48 小时)。 ```bash curl --fail-with-body https://rcn.reelway.ai/v1/creative-agent/workflows \ -H "api-key: $REELWAY_API_KEY" \ -H "Idempotency-Key: wf-20261102-001" \ -d '{"steps":[{"id":"shot","tool":"generate_video","input":{"model":"minimax-h3-fl2va-fp8_t2v_turbo","prompt":"雨后屋顶上的橘猫"}}]}' ``` ## DAG 校验 | HTTP | 错误码 | 场景 | | ---- | ------ | -------------------------- | | 422 | `1007` | DAG 存在环,或依赖指向更晚的 step | | 422 | `1008` | `dependsOn` 引用不存在的 step id | | 422 | `1001` | step 引用了未实现的工具 | ## 状态生命周期 `created → running → completed | failed | cancelled`;`cancel` 对已终态工作流返回 `409`(`1006`)。`reseed` 以 `{seed_overrides: {stepId: seed}}` 产生一次**新 run**(响应 201),原 run 保持不变。完整端点行为见[快速开始](https://docs.reelway.ai/api-reference/getting-started.md)的错误码表。 --- url: https://docs.reelway.ai/api-reference/templates.md --- > 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 当前的模板能力由[直接工具执行](https://docs.reelway.ai/api-reference/tool-execution.md)中的 `compose_workflow_template` 托管工具提供:输入创意简报与参数意图,返回参数化的工作流模板定义与示例计划;持久化由调用方完成(存入你的数据库,或经[回放记录](https://docs.reelway.ai/api-reference/replay.md)归档)。 预览托管工具为占位实现;服务端模板 CRUD 未提供 ## 组合模板 ```bash curl --fail-with-body https://rcn.reelway.ai/v1/creative-agent/tools/execute \ -H "api-key: $REELWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tool": "compose_workflow_template", "arguments": { "brief": "为任意商品生成一段 6 秒展示视频", "parameters": ["product_name", "tone", "duration_seconds"] } }' ``` 响应 `data` 含参数化模板定义与示例计划。把模板中的参数替换为实际值后,以 `POST /v1/creative-agent/workflows` 提交执行(见[创意工作流](https://docs.reelway.ai/api-reference/workflows.md))。 ## 服务端模板存储(规划中) 规划中 Sogni 提供的 `POST /v1/creative-agent/workflows/templates` 等服务端模板 CRUD 端点,Reelway **尚未提供**;模板定义当前由调用方持久化。需要服务端存储时,可用[回放记录](https://docs.reelway.ai/api-reference/replay.md)把模板 JSON 归档在账户命名空间下。 ## 另见 - [创意工作流](https://docs.reelway.ai/api-reference/workflows.md) —— 模板的执行载体 - [直接工具执行](https://docs.reelway.ai/api-reference/tool-execution.md) —— `compose_workflow` / `compose_workflow_template` 工具参考 - [Intelligence · 工作流模板](https://docs.reelway.ai/intelligence/workflow-templates.md) —— 面向构建者的使用指南 --- url: https://docs.reelway.ai/api-reference/media.md --- > 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. # 媒体与图像 URL Reelway 不接受把文件内联在 API 请求或 WebSocket 帧里。输入(参考图、首尾帧、参考音频)通过**预签名上传 URL** 直传对象存储;产物通过**预签名下载 URL** 获取。四个端点分为 `image` 与 `media` 两组槽位,语义相同,只在内容类型白名单上不同。 | 端点 | 槽位 | 内容类型 | | ----------------------------------------- | ----- | --------- | | `GET /v1/image/uploadUrl` / `downloadUrl` | 图像 | `image/*` | | `GET /v1/media/uploadUrl` / `downloadUrl` | 音频、视频 | 音频/视频白名单 | 需要**可复用**的上传(多次项目引用同一文件、去重、配额管理)请使用[资产库 `/v1/assets`](https://docs.reelway.ai/api-reference/media-utilities.md#%E8%B5%84%E4%BA%A7%E5%BA%93),它在同一存储之上提供 `prepare → PUT → finalize → bind` 状态机。 ## `GET /v1/image/uploadUrl` GEThttps://rcn.reelway.ai/v1/image/uploadUrl鉴权:凭证 / 节点任务能力 签发预签名 PUT 上传 URL ### 查询参数 | 参数 | 说明 | | ------------- | ---------------------------------------- | | `type` | 槽位用途,例如 `startingImage`、`referenceImage` | | `jobId` | 关联的项目 id | | `contentType` | 将要上传的 MIME 类型,必须在白名单内 | ### 响应 ```json { "status": "success", "data": { "uploadUrl": "https://…/presigned-put", "uploadHeaders": { "Content-Type": "image/png" } } } ``` 随后以 **HTTP PUT** 把文件体直传到 `uploadUrl`,并原样携带 `uploadHeaders` 中的每一个头: ```bash curl --fail-with-body -X PUT "$UPLOAD_URL" \ -H "Content-Type: image/png" \ --data-binary @start-frame.png ``` :::info 节点侧用法 GPU 节点在完成任务时也调用本端点申请**产物上传 URL**:无凭证,凭任务能力 `(jobId, imageId)` 申请 `complete` 槽位。这是协议面的细节,见[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md)。 ::: ## `GET /v1/image/downloadUrl` GEThttps://rcn.reelway.ai/v1/image/downloadUrl鉴权:凭证 签发产物或输入的下载 URL ### 查询参数 | 参数 | 说明 | | ----------------- | ------------------------------------------------------ | | `type` | 槽位,产物用 `complete` | | `jobId` | 项目 id | | `imageId`(或 `id`) | 作业的 `imgID`(来自 `jobResult` 帧或 `GET /v2/projects/{id}`) | ### 响应 ```json { "status": "success", "data": { "downloadUrl": "https://…/presigned-get" } } ``` 对象不存在返回 `404`。`complete` 槽位按登记的产物解析对象键,因此只能在 `jobResult` 之后调用。 ## `GET /v1/media/uploadUrl` 与 `GET /v1/media/downloadUrl` GEThttps://rcn.reelway.ai/v1/media/uploadUrl鉴权:凭证 / 节点任务能力 同 image 组,内容类型为音频/视频白名单 GEThttps://rcn.reelway.ai/v1/media/downloadUrl鉴权:凭证 同 image 组,media 侧槽位 参数与响应与 `image` 组完全一致。视频产物(MiniMax H3)与音频产物(CosyVoice 3)走本组。 ## URL 有效期与安全 - `jobResult` 帧里的 `resultUrl` 与本页签发的 `downloadUrl` 均为**48 小时**有效的签名 URL;过期后重新调用 `downloadUrl` 即可再次签发。 - 签名 URL 可被任何持有者访问:不要写进日志或分享到公共渠道;需要公开分发请转存到自有存储。 - 上传 URL 仅接受一次 PUT 且绑定 `contentType`;类型不符会被存储侧拒绝。 ## 错误 | HTTP | 错误码 | 含义 | | ---- | ------ | ----------------------------------------- | | 400 | — | 缺少 `jobId` / `type`,或 `contentType` 不在白名单 | | 401 | `101` | 凭证无效 | | 404 | — | 对象不存在(产物尚未上传,或 `imageId` 错误) | | 500 | `1004` | 对象存储故障,可重试 | --- url: https://docs.reelway.ai/api-reference/account-and-usage.md --- > 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. # 余额与用量 账户维度的资金与身份查询。除标注公开的端点外,全部以**账户凭证**鉴权,只返回凭证所有者的数据。 ## 账户身份 GEThttps://rcn.reelway.ai/v1/account/me鉴权:账户 完整资料(邮箱验证状态等) GEThttps://rcn.reelway.ai/v2/account/me鉴权:账户 精简 {walletAddress, username, emailVerified} ## 余额 GEThttps://rcn.reelway.ai/v4/account/balance鉴权:账户 账户余额(BalanceV4 形状) ```bash curl --fail-with-body https://rcn.reelway.ai/v4/account/balance \ -H "api-key: $REELWAY_API_KEY" ``` 作为**余额监控与快速开始的第一调用**:无副作用、廉价、可直接验证 Key 有效性。WebSocket 通道的 `authenticated` 首帧同样携带余额(`balanceVersion: 2`)。 ## 流水 GEThttps://rcn.reelway.ai/v1/transactions/list?limit=&offset=鉴权:账户 流水分页;整页 50 条时返回 next=offset+页大小 响应 `{transactions[], next}`:`next` 存在时用其作为下一页 `offset` 继续翻页,缺失表示末页。适合对账与消费审计;按 Key 拆分的用量见控制台 Key 列表。 ## 公告 GEThttps://rcn.reelway.ai/v1/announcements/active?platform=鉴权:可选 有效公告,上限 50 条,pinned 优先;有凭证时排除已 dismiss POSThttps://rcn.reelway.ai/v1/announcements/{id}/dismiss鉴权:凭证 标记公告为已读(幂等) ## 排行榜 GEThttps://rcn.reelway.ai/v1/leaderboard?type=&period=鉴权:可选 仅两类:consumption|spending(账本聚合)与 creations|jobs(完成项目数);period: day|lifetime 未实现类型返回 `422`(`1001`);上限 50 名,形状 `{leaderboard[{rank, artist, value}]}`。 ## 控制台数据面(console) `/console/*` 端点(`GET /console/me`、`GET /console/ledger`、`GET /console/usage`、`GET /console/subscription` 等)为**控制台后端专用**:以 service key + `X-Console-User` 断言头鉴权,供 [dashboard.reelway.ai](https://dashboard.reelway.ai) 调用,不面向第三方开发者。第三方用途请使用本页其余端点。 --- url: https://docs.reelway.ai/api-reference/replay.md --- > 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. # 回放记录 回放记录(replay records)把一次可复现的生成上下文(提示词、参数、种子、中间产物引用)以**结构化记录**归档在账户命名空间下,供后续检索与复现。 POSThttps://rcn.reelway.ai/v1/replay/records鉴权:凭证 写入记录;返回 runId 与时间戳 GEThttps://rcn.reelway.ai/v1/replay/records?limit=鉴权:凭证 分页列出;limit>100 归一 20 GEThttps://rcn.reelway.ai/v1/replay/records/{id}鉴权:凭证 单条;不存在 404 ## 写入 ```bash curl --fail-with-body https://rcn.reelway.ai/v1/replay/records \ -H "api-key: $REELWAY_API_KEY" \ -d '{ "schemaVersion": 1, "record": { "prompt": "…", "seed": 20251102, "modelId": "z_image_turbo_bf16" } }' ``` - `record` 内容由调用方定义(`schemaVersion` 标注结构),平台不解释其语义。 - 响应含 `runId`、`schemaVersion`、`redacted` 与时间戳。 - 平台侧脱敏钩子待接入(当前 `redacted: false`);**敏感信息请先自行脱敏再写入**。 ## 检索 列表按写入顺序倒序返回,`limit` 归一上限 20。需要按业务键检索时,请在 `record` 内自建索引字段并在客户端过滤。 ## 另见 - [创意工作流](https://docs.reelway.ai/api-reference/workflows.md) —— 执行面;回放记录承担「可复现上下文」的归档面 - [工作流模板](https://docs.reelway.ai/api-reference/templates.md) —— 模板持久化的替代方案 --- url: https://docs.reelway.ai/api-reference/worker-analytics.md --- > 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. # 节点分析 「节点分析」覆盖两类只读数据:平台运营方的**车队观测**(admin 面)与所有开发者可见的**模型供给/需求信号**。 ## 车队观测(admin 面) GEThttps://rcn.reelway.ai/admin/workers鉴权:admin 在线节点车队观测,只读 以 admin 凭证(`Bearer ∈ REELWAY_ADMIN_KEYS`)查询在线节点的实时快照: | 字段 | 说明 | | ---------------------------- | ----------- | | `appID` | 节点连接的 appId | | `workerType` | 节点类型标识 | | `workerModels[]` | 能力上报的模型集 | | `hardwareRating` | 硬件评级 | | `ready` | 就绪门控状态 | | `inflightJobs[]` | 在途任务 | | `connectedAt` / `lastSeenAt` | 接入与最近心跳时间 | 供平台运营与[节点面板](https://docs.reelway.ai/run-a-worker/comfy-worker/worker-dashboard.md)取数;`GET /admin/stats` 提供平台级统计聚合。 ## 模型需求信号 GEThttps://rcn.reelway.ai/v1/model-demand?network=鉴权:公开 网络维度的模型供给/需求 响应 `data.demand`。开发者的可操作信号是:目录中 `downloads` 维度反映真实使用量,派单计数以节点实际服务为准。配合 `GET /v1/model-catalog` 使用,见[模型与网络需求](https://docs.reelway.ai/api-reference/model-discovery.md)。 ## 轮询建议 车队观测面向运营大屏,建议 5–15 秒轮询;`model-demand` 变化缓慢,分钟级轮询足够。两个端点均为只读,无副作用。 --- url: https://docs.reelway.ai/api-reference/model-discovery.md --- > 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. # 模型与网络需求 生成模型(图像/视频/语音)的**权威目录**是公开端点,无需凭证即可查询;构建模型白名单、参数 UI 与容量预估都应以运行时目录为准。 GEThttps://rcn.reelway.ai/v1/model-catalog?mediaType=&network=鉴权:公开 全目录;ETag 命中 304 GEThttps://rcn.reelway.ai/v1/model-catalog/{modelId}鉴权:公开 单模型;未收录 404 GEThttps://rcn.reelway.ai/v1/model-demand?network=鉴权:公开 网络维度的供给/需求 GEThttps://rcn.reelway.ai/v1/model-gallery鉴权:公开 模型样例图库(当前恒空) GEThttps://rcn.reelway.ai/v1/loras/comfy鉴权:公开 节点侧 ComfyUI LoRA 目录(当前恒空) ## 目录响应 ```json { "status": "success", "data": { "catalogVersion": "…", "updatedAt": "2026-11-02T12:00:00Z", "models": [ { "id": "minimax-h3-fl2va-fp8_t2v_turbo", "name": "MiniMax H3 Turbo T2V", "mediaType": "video" } ] } } ``` 关键语义: - `catalogVersion` / `updatedAt` 支持对账;请求携带 `If-None-Match` 命中时返回 `304`。 - 模型 id 命名规则 `---<精度>_<任务>[_档位]`,详见[模型指南](https://docs.reelway.ai/models/index.md)。 - `mediaType`: `image | video | audio`;`network` 参数过滤 `fast | relaxed` 可用集。 ## 用法示例 ```bash # 视频模型清单 curl "https://rcn.reelway.ai/v1/model-catalog?mediaType=video" | jq '.data.models[].id' ``` ## 错误 | HTTP | 说明 | | ---- | --------------------------------------- | | 400 | 查询参数非法 | | 404 | `GET /v1/model-catalog/{modelId}`:模型未收录 | `catalogVersion` / `updatedAt` 语义以响应为准;目录更新通过版本号与时间戳对账。 --- url: https://docs.reelway.ai/api-reference/sdks.md --- > 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. *** title: SDK 与资源 description: @reelway/client、llms.txt、示例仓库与支持渠道。 ------------------------------------------------ # SDK 与资源 ## 客户端库 `@reelway/client` —— JavaScript / TypeScript 客户端,由官方 Sogni SDK fork 而来,接口契约一致,默认对接 reelway 平台(`https://rcn.reelway.ai` 与 `wss://rcn.reelway.ai/socket`)。 ```bash git clone git@git.ensurebit.net:reelway/reelway-client-ts.git && cd reelway-client-ts npm install && npm run build npm pack # 生成 tgz,业务仓以 npm install 引用 ``` 详见 [Reelway SDK](https://docs.reelway.ai/sdk/index.md) 与 [JavaScript / TypeScript 客户端](https://docs.reelway.ai/sdk/javascript-client.md)。 ## LLM 友好资源 本站每页提供 Markdown 版本(`<页面路径>.md`),另有全站索引: - [`/llms.txt`](https://docs.reelway.ai/llms.txt) —— 页面索引 - [`/llms-full.txt`](https://docs.reelway.ai/llms-full.txt) —— 全文单文件 ## 示例 `reelway-client-ts` 仓的 `examples/` 提供 \~35 个可运行示例(t2i、i2v、t2v、r2v、TTS、chat、工具调用、创意工作流、LoRA、事件驱动等);示例当前以 Sogni 端点演示契约,接入 reelway 只需替换端点与 Key。 :::warning 示例使用 Sogni 端点演示 examples/ 的示例代码面向上游契约编写,模型 ID 与端点未替换为 reelway 生产值。运行前请把端点改为 `https://rcn.reelway.ai` 并换用 reelway 模型 ID(见[模型指南](https://docs.reelway.ai/models/index.md))。 ::: ## 支持渠道 - 平台公告:`GET /v1/announcements/active`(见[余额与用量](https://docs.reelway.ai/api-reference/account-and-usage.md)) - 问题反馈:控制台或联系平台运营 --- url: https://docs.reelway.ai/intelligence/introduction.md --- > 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 Intelligence Reelway Intelligence 是面向构建者的 AI 平台层:以 **OpenAI 兼容**的方式提供对话与智能体能力,并以 Sogni 协议兼容的通道承载生成与工作流。 ## 能力一览 | 能力 | 入口 | 状态 | | ------------------------- | ---------------------------------- | ------------------------------------------------------ | | 对话补全(OpenAI 兼容,支持流式与函数工具) | `api.reelway.ai/v1` | | | LLM 模型列表 | `GET api.reelway.ai/v1/models` | | | 持久对话运行(可恢复、事件流) | `rcn.reelway.ai` `/v1/chat/runs` | | | 创意工作流(多步 DAG) | `/v1/creative-agent/workflows` | | | 同步托管工具(6 个) | `/v1/creative-agent/tools/execute` | | ## 面向智能体与集成 - **任何 OpenAI SDK / 框架**:改 `baseURL` 即可接入对话补全,计费走 Reelway 余额。 - **智能体框架**:以[API Key](https://docs.reelway.ai/api-reference/api-keys.md)为智能体建独立身份与限额;长任务用[持久对话运行](https://docs.reelway.ai/intelligence/durable-chat-runs.md)与[创意工作流](https://docs.reelway.ai/intelligence/creative-agent-workflows.md)获得可恢复性。 - **通用工具集成**:Open WebUI、OpenClaw、Hermes Agent 等以 OpenAI 兼容端点接入,见各集成页。 ## 计费 统一从账户余额按量计费:受理时按预估扣费、完成时校正;失败不计费。详见[计费与成本控制](https://docs.reelway.ai/intelligence/billing-and-cost-control.md)。 ## 下一步 **5 分钟接入** ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.reelway.ai/v1', apiKey: process.env.REELWAY_API_KEY }); ``` 见[OpenAI SDK 兼容性](https://docs.reelway.ai/intelligence/openai-sdk-compatibility.md)。 **生产形态** 无服务器集成走[持久对话运行](https://docs.reelway.ai/intelligence/durable-chat-runs.md)与[创意工作流](https://docs.reelway.ai/intelligence/creative-agent-workflows.md)的幂等创建 + SSE 事件流;交互式应用走 `@reelway/client` 的实时通道。 --- url: https://docs.reelway.ai/intelligence/chat-completions.md --- > 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. # 对话补全 本页是 Intelligence 视角的**构建指南**;端点字段级细节见 [API 参考 → 对话补全](https://docs.reelway.ai/api-reference/chat-completions.md)。 ## 基本用法 ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.reelway.ai/v1', apiKey: process.env.REELWAY_API_KEY, }); const completion = await client.chat.completions.create({ model: 'qwen3.6-35b-a3b-gguf-iq4xs', messages: [ { role: 'system', content: '你是短视频口播稿改写助手。' }, { role: 'user', content: '把这段简介改写成视频口播稿:…' } ], }); console.log(completion.choices[0].message.content); ``` ## 流式 ```js const stream = await client.chat.completions.create({ model, messages, stream: true }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content ?? ''); } ``` 网关已配置 `flush_interval -1`:流式响应不被代理缓冲,SSE 分片即时到达。 ## 函数工具调用 标准 OpenAI `tools` 数组与 `tool_choice`;模型返回 `tool_calls` 后由你的代码执行工具并回填 `role: "tool"` 消息。 ## 计费 按输入/输出 token 计费,统一余额扣费(受理时预估、完成时校正)。单价以模型卡片与价格规则为准。 ## 陷阱与建议 - `developer` 角色被归一为 `system`;不要依赖两者的区分。 - 对话历史由调用方维护;需要服务端可恢复的长对话请改用[持久对话运行](https://docs.reelway.ai/intelligence/durable-chat-runs.md)。 - 限流退避、`429`/`Retry-After` 处理与[生产集成](https://docs.reelway.ai/api-reference/production-integrations.md)一致。 --- url: https://docs.reelway.ai/intelligence/openai-sdk-compatibility.md --- > 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. # OpenAI SDK 官方兼容 推理面与 OpenAI Chat Completions API 同形:`POST https://api.reelway.ai/v1/chat/completions`。 ## 官方 SDK | 语言 | 接入 | | --------------------- | -------------------------------------------------------------- | | JavaScript / TS | `new OpenAI({ baseURL: 'https://api.reelway.ai/v1', apiKey })` | | Python | `OpenAI(base_url='https://api.reelway.ai/v1', api_key=…)` | | Go / .NET / Java 等官方库 | 同样以 `baseURL` + `api_key` 两项切换 | 任何以 OpenAI 协议为默认方言的框架(LangChain、LlamaIndex、AutoGen、Vercel AI SDK 等)同样适用。 ## 平台差异 | 项 | 说明 | | ---------- | ------------------------------------------------------------------------------------------------------------------------- | | 模型列表 | `GET /v1/models` 返回网关配置的模型;以运行时查询为准,不要硬编码 | | 计费 | 走 Reelway 余额,不走 OpenAI 账号;`429` 附 `Retry-After` | | Sogni 兼容字段 | `token_type` / `billing_mode` 仅作形状兼容;`sogni_tools` 未提供 | | 创意能力 | 对话补全是纯文本(含函数工具);图像/视频/语音生成走 [rcn 生成面](https://docs.reelway.ai/api-reference/direct-generation.md),不在 `chat/completions` 内 | ## 验证连通 ```bash curl https://api.reelway.ai/v1/models \ -H "Authorization: Bearer $REELWAY_API_KEY" ``` 返回模型列表即接入成功;`401` 说明 Key 无效,见[API Keys](https://docs.reelway.ai/api-reference/api-keys.md)。 --- url: https://docs.reelway.ai/intelligence/durable-chat-runs.md --- > 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:创建即受理、幂等去重、事件流断线重放、费用自动校正。端点细节见 [API 参考 → 持久对话运行](https://docs.reelway.ai/api-reference/chat-runs.md)。 ## 何时用 runs 而不是 completions | 场景 | 选择 | | --------------------- | ---------------- | | 函数计算 / 队列消费者,进程随时可能消失 | runs(幂等键 + 事件回放) | | 交互式聊天,历史由前端维护 | completions | | 高价值长任务(整理长文档、多轮规划) | runs | | 需要对账与审计每一步 | runs(事件历史永久保留) | ## 创建并消费 ### 创建 `POST /v1/chat/runs` + `Idempotency-Key`;`202` 返回 `chatRun.id`。请求体与 completions 同形。 ### 订阅或轮询事件 长连接组件订阅 `GET …/{id}/events/stream`(SSE);无连接环境轮询 `GET /v1/chat/runs/{id}` 或以 `after` 参数分页事件。断线重放:`Last-Event-ID` 头携带最后收到的 `seq`。 ### 取终态 终态事件(`run_completed` / `run_failed` / `run_cancelled`)后服务端关流;产物与状态经 GET 获取。 ## 计费与状态 - 受理即按预估扣费,完成时校正;失败与取消不计费(已扣部分自动校正)。 - 状态机 `created → running → completed | failed | cancelled`;`cancel` 对终态运行返回 `409`(`1006`)。 - `confirm-cost` 端点为 Sogni 兼容保留(当前恒 `409`,引擎无费用审批暂停)。 ## 与创意工作流的关系 对话任务用 runs;**多步媒体生产**(生成→编辑→合成)用[创意工作流](https://docs.reelway.ai/intelligence/creative-agent-workflows.md):DAG 结构、`dependsOn` 依赖、`reseed` 换种子重播。两者共享幂等键机制与 SSE 事件协议。 --- url: https://docs.reelway.ai/intelligence/media-upload-urls.md --- > 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. # 媒体上传 URL 托管工具与生成任务需要「HTTP(S) URL」形态的媒体引用(`media_references` 校验 http(s),`1009` 错误码兜底)。把本地文件变成可引用 URL 的两条路径: | 方式 | 端点 | 适用 | | | ---------- | ------------------------------------------------- | --------------------- | ------------------ | | 预签名 URL 直传 | \`GET /v1/image | media/uploadUrl\` | 一次性输入(首帧、参考图、参考音频) | | 获取下载 URL | \`GET /v1/image | media/downloadUrl\` | 读取已完成项目的产物或已上传槽位 | | 资产库(可复用) | `POST /v1/assets/prepare → PUT → finalize → bind` | 同一文件被多个项目引用、需要去重与配额管理 | | ## 直传示例 ```bash # 1. 申请上传 URL curl "https://rcn.reelway.ai/v1/image/uploadUrl?type=referenceImage&jobId=$JOB_ID&contentType=image/png" \ -H "api-key: $REELWAY_API_KEY" # 2. PUT 文件体(原样携带 uploadHeaders) curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @ref.png ``` 槽位枚举(image 侧):`preview`、`complete`、`startingImage`、`cnImage`、`contextImage1..16`、`keyframeImage1..8`、`referenceImage`、`referenceImageEnd`、`referenceMask`;media 侧:`referenceAudio`、`referenceVideo`。细节见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md)。 ## 资产库四步 `prepare` 按 sha256 去重(同文件直接 `reused: true` 跳过上传),`finalize` 复验哈希与大小后置 `ready`,`bind` 把资产绑定到项目槽位;配额见[媒体工具](https://docs.reelway.ai/api-reference/media-utilities.md)。 ## 错误速查 | HTTP | 错误码 | 场景 | | ---- | ------ | ------------------------------------- | | 400 | `1009` | 工作流 `media_references` 引用了非 http(s) 值 | | 404 | — | `downloadUrl` 对象不存在 | | 423 | — | `bind` 时资产非 `ready` | --- url: https://docs.reelway.ai/intelligence/billing-and-cost-control.md --- > 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. # 计费与成本控制 ## 钱从哪里扣 统一从**账户余额**扣费。查询 `GET /v4/account/balance`,流水 `GET /v1/transactions/list`。不存在代币双轨或订阅抵扣。 ## 扣费时点 ``` 提交 ──受理(按预估扣费)──► 执行 ──完成(按实际校正)──► 差额回补 ``` 失败或无产物的任务不计费;已在途任务不受余额波动影响。 ## 成本控制手段 | 手段 | 机制 | | -------- | --------------------------------------------------------------------------------------------------- | | 单 Key 限额 | 为每把 API Key 设置配额,触顶 `402`(`1013`);隔离失控重试的爆炸半径 | | 幂等键 | 三个付费 `POST`(workflows / chat runs / world builds)携带 `Idempotency-Key`,网络重试不会重复扣费(同键异体 `422`/`1012`) | | 目录刷新 | 模型不在目录 `400`(`1002`)、缺价格行 `400`(`1014`)在**扣费前**拒绝 | | 预估 | socket estimate 端点返回结构完整的零报价(`preview`),实际扣费以受理时价格规则为准 | | 余额告警 | 监控 `GET /v4/account/balance` 并设阈值;余额不足时提交在扣费前被拒(`402`/`1005`) | ## 对账 - 流水 `GET /v1/transactions/list` 分页(`limit`/`offset`,`next` 游标);按 Key 拆分的用量在控制台 Key 列表。 - [回放记录](https://docs.reelway.ai/api-reference/replay.md)可把每次任务的参数与种子归档,支撑事后复现与审计。 ## 分销场景 下级账户的余额由分销商充值,费率沿链连乘;分销商毛利报表见[分销体系](https://docs.reelway.ai/pricing/reseller.md)。 --- url: https://docs.reelway.ai/intelligence/creative-agent-workflows.md --- > 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. # 创意智能体工作流 工作流面向**多步媒体生产**:生成→编辑→合成的多步链条、需要断线恢复与对账的长任务。单次对话用 runs,单步工具用 tools/execute;链条用 workflow。 ## 何时用 - 一条生成链(提示词扩写 → 生成视频 → 提取参数)需要按依赖顺序执行; - 任务价值高,进程重启不能丢:幂等创建 + 事件回放; - 需要换种子重播同结构任务:`reseed`。 ## 创建 ```bash curl --fail-with-body https://rcn.reelway.ai/v1/creative-agent/workflows \ -H "api-key: $REELWAY_API_KEY" -H "Idempotency-Key: wf-" \ -d '{"steps":[{"id":"shot","tool":"generate_video","input":{"model":"minimax-h3-fl2va-fp8_t2v_turbo","prompt":"…"}}]}' ``` 请求体 ≤ 1 MiB、严格解码(`1010`);DAG 环 `1007`、`dependsOn` 缺失 `1008`。响应 `201` 工作流形状。端点族细节见 [API 参考 → 创意工作流](https://docs.reelway.ai/api-reference/workflows.md)。 ## 消费事件 SSE(`…/events/stream`,`Last-Event-ID` 重放)或 `after` 分页轮询;事件形状 `{seq, name, payload, createdAt}`;终态后关流。产物经 `downloadUrl` 签发(48 小时)。 ## 重播(reseed) `POST …/{id}/reseed` body `{seed_overrides: {stepId: seed}}` 产生一次**新 run**(201),原 run 保留;适合同一结构批量探索种子。 预览执行器 M1 为占位:契约稳定,内容质量随真实引擎接入提升 --- url: https://docs.reelway.ai/intelligence/workflow-templates.md --- > 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. # 工作流模板 模板解决「同一结构、不同输入」的复用:商品视频模板 × N 个商品、口播视频模板 × N 个脚本。Reelway 的模板能力由 `compose_workflow_template` 托管工具提供,组合出的模板定义由调用方持久化,执行时替换参数提交 `POST /v1/creative-agent/workflows`。 ## 组合与执行 ### 组合 `POST /v1/creative-agent/tools/execute`(`tool: compose_workflow_template`),arguments 填入简报与参数意图;响应含参数化模板与示例计划。 ### 持久化 模板 JSON 存入你的数据库(或经[回放记录](https://docs.reelway.ai/api-reference/replay.md)归档);服务端模板存储为规划中能力。 ### 执行 把参数替换为实际值,以 `Idempotency-Key` 提交 `POST /v1/creative-agent/workflows`,消费事件直到终态。 ## 与手工 DAG 的取舍 | 手工定义 DAG | compose_workflow_template | | ------------ | ------------------------- | | 完全掌控 step 结构 | 快速起草,产出可再手改 | | 适合稳定生产链 | 适合探索与模板化复用 | 工具当前为占位实现(预览);完整字段见 [API 参考 → 工作流模板](https://docs.reelway.ai/api-reference/templates.md) 。 --- url: https://docs.reelway.ai/intelligence/creative-agent-skill.md --- > 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. # 创意智能体技能 「技能」是把平台能力封装成智能体可复用单元的**实现模式**(而非服务端功能):受控的提示词模板 + 固定的工具组合 + 明确的输入输出契约。任何支持函数工具调用的智能体框架都能接入。 ## 技能的三要素 1. **提示词模板**:把创意意图固定为可参数化的提示词结构(如「产品 + 场景 + 镜头语言」三段式),避免自由发挥导致的参数漂移; 2. **工具面**:技能只暴露封装后的动作(如 `generate_product_shot`),内部固定模型 ID 与参数档位(如 `_turbo`),不把原始 API 面暴露给模型; 3. **输出契约**:统一返回产物 URL、种子与费用,便于上层审计。 ## 实现路径 - 底层动作走 [API 参考 → 直接工具执行](https://docs.reelway.ai/api-reference/tool-execution.md)与[生成配方](https://docs.reelway.ai/api-reference/direct-generation.md); - 多步链走[创意工作流](https://docs.reelway.ai/intelligence/creative-agent-workflows.md),技能 = 预定义 DAG + 参数; - 模板复用走[工作流模板](https://docs.reelway.ai/intelligence/workflow-templates.md); - 为智能体分配独立 [API Key](https://docs.reelway.ai/api-reference/api-keys.md)并设置限额,隔离成本。 预览托管工具为占位实现;技能模式本身不依赖占位工具,可先以生成 API 落地 --- url: https://docs.reelway.ai/intelligence/integration-open-webui.md --- > 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. # Open WebUI [Open WebUI](https://github.com/open-webui/open-webui) 支持「OpenAI 兼容连接」:把 Reelway 推理面挂为后端即可在 Open WebUI 中使用 Reelway 的 LLM。 ## 配置 只需两个值: | 项 | 值 | | ---------- | ---------------------------------------------------------------------- | | API 端点 URL | `https://api.reelway.ai/v1` | | API 密钥 | 你的 Reelway API Key([控制台创建](https://dashboard.reelway.ai/console/keys)) | 在 Open WebUI 的 **设置 → 外部连接(OpenAI API)** 中填入以上两项并保存;模型列表会自动拉取(对应 `GET /v1/models`)。界面名称与入口随 Open WebUI 版本略有差异,以你的版本为准。 ## 验证 回到对话页,选择拉取到的模型发送一条消息;失败时先在 Open WebUI 的连接测试或用 curl 验证: ```bash curl https://api.reelway.ai/v1/chat/completions \ -H "Authorization: Bearer $REELWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"qwen3.6-35b-a3b-gguf-iq4xs","messages":[{"role":"user","content":"ping"}]}' ``` ## 注意 - 计费走你的 Reelway 余额;为 Open WebUI 服务端使用独立 [API Key](https://docs.reelway.ai/api-reference/api-keys.md) 便于限额与审计。 - 嵌入(embedding)等其他能力不在 Reelway 推理面范围内,请保留 Open WebUI 原有配置。 --- url: https://docs.reelway.ai/intelligence/integration-openclaw.md --- > 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. # OpenClaw OpenClaw 属于「OpenAI 兼容提供方」生态:以 `baseURL` + API Key 两个值接入 Reelway。 ## 配置 | 项 | 值 | | ------- | ------------------------------------------------------------------- | | baseURL | `https://api.reelway.ai/v1` | | API Key | Reelway API Key([控制台创建](https://dashboard.reelway.ai/console/keys)) | | 模型 | 以 `GET /v1/models` 返回为准 | 在 OpenClaw 的提供方/模型配置中,选择 OpenAI 兼容类型并填入以上值;配置字段名随版本可能不同(`base_url` / `api_base` 等),语义一致即可。 ## 注意 - 计费走 Reelway 余额;为 OpenClaw 使用独立 [API Key](https://docs.reelway.ai/api-reference/api-keys.md)。 - 流式、函数工具调用按 OpenAI 协议透传;非文本能力(图像/视频/语音生成)不在 chat/completions 内,见[生成配方](https://docs.reelway.ai/api-reference/direct-generation.md)。 --- url: https://docs.reelway.ai/intelligence/integration-hermes-agent.md --- > 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. # Hermes Agent Hermes Agent 以 OpenAI 兼容端点接入 Reelway。 ## 配置 | 项 | 值 | | ------- | ------------------------------------------------------------------- | | 端点 | `https://api.reelway.ai/v1` | | API Key | Reelway API Key([控制台创建](https://dashboard.reelway.ai/console/keys)) | | 模型 | 以 `GET /v1/models` 返回为准 | 在 Hermes Agent 的模型/提供方设置中选择 OpenAI 兼容类型并填入以上值;字段名随版本可能不同,语义一致即可。 ## 注意 - 为智能体使用独立 [API Key](https://docs.reelway.ai/api-reference/api-keys.md) 并依赖单 Key 限额控制成本。 - 长任务的断线恢复请用[持久对话运行](https://docs.reelway.ai/intelligence/durable-chat-runs.md)的幂等创建与事件回放,而不是在智能体循环里裸调 completions。 --- url: https://docs.reelway.ai/sdk/index.md --- > 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. *** title: Reelway SDK description: @reelway/client —— JavaScript / TypeScript 客户端:安装、鉴权与能力面。 ---------------------------------------------------------------------- # Reelway SDK `@reelway/client` 是平台的官方客户端,由官方 Sogni SDK(`@sogni-ai/sogni-client`)fork 而来,**接口契约与上游一致**,默认对接 reelway 平台(REST `https://rcn.reelway.ai`,WebSocket `wss://rcn.reelway.ai/socket`),无需任何端点配置。 ## 安装 包未发布到 npm(构建产物不入库): ```bash git clone git@git.ensurebit.net:reelway/reelway-client-ts.git && cd reelway-client-ts npm install && npm run build npm pack # 生成 reelway-client-<版本>.tgz,业务仓以 npm install 引用 ``` ## 初始化与鉴权 ```js import { SogniClient } from '@reelway/client'; const client = await SogniClient.createInstance({ appId: 'my-app', // 每个客户端实例唯一;同账号同 appId 的新连接会接管旧连接 network: 'fast', // fast | relaxed apiKey: process.env.REELWAY_API_KEY, // 或 username/password 账号登录 }); ``` 鉴权二选一:[API Key](https://docs.reelway.ai/api-reference/api-keys.md)(推荐,控制台随时创建与复制)或 SDK 账户的用户名/密码。Key 由 SDK 代为放入 REST 请求头与 WebSocket 握手头。 ## 能力面 | 域 | 入口 | | ---------- | ---------------------------------------------------------------- | | 图像/视频/语音生成 | `client.projects.create()` + 事件(`progress`/`completed`/`failed`) | | 资产上传 | `client.projects.assets.upload(file, contentType, name)` | | 费用预估 | `client.projects.estimateVideoCost()` | | 对话与工具 | `client.chat.*`(契约同上游) | | 项目恢复 | 重连后自动 `projects/sync` | 各域的端点级细节见 [API 参考](https://docs.reelway.ai/api-reference/index.md);快速配方见[生成配方](https://docs.reelway.ai/api-reference/direct-generation.md)。 --- url: https://docs.reelway.ai/sdk/javascript-client.md --- > 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. *** title: JavaScript / TypeScript 客户端 description: @reelway/client 的完整使用指南:初始化、生成、上传、事件与恢复。 ----------------------------------------------------- # JavaScript / TypeScript 客户端 ## 事件驱动与 Promise 两种风格 ```js // 事件驱动 const project = client.projects.create({ modelId: 'z_image_turbo_bf16', positivePrompt: '…' }); project.on('progress', (p) => console.log(p.progress)); project.on('completed', (urls) => console.log(urls)); // Promise 风格 const urls = await project.waitForCompletion(); // 48 小时有效签名 URL ``` ## 上传输入 SDK 接受 `Buffer` / `Blob` / `File` 并自动完成预签名上传: ```js import fs from 'node:fs'; const project = client.projects.create({ modelId: 'minimax-h3-fl2va-fp8_i2v', positivePrompt: '人物转身微笑', referenceImage: fs.readFileSync('./first-frame.png'), }); // 可复用资产:显式上传 const saved = await client.projects.assets.upload(file, file.type, 'product-ref'); ``` ## 预估费用 ```js const quote = await client.projects.estimateVideoCost({ modelId, duration }); ``` 预览预估当前返回结构完整的零报价,实际以受理时价格规则为准 ## 恢复与多实例 - **同账号同 `appId` 的新连接以关闭码 `4015` 接管旧连接**;多实例请用不同 `appId`。 - 进程重启后 SDK 重连时自动调用 `projects/sync`,继续追踪在途项目并领取已完成结果。 ## 更多 - 上游契约的完整能力说明与示例见 `reelway-client-ts` 仓的 `README.md`、`llms.txt`、`examples/`(35+ 可运行示例)。 - 端点级参考见 [API 参考](https://docs.reelway.ai/api-reference/index.md);视频模型参数见[模型指南](https://docs.reelway.ai/models/index.md)。 --- url: https://docs.reelway.ai/sdk/intelligence-client.md --- > 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. # Intelligence 客户端 Reelway 的 Intelligence 能力不发布独立 SDK:推理面与 OpenAI 同形,**OpenAI 官方 SDK 就是 Intelligence 客户端**。 ```js import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.reelway.ai/v1', apiKey: process.env.REELWAY_API_KEY }); ``` 对话、流式与函数工具的用法见[OpenAI SDK 兼容性](https://docs.reelway.ai/intelligence/openai-sdk-compatibility.md);服务端持久运行经 REST 直接调用 `POST /v1/chat/runs`,见[持久对话运行](https://docs.reelway.ai/intelligence/durable-chat-runs.md)。 --- url: https://docs.reelway.ai/sdk/protocol.md --- > 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 协议 平台实时通道挂载于 `wss://rcn.reelway.ai/socket`,按握手头 `client-type` 分流为两条同构通道;线协议统一为 `{type, data: base64(JSON)}`。端点级细节见 [API 参考 → 快速开始](https://docs.reelway.ai/api-reference/getting-started.md#websocket-%E6%8F%A1%E6%89%8B)。 ## 通道与鉴权 | 通道 | client-type | 凭证 | 附加 | | | ------ | ----------- | ------------------ | --------------------------------------- | ------------------------------------ | | artist | (缺省) | `api-key` 或 JWT | 查询串 `?appId=`、可选 \`forceWorkerId=fast | relaxed`、`socketEventSubscriptions\` | | worker | `worker` | worker 用途的 API Key | 头 `app-id`(节点 UUID,必填)、可选 `worker-type` | | 关闭码:`4021` 认证失败;`4015` 同 id 接管。心跳:服务端 25 s ping、60 s pong 窗口;artist 单帧上限 1 MiB、worker 8 MiB。 ## artist 通道帧速查 | 方向 | type | 语义 | | -- | ------------------------------------------------------ | ----------------------------------------------------- | | ↑ | `jobRequest` | 提交项目(`keyFrames[0]` 携带模型与提示词参数) | | ↑ | `jobError` | 仅 artistCanceled 语义(取消);回执 `artistCancelConfirmation` | | ↑ | `changeNetwork` | fast ⇄ relaxed | | ↑ | `setSocketEventSubscriptions` | 事件订阅快照 | | ↓ | `authenticated` | 首帧:余额、网络、activeProjects、unclaimedCompletedProjects | | ↓ | `swarmModels` | `{modelId: workerCount}` | | ↓ | `projectQueue` / `jobState` / `jobProgress` / `jobETA` | 排队、状态、进度、ETA | | ↓ | `jobResult` / `jobError` | 产物(48 h 签名 URL)与失败 | | ↓ | `artistCancelConfirmation` | 取消回执 | ## worker 通道帧速查 | 方向 | type | 语义 | | -- | ----------------------------------------------------- | --------------------------------------------------------------- | | ↑ | `workerInfo` | 全量能力快照(workerModels\[]、loadedModelID、hardwareRating) | | ↑ | `workerModelsChange` | 模型集增量 | | ↑ | `readyToAcceptJobs` | 就绪门控(含断线清理标记 postDisconnectCleanupComplete) | | ↑ | `jobState` / `jobProgress` / `jobResult` / `jobError` | 执行遥测与结果 | | ↓ | `authenticated` | 空负载确认 | | ↓ | `jobRequest` | 派单(jobID、imageId、workflowId、clientParams、previews、outputFormat) | | ↓ | `jobCancel` | 取消在途任务 | 完整帧负载字段见 [API 参考](https://docs.reelway.ai/api-reference/getting-started.md)与节点侧[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md)。 --- url: https://docs.reelway.ai/models/index.md --- > 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. # 模型指南 平台当前提供 4 个模型族、19 个模型 ID。权威来源是公开目录 `GET /v1/model-catalog`(见[模型与网络需求](https://docs.reelway.ai/api-reference/model-discovery.md));本指南按族整理能力与参数边界。 ## 能力矩阵 | 族 | 媒体 | 任务 | 档位 | 模型 ID 数 | | -------------------------------------------------------------------- | -- | ----------------------- | --------------------------------- | ------- | | [MiniMax H3](https://docs.reelway.ai/models/minimax-h3.md) | 视频 | t2v / i2v / flf2v / r2v | base / balanced / turbo(+r2v 两段式) | 16 | | [Qwen Image 2512](https://docs.reelway.ai/models/qwen-image-2512.md) | 图像 | 文生图 | — | 1 | | [Z-Image Turbo](https://docs.reelway.ai/models/z-image-turbo.md) | 图像 | 文生图 | — | 1 | | [CosyVoice 3 TTS](https://docs.reelway.ai/models/cosyvoice3-tts.md) | 音频 | 零样本克隆 TTS | — | 1 | 模型 id 命名规则:`---<精度>_<任务>[_档位]`。**checkpoint 族段如实反映实际权重**(例如 hybrid 档使用混合 int8 权重),命名不随任务漂移。 ## 选择建议 - 快速出片:`minimax-h3-fl2va-fp8_t2v_turbo`(4 步)、`z_image_turbo_bf16`(4 步); - 质量优先:`minimax-h3-fl2va-fp8_t2v`(20 步)、`qwen_image_2512_fp8`(20 步); - 主体一致性:R2V 族(`referenceImage` + `contextImages`,参考上限 9 图/3 视频/3 音频); - 语音:`cosyvoice3-tts-0.5b`,3–30 秒参考音频克隆音色。 :::info 目录先行 模型上下线频繁;构建白名单与参数 UI 时以运行时目录为准(ETag/304 支持),不要硬编码模型列表。 ::: --- url: https://docs.reelway.ai/models/minimax-h3.md --- > 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. # MiniMax H3 与 H3 Turbo MiniMax H3 是平台的主力视频族:四种输入模式、三档速度、原生音频输出、24 fps。 ## 模型 ID 一览 | 任务 | base | balanced | turbo | | ------------- | ------------------------------------ | ----------------------- | --------------- | | 文生视频 t2v | `minimax-h3-fl2va-fp8_t2v` | `…_t2v_balanced` | `…_t2v_turbo` | | 图生视频 i2v | `…_i2v` | `…_i2v_balanced` | `…_i2v_turbo` | | 首尾帧 flf2v | `…_flf2v` | `…_flf2v_balanced` | `…_flf2v_turbo` | | 参考视频 r2v | `minimax-h3-ref2va-fp8_r2v` | `…_r2v_balanced` | `…_r2v_turbo` | | 两段式 r2v | `…_r2v_2stage` | `…_r2v_balanced_2stage` | — | | 混合 int8 | `minimax-h3-fl2va-ref2va-int8_r2v` | — | — | | 混合 int8 flf2v | `minimax-h3-fl2va-ref2va-int8_flf2v` | — | — | ## 档位差异 | 档位 | 步数 | 采样器 | 参考表 | | -------- | ------------------------ | ------------- | ------- | | base | 20(固定) | res_multistep | 质量优先 | | balanced | 8(固定) + shift 4–12(默认 6) | — | 速度/质量折中 | | turbo | 4(固定) | euler | 最快出片 | ## 共同参数边界 | 参数 | 取值 | | ---- | ---------------------------------------------- | | 提示词 | ≤ 7000 字符 | | 尺寸 | 480–1344,步进 32;默认 1344×768,`maxPixels` 1032192 | | 帧数 | 124–362,步进 17(即约 5–15 秒 @24fps) | | 帧率 | 24 fps(固定) | | 音频 | 原生音频;`generateAudio` 缺省开启,可关 | | 引导系数 | 固定 `1` | 细节以目录与参数卡(`GET /v1/model-catalog/{id}`)为准。 ## 输入模式 - **t2v**:仅文本; - **i2v**:参考图作首帧(`referenceImage`); - **flf2v**:首帧 + 尾帧(`referenceImage` + `referenceImageEnd`); - **r2v**:多参考(`inputMode: multi-reference`):上限 **9 图 / 3 视频 / 3 音频 / 12 资产**,`referenceImage` + `contextImages`。 - 两段式(`_2stage`):同 r2v 输入,先渲染后放大精修,尺寸下限降至 384(384–1344),输出翻倍分辨率。 - 混合 int8(`minimax-h3-fl2va-ref2va-int8_flf2v` / `_r2v`):12 步,帧上限 481,默认竖屏 704×1280。 :::tip 关键帧(keyframes) 除 t2v 外,H3 全族支持**中间关键帧**:最多 8 张,以 `{image, frameIndex}` 钉在 24fps 时间线上(帧 0 与最后一帧由输入模式占据)。SDK 上传槽位为 `keyframeImage1..8`。 ::: ## 用法 ```js const project = client.projects.create({ modelId: 'minimax-h3-fl2va-fp8_t2v_turbo', positivePrompt: '一只橘猫在雨后的屋顶上伸懒腰,镜头缓慢推进,环境音', }); const [videoUrl] = await project.waitForCompletion(); ``` 输入上传与槽位见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md);配方见[生成配方](https://docs.reelway.ai/api-reference/direct-generation.md)。 --- url: https://docs.reelway.ai/models/qwen-image-2512.md --- > 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. # Qwen Image 2512 `qwen_image_2512_fp8` 是平台的**质量优先**文生图模型:默认 1328×1328、最高 2048×2048,20 步 euler/simple。 | 参数 | 取值 | | ----- | --------------------------- | | 模型 ID | `qwen_image_2512_fp8` | | 步数 | 1–50,默认 20 | | 引导系数 | 0–10(一位小数),默认 4 | | 尺寸 | 256–2048,步进 16;默认 1328×1328 | | 采样器 | euler / simple(固定组合) | | 负向提示词 | 支持 | ```js const project = client.projects.create({ modelId: 'qwen_image_2512_fp8', positivePrompt: '黄昏下的江南水乡,倒影,胶片质感', negativePrompt: '模糊, 低质量', }); ``` :::info 参数卡口径 参数卡来源标注为「derived: reelway-comfyui 工作流模板默认值(非 Sogni 官方参数卡快照)」——数值真实可用,标注口径诚实。以 `GET /v1/model-catalog/{id}` 运行时为准。 ::: 另见[模型指南](https://docs.reelway.ai/models/index.md)与[生成配方](https://docs.reelway.ai/api-reference/direct-generation.md)。 --- url: https://docs.reelway.ai/models/z-image-turbo.md --- > 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. # Z-Image Turbo `z_image_turbo_bf16` 是**速度优先**的文生图模型:默认 4 步、1024×1024,适合交互式场景与批量草稿。 | 参数 | 取值 | | ----- | ---------------------------- | | 模型 ID | `z_image_turbo_bf16` | | 步数 | 1–12,默认 4 | | 引导系数 | 0–5(一位小数),默认 1 | | 尺寸 | 256–2048,步进 16;默认 1024×1024 | | 采样器 | res_multistep / simple(固定组合) | ```js const project = client.projects.create({ modelId: 'z_image_turbo_bf16', positivePrompt: '赛博朋克雨夜街道,霓虹倒影', seed: 42, }); ``` 它是当前**真实派单**链路最早打通的图像模型(生产验证最充分)。另见[模型指南](https://docs.reelway.ai/models/index.md)。 --- url: https://docs.reelway.ai/models/cosyvoice3-tts.md --- > 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. # CosyVoice 3 TTS `cosyvoice3-tts-0.5b` 提供零样本声音克隆:一段 3–30 秒的参考音频即可复刻音色,合成任意中文文本语音。 | 参数 | 取值 | | ----- | ------------------------------------- | | 模型 ID | `cosyvoice3-tts-0.5b` | | 输入模式 | `zero-shot-clone` | | 提示词 | 即要合成的文本,≤ 5000 字符 | | 参考音频 | 必填;3–30 秒;走 media 槽位 `referenceAudio` | | 产物 | 音频文件,经 `GET /v1/media/downloadUrl` 签发 | ```js const project = client.projects.create({ modelId: 'cosyvoice3-tts-0.5b', positivePrompt: '欢迎使用 Reelway,祝你创作愉快。', referenceAudio: fs.readFileSync('./voice.wav'), }); const [audioUrl] = await project.waitForCompletion(); ``` 参考音频要求清晰、单人、无背景音乐;克隆质量随参考时长在 3–30 秒区间提升。TTS 作为 `audio` 媒体项目提交,走与图像/视频相同的[项目生命周期](https://docs.reelway.ai/api-reference/project-status.md)。 --- url: https://docs.reelway.ai/run-a-worker/index.md --- > 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 算力协作网络(RCN)由运行 ComfyUI 节点软件的 GPU 主机组成。节点以 WebSocket 接入 `wss://rcn.reelway.ai/socket`,接收派单、渲染、回传产物,按完成任务结算到账户余额。 ## 接入三要素 1. **账户与 API Key**:在[控制台](https://dashboard.reelway.ai/console/keys)为每台节点单独创建子 Key; 2. **节点软件**:基于 `reelway-comfyui` fork 的 ComfyUI 节点镜像(视频与图像模型); 3. **接入协议**:见[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md)——握手、能力上报、就绪门控、派单与结果回传。 ## 本节导览 - [关于 Reelway Worker](https://docs.reelway.ai/run-a-worker/comfy-worker/about.md) —— 节点软件职责与目录面 - [硬件要求](https://docs.reelway.ai/run-a-worker/comfy-worker/hardware-requirements.md) · [本地运行](https://docs.reelway.ai/run-a-worker/comfy-worker/running-locally.md) · [远程运行](https://docs.reelway.ai/run-a-worker/comfy-worker/running-remotely.md) - [高级配置](https://docs.reelway.ai/run-a-worker/comfy-worker/advanced-configuration.md) · [节点面板](https://docs.reelway.ai/run-a-worker/comfy-worker/worker-dashboard.md) · [节点常见问题](https://docs.reelway.ai/run-a-worker/comfy-worker/faq.md) - [版本说明](https://docs.reelway.ai/run-a-worker/comfy-worker/release-notes.md) · [节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md) :::info 当前接入形态 公开的一键安装器与官方镜像分发**尚未提供**(规划中);当前接入方式为基于 `reelway-comfyui` fork 自建镜像并以节点协议接入。收益按完成任务结算到账户余额,费率见[方案与定价](https://docs.reelway.ai/pricing/index.md)。 ::: --- url: https://docs.reelway.ai/run-a-worker/comfy-worker/about.md --- > 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 Worker Reelway Worker 是运行在 GPU 主机上的节点软件,核心是 **ComfyUI fork**(reelway-comfyui):以常驻服务监听本地 8188,叠加平台兼容层(8 项兼容层对齐平台协议),经 WebSocket 接入 RCN 接收派单。 ## 职责 1. **能力上报**:`workerInfo` 上报可服务的模型集(`workerModels[]`)、当前加载模型与硬件评级; 2. **执行派单**:按 `jobRequest.clientParams` 选择工作流模板,渲染并回传 `jobProgress` / `jobResult`; 3. **模型目录消费**:启动与运行期从 `GET /v1/worker/config/comfy` 拉取目录(1 分钟缓存),`filter` 支持按 `workflowDependencies` 键子串过滤; 4. **产物回传**:凭 `(jobId, imageId)` 申请 `complete` 槽位上传产物。 ## 工作流模板 平台侧目录(`workflowDependencies`)定义每个模型 ID 对应的工作流模板与依赖;**模板无自动更新**——模板随节点镜像(仓库)发布,更新走「更新镜像/仓库 + 重启」。协议细节见[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md)。 ## 目录面差异说明 上游 Sogni 的 Comfy Worker 镜像(`sogni/comfy-worker` 系列)与本节点软件同源;Reelway 当前未提供公开镜像分发,接入方式见[本地运行](https://docs.reelway.ai/run-a-worker/comfy-worker/running-locally.md)。 --- url: https://docs.reelway.ai/run-a-worker/comfy-worker/hardware-requirements.md --- > 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. # 硬件要求 ## GPU 与显存 | 项 | 要求 | | --- | ------------------------------------------- | | GPU | NVIDIA,支持 CUDA 的 x86-64 主机;主力验证环境为 RTX 5090 | | 显存 | 视频模型(H3)建议 ≥ 24 GB;图像模型要求更低 | | 磁盘 | 模型与资产缓存:200 GB 起步(H3 全族权重较重);SSD 推荐 | | 网络 | 与 `rcn.reelway.ai` 保持稳定长连接;产物上传带宽影响吞吐 | | 驱动 | 与镜像内 CUDA 版本匹配的 NVIDIA 驱动 | ## 平台无关口径 - 上游镜像另有 DGX Spark 与 ARM64 变体;Reelway 当前以 x86-64 + NVIDIA 为主; - 硬件评级(`hardwareRating`)在 `workerInfo` 中上报,参与派单选择; - 不同模型的实际显存占用以各模型工作流模板为准;跨工作流切换注意[高级配置](https://docs.reelway.ai/run-a-worker/comfy-worker/advanced-configuration.md)中的显存释放约定。 --- url: https://docs.reelway.ai/run-a-worker/comfy-worker/running-locally.md --- > 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. # 本地运行 :::info 当前接入形态 公开一键安装器尚未提供(规划中)。当前方式:基于 `reelway-comfyui` 仓的 `Dockerfile.wan-worker` 自建镜像,并以节点协议接入。 ::: ### 准备 Linux + NVIDIA GPU 主机;安装 Docker 与 NVIDIA Container Toolkit;准备好账户 API Key。 ### 构建镜像 在 reelway-comfyui 仓执行(视频工作流镜像): ```bash docker build -f Dockerfile.wan-worker -t reelway/comfy-worker:local . ``` ### 运行并接入 以 `--gpus all` 启动容器,注入环境变量: | 变量 | 说明 | | ----------------- | ----------------------------- | | `API_KEY` | 节点用途的账户 API Key | | `APP_ID` | 节点唯一 UUID(自生成,保持稳定) | | `SOCKET_ENDPOINT` | `wss://rcn.reelway.ai/socket` | 容器内节点进程完成握手后即可接收派单;连接前可用 `POST /v1/client/key` 预检 Key。 ### 验证 在 [节点面板](https://docs.reelway.ai/run-a-worker/comfy-worker/worker-dashboard.md)(运营侧 `GET /admin/workers`)或日志中确认 `authenticated → workerInfo → readyToAcceptJobs` 时序完成。 排查时以交互方式进入容器(入口改 `/bin/bash`),手动执行启动脚本观察日志。 --- url: https://docs.reelway.ai/run-a-worker/comfy-worker/running-remotely.md --- > 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. # 远程运行 流程与[本地运行](https://docs.reelway.ai/run-a-worker/comfy-worker/running-locally.md)完全一致,差异仅在基础设施: ### 选择实例 x86-64 + NVIDIA GPU 的云实例(显存要求见[硬件要求](https://docs.reelway.ai/run-a-worker/comfy-worker/hardware-requirements.md));按目标模型族选择显存档位。 ### 部署镜像 把[本地构建](https://docs.reelway.ai/run-a-worker/comfy-worker/running-locally.md#%E6%9E%84%E5%BB%BA%E9%95%9C%E5%83%8F)的镜像推送到你的镜像仓库,在实例上拉取运行;或将仓库克隆到实例上现场构建。 ### 稳定性要点 - `APP_ID` 保持稳定:断线重连与清理协议以 `app-id` 为锚(见[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md#%E6%96%AD%E7%BA%BF%E4%B8%8E%E6%B8%85%E7%90%86)); - 心跳依赖 pong 响应:勿在容器内阻塞事件循环; - 产物上传带宽不足会拖慢整体吞吐,选择上行带宽充足的实例。 :::info 断线清理协议 节点异常断线时,在途任务收敛失败且该 `app-id` 进入 `pendingCleanup`;恢复后必须在首个 `readyToAcceptJobs` 中携带 `postDisconnectCleanupComplete: true` 才恢复派单。清理期间不产生计费。 ::: --- url: https://docs.reelway.ai/run-a-worker/comfy-worker/advanced-configuration.md --- > 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. # 高级配置 ## 模型白名单与过滤 节点从 `GET /v1/worker/config/comfy` 拉取目录;`filter` 参数按 `workflowDependencies` 键子串过滤,可让节点只暴露目标模型族(如 `filter=minimax-h3`)。目录文件缺失时节点上报**零模型**——宁缺勿滥,避免误报能力。 ## 显存释放(/free) **任意跨工作流切换前先调用 `/free`** 释放已加载权重。这是当前 fork 的既定行为约定:跳过会导致显存碎片与切换失败;节点兼容层已内置该约定,自研接入方同样应遵守。 ## 资产目录 - 资产白名单根为 `/downloads/comfy-assets`;产物与缓存集中于此,便于配额与清理; - Docker 打包节点镜像时,**working_dir 必须为 ComfyUI 根**,否则兼容层与模板解析失效。 ## 安全配置 `GET /v1/worker/config/prompt-safety` 提供 fail-closed 口径的提示词安全配置(端点常驻;当前词表为占位哨兵,真实词表由运营配置接入后替换)。节点执行时按该配置处理敏感内容。 ## 升级 **节点从不自升级**:版本更新由主机侧运维完成(更新镜像/仓库后重启容器)。服务端仅触发与校验,不存在节点内的自动升级通道。工作流模板同样随镜像发布。 --- url: https://docs.reelway.ai/run-a-worker/comfy-worker/worker-dashboard.md --- > 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. # 节点面板 节点面板面向**平台运营方**:数据源为 admin 面 `GET /admin/workers`(只读车队观测)与平台统计。开发者侧的对等数据是 `GET /v1/model-demand`。 ## 车队概览 在线节点数、就绪比例(`ready` 门控)、`app-id` 维度的在途任务;节点粒度字段见[节点分析](https://docs.reelway.ai/api-reference/worker-analytics.md)。 ## 节点详情与遥测 - 连接信息:`connectedAt` / `lastSeenAt`、`app-id`、`worker-type`; - 能力:`workerModels[]`、`loadedModelID`、`hardwareRating`; - 在途:`inflightJobs[]` 与就绪门控状态; - 断线清理:`pendingCleanup` 状态与恢复条件(见[节点协议](https://docs.reelway.ai/run-a-worker/worker-protocol.md#%E6%96%AD%E7%BA%BF%E4%B8%8E%E6%B8%85%E7%90%86))。 ## 收益视图 按完成任务结算到**账户余额**;对账入口是账户流水 `GET /v1/transactions/list` 与[余额与用量](https://docs.reelway.ai/api-reference/account-and-usage.md)。 :::info 与上游 Sogni Worker Dashboard 的关系 上游面板的 Settings 远程配置、Care、订阅收益双记账等模块属于上游产品形态;Reelway 当前以 admin 车队观测 + 账户结算流水覆盖运营刚需,面板产品化另行规划。 ::: --- url: https://docs.reelway.ai/run-a-worker/comfy-worker/faq.md --- > 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. # 节点常见问题 ### 连接被以 4021 关闭 `api-key` 头缺失、Key 无效或已吊销;`app-id` 头缺失同样拒绝。用 `POST /v1/client/key` 预检。 ### 连接被以 4015 关闭 同一 `app-id` 已有在线连接,新连接将其接管。若为误接管,检查是否有多台节点复用了同一 UUID。 ### 不派单(连接正常但无任务) 按序检查:`readyToAcceptJobs` 是否已发且 `ready: true`;是否处于 `awaitingCleanup` 且未携带 `postDisconnectCleanupComplete`;`workerModels[]` 是否为空(目录缺失时上报零模型,宁缺勿滥);`worker-type` 与目标网络(`fast|relaxed`)匹配。 ### 跨工作流切换失败 任意跨工作流切换前先 `/free` 释放权重,见[高级配置](https://docs.reelway.ai/run-a-worker/comfy-worker/advanced-configuration.md)。 ### 派单后断线会发生什么 在途任务收敛失败(`5001`),任务不计费;`app-id` 进入 `pendingCleanup`,恢复派单条件见[断线与清理](https://docs.reelway.ai/run-a-worker/worker-protocol.md#%E6%96%AD%E7%BA%BF%E4%B8%8E%E6%B8%85%E7%90%86)。 ### 节点如何升级 节点从不自升级:更新镜像/仓库后重启容器。见[高级配置 → 升级](https://docs.reelway.ai/run-a-worker/comfy-worker/advanced-configuration.md#%E5%8D%87%E7%BA%A7)。 --- url: https://docs.reelway.ai/run-a-worker/comfy-worker/release-notes/index.md --- > 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. # 版本说明 - [Comfy Worker](https://docs.reelway.ai/run-a-worker/comfy-worker/release-notes/comfy-worker.md) —— ComfyUI 节点镜像版本记录。 节点镜像随 `reelway-comfyui` 仓发布;版本以镜像 tag 与仓内 CHANGELOG 为准,本站版本说明为摘要转述。**发布完整性口径**:候选镜像的指纹注册(关键代码与自定义节点指纹)在节点放量前完成。 --- url: https://docs.reelway.ai/run-a-worker/comfy-worker/release-notes/comfy-worker.md --- > 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. # Comfy Worker | 日期 | 说明 | | ---------- | ---------------------------------------------------------------------------------------------------- | | 2026-11-02 | H3 hybrid 模型族(minimax-h3-fl2va-ref2va-int8_r2v / \_flf2v)在节点侧端到端打通;fork 内 8 项兼容层;catalog byID 排序缺陷修复 | | 2026-11-01 | 5090 节点切换读写 deploy key;fork 仓库迁移至 Gitea reelway 组织 | | 2026-10-31 | H3 全族(t2v/i2v/flf2v/r2v)生产出片;B 线资产透传(bind 物化 + 等待探测 + 槽位双候选) | 本页为摘要转述;权威记录以 `reelway-comfyui` 仓提交历史与镜像 tag 为准。 --- url: https://docs.reelway.ai/run-a-worker/worker-protocol.md --- > 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. # 节点协议 节点(worker)通道挂载于同一 WS 端点,按握手头分流;线协议 `{type, data: base64(JSON)}`,worker 侧单帧上限 8 MiB。客户端侧协议见 [SDK → Reelway 协议](https://docs.reelway.ai/sdk/protocol.md)。 ## 握手 | 项 | 说明 | | ------------- | ------------------------------ | | 端点 | `wss://rcn.reelway.ai/socket` | | `api-key` | 节点用途的账户 API Key(建议独立子 Key) | | `app-id` | 节点唯一 UUID,必填;缺失或认证失败关闭码 `4021` | | `client-type` | `worker`(必填) | | `worker-type` | 可选,默认 `Comfy.FastWorker` | 同 `app-id` 的后连者以关闭码 `4015` 接管前连者。服务端 25 s ping / 60 s pong 窗口;空闲靠 pong 保活(`lastSeenAt`)。 ## 时序 ``` 握手 → authenticated(空负载) → workerInfo(全量能力) → readyToAcceptJobs(ready=true) → 服务端 push jobRequest ``` ## 上行帧 | type | 负载 | 说明 | | -------------------- | -------------------------------------------------------------------- | --------------------------------------- | | `workerInfo` | `{workerModels[], loadedModelID, hardwareRating}` | 全量能力快照;字段名为 `workerModels`(非 workflows) | | `workerModelsChange` | `{added[], removed[]}` | 只按增量维护模型集;其余遥测不得触碰全量快照 | | `readyToAcceptJobs` | `{ready, reason, postDisconnectCleanupComplete, readinessSessionId}` | `awaitingCleanup` 时未携清理完成标记则不派单 | | `jobState` | `type: jobStarted(stepCount) / jobCompleted` | 失败路径先 `jobResult` 后 `jobError` | | `jobProgress` | `{jobID, imgID, step, stepCount, hasImage, etaSeconds}` | 执行进度 | | `jobResult` | `{jobID, imageId, …结果元数据}` | 服务端以 `(jobID, imageId)` 重建产物键并探测对象收敛 | | `jobError` | `{jobID, imgID, error, error_message}` | `5000` 执行失败 / `5001` 节点断线收敛失败;终态 | ## 下行帧 | type | 负载 | 说明 | | --------------- | ------------------------------------------------------------------------------------ | ---------------------------------- | | `authenticated` | 空负载 | 确认鉴权通过 | | `jobRequest` | `{jobID, imageId, workflowId, clientParams, assets, previews, outputFormat, isTest}` | 派单;`imageId` 即渲染身份 `imgID`,贯穿上传/下载 | | `jobCancel` | `{jobID, reason}` | 客户端取消在途任务 | ## 断线与清理 节点断线时在途任务收敛失败(`5001`),该 `app-id` 进入 `pendingCleanup`;其**下一次连接**的 `readyToAcceptJobs` 必须携带 `postDisconnectCleanupComplete: true` 才会恢复派单(断线清理就绪协议 v1)。 ## REST 配置面(公开) POSThttps://rcn.reelway.ai/v1/client/key鉴权:worker key 连接前密钥预检;body 为 text/plain 密钥原文 GEThttps://rcn.reelway.ai/v1/worker/config/comfy[?filter=<子串>]鉴权:公开 模型目录;filter 按 workflowDependencies 键子串过滤;1 分钟缓存 GEThttps://rcn.reelway.ai/v1/worker/config/comfy/loras鉴权:公开 LoRA 目录(当前恒空) GEThttps://rcn.reelway.ai/v1/worker/config/prompt-safety鉴权:公开 提示词安全配置;fail-closed 口径端点常驻 ## 产物上传 完成任务时凭任务能力 `(jobId, imageId)` 申请 `GET /v1/image|media/uploadUrl` 的 `complete` 槽位上传产物;无凭证。详见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md)。 --- url: https://docs.reelway.ai/accounts.md --- > 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 账户由 `auth.reelway.ai` 统一鉴权(casdoor OIDC),按用途分三类: | 类型 | 来源 | 能力 | | ---------- | ----------------------------------- | ----------------------------------------------------------------------- | | **个人账户** | 官网注册/登录(casdoor) | 创作应用、控制台、API Key 管理 | | **API 用户** | 纯 API 面使用(`owner = rsub_<12hex>`) | 由分销商建档的纯 API 身份:占位钱包、不可钱包登录;主 Key 明文仅建档响应返回一次 | | **分销下级** | 分销商经 `/v1/reseller/subordinates` 建档 | API 用户 + 上级充值/费率管理,见[分销体系](https://docs.reelway.ai/pricing/reseller.md) | ## 身份与凭证的关系 - 账户是所有权的锚:项目、资产、LoRA、流水都归属 `owner`; - API Key 是凭证:一把账户可持 99 把在用 Key,任意 Key 都代表同一 owner; - 会话 JWT(`POST /v1/account/login`)主要服务 Web 应用与 SDK 账号登录模式;API Key 与 JWT 可在 WS 握手中并存分流(按值形态自动识别)。 ## 账户相关的端点 - `POST /v1/account/username/validate` —— 用户名可用性; - `POST /v1/account/refresh-token` —— 刷新令牌轮换; - `GET /v1|v2/account/me` —— 资料,见[余额与用量](https://docs.reelway.ai/api-reference/account-and-usage.md)。 注册/登录/找回密码等账户操作在 [dashboard.reelway.ai](https://dashboard.reelway.ai) 完成。 --- url: https://docs.reelway.ai/agents/authentication.md --- > 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. # 智能体鉴权 ## Key 策略 - **一智能体一 Key**:每个智能体/每套环境独立子 Key,名称写明用途;泄露时单点吊销(见 [API Keys](https://docs.reelway.ai/api-reference/api-keys.md))。 - **Key 只在服务端**;客户端直连仅用于个人脚本场景。 - **限额即隔离**:平台可为 Key 设置消费配额,触顶 `402`(`1013`)。智能体失控重试的损失被限制在该 Key 的配额内。 ## 轮换 「先建后吊」:新 Key 部署 → 确认流量切换 → 吊销旧 Key。智能体运行中断连的会话以 `4021` 关闭码体现;重试时使用新 Key。 ## 与 OpenAI SDK 的组合 OpenAI SDK 以 `apiKey` 传 Reelway Key;同一智能体的媒体面(`@reelway/client`)用同一把 Key。不要在两端使用不同账户——余额与用量对账会割裂。 --- url: https://docs.reelway.ai/agents/first-result.md --- > 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. # 你的第一张智能体图像 ### 建 Key 在[控制台](https://dashboard.reelway.ai/console/keys)创建子 Key(如 `agent-prod`),明文仅显示一次。 ### 初始化双面客户端 文本面用 OpenAI SDK 指向 `api.reelway.ai/v1`;媒体面用 `@reelway/client`(见[智能体首页](https://docs.reelway.ai/agents.md#%E6%9C%80%E7%9F%AD%E8%B7%AF%E5%BE%84))。 ### 提交并等待 ```js const project = sogni.projects.create({ modelId: 'z_image_turbo_bf16', positivePrompt: '黄昏水乡,倒影,胶片质感', }); const [url] = await project.waitForCompletion(); // 48 小时签名 URL ``` ### 转存 签名 URL 48 小时过期;生产系统在拿到 URL 后立即转存自有存储。 失败排查:模型不在目录(`400`/`1002`)、余额不足(`402`/`1005`)、Key 无效(`401`/`101`)。错误码总表见[快速开始](https://docs.reelway.ai/api-reference/getting-started.md)。 --- url: https://docs.reelway.ai/agents/index.md --- > 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. # AI 智能体 Reelway 对智能体是「OpenAI 兼容 + 生成 API」的组合:文本规划与工具循环走 [Intelligence 推理面](https://docs.reelway.ai/intelligence/introduction.md),媒体生产走 [rcn 生成面](https://docs.reelway.ai/api-reference/direct-generation.md),两者共用同一把 Key 与同一个余额。 ## 最短路径 ```js import OpenAI from 'openai'; import { SogniClient } from '@reelway/client'; // 文本规划面 const llm = new OpenAI({ baseURL: 'https://api.reelway.ai/v1', apiKey: process.env.REELWAY_API_KEY }); // 媒体生产面(同一把 Key) const sogni = await SogniClient.createInstance({ appId: 'agent-prod', network: 'fast', apiKey: process.env.REELWAY_API_KEY }); // 在智能体的工具实现里生成媒体: const project = sogni.projects.create({ modelId: 'z_image_turbo_bf16', positivePrompt: '…' }); const urls = await project.waitForCompletion(); ``` ## 本节导览 - [你的第一张智能体图像](https://docs.reelway.ai/agents/first-result.md) —— 从 Key 到第一张结果 - [智能体鉴权](https://docs.reelway.ai/agents/authentication.md) —— Key 策略与限额 - [智能体计价与充值](https://docs.reelway.ai/agents/pricing.md) —— 扣费时点与成本隔离 - [智能体任务、资产与恢复](https://docs.reelway.ai/agents/jobs.md) —— 生命周期与断线恢复 ### 建身份 为该智能体创建独立子 Key 并命名(如 `agent-prod`)。 ### 接入 文本面改 `baseURL`;媒体面用 `@reelway/client` 或直调 REST/WS。 ### 控成本 依赖单 Key 限额(`402`/`1013`)与幂等键,防失控重试。 --- url: https://docs.reelway.ai/agents/jobs.md --- > 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. # 智能体任务、资产与恢复 ## 任务生命周期 智能体经 artist 通道提交的项目遵循统一生命周期: ``` jobRequest → projectQueue → jobState(queued→assigned→initiatingModel→jobStarted) → jobProgress → jobResult | jobError ``` - `jobResult.resultUrl` 为 **48 小时**签名 URL;拿到即转存; - `jobError`(`5000`/`5001`)不计费,可按原参数重试; - NSFW 双语义:`triggered`(无媒体)与 `detected`(媒体已交付仅提示),见 `GET /v2/projects/{id}` 的标记。 ## 查询与恢复 | 场景 | 手段 | | | ----------- | --------------------------------------------------------------------------------------------- | ------------------- | | 查询单个项目当前状态 | `GET /v2/projects/{id}`(见[项目状态 API](https://docs.reelway.ai/api-reference/project-status.md)) | | | 进程重启后在途项目恢复 | `GET /api/v1/artist/projects/sync`(activeProjects + unclaimedCompletedProjects) | | | 历史任务(近 7 天) | `GET /v1/jobs/list` | | | 已完成产物再次签发 | \`GET /v1/image | media/downloadUrl\` | ## 资产治理 参考图/音频等可复用输入走资产库(`/v1/assets`,四步状态机);每账户 500 条 / 5 GiB / 单文件 100 MiB,闲置 7 天回收。治理要点见[媒体工具](https://docs.reelway.ai/api-reference/media-utilities.md)。 --- url: https://docs.reelway.ai/agents/pricing.md --- > 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. # 智能体计价与充值 ## 扣费时点 受理时按预估扣费、完成时按实际校正;失败与无产物不计费。两种拒绝都发生在**扣费之前**: | HTTP | 错误码 | 场景 | 处理 | | ---- | ------ | ---------- | ------------ | | 402 | `1005` | 账户余额不足 | 充值;已在途任务不受影响 | | 402 | `1013` | 单 Key 限额触顶 | 提高限额或换 Key | ## 充值与监控 充值与方案由平台运营侧管理(分销下级由上级分销商充值,见[分销体系](https://docs.reelway.ai/pricing/reseller.md));账户余额与流水见[余额与用量](https://docs.reelway.ai/api-reference/account-and-usage.md)。 生产智能体建议: - 监控 `GET /v4/account/balance` 并设阈值告警; - 所有付费 `POST` 带 `Idempotency-Key`(workflows / chat runs / world builds); - 每日用量对账用 `GET /v1/transactions/list`。 ## 单价 按「模型 × 分辨率桶」的价格规则计价;缺少价格行时提交被拒(`400`/`1014`),不会静默免费。单价以运营配置为准。 --- url: https://docs.reelway.ai/app-tutorials/controlling-the-output.md --- > 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. # 控制输出 四个旋钮按序使用: ### 提示词定方向 结构化描述(主体+场景+镜头+质感);不满意的要素写进负向词。 ### 种子定复现 记下满意结果的种子;迭代时**固定种子改提示词**,或**固定提示词扫种子**。 ### 步数定质感 Turbo 族低步数即收敛;质量模型大尺寸下适当加步。 ### 引导系数定服从 从默认值出发 ±1 档微调;过高会僵硬。 复现要素齐备后可搬进 API(见[生成配方](https://docs.reelway.ai/api-reference/direct-generation.md));种子的实际值以 `seedUsed` 为准。 --- url: https://docs.reelway.ai/app-tutorials/dynamic-prompting.md --- > 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. # 动态提示词 把一个提示词模板展开成多个变体,批量比选: ### 定模板 固定可复用骨架:「\{主体},\{场景},\{镜头语言},\{质感}」。 ### 逐位替换 每批只动一位:场景位换 4 个、镜头位换 3 个;配合固定种子排除随机性干扰。 ### 批量提交 变体拆为多次小批次提交(见[批量生成](https://docs.reelway.ai/create/web/creating-images/generating-batches.md));比选后固定胜出组合。 :::info 说明 平台 API 无内置动态提示词语法;模板展开由调用方(或你自己的脚本)完成,提交时每个变体都是普通项目。 ::: --- url: https://docs.reelway.ai/app-tutorials/how-to-generate-larger-batches.md --- > 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. # 一次生成更多图像 `numberOfImages` 单次上限之外,靠**项目并发**扩容: ### 拆分项目 把 N 张拆为 ⌈N/k⌉ 个项目(每项目 k 张,k 取小批次如 4);共享同一参数与种子起点。 ### 并发提交 以独立 `jobID` 并发提交(WebSocket 单连接可挂多项目;REST 走幂等键);并发度受[公平使用队列](https://docs.reelway.ai/pricing/fair-use-queue.md)约束。 ### 归集产物 各项目的 `imgID` 逐个签发下载;对账用 `GET /v1/jobs/list`。 :::tip 预览张数(previews) `previews` 可在成片前拿到低成本的中间预览;交互式场景先开预览再决定是否出全量。 ::: --- url: https://docs.reelway.ai/app-tutorials/index.md --- > 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. # 应用教程与指南 面向创作者的分步教程;开发者侧配方见[开发者教程](https://docs.reelway.ai/developer-tutorials.md)。 - [控制输出](https://docs.reelway.ai/app-tutorials/controlling-the-output.md) —— 用参数稳定结果 - [动态提示词](https://docs.reelway.ai/app-tutorials/dynamic-prompting.md) —— 变体批量探索 - [一次生成更多图像](https://docs.reelway.ai/app-tutorials/how-to-generate-larger-batches.md) —— 批次策略 --- url: https://docs.reelway.ai/create/index.md --- > 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 Create Reelway Create 是浏览器创作应用(reelway.ai 创作工作台),由统一鉴权登入,经 artist 通道提交任务、实时展示进度与产物。 ## 六个工作台 | 工作台 | 路径 | 状态 | | ----------------------------------------------------------------- | ------------------- | ------------------------------------------ | | [图像](https://docs.reelway.ai/create/web/creating-images/index.md) | `/studio/image` | | | [视频](https://docs.reelway.ai/create/web/creating-videos/index.md) | `/studio/video` | | | [音频](https://docs.reelway.ai/create/web/index.md) | `/studio/audio` | | | [聊天与创意智能体](https://docs.reelway.ai/create/web/index.md) | `/studio/chat` | | | [工作流](https://docs.reelway.ai/create/web/index.md) | `/studio/workflows` | | | [世界构建](https://docs.reelway.ai/create/web/index.md) | `/studio/worlds` | | ## 用户管理面 项目历史与恢复(`/projects`)、资产库(`/assets`)、个人 LoRA(`/loras`)、钱包与账单(`/account/wallet`),入口见[控制台](https://dashboard.reelway.ai)。 ## 从 API 使用同样能力 创作工作台的全部生成能力与 [API 参考](https://docs.reelway.ai/api-reference/index.md) 一一对应:同样的模型目录、参数边界与计费。开发者可以「应用里先试,接口里复刻」。 --- url: https://docs.reelway.ai/create/web/activity-and-queue.md --- > 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. # 活动面板与后台队列 ## 实时进度 任务进度经 artist 通道推送(`projectQueue` → `jobState` → `jobProgress`);断线后应用自动重连并调用 `projects/sync` 恢复在途项目与未领取产物——**关掉页面任务不会丢**。 ## 历史与恢复 - `/projects` 页列出近 7 天历史(对应 `GET /v1/jobs/list`); - 已完成项目的产物经预签名 URL 重新签发(48 小时有效期),见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md)。 ## 失败与重试 失败任务不计费;应用内重试以新 `jobID` 重新提交,幂等键用于服务端集成场景(见[幂等](https://docs.reelway.ai/api-reference/getting-started.md#%E5%B9%82%E7%AD%89))。 --- url: https://docs.reelway.ai/create/web/creating-images/generating-batches.md --- > 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. # 批量生成 `numberOfImages` 控制单次项目的产物数量;批次内种子自动递增,一次拿到多样结果。 - 交互式探索用小批次(2–4)快速比选; - 大批量拆分为多次项目提交(并发受网络档位与节点容量约束,见[公平使用队列](https://docs.reelway.ai/pricing/fair-use-queue.md)); - 视频(`numberOfImages` 通常为 1)与音频不适用大批次。 批次产物的 `imgID` 逐个出现在 `GET /v2/projects/{id}` 的 `completedWorkerJobs[]`,可单独签发下载 URL。更多策略见[应用教程 → 一次生成更多图像](https://docs.reelway.ai/app-tutorials/how-to-generate-larger-batches.md)。 --- url: https://docs.reelway.ai/create/web/creating-images/generation-seed.md --- > 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. # 生成种子 `seed` 决定采样的初始噪声:同参数 + 同种子 = 同结果。 - **复现**:满意的结果记下种子与全部参数,下次精确复现;`GET /v2/projects/{id}` 的完成作业返回 `seedUsed`(实际种子); - **探索**:留空由系统随机分配;批次(`numberOfImages`)内种子自动递增; - **变体**:固定种子,微调提示词,即可在同一构图上迭代。 API 侧在 `keyFrames[0].seed` 传入;工作流的重播(`reseed`)按 step 覆写种子,见[创意工作流](https://docs.reelway.ai/api-reference/workflows.md)。 --- url: https://docs.reelway.ai/create/web/creating-images/guidance-scale.md --- > 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. # 引导系数 引导系数(`guidance`)控制结果对提示词的遵循强度: | 模型 | 范围 | 默认 | | --------------- | ---------- | -- | | Z-Image Turbo | 0–5(一位小数) | 1 | | Qwen Image 2512 | 0–10(一位小数) | 4 | | H3 视频 | 固定 1 | 1 | - 调高:更贴合提示词,过高会过饱和/僵硬; - 调低:更自由,构图更松; - 从默认值出发微调 ±1 档观察,优于大步长调整。 --- url: https://docs.reelway.ai/create/web/creating-images/guide-image.md --- > 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. # 参考图 图像侧的参考输入走 `startingImage` 槽位(改写/变体场景)与 `contextImages`(多参考场景);上传经预签名 URL,见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md)。 | 场景 | 用法 | | -------- | ------------------------------------------------------------------------------------------------ | | 以图改图 | `startingImage` + 提示词描述改动点 | | 多参考合成 | `contextImage1..16` 槽位(按模型上限) | | 角色/产品一致性 | 图像参考 + 固定种子;视频侧用 [R2V](https://docs.reelway.ai/create/web/creating-videos/reference-to-video.md) | :::info 能力边界 「Guide Image」的 ControlNet 级结构控制(深度/姿态预处理)当前**不在平台能力内**;图像输入以改写与参考为主。边界以目录能力字段为准。 ::: --- url: https://docs.reelway.ai/create/web/creating-images/index.md --- > 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. # 创作图像 图像工作台(`/studio/image`)使用平台两个图像模型:质量优先的 [Qwen Image 2512](https://docs.reelway.ai/models/qwen-image-2512.md) 与速度优先的 [Z-Image Turbo](https://docs.reelway.ai/models/z-image-turbo.md)。 | 参数 | Qwen Image 2512 | Z-Image Turbo | | ---- | --------------- | ------------- | | 默认步数 | 20 | 4 | | 默认尺寸 | 1328×1328 | 1024×1024 | | 引导系数 | 4 | 1 | 各参数的含义与调法见子页:[提示词](https://docs.reelway.ai/create/web/creating-images/prompts.md) · [生成种子](https://docs.reelway.ai/create/web/creating-images/generation-seed.md) · [推理步数](https://docs.reelway.ai/create/web/creating-images/inference-steps.md) · [引导系数](https://docs.reelway.ai/create/web/creating-images/guidance-scale.md) · [参考图](https://docs.reelway.ai/create/web/creating-images/guide-image.md) · [批量生成](https://docs.reelway.ai/create/web/creating-images/generating-batches.md)。 :::info 应用与 API 同参 工作台展示的参数边界与 API 参数卡一致(步进 16 的尺寸网格、引导系数一位小数);在应用里确认的参数可直接搬进 API 调用。 ::: --- url: https://docs.reelway.ai/create/web/creating-images/inference-steps.md --- > 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. # 推理步数 步数(`steps`)是去噪迭代次数: - **Z-Image Turbo**:1–12,默认 **4**——Turbo 架构低步数即收敛,调高收益递减; - **Qwen Image 2512**:1–50,默认 **20**——降低步数换速度,提高步数在大尺寸下更稳; - 视频 H3 族步数**按档位固定**(base 20 / balanced 8 / turbo 4),不开放调节,速度选型见[MiniMax H3](https://docs.reelway.ai/models/minimax-h3.md)。 步数与耗时近似线性;费用按「模型 × 分辨率桶」规则,与步数同向。以应用内预览对比后定档,是性价比最高的方式。 --- url: https://docs.reelway.ai/create/web/creating-images/prompts.md --- > 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. # 提示词 | 槽位 | 作用 | | ---------------- | ------------------------ | | `positivePrompt` | 主描述:主体 + 场景 + 构图/镜头 + 质感 | | `negativePrompt` | 排除项:模糊、低质量等 | | `stylePrompt` | 风格标签层(可选) | 写法建议: - 结构化描述优于关键词堆砌:「黄昏下的江南水乡,水面倒影,胶片质感」胜过「水乡 黄昏 好看」; - 负向词简短通用即可,过长会稀释权重; - 长度上限按模型参数卡(`maxPromptLength`,图像族见[模型指南](https://docs.reelway.ai/models/index.md))。 动态提示词(变体批量探索)见[应用教程](https://docs.reelway.ai/app-tutorials/dynamic-prompting.md)。 --- url: https://docs.reelway.ai/create/web/creating-videos/image-to-video.md --- > 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. # 图生视频(i2v) 模型:`minimax-h3-fl2va-fp8_i2v` 三档。输入:首帧(`referenceImage`)+ 提示词。 适合「静态素材动起来」:产品图、插画、场景图。首帧质量决定整段视频的视觉基调;提示词描述**运动与镜头**,而不是重复描述首帧内容。 ```js const project = sogni.projects.create({ modelId: 'minimax-h3-fl2va-fp8_i2v', positivePrompt: '人物转身微笑,自然光,镜头缓慢推进', referenceImage: fs.readFileSync('./first-frame.png'), }); ``` 需要控制结束画面时用[首尾帧](https://docs.reelway.ai/create/web/creating-videos/start-and-end-frames.md);需要主体一致性的叙事镜头用[参考视频](https://docs.reelway.ai/create/web/creating-videos/reference-to-video.md)。 --- url: https://docs.reelway.ai/create/web/creating-videos/index.md --- > 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. # 创作视频 视频工作台(`/studio/video`)使用 [MiniMax H3 全族](https://docs.reelway.ai/models/minimax-h3.md):t2v / i2v / flf2v / r2v 四种输入模式,base / balanced / turbo 三档速度,输出带原生音频,24 fps。 | 模式 | 输入 | 子页 | | ---- | ---------- | --------------------------------------------------------------------------------- | | 文生视频 | 提示词 | [文生视频](https://docs.reelway.ai/create/web/creating-videos/text-to-video.md) | | 图生视频 | 首帧 + 提示词 | [图生视频](https://docs.reelway.ai/create/web/creating-videos/image-to-video.md) | | 首尾帧 | 首帧 + 尾帧 | [首尾帧](https://docs.reelway.ai/create/web/creating-videos/start-and-end-frames.md) | | 参考视频 | 参考图 + 上下文图 | [参考视频](https://docs.reelway.ai/create/web/creating-videos/reference-to-video.md) | 共同边界:提示词 ≤ 7000 字符;尺寸 480–1344(步进 32);帧数 124–362(步进 17,约 5–15 秒);24 fps。 :::tip 中间关键帧 除 t2v 外全族支持最多 8 个中间关键帧(`keyframes`),把画面钉在指定帧位;应用内以时间线方式编辑。 ::: --- url: https://docs.reelway.ai/create/web/creating-videos/reference-to-video.md --- > 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. # 参考视频(r2v) 模型:`minimax-h3-ref2va-fp8_r2v` 三档 + 两段式(`_2stage`)。输入模式为**多参考**: | 输入 | 槽位/参数 | 上限 | | ----- | ---------------- | ---------------------------- | | 主参考 | `referenceImage` | 1 | | 上下文参考 | `contextImages` | 合计 9 图 / 3 视频 / 3 音频 / 12 资产 | 用途:同一角色/产品的多镜头叙事。提示词描述**本镜头**的内容与运动;一致性由参考锚定。 ```js const project = sogni.projects.create({ modelId: 'minimax-h3-ref2va-fp8_r2v', positivePrompt: '同一位角色在咖啡馆里阅读', referenceImage: fs.readFileSync('./character.png'), contextImages: [fs.readFileSync('./outfit.png')], }); ``` 更长有效时长或更高输出分辨率用 `_2stage` 变体(先渲染后放大精修,输出翻倍);混合 int8 档(`fl2va-ref2va-int8`)为低显存节点提供 r2v/flf2v 能力。参数详见 [MiniMax H3](https://docs.reelway.ai/models/minimax-h3.md)。 --- url: https://docs.reelway.ai/create/web/creating-videos/start-and-end-frames.md --- > 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. # 首尾帧(flf2v) 模型:`minimax-h3-fl2va-fp8_flf2v` 三档。输入:首帧(`referenceImage`)+ 尾帧(`referenceImageEnd`)+ 提示词(描述过渡)。 适合「A→B 转场」:改造前后、日夜过渡、形态变化。首尾帧风格与色调越接近,过渡越稳;差异大时提示词补足过渡逻辑。 ```js const project = sogni.projects.create({ modelId: 'minimax-h3-fl2va-fp8_flf2v_turbo', positivePrompt: '从白天过渡到夜晚的城市天际线', referenceImage: fs.readFileSync('./day.png'), referenceImageEnd: fs.readFileSync('./night.png'), }); ``` 帧 0 与最后一帧由两张输入占据;中间帧位可用关键帧进一步钉住(见[创作视频](https://docs.reelway.ai/create/web/creating-videos.md#%E4%B8%AD%E9%97%B4%E5%85%B3%E9%94%AE%E5%B8%A7))。 --- url: https://docs.reelway.ai/create/web/creating-videos/text-to-video.md --- > 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. # 文生视频(t2v) 模型:`minimax-h3-fl2va-fp8_t2v` 三档(base/balanced/turbo)。 ### 写提示词 主体 + 动作 + 镜头语言 + 环境音描述(≤ 7000 字符);音频由模型原生生成,`generateAudio` 可关。 ### 选档位 turbo(4 步)快速迭代,balanced(8 步)折中,base(20 步)成片。 ### 选规格 尺寸默认 1344×768;帧数在 124–362 网格上选(24 fps)。 ```js const project = sogni.projects.create({ modelId: 'minimax-h3-fl2va-fp8_t2v_turbo', positivePrompt: '一只橘猫在雨后的屋顶上伸懒腰,镜头缓慢推进,环境音', }); ``` 纯文本之外的输入需求(首帧、尾帧、参考)见对应子页;更多配方见[生成配方](https://docs.reelway.ai/api-reference/direct-generation.md)。 --- url: https://docs.reelway.ai/create/web/index.md --- > 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. # Web 应用 reelway.ai 创作工作台面向创作者:统一鉴权登录(auth.reelway.ai),经 artist 通道实时创作。 ## 入口与登录 - 入口:[reelway.ai](https://reelway.ai) 创作工作台;账户体系见[账户类型](https://docs.reelway.ai/accounts.md); - 登录后进入 `/studio/*` 工作台;找回密码见[找回密码](https://docs.reelway.ai/create/web/recover-password.md)。 ## 工作台与队列 任务经 artist 通道提交,实时进度经 WS 推送;后台队列与历史见[活动面板与后台队列](https://docs.reelway.ai/create/web/activity-and-queue.md)。产物 48 小时签名 URL;历史与恢复见 `/projects`。 ## 管理面入口 钱包与账单、资产库、LoRA 库等在[控制台](https://dashboard.reelway.ai)管理;API 用户与分销下级同样经 dashboard 管理充值与费率(见[分销体系](https://docs.reelway.ai/pricing/reseller.md))。 --- url: https://docs.reelway.ai/create/web/recover-password.md --- > 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. # 找回密码 账户密码由 `auth.reelway.ai`(casdoor)管理,docs 站不承载账户操作: ### 打开找回入口 在 [dashboard.reelway.ai](https://dashboard.reelway.ai) 登录页选择「忘记密码」。 ### 验证身份 按界面完成邮箱验证,设置新密码。 ### 重新登录 新密码对创作工作台、控制台与 API 账号登录(SDK username/password 模式)同时生效。 :::tip 密码与 API Key 相互独立 改密不影响已签发的 API Key;需要收紧访问请吊销并重建 Key(见 [API Keys](https://docs.reelway.ai/api-reference/api-keys.md))。 ::: --- url: https://docs.reelway.ai/developer-tutorials.md --- > 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. # 开发者教程 配方级操作细节在[生成配方](https://docs.reelway.ai/api-reference/direct-generation.md);本页是场景化演练索引,示例共用同一初始化(见 [SDK](https://docs.reelway.ai/sdk/index.md))。 ## 文生图,带复用资产 1. `POST /v1/assets/prepare` 登记文件(sha256 去重); 2. `PUT` 上传 + `finalize` 复验; 3. `bind` 到项目槽位后提交 `z_image_turbo_bf16`; 4. 完成 `waitForCompletion()` 并转存产物。 ## 视频批次与档位选型 同一提示词跑三档(`_turbo` → `_balanced` → base)比选;帧数在 124–362(步进 17)网格上选择;`estimateVideoCost` 预估(预览零报价口径)。 ## 首尾帧产品演示 `flf2v` 以首帧 + 尾帧生成过渡:适合"改造前后"对比视频;输入槽位 `referenceImage` + `referenceImageEnd`。 ## 参考角色一致性 `r2v` 以 `referenceImage` 锚定主体,`contextImages` 提供服装/场景参考;需要更长有效时长时用 `_2stage` 变体(输出翻倍分辨率)。 ## OpenAI SDK 快速接入 只改 `baseURL` 的完整流程见[OpenAI SDK 兼容性](https://docs.reelway.ai/intelligence/openai-sdk-compatibility.md);把 Reelway 挂进 Open WebUI 见对应[集成页](https://docs.reelway.ai/intelligence/integration-open-webui.md)。 --- url: https://docs.reelway.ai/faqs.md --- > 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 与 Sogni 是什么关系 Reelway 是 Sogni 协议兼容的平台:API 面、SDK 契约与节点协议与 Sogni 同构,但平台、账户、余额、模型目录与运营完全独立。 ### 生成一个视频要多久 取决于模型档位与时长:4 步 turbo 档最快,20 步 base 档质量优先;`GET /v1/model-catalog` 的参数卡带 benchmark 字段。产物 URL 有效 48 小时。 ### 哪些模型可用 以 `GET /v1/model-catalog`(公开)为权威;指南见[模型指南](https://docs.reelway.ai/models/index.md)。模型上下线通过公告端点与目录版本号体现。 ### 怎么计费 统一余额按量计费:受理时预估扣费、完成时校正;失败不计费。见[方案与定价](https://docs.reelway.ai/pricing/index.md)与[计费与成本控制](https://docs.reelway.ai/intelligence/billing-and-cost-control.md)。 ### API Key 丢了怎么办 子 Key 明文不可取回:立即吊销并新建;主 Key 明文可在控制台随时复制。见[API Keys](https://docs.reelway.ai/api-reference/api-keys.md)。 ### 生成失败会扣费吗 不会。`jobError`(`5000`/`5001`)与无产物任务不计费;已在途任务不受余额波动影响。 ### 支持哪些集成方式 OpenAI 兼容推理面(任何 OpenAI SDK/框架,见[兼容性](https://docs.reelway.ai/intelligence/openai-sdk-compatibility.md))、Sogni 协议生成面(`@reelway/client` 或直调 REST/WS)、Open WebUI / OpenClaw / Hermes 等工具集成。 ### 算力节点如何结算 按完成任务结算到账户余额;接入方式见[运行算力节点](https://docs.reelway.ai/run-a-worker/index.md)。 --- url: https://docs.reelway.ai/index.md --- > 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 创作栈,端到端。 > 面向开发者的 OpenAI 兼容推理与智能体 API,内置图像、视频、语音等创意媒体工具;面向创作者的 Web 创作应用;面向算力提供方的 Reelway 算力协作网络(RCN)。 [快速开始](/api-reference/getting-started) | [API 参考](/api-reference/) ## Features - [🧠 **Reelway Intelligence**](/intelligence/introduction): 构建 · 平台 —— OpenAI 兼容的对话补全、可持久化的智能体运行、创意工作流与可保存的工作流模板。 - [📘 **API 参考**](/api-reference/): 构建 · 参考 —— 逐端点的 REST 文档,附 curl 与 JavaScript 示例,覆盖生成、媒体、账户与网络。 - [🧩 **Reelway SDK**](/sdk/): 构建 · SDK —— JavaScript / TypeScript 客户端,Node 与浏览器均可,通过 WebSocket 实时接收进度与结果。 - [🎬 **Reelway Create**](/create/): 应用 · 创作 —— 旗舰 Web 创作应用:文生图、文生视频、图生视频、首尾帧与参考视频。 - [⚙️ **运行算力节点**](/run-a-worker/): 网络 · 节点 —— 加入 Reelway 算力协作网络,贡献 GPU 时间并按完成任务结算收益。 - [🗂️ **模型指南**](/models/): 构建 · 模型 —— MiniMax H3 视频全族、Qwen Image 2512、Z-Image Turbo、CosyVoice 3 TTS 的能力与参数说明。 - [🛠️ **开发者教程**](/developer-tutorials): 构建 · 教程 —— 常见工作流的配方与分步演练。 - [💳 **方案与定价**](/pricing/): 入门 · 计费 —— 余额、充值、按量计费与分销体系。 - [❓ **常见问题**](/faqs): 帮助 —— 关于应用、网络与计费的常见问题解答。 --- url: https://docs.reelway.ai/pricing/fair-use-queue.md --- > 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. # 公平使用队列 提交生成任务时选择 `network`: | 网络 | 语义 | 适合 | | --------- | ----------- | ---------- | | `fast` | 优先派发到就绪节点 | 交互式产品、实时反馈 | | `relaxed` | 允许更长排队,低成本档 | 批处理、离线任务 | 排队规则: - WS 握手查询串 `forceWorkerId=fast|relaxed` 定档;SDK 以 `network` 参数定档;连接后可用 `changeNetwork` 帧换档(回执同 type 帧); - 派单按节点就绪门控(`readyToAcceptJobs`)与能力匹配(`workerModels[]`)执行; - 队列状态经 `projectQueue` 帧(`waitingReason: queued`)推送,REST 侧以 `GET /v2/projects/{id}` 查询。 :::info 口径说明 公平使用阈值与跨档迁移细则由平台运营配置;当前以「就绪节点优先匹配」为第一原则。容量观测见[节点分析](https://docs.reelway.ai/api-reference/worker-analytics.md)。 ::: --- url: https://docs.reelway.ai/pricing/index.md --- > 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` | | 价格规则 | 按「模型 × 分辨率桶」计价 | 平台配置;缺价格行时提交被拒 `400`(`1014`) | | 单 Key 限额 | 每把 Key 的消费配额 | 触顶 `402`(`1013`) | | 幂等 | 重试不重复扣费 | `Idempotency-Key`(三个付费 POST) | ## 充值 个人账户联系平台运营充值;[分销下级](https://docs.reelway.ai/pricing/reseller.md)由上级分销商充值。充值到账即入余额,无最小消费门槛。 ## 与订阅无关 Reelway 当前没有订阅抵扣与代币双轨;Sogni 兼容形状中的 `billing_mode` / `token_type` 字段仅作兼容保留(见[对话补全](https://docs.reelway.ai/api-reference/chat-completions.md))。 成本控制手段汇总见[计费与成本控制](https://docs.reelway.ai/intelligence/billing-and-cost-control.md)。 --- url: https://docs.reelway.ai/pricing/refund-policy.md --- > 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. # 退款与生成策略 ## 计费事实 1. **受理即扣费**:提交成功即按预估扣费; 2. **完成即校正**:按实际用量校正差额; 3. **失败不计费**:`jobError`(`5000`/`5001`)、NSFW `triggered`(无媒体交付)与无产物任务,已扣费用自动校正为零; 4. **幂等防重复**:网络层重试携带同一 `Idempotency-Key` 不会产生双份计费。 ## 常见争议与处理 | 情形 | 结果 | | ------------------- | ------------------------------------------------ | | 产物 URL 48 小时内未下载而过期 | 不退款;可用 `downloadUrl` 重新签发(对象仍在保留期内) | | 参数错误被拒(扣费前) | 未扣费,无争议 | | 节点执行中断(断线收敛) | 不计费,可重新提交 | | 对账差异 | 以 `GET /v1/transactions/list` 流水为准;凭据齐全时联系平台运营复核 | 争议处理窗口与流程由平台运营公布;先对账、后申诉。 --- url: https://docs.reelway.ai/pricing/reseller.md --- > 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. # 分销体系 分销体系允许账户发展为**二级分销商**:为下级账户建档、充值、设置费率,并查看毛利报表。下级是纯 API 用户(`owner = rsub_<12hex>`),主 Key 明文仅在建档响应中返回一次。 ## 端点面 POSThttps://rcn.reelway.ai/v1/reseller/subordinates鉴权:账户 建下级;201 {owner, apiKey, bifrostVK} GEThttps://rcn.reelway.ai/v1/reseller/subordinates鉴权:账户 直属下级清单 PUThttps://rcn.reelway.ai/v1/reseller/subordinates/{owner}/rate鉴权:账户 设费率(user_rate > 1) POSThttps://rcn.reelway.ai/v1/reseller/subordinates/{owner}/deposit鉴权:账户 充值(amount>0;type: recharge|adjust) POSThttps://rcn.reelway.ai/v1/reseller/subordinates/{owner}/provision鉴权:账户 重推建档(幂等补建) GEThttps://rcn.reelway.ai/v1/reseller/report?limit=鉴权:账户 毛利报表;金额 6 位定点字符串 ## 费率模型 - `user_rate` 是**相对上级生效的倍率**,沿分销链**连乘**;根分销商相对牌价 1.0; - 下级费率必须 > 1(库级校验兜底),上级赚差价; - 控制台断言面(`/console/reseller/*`)供 [dashboard.reelway.ai](https://dashboard.reelway.ai) 使用,形状与 v1 面一致。 ## 错误 非直属上级操作 → `403`;未建档 → `409`(`1006`);校验失败 → `400`(`1010`);结算网关故障 → `502`(details 附 retry 入口)。