快速开始

本页内容适用于参考中的每一个端点: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

JavaScript(SDK)

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":"你好"}]}'

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 里:

curl --fail-with-body https://rcn.reelway.ai/v1/account/me \
  -H "api-key: $REELWAY_API_KEY"

两种凭证形态

凭证	头形态	说明
API Key	`api-key: <key>` 或 `Authorization: Bearer <key>`	在控制台创建,服务端按 SHA-256 查表,状态为 `active` 时放行。详见 API Keys
会话 JWT	`Authorization: <jwt>` 或 `Authorization: Bearer <jwt>`	由 `POST /v1/account/login` 签发,`refreshToken` 轮换;主要供 Web 应用与 SDK 的账号登录模式使用

两种形态可混用于同一个 Authorization 头:服务端按值中是否含两个 . 分流为 JWT 或 Key。

WebSocket 握手使用同一套凭证:api-key 头(或 JWT),外加查询串 ?appId=(必填)。GPU 节点另需 client-type: worker 与 app-id 头,详见节点协议。

凭证口径(端点表中的「鉴权」列)

公开:无凭证要求(模型目录、模型需求、健康检查等)
凭证:需 API Key 或 JWT,缺失或无效返回 401(错误码 101)
账户:凭证之上还要求账户行存在(余额、流水、/v1/account/me)
可选:携带凭证时按账户过滤,不带亦放行 :::

版本

版本号附着于单个端点而非整个 API。同一账户相关的能力会出现 GET /v1/account/me、GET /v2/account/me、GET /v4/account/balance 这样的组合,请按参考中给出的路径原样调用。新版本的端点在旧版本保持可用的前提下增加;弃用会提前在本站公告。

错误

错误信封

绝大多数端点使用标准信封:

// 成功
{ "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: <seq>`、`event: <name>`、`data: <json>`

错误码

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	余额不足	充值
`1006`	409	状态机非法迁移	先读取当前状态
`1007`	422	工作流 DAG 存在环或指向更晚的 step	修正 `dependsOn`
`1008`	422	`dependsOn` 引用了不存在的 step	修正 step id
`1009`	400	`media_references` 非 http(s)	先上传得到 URL
`1010`	400	请求体含未知字段(严格解码)	删除多余字段
`1011`	400	两段式创建的常规路径响应	见创意工作流
`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)区分。
分销体系:二级分销商可为下级账户充值、设置费率并查看毛利报表,详见方案与定价。

:::tip 余额不足时发生什么提交被拒绝于扣费之前,不会产生部分计费;已在途的任务不受影响。充值后直接重试即可。

下一步

API Keys —— 创建与管理 Key
生成配方 —— 提交第一个图像或视频项目
生产集成 —— 恢复、重试与错误处理清单

#快速开始

#简介

#这里有什么

#快速开始

#认证

#两种凭证形态

#版本

#错误

#错误信封

#错误码

#400 与 errorCode: 1010

#限流

#幂等

#请求头

#支持的端点

#计费

#下一步

快速开始

简介

这里有什么

快速开始

认证

两种凭证形态

版本

错误

错误信封

错误码

400 与 `errorCode: 1010`

限流

幂等

请求头

支持的端点

计费

下一步