MuleRouter API

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

必需的环境变量

使用本技能前，需预先设置以下环境变量：

*MULEROUTER_BASE_URL 与 MULEROUTER_SITE 至少需设置其一。

调用配置的 API 端点时，API 密钥将作为 Authorization: Bearer 请求头的一部分自动携带。

若上述任一变量缺失，脚本将因配置错误而失败。 请参阅下方“配置检查”部分完成设置。

配置检查

执行任何命令前，请先验证运行环境是否已正确配置：

步骤 1：检查现有配置

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

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

若输出为 Configuration OK，请跳至 步骤 3；若抛出 ValueError 异常，则继续执行步骤 2。

步骤 2：按需完成配置

若上述环境变量尚未设置，请向用户索取其 API 密钥及首选端点。

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

# 方案 1：使用自定义基础 URL（优先级高于 SITE）
MULEROUTER_BASE_URL=https://api.mulerouter.ai
MULEROUTER_API_KEY=your-api-key

# 方案 2：使用站点标识（仅当未设置 BASE_URL 时生效）
# 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. 列出可用模型

uv run python scripts/list_models.py

2. 查看模型参数

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

3. 生成内容

文本生成视频（Text-to-Video）：

uv run python models/alibaba/wan2.6-t2v/generation.py --prompt "一只猫漫步穿过花园"

文本生成图像（Text-to-Image）：

uv run python models/alibaba/wan2.6-t2i/generation.py --prompt "宁静的高山湖泊"

图像生成视频（Image-to-Video）：

uv run python models/alibaba/wan2.6-i2v/generation.py --prompt "缓慢缩放镜头" --image "https://example.com/photo.jpg" # 远程图片 URL

uv run python models/alibaba/wan2.6-i2v/generation.py --prompt "缓慢缩放镜头" --image "/path/to/local/image.png" # 本地图片路径

图像输入

对于图像类参数（如 --image、--images 等），建议优先使用本地文件路径而非 base64 字符串。

# 推荐方式：本地文件路径（将自动转换为 base64）
--image /tmp/photo.png

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

本地文件路径将在读取前进行校验：仅接受具有标准图像扩展名的文件（包括 .png、.jpg、.jpeg、.gif、.bmp、.webp、.tiff、.tif、.svg、.ico、.heic、.heif、.avif）。指向敏感系统目录或非图像文件的路径将被拒绝。经校验有效的图像文件将被自动编码为 base64 并发送至 API，从而规避原始 base64 字符串可能引发的命令行长度限制问题。

工作流程

1. 检查配置：确认已设置 MULEROUTER_API_KEY，以及 MULEROUTER_BASE_URL 或 MULEROUTER_SITE 中至少一项
2. 安装依赖：运行 uv sync
3. 运行 uv run python scripts/list_models.py 发现可用模型
4. 运行 uv run python models//.py --list-params 查看具体参数
5. 使用合适参数执行生成任务
6. 解析返回结果中的输出 URL

模型选择

在列出模型时，每个模型名称旁默认显示其标签（例如：[SOTA]）。这些标签可帮助用户快速识别模型特性——例如，SOTA 表示该模型为当前最先进的（State-of-the-Art）模型。

您也可使用 --tag 参数按标签筛选模型：

uv run python scripts/list_models.py --tag SOTA

若您不确定应选用哪个模型，请向用户展示所有可用选项并由其自主选择。可使用 AskUserQuestion 工具（或等效的交互式提示机制）询问用户倾向的模型。例如，当用户仅提出“生成一张图像”但未指定模型时，应列出所有相关的图像生成模型及其标签与简要说明，并引导用户从中选择一项。

使用提示

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

参考资料

• REFERENCE.md —— API 配置与 CLI 参数说明
• MODELS.md —— 完整模型规格文档