# muse-gateway 中文文档

规范地址：https://npmcn.com/package/muse-gateway/

版本：1\.0\.9
npm 元数据更新时间：2026-11-04T02:32:14.719Z
中文译文更新时间：2026-11-04T05:35:32.268Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/muse-gateway
原文对照：https://npmcn.com/package/muse-gateway/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：148 MB，6481 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.9\.0
- 运行依赖：0 个
- 首次发布：2026-10-28T16:53:52.109Z
- 最新版本发布：2026-11-04T02:32:14.568Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

缪斯网关-本地缪斯会话池和openai兼容网关。解锁/v1/\* API所需的许可密钥。

## 安装

```sh
npm install muse-gateway
```

也可以使用：`pnpm add muse-gateway`、`yarn add muse-gateway`、`bun add muse-gateway`

## README

# 缪斯网关

自托管Muse会话池+ openai兼容网关(`/v1/chat/completions`， `/v1/responses`， `/v1/tasks`， `/v1/models`)与web仪表板和Windows系统托盘集成。它运行在你自己的机器上，有你自己的Muse帐户，任何使用OpenAI API的工具都可以使用它。

> **许可要求。** 任何人都可以安装和打开仪表板，但是 `/v1/*` 网关API保持锁定（HTTP 402），直到您激活购买的许可密钥。 **买一把钥匙 [https://www.storetiki.online](https://www.storetiki.online/)** （浮动或hwid绑定，时间限制）-支持：电报 [@storetiki\_bot](https://t.me/storetiki_bot)。

## 安装

```bash
npm install -g muse-gateway
```

## 运行

```bash
muse-gateway
```

如果 `muse-gateway` 安装后不识别，npm的全局bin 目录可能不在您的PATH - `npx muse-gateway` 是这样的 Case （npx解析全局安装的包本身）。为了解决它 永久地，添加npm的全局bin dir(通常是 `%APPDATA%\npm`，与 `npm prefix -g`)到你的路径。

打开一个交互式菜单：

```
=======================================================
  Muse Gateway  v1.0.2
  Server:  http://127.0.0.1:1412   ● running — pro
=======================================================
> Open Dashboard (Web UI)
  Hide to Tray (Background)
  Run in this terminal (foreground)
  Enter License Key…
  Stop Server
  Exit
```

-   **打开仪表板** -启动服务器，如果需要，打开http://127.0.0.1:1412
-   **隐藏到托盘** -运行在后台的系统托盘图标（打开仪表盘/自动启动/退出）和一个通知，确认您可以关闭终端
-   **在这个终端运行** —前台服务器，按Ctrl+C停止
-   **输入许可密钥** -粘贴a `MUSE1.…` 钥匙，无需打开仪表盘即可启动

## 激活license

三种方式——都是等价的：

1.  `muse-gateway` 菜单→ **输入许可密钥…** →粘贴钥匙
2.  仪表板→ **Bản quyền** TAB键→粘贴键→ **Kich hoạt**
3.  `curl -X POST http://127.0.0.1:1412/api/license -H "content-type: application/json" -d '{"action":"activate","licenseKey":"MUSE1.…"}'`

在激活有效密钥之前，每个 `/v1/*` 请求返回 `402 license_required`。 仪表盘和 `/api/*` 管理路由始终可用。

## 连接你的工具

在仪表板中激活并添加Muse帐户后，在任何带有自定义OpenAI端点的工具中使用这三个值：

| 设置 | 价值 |
| --- | --- |
| 基URL | `http://127.0.0.1:1412/v1` |
| API密匙 | 在仪表板中创建一个。在第一个键存在之前，本地调用不需要。 |
| 模型 | `muse-chat`， `muse-image` 或 `muse-video` |

```python
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:1412/v1", api_key="YOUR_KEY")
reply = client.chat.completions.create(
    model="muse-chat",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)
```

### 模型

模型决定了你能得到什么。网关从不根据提示进行猜测。

| 模型 | 返回 | 笔记 |
| --- | --- | --- |
| `muse-chat` | 文本 | 当回复确定时返回。如果Muse附加了一个文件，它的链接也会包含在内。 |
| `muse-image` | 图片 | 总是向Muse请求图像并等待它。没有图像是错误的。 |
| `muse-video` | 一个视频 | 就像 `muse-image`，并等待所请求的长度(`duration`）. |
| 组合名称 | 同类 | 每个组合都在仪表板中设置为聊天，图像或视频，并且行为与该模型相似。 |

`GET /v1/models` 列出每个带有 `kind` 字段(`chat`， `image` 或 `video`）. 名称如 `gpt-4o` 或 `claude-3-5-sonnet` 是只提供这些名字的客户的别名；缪斯的回答是 `muse-chat`。

对于另一台机器上的工具，打开仪表板中的隧道并使用它提供的公共地址，例如 `https://u-xxxx.storetiki.online/v1`． 通过隧道总是需要API密钥，因此将该密钥视为密码。

## 生成图像和视频

### 图片: `POST /v1/images/generations`

标准的OpenAI图像端点，因此具有内置图像功能的工具直接工作：

```bash
curl http://127.0.0.1:1412/v1/images/generations \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"model": "muse-image", "prompt": "a cat on the grass", "size": "1024x1792"}'
```

`size` 被映射为Muse所理解的最接近的比例（1:1,16:9,9:16,4:3,3:4,3:2,2:3）。 `n` 返回Muse制作的多达4张图像。 `response_format` 是 `url` (默认)或 `b64_json`． 答案是 `{ "created": ..., "data": [{ "url": "...", "revised_prompt": "..." }] }`。

### 视频和长作业：任务API

视频需要几分钟，所以使用任务API：创建一个任务，然后轮询它或接收一个webhook。结果存储在您的机器上。

### 创建任务

```bash
curl http://127.0.0.1:1412/v1/tasks \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_KEY" \
  -d '{
    "model": "muse-video",
    "prompt": "A cat playing piano on a rooftop at night",
    "duration": 30,
    "ratio": "9:16",
    "images": ["https://example.com/cat.jpg"],
    "webhook_url": "https://example.com/hooks/muse",
    "webhook_secret": "choose-a-secret"
  }'
```

门户的答案 `202` 马上就有了一个任务 `status` 是 `running`。

| 场 | 要求 | 意义 |
| --- | --- | --- |
| `prompt` | 是 | 创建什么，多达20,000个字符 |
| `model` | 否 | `muse-video` (默认), `muse-image` 或 `muse-chat` |
| `duration` | 否 | 视频长度，以秒为单位，1到60 |
| `ratio` | 否 | `9:16`， `16:9`， `1:1`， `4:3` 或 `3:4` |
| `images` | 否 | 多达16个参考图像，如 `http(s)` url或 `data:image/...` url，每个最多20MB |
| `webhook_url` | 否 | 任务结束时调用一次 |
| `webhook_secret` | 否 | 在webhook上签名 |
| `idempotency_key` | 否 | 再次发送相同的键返回现有的任务 |
| `new_chat` | 否 | 默认的 `true`． 集 `false` 继续当前的对话 |
| `thread`， `account` | 否 | 继续一个Muse线程；通过之前的结果 |

无法加载的URL将导致请求失败 `400`，因此，如果没有您发送的参考，作业永远不会运行。

### 读取结果

```bash
curl http://127.0.0.1:1412/v1/tasks/TASK_ID -H "authorization: Bearer YOUR_KEY"
```

```json
{
  "id": "task_3f9c...",
  "object": "task",
  "status": "succeeded",
  "model": "muse-video",
  "requested_duration_sec": 30,
  "url": "http://127.0.0.1:1412/api/media/media-abc.mp4",
  "duration_sec": 30.1,
  "media": [{ "url": "http://127.0.0.1:1412/api/media/media-abc.mp4", "kind": "video", "duration_sec": 30.1 }],
  "partial": false,
  "text": "Your video is ready.",
  "thread_url": "https://muse.ai/thread/...",
  "account_id": "...",
  "error": null,
  "webhook_status": "delivered"
}
```

-   `status` 是 `running`， `succeeded`， `failed` 或 `cancelled`． 每10秒左右轮询一次。
-   `url` 是最终文件。 `media` 列出所有已交付的内容。
-   `partial: true` 表示Muse在请求的长度之前停止，并且 `url` 是它发出的最长的剪辑。开放 `thread_url` 检查一下。
-   媒体链接只有在网关保存文件时才是永久的。复制你想要保留的结果。

其他电话:

| 呼叫 | 效果 |
| --- | --- |
| `GET /v1/tasks?limit=20` | 你最近的任务，多达100个 |
| `DELETE /v1/tasks/TASK_ID` | 停止等待任务。已经在Muse内部的渲染会继续在那里运行，并可能使用您的Muse配额。 |

重新启动网关会使仍在运行的任务失败；完成的结果保持可读性。最后500个已完成的任务被保留。

### Webhook

当任务结束时，网关发送一个 `POST` 来 `webhook_url`，如果您的服务器没有响应，请重试两次 `2xx`：

```json
{ "event": "task.succeeded", "task": { "id": "task_3f9c...", "status": "succeeded", "url": "..." } }
```

事件是 `task.succeeded`， `task.failed` 或 `task.cancelled`。与一个 `webhook_secret`,验证 `X-Muse-Signature`，也就是 `sha256=` 加上原始体的HMAC-SHA256：

```js
import crypto from "node:crypto";

const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const valid =
  signature.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
```

网络钩子需要一个网关可以到达的地址。通过隧道发出的呼叫不能针对私有网络地址，所以 `localhost` Webhooks只适用于本地调用者。

### 使用聊天完成功能

`POST /v1/chat/completions` 与 `muse-image` 或 `muse-video` （或图像/视频组合）也生成媒体，这适合只讲OpenAI API的工具。发送 `stream: true`，因为代理切断了长时间的静默请求。额外的字段有 `duration`， `thread`， `account`， `new_chat` 和 `idempotency_key`． 图像输入 `image_url` 部件，作为url或数据url，在最后一个用户消息上。

链接显示为文本 `Attachments:`，最后一块也以结构化的形式携带它们：

```json
{ "muse": { "media": [{ "url": "...", "kind": "video", "duration_sec": 30.1 }], "partial": false, "thread_url": "...", "account_id": "..." } }
```

### 很高兴知道

-   一份工作可提供长达60秒的时间。将较长的视频分成几个任务。
-   一段长视频可能需要好几分钟。网关等待请求的长度，并在没有进展的情况下在5分钟后返回它所拥有的长度。将其更改为 `MUSE_LONG_RENDER_GRACE_MS`。
-   每个帐户一次运行几个作业；额外的工作在排队等待。
-   不支持音频输入。
-   `/v1/responses` 不接受参考图片。

### 错误

| HTTP | 意义 |
| --- | --- |
| `400` | 无效请求，或者无法加载参考图像 |
| `401` | API密钥丢失或错误 |
| `402` | License未激活 |
| `403` | 这把钥匙不能用那个型号 |
| `404` | 没有找到任务，或者它属于另一个键 |

## 你的责任

大门驱动着你自己的灵感。通过浏览器访问帐户。在使用Muse之前，请检查是否符合Muse的条款，并接受账户可能被限制或禁止的风险。只生成你有权制作的内容，尤其是使用真人面孔的内容。

## 命令

| 命令 | 效果 |
| --- | --- |
| `muse-gateway` | 交互式菜单 |
| `npx muse-gateway` | 同样的，不需要npm在PATH上的bin dir |
| `muse-gateway stop` | 停止后台实例 |
| `muse-gateway --open` | 打开仪表盘 |
| `muse-gateway --serve` | 在前台运行服务器（内部使用） |
| `muse-gateway --version` | 打印版本 |
| `MUSE_PORT=4000 muse-gateway` | 自定义端口（默认1412） |

## 数据位置

所有运行时状态（会话、许可证、API密钥、使用情况、媒体、日志）都存在 `~/.muse-gateway` -不要在已安装的包中。卸载保留数据； 删除 `~/.muse-gateway` 完全重置。

-   `~/.muse-gateway/server.log` -后台服务器日志
-   `~/.muse-gateway/data/` - sessions, license。json,钥匙。Json，池，媒体

## 需求

-   Windows 10/11, Node.js≥20.9
-   安装Chrome或Edge（用于Muse帐户登录捕获）

## 许可证

商业, `UNLICENSED`． 网关API需要购买激活密钥。

## 常见问题

### muse-gateway 是什么？

缪斯网关-本地缪斯会话池和openai兼容网关。解锁/v1/\* API所需的许可密钥。

### 如何安装 muse-gateway？

在项目目录运行 npm install muse-gateway，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 muse-gateway，可以用 npx muse-gateway 直接运行。

### muse-gateway 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/muse-gateway 是否存在。

### muse-gateway 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.9\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### muse-gateway 可以商用吗？

muse-gateway 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### muse-gateway 还在维护吗？

最新版本 1\.0\.9 发布于 2026/11/04（今天）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/10/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。