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.

## Configuration Check

Before running any commands, verify the environment is configured:

### Step 1: Check for existing configuration

```bash
# Check environment variables
echo "MULEROUTER_BASE_URL: $MULEROUTER_BASE_URL"
echo "MULEROUTER_SITE: $MULEROUTER_SITE"
echo "MULEROUTER_API_KEY: ${MULEROUTER_API_KEY:+[SET]}"

# Check for .env file
ls -la .env 2>/dev/null || echo "No .env file found"
```

### Step 2: Configure if needed

**Option A: Environment variables with custom base URL (highest priority)**
```bash
export MULEROUTER_BASE_URL="https://api.mulerouter.ai"  # or your custom API endpoint
export MULEROUTER_API_KEY="your-api-key"
```

**Option B: Environment variables with site (used if base URL not set)**
```bash
export MULEROUTER_SITE="mulerun"    # or "mulerouter"
export MULEROUTER_API_KEY="your-api-key"
```

**Option C: Create .env file**

Create `.env` in the current 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 tool only reads `.env` from the current directory. Run scripts from the skill root (`skills/mulerouter-skills/`).

### 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"]
```

The skill automatically converts local file paths to base64 before sending to the API. This avoids command-line length limits that occur with raw base64 strings.

## Workflow

1. Check configuration: verify `MULEROUTER_BASE_URL` or `MULEROUTER_SITE`, and `MULEROUTER_API_KEY` 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

## 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 生成图像和视频。

## 配置检查

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

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

```bash
# Check environment variables
echo "MULEROUTER_BASE_URL: $MULEROUTER_BASE_URL"
echo "MULEROUTER_SITE: $MULEROUTER_SITE"
echo "MULEROUTER_API_KEY: ${MULEROUTER_API_KEY:+[SET]}"

# Check for .env file
ls -la .env 2>/dev/null || echo "No .env file found"
```

### 步骤 2：按需配置

**选项 A：带自定义 base URL 的环境变量（优先级最高）**
```bash
export MULEROUTER_BASE_URL="https://api.mulerouter.ai"  # or your custom API endpoint
export MULEROUTER_API_KEY="your-api-key"
```

**选项 B：带 site 的环境变量（在未设置 base URL 时使用）**
```bash
export MULEROUTER_SITE="mulerun"    # or "mulerouter"
export MULEROUTER_API_KEY="your-api-key"
```

**选项 C：创建 .env 文件**

在当前工作目录中创建 `.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`。请从技能根目录（`skills/mulerouter-skills/`）运行脚本。

### 步骤 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"]
```

该技能会在发送到 API 之前自动将本地文件路径转换为 base64。这可以避免原始 base64 字符串带来的命令行长度限制问题。

## 工作流程

1. 检查配置：确认已设置 `MULEROUTER_BASE_URL` 或 `MULEROUTER_SITE`，以及 `MULEROUTER_API_KEY`
2. 安装依赖：运行 `uv sync`
3. 运行 `uv run python scripts/list_models.py` 以发现可用模型
4. 运行 `uv run python models/<path>/<action>.py --list-params` 查看参数
5. 使用合适的参数执行
6. 从结果中解析输出 URL

## 提示

1. 对于图像生成模型，建议的超时时间为 5 分钟。
2. 对于视频生成模型，建议的超时时间为 15 分钟。

## 参考

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