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. 生成内容

文本转视频：

uv run python models/alibaba/wan2.6-t2v/generation.py --prompt "A cat walking through a garden"

文本转图像：

uv run python models/alibaba/wan2.6-t2i/generation.py --prompt "A serene mountain lake"

图像转视频：

uv run python models/alibaba/wan2.6-i2v/generation.py --prompt "Gentle zoom in" --image "https://example.com/photo.jpg" # 远程图片链接

uv run python models/alibaba/wan2.6-i2v/generation.py --prompt "Gentle zoom in" --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 表示该模型为当前最先进水平。

也可通过 --tag 参数筛选模型：

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

若不确定使用哪个模型，请向用户展示所有可用选项，并由用户自行选择。可使用 AskUserQuestion 工具（或等效交互式提示）询问用户偏好。例如，当用户要求“生成一张图像”但未指定模型时，列出相关图像生成模型及其标签和描述，并请用户选择一个。

小贴士

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

参考资料

• [REFERENCE.md](references/REFERENCE.md) - API 配置与 CLI 选项说明
• [MODELS.md](references/MODELS.md) - 完整的模型规格说明