modellix

Modellix 技能

Modellix 是一个面向异步图像、视频和音频工作流的模型即服务（MaaS）平台。请优先使用官方 CLI（modellix-cli），让提交、等待和下载保持为一个连贯的工作流。针对特定主机的持久会话防护规则也位于 rules/*.mdc 下。

官方文档

• AI 入门指南：https://docs.modellix.ai/get-started.md
• REST API：https://docs.modellix.ai/ways-to-use/api.md
• 完整模型索引：https://docs.modellix.ai/llms.txt
• Docs MCP（搜索／阅读文档）：https://docs.modellix.ai/mcp
• CLI 软件包（CLI 行为的事实来源）：https://www.npmjs.com/package/modellix-cli

文档查询策略

此插件可能会提供 Modellix Docs MCP（.mcp.json → https://docs.modellix.ai/mcp）。它是一个只读文档服务（search_modellix、文档文件系统查询、可选反馈）。它不会提交生成任务、轮询、下载或处理 API 密钥。

查询产品／API／安装文档与请求正文架构时：

1. 对于请求／响应架构，使用 modellix-cli model get-schema <slug>（默认输出 JSON；该端点公开访问，无需 API 密钥）。如果 CLI 不可用，则使用 Docs MCP，然后查阅 model describe 中的 docs_url 或 https://docs.modellix.ai/llms.txt。
2. 对于产品／安装说明，如果主机已连接 Docs MCP，请优先使用它（先搜索，再阅读匹配的页面）。否则，使用 model describe <slug> --json → docs_url，或浏览 llms.txt 并获取模型 .md 文件。
3. 对于 CLI 命令语法和标志，请优先参考此技能、references/cli-playbook.md、npm README 或 modellix-cli --help——不要相信网站上的 CLI 页面，而应以 CLI 软件包为准（文档可能滞后）。

如果 Docs MCP 提供了技能资源，请将此 SKILL.md 视为执行策略的事实来源（CLI 优先、默认值、付费提交安全性）。

不要依赖网站上的 CLI 指南页面来确定命令语法。

执行策略（CLI 优先）

按以下顺序选择执行方式：

1. 如果 scripts/preflight.py --json 检测到 CLI，则使用 CLI。预检会检查公共 npm 的 latest 版本，仅在有更新版本时安装指定的精确版本，并在更新基础设施不可用时保留现有 CLI。
2. 只有在 CLI 未安装、不适用或缺少所需功能时，才使用 REST。
3. 自动化时优先使用机器可读输出（--json 或 --quiet）。

标准单任务流程：

python3 scripts/preflight.py --json
modellix-cli doctor --json
modellix-cli model get-schema <provider/model>
modellix-cli model run \
  --model-slug <provider/model> \
  --body '<json>' \
  --wait --timeout 5m --json
modellix-cli task download <task_id> --output-dir ./outputs --json

如果技能默认值和下方示例已列出所需字段，或用户已提供完整正文，则跳过 get-schema。

model invoke 是 model run 的兼容别名。新命令应使用 model run。

如果 CLI 提供了 wait，不要重新实现轮询循环。不要虚构已弃用的标志（例如 --model-type）。只有在行为不明确时才使用 --help。

默认模型

如果用户未指定模型，请立即使用以下默认模型（不要先扫描目录）：

任务类型	默认模型别名
文本生成图像（T2I）	google/nano-banana-2-lite
文本生成视频（T2V）	bytedance/seedance-2.0-mini-t2v
图像编辑／图像生成图像（I2I）	google/nano-banana-2-lite-edit
图像生成视频／图像转视频（I2V）	bytedance/seedance-2.0-fast-i2v
视频生成视频（V2V）	bytedance/seedance-2.0-fast-v2v
文本转语音（TTS）	alibaba/qwen-audio-3.0-tts-flash
语音转文本（STT）	openai/whisper-1
语音转语音（STS）	alibaba/cosyvoice-clone

API 密钥生命周期策略

按以下流程处理凭据：discover -> request -> use-session -> (optional) persist。

1）先查找现有密钥

询问用户之前：

1. 会话／进程环境变量 MODELLIX_API_KEY
2. 已保存的 CLI 配置（modellix-cli auth status／doctor — 密钥通过 --profile、MODELLIX_PROFILE 或 currentProfile 指定）
3. 如果仍未找到，则向用户索取密钥

如果已能找到可用密钥，绝不再次询问。CLI 密钥解析顺序为：--api-key → MODELLIX_API_KEY → 所选的已保存配置。

2) 仅在缺少密钥时请求

• 从 Modellix Console 请求密钥。
• 不要打印或回显密钥值。
• 优先使用当前运行的会话环境变量。

3) 可选持久化

默认情况下，不自动持久化。

只有当用户明确要求持久化时：

1. 首选：modellix-cli auth login 或 modellix-cli init（CLI 会验证并安全存储配置文件）。
2. 替代方案：仅当用户坚持使用环境变量持久化时，才使用用户级 MODELLIX_API_KEY。
3. 不要写入系统级环境变量或其他 Agent 的配置文件。

4) 密钥轮换

如果用户提供了新密钥：先更新会话；如果用户要求持久化，则通过 auth login/init（或用户级环境变量）替换。继续之前，使用 modellix-cli doctor --json（或 scripts/preflight.py --json）重新检查。

预检与确定性执行

有 Python 3 时，首次工作流必须执行以下检查：

python3 scripts/preflight.py --json

捆绑的辅助脚本：

1. scripts/preflight.py — 检查公共 npm latest，在付费工作前安全地更新缺失或较旧的全局 CLI，固定较新的本地安装而非降级，封装 doctor，并推荐使用 cli、rest 或 none。
2. scripts/invoke_and_poll.py — 提交前执行相同的解析，为工作流固定解析出的可执行文件，在 CLI 上使用 model run --wait，否则使用 REST 提交并轮询作为后备方案。

只有当环境必须保留已安装的 CLI 版本时，才设置 MODELLIX_CLI_AUTO_UPDATE=0（也接受 false 或 off）。注册表/安装失败不会造成破坏：如果现有 CLI 仍通过 doctor 检查，则使用它；如果没有可用的 CLI 且存在会话 API 密钥，则使用 REST。付费提交开始后，绝不要更新或替换 CLI。

当预检/doctor 报告缺少凭据时，按上述生命周期处理。

CLI 不可用时：

1. 使用 REST（references/rest-playbook.md）。
2. 报告预检更新警告；不要在同一个付费工作流中反复尝试安装。

核心工作流

1) 准备环境

• 查找或请求 API 密钥（按上述生命周期处理）。
• 运行 scripts/preflight.py --json；只有 doctor 检查通过的 CLI 路径，或经过身份验证的 REST 后备方案，才能继续。
• 只有在身份验证和连接状态正常（或已设置 REST 密钥）时才能继续。

2) 选择模型

1. 如果用户未指定模型：使用 默认模型 表（不要先扫描目录）。
2. 如果用户指定了模型或需要发现模型：使用 modellix-cli model list / modellix-cli model describe <slug>（目录元数据；describe 会返回 docs_url）。
3. 如需请求正文架构：使用 modellix-cli model get-schema <slug>（默认为 JSON；公开访问，无需 API 密钥）。当用户指定了非默认 slug、正文需要超出已记录示例的字段、收到 HTTP 400 后，或需要报告必填字段时，调用此命令。如果技能默认值和示例已列出必填字段，或用户提供了完整正文，则跳过。
4. 如果 CLI 不可用于架构查询或模型发现：使用 Docs MCP 或浏览 llms.txt，然后获取目标模型的 .md 文件。不要根据文件名臆造 slug（小数版本号往往很重要，例如 bytedance/seedance-2.0-mini-t2v）。

3) 运行并等待

默认（单项任务）：

modellix-cli model run \
  --model-slug google/nano-banana-2-lite \
  --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
  --wait --timeout 5m --json

适用时使用拆分流程（管道、并发）：

TASK_ID=$(modellix-cli model run --model-slug ... --body '...' --output task-id)
modellix-cli task wait "$TASK_ID" --timeout 10m --json

批处理（必须进行付费保护）：modellix-cli model batch tasks.jsonl --max-tasks N [--wait]。

手动使用 REST：references/rest-playbook.md。可选辅助脚本：scripts/invoke_and_poll.py。

4) 下载结果

modellix-cli task download <task_id> --output-dir ./outputs --json

如果下载失败并提示 Resource host resolves to a private or reserved network address（常见于本地代理/VPN 将 file.modellix.ai 等 CDN 主机映射到 198.18.0.0/15 的情况），对于可信的 Modellix CDN 主机，可使用 --allow-private-network 重试；也可以改用 curl/wget 下载 result.resources[].url。

资源 URL 大约 7 天后过期——请尽快保存。如果手动下载（REST 路径），请按以下规则命名文件：

modellix-{model_slug}-{timestamp}.{ext}

（将 slug 中的 / 替换为 -）。

示例：

• modellix-google-nano-banana-2-lite-20260430-113000.png
• modellix-bytedance-seedance-2.0-mini-t2v-20260430-113500.mp4

快速示例

T2I（默认模型）——必需参数：prompt：

modellix-cli model run \
  --model-slug google/nano-banana-2-lite \
  --body '{"prompt":"A cinematic sunset over a futuristic city skyline"}' \
  --wait --timeout 5m --json

T2V（默认模型）——必需参数：prompt：

modellix-cli model run \
  --model-slug bytedance/seedance-2.0-mini-t2v \
  --body '{"prompt":"A cat playing in a sunny garden"}' \
  --wait --timeout 10m --json

I2I——prompt + image 数组：

modellix-cli model run \
  --model-slug google/nano-banana-2-lite-edit \
  --body '{"prompt":"Convert to watercolor style","image":["https://example.com/input.jpg"]}' \
  --wait --timeout 5m --json

I2V——至少需要一个图像参数（first_frame_image、last_frame_image 或 reference_images）：

modellix-cli model run \
  --model-slug bytedance/seedance-2.0-fast-i2v \
  --body '{"prompt":"A cat playing in the garden","first_frame_image":"https://example.com/frame.jpg"}' \
  --wait --timeout 10m --json

V2V——video_urls 数组：

modellix-cli model run \
  --model-slug bytedance/seedance-2.0-fast-v2v \
  --body '{"video_urls":["https://example.com/source.mp4"]}' \
  --wait --timeout 10m --json

TTS（默认模型）——必需参数：text + voice（使用 model get-schema 或模型文档确认语音；仅限 Flash 语音）：

modellix-cli model run \
  --model-slug alibaba/qwen-audio-3.0-tts-flash \
  --body '{"text":"There is a large garden behind my house.","voice":"longanhuan_v3.6"}' \
  --wait --timeout 5m --json

STT（默认模型）——必需参数：公开音频 url：

modellix-cli model run \
  --model-slug openai/whisper-1 \
  --body '{"url":"https://example.com/meeting.mp3"}' \
  --wait --timeout 5m --json

STS（默认模型）——克隆参考 url + 合成 text + 目标 CosyVoice model：

modellix-cli model run \
  --model-slug alibaba/cosyvoice-clone \
  --body '{"model":"cosyvoice-v3.5-plus","url":"https://example.com/reference.wav","text":"There is a large garden behind my house."}' \
  --wait --timeout 5m --json

5) 任务完成后的 CLI 建议

如果本次会话因缺少 CLI 而使用了 REST，请建议之后安装 CLI。

渐进式参考路由

只阅读任务所需的内容：

• references/cli-playbook.md — 安装、身份验证、运行/等待/下载、批处理、恢复
• references/rest-playbook.md — CLI 不可用时的 REST 提交/轮询
• references/capability-matrix.md — CLI ↔ REST 映射和回退规则

捆绑资源

• assets/output/task-result.schema.json

凭据与数据外传

• 主要凭据：MODELLIX_API_KEY（也可通过 CLI 配置文件使用）。
• 网络外传：https://api.modellix.ai（仅可使用可信的 --base-url / MODELLIX_BASE_URL 覆盖）。
• 调用期间，用户提示词和媒体输入可能会发送到 Modellix。
• 切勿在日志、屏幕截图、文字记录或提交中暴露 API 密钥。
• 默认仅使用会话级凭据；持久化写入需要获得用户明确批准。

错误/重试策略

情况	操作
HTTP/API 400	不要重试。修正参数或请求正文（如果接口约定不明确，请使用 model get-schema）。
401	不要重试。修正密钥（doctor、auth login）。
402	不要重试。余额不足。
404	不要重试。确认 task_id 或模型 slug。
429 / 只读 5xx	CLI 已在时限内重试安全的 GET 请求；不要盲目重新 POST 付费提交。
付费提交结果未知	不要立即重新运行相同的 model run。先检查 task history、控制台活动记录以及任何已打印的任务 ID。
退出码 124	本地等待超时；远程任务可能仍在运行——使用 task wait / task get 恢复，然后使用 task download。
退出码 2	参数或安全防护导致的退出（例如批处理成本上限）——修正标志。

验证清单

• Doctor/预检已通过，或 REST 密钥已就绪
• 已选择模型（默认表格中的模型，或用户指定/目录中的模型）
• 对于非简单请求，已使用 model get-schema 检查请求正文架构（CLI 不可用时则查看模型文档）
• 使用了 model run --wait（或 task wait），而非手动编写轮询循环
• 已下载结果（使用 task download，或在 7 天到期前手动保存）
• 付费提交结果未知时，没有盲目重试
• 仅在 CLI 路径不可用时使用 REST