> 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: <key>` 或 `Authorization: Bearer <key>`       | 在[控制台](https://dashboard.reelway.ai/console/keys)创建,服务端按 SHA-256 查表,状态为 `active` 时放行。详见 [API Keys](https://docs.reelway.ai/api-reference/api-keys.md) |
| **会话 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` 头,详见[节点协议](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: <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     | 余额不足                         | [充值](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) —— 恢复、重试与错误处理清单