> 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 默认 | <Status kind="ga" />                            |
| 创意工作流 REST             | `POST /v1/creative-agent/workflows` | 无状态服务端、多步编排、幂等重放  | <Status kind="preview" note="M1 执行器为占位,契约稳定" /> |

本页的配方全部基于目录中的真实模型 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=<id>&forceWorkerId=fast鉴权:api-key 握手头

artist 通道;握手后首帧为 authenticated


**上行 `jobRequest`**(线协议 `{type, data: base64(JSON)}`);图像输入先经 `GET /v1/image/uploadUrl?type=<槽位>&jobId=<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))。