mulerouter

使用 MuleRouter 或 MuleRun 多模式 API 生成图像和视频。文本到图像、图像到图像、文本到视频、图像到视频、视频编辑（VACE、关键帧插值）。当用户想要使用 Wan2.6、Veo3、Nano Banana Pro、Sora2、Midjourney 等 AI 模型生成、编辑或转换图像和视频时使用。

# MuleRouter API

Generate images and videos using MuleRouter or MuleRun multimodal APIs.

## Required Environment Variables

This skill requires the following environment variables to be set before use:

| Variable | Required | Description |
|----------|----------|-------------|
| `MULEROUTER_API_KEY` | **Yes** | API key for authentication ([get one here](https://www.mulerouter.ai/app/api-keys?utm_source=github_claude_plugin)) |
| `MULEROUTER_BASE_URL` | **Yes*** | Custom API base URL (e.g., `https://api.mulerouter.ai`). Takes priority over SITE. |
| `MULEROUTER_SITE` | **Yes*** | API site: `mulerouter` or `mulerun`. Used if BASE_URL is not set. |

*At least one of `MULEROUTER_BASE_URL` or `MULEROUTER_SITE` must be set.

The API key is included in `Authorization: Bearer` headers when making network calls to the configured API endpoint.

**If any of these variables are missing, the scripts will fail with a configuration error.** Check the Configuration section below to set them up.

## Configuration Check

Before running any commands, verify the environment is configured:

### Step 1: Check for existing configuration

Run the built-in config check script:

```bash
uv run python -c "from core.config import load_config; load_config(); print('Configuration OK')"
```

If this prints "Configuration OK", skip to **Step 3**. If it raises a `ValueError`, proceed to Step 2.

### Step 2: Configure if needed

**If the variables above are not set**, ask the user to provide their API key and preferred endpoint.

**Create a `.env` file** in the skill's working directory:

```env
# Option 1: Use custom base URL (takes priority over SITE)
MULEROUTER_BASE_URL=https://api.mulerouter.ai
MULEROUTER_API_KEY=your-api-key

# Option 2: Use site (if BASE_URL not set)
# MULEROUTER_SITE=mulerun
# MULEROUTER_API_KEY=your-api-key
```

**Note:** `MULEROUTER_BASE_URL` takes priority over `MULEROUTER_SITE`. If both are set, `MULEROUTER_BASE_URL` is used.

**Note:** The skill only loads variables prefixed with `MULEROUTER_` from the `.env` file. Other variables in the file are ignored.

**Important:** Do NOT use `export` shell commands to set credentials. Use a `.env` file or ensure the variables are already present in your shell environment before invoking the skill.

### Step 3: Using `uv` to run scripts

The skill uses `uv` for dependency management and execution. Make sure `uv` is installed and available in your PATH.

Run `uv sync` to install dependencies.

## Quick Start

### 1. List available models

```bash
uv run python scripts/list_models.py
```

### 2. Check model parameters

```bash
uv run python models/alibaba/wan2.6-t2v/generation.py --list-params
```

### 3. Generate content

**Text-to-Video:**
```bash
uv run python models/alibaba/wan2.6-t2v/generation.py --prompt "A cat walking through a garden"
```

**Text-to-Image:**
```bash
uv run python models/alibaba/wan2.6-t2i/generation.py --prompt "A serene mountain lake"
```

**Image-to-Video:**
```bash
uv run python models/alibaba/wan2.6-i2v/generation.py --prompt "Gentle zoom in" --image "https://example.com/photo.jpg" #remote image url
```
```bash
uv run python models/alibaba/wan2.6-i2v/generation.py --prompt "Gentle zoom in" --image "/path/to/local/image.png" #local image path
```

## Image Input

For image parameters (`--image`, `--images`, etc.), **prefer local file paths** over base64.

```bash
# Preferred: local file path (auto-converted to base64)
--image /tmp/photo.png

--images ["/tmp/photo.png"]
```

Local file paths are validated before reading: only files with recognized image extensions (`.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`, `.tiff`, `.tif`, `.svg`, `.ico`, `.heic`, `.heif`, `.avif`) are accepted. Paths pointing to sensitive system directories or non-image files are rejected. Valid image files are converted to base64 and sent to the API, avoiding command-line length limits that occur with raw base64 strings.

## Workflow

1. Check configuration: verify `MULEROUTER_API_KEY` and either `MULEROUTER_BASE_URL` or `MULEROUTER_SITE` are set
2. Install dependencies: run `uv sync`
3. Run `uv run python scripts/list_models.py` to discover available models
4. Run `uv run python models/<path>/<action>.py --list-params` to see parameters
5. Execute with appropriate parameters
6. Parse output URLs from results

## Model Selection

When listing models, each model's **tags** (e.g., `[SOTA]`) are displayed by default next to its name. Tags help identify model characteristics at a glance — for example, `SOTA` indicates a state-of-the-art model.

You can also filter models by tag using `--tag`:
```bash
uv run python scripts/list_models.py --tag SOTA
```

**If you are unsure which model to use**, present the available options to the user and let them choose. Use the `AskUserQuestion` tool (or equivalent interactive prompt) to ask the user which model they prefer. For example, if the user asks to "generate an image" without specifying a model, list the relevant image generation models with their tags and descriptions, and ask the user to pick one.

## Tips
1. For an image generation model, a suggested timeout is 5 minutes.
2. For a video generation model, a suggested timeout is 15 minutes.

## References

- [REFERENCE.md](references/REFERENCE.md) - API configuration and CLI options
- [MODELS.md](references/MODELS.md) - Complete model specifications

---

## 中文说明

# MuleRouter API

使用 MuleRouter 或 MuleRun 多模态 API 生成图像和视频。

## 必需的环境变量

本技能在使用前需要设置以下环境变量：

| 变量 | 是否必需 | 说明 |
|----------|----------|-------------|
| `MULEROUTER_API_KEY` | **是** | 用于身份验证的 API 密钥（[在此获取](https://www.mulerouter.ai/app/api-keys?utm_source=github_claude_plugin)） |
| `MULEROUTER_BASE_URL` | **是\*** | 自定义 API base URL（例如 `https://api.mulerouter.ai`）。优先级高于 SITE。 |
| `MULEROUTER_SITE` | **是\*** | API 站点：`mulerouter` 或 `mulerun`。在未设置 BASE_URL 时使用。 |

\*`MULEROUTER_BASE_URL` 或 `MULEROUTER_SITE` 中至少需设置一个。

在向所配置的 API 端点发起网络调用时，API 密钥会包含在 `Authorization: Bearer` 请求头中。

**如果缺少其中任何变量，脚本将因配置错误而失败。** 请查看下方的「配置」一节进行设置。

## 配置检查

在运行任何命令之前，先确认环境已配置完毕：

### 步骤 1：检查现有配置

运行内置的配置检查脚本：

```bash
uv run python -c "from core.config import load_config; load_config(); print('Configuration OK')"
```

如果输出 "Configuration OK"，则跳至**步骤 3**。如果抛出 `ValueError`，则继续步骤 2。

### 步骤 2：按需配置

**如果上述变量未设置**，请要求用户提供其 API 密钥和首选端点。

**在技能的工作目录中创建一个 `.env` 文件**：

```env
# Option 1: Use custom base URL (takes priority over SITE)
MULEROUTER_BASE_URL=https://api.mulerouter.ai
MULEROUTER_API_KEY=your-api-key

# Option 2: Use site (if BASE_URL not set)
# MULEROUTER_SITE=mulerun
# MULEROUTER_API_KEY=your-api-key
```

**注意：** `MULEROUTER_BASE_URL` 的优先级高于 `MULEROUTER_SITE`。如果两者都设置了，则使用 `MULEROUTER_BASE_URL`。

**注意：** 本技能只会从 `.env` 文件中加载以 `MULEROUTER_` 为前缀的变量。文件中的其他变量将被忽略。

**重要：** 请勿使用 `export` shell 命令来设置凭据。请使用 `.env` 文件，或确保在调用本技能之前这些变量已存在于你的 shell 环境中。

### 步骤 3：使用 `uv` 运行脚本

本技能使用 `uv` 进行依赖管理和执行。请确保已安装 `uv` 并使其在你的 PATH 中可用。

运行 `uv sync` 以安装依赖。

## 快速开始

### 1. 列出可用模型

```bash
uv run python scripts/list_models.py
```

### 2. 查看模型参数

```bash
uv run python models/alibaba/wan2.6-t2v/generation.py --list-params
```

### 3. 生成内容

**文本到视频：**
```bash
uv run python models/alibaba/wan2.6-t2v/generation.py --prompt "A cat walking through a garden"
```

**文本到图像：**
```bash
uv run python models/alibaba/wan2.6-t2i/generation.py --prompt "A serene mountain lake"
```

**图像到视频：**
```bash
uv run python models/alibaba/wan2.6-i2v/generation.py --prompt "Gentle zoom in" --image "https://example.com/photo.jpg" #remote image url
```
```bash
uv run python models/alibaba/wan2.6-i2v/generation.py --prompt "Gentle zoom in" --image "/path/to/local/image.png" #local image path
```

## 图像输入

对于图像参数（`--image`、`--images` 等），**优先使用本地文件路径**而非 base64。

```bash
# Preferred: local file path (auto-converted to base64)
--image /tmp/photo.png

--images ["/tmp/photo.png"]
```

本地文件路径在读取前会经过校验：仅接受具有可识别图像扩展名（`.png`、`.jpg`、`.jpeg`、`.gif`、`.bmp`、`.webp`、`.tiff`、`.tif`、`.svg`、`.ico`、`.heic`、`.heif`、`.avif`）的文件。指向敏感系统目录或非图像文件的路径会被拒绝。有效的图像