*更新日期: 2026-11-07*

# Agent / CLI

把平台模型能力接入 Cursor / Claude Desktop / Codex，或在终端、脚本里直接调用。工具与 `/v1` 使用同一把 API Key，按租户余额计费。

> `@momotoken/api-mcp` 发布到 npm 后可用 `npx`；本地开发阶段可运行 `node packages/api-mcp/src/cli.js`。

## 准备

- Node.js **>= 18.3**（推荐 20 LTS）
- 一把 `sk_live_...` API Key（在租户台创建）

```bash
export MOMO_API_BASE_URL=https://tokenmei.com
export MOMO_API_KEY=sk_live_...
```

验证配置与连通性：

```bash
npx -y @momotoken/api-mcp doctor
```

## 命令行

| 命令 | 作用 |
|------|------|
| `momo-api models [--capability chat\|image\|video]` | 列出可用模型 |
| `momo-api models get <id>` | 模型详情 |
| `momo-api chat [prompt] -m <model>` | 对话，默认流式 |
| `momo-api image generate\|edit <prompt>` | 生图 / 图生图 |
| `momo-api video create <prompt>` | 创建视频任务 |
| `momo-api video get\|wait\|download <id>` | 查询、等待、下载视频 |
| `momo-api task get\|wait <id>` | 通用任务查询 |
| `momo-api task ls` | 本机任务记录 |
| `momo-api login` / `logout` | 保存 / 移除配置里的 Key |
| `momo-api mcp --print-config` | 输出 MCP 配置片段 |

常用示例：

```bash
# 对话（可管道）
momo-api chat "用三句话解释 MCP" -m doubao-seed-1.6

# 生图并落盘
momo-api image generate "雨夜霓虹街头的橙猫" -m <image-model> \
  --size 1024x1024 -o ./out/

# 视频：创建 → 等待 → 下载
momo-api video create "镜头跟随橙猫穿过雨夜街道" -m <video-model> \
  --duration 5 --ratio 16:9 --resolution 720p --json
momo-api video wait video_xxx --timeout 16m
momo-api video download video_xxx -o ./out/cat.mp4
```

生图默认同步；加 `--async` 返回任务 id，用 `momo-api task wait <id> --out ./out/` 取结果。视频始终异步。

常用参数：`--n`、`--size`、`--aspect-ratio`、`--quality`、`--ref`（参考图，可重复）、`--duration`、`--ratio`、`--resolution`、`--audio`、`--watermark`、`--out`、`--force`、`--json`、`--jsonl`、`--dry-run`、`--timeout`。

## 配置

优先级：命令行参数 > 环境变量 > profile 文件。

| 变量 | 说明 |
|------|------|
| `MOMO_API_BASE_URL` | API 源站，如 `https://tokenmei.com` |
| `MOMO_API_KEY` | `sk_live_...` |
| `MOMO_API_PROFILE` | 选择 profile |
| `MOMO_API_HOME` | 覆盖配置目录 |

配置文件在 `~/.config/momo-api/config.json`（Windows 为 `%APPDATA%\momo-api\config.json`），目录 `0700`、文件 `0600`。`momo-api login` 会验证 Key 后写入：

```bash
echo "$MOMO_API_KEY" | momo-api login --base-url https://tokenmei.com
momo-api profile list
momo-api profile use default
```

## MCP

```json
{
  "mcpServers": {
    "momo-api": {
      "command": "npx",
      "args": ["-y", "@momotoken/api-mcp", "mcp"],
      "env": {
        "MOMO_API_BASE_URL": "https://tokenmei.com",
        "MOMO_API_KEY": "sk_live_..."
      }
    }
  }
}
```

把 `momo-api mcp --print-config` 的输出粘贴到客户端即可。

### 工具

| 工具 | 说明 |
|------|------|
| `momo_models_list` | 列模型；生成前先调用 |
| `momo_models_get` | 单个模型与价格 |
| `momo_chat` | 对话（缓冲返回） |
| `momo_image_generate` | 生图，默认异步 |
| `momo_image_edit` | 带参考图的图生图 |
| `momo_video_create` | 创建视频任务 |
| `momo_task_get` | 查询一次任务 |
| `momo_task_wait` | 等待最多 45 秒，返回 `done` |
| `momo_asset_inline` | 把 ≤4MB 图片内联进上下文 |

### 长任务

生图/生视频返回 `taskId` 时，继续调用 `momo_task_wait`，不要把 `momo_video_create` / `momo_image_generate` 再调一次——重复创建会重复扣费。单次 `momo_task_wait` 最多 45 秒，未完成时按返回的 `retryAfterSeconds` 继续。

## 退出码

| 退出码 | 含义 |
|--------|------|
| 0 | 成功 |
| 2 | 参数 / 配置错误 |
| 3 | API Key 无效 |
| 4 | 余额不足 |
| 5 | 触发限流 |
| 6 | 模型或任务不存在 |
| 7 | 能力未开通 |
| 8 | 上游错误 |
| 9 | 超时 / 网络错误 |
| 10 | 本地文件错误 |

## 安全与限制

- 所有输出中的 Key 都会脱敏；非 localhost 强制 HTTPS。
- 本地参考图上限 10MB；下载上限 512MB，先写 `.part` 再改名。
- 生成类 POST 不会自动重试（避免重复扣费）；`GET` 失败会有限重试。
- 任务完成后 URL 有保留期，需要长期保存请下载到本地。

CLI / MCP 不封装余额查询。需要时直接调 `GET /v1/balance`，见 [计费与产物](/docs/usage)。

更多契约见 [模型](/docs/models)、[对话](/docs/chat)、[生图](/docs/images)、[生视频](/docs/videos)、[任务查询](/docs/tasks)、[计费与产物](/docs/usage)、[错误码](/docs/errors)。
