核心用法
Modellix Skill 是官方推出的 Model-as-a-Service (MaaS) 平台集成工具，为开发者提供统一的 AI 图像与视频生成 API 调用能力。核心工作流遵循 "提交任务 → 获取 task_id → 轮询至完成" 的异步模式，支持文本生图（T2I）、图生图（I2I）、文本/图生视频（T2V/I2V）、视频编辑（V2V）及虚拟试穿等场景。
执行路径优先级：CLI 优先 → REST 回退。当 modellix-cli 可用时，使用 modellix-cli model invoke 提交任务，modellix-cli task get <task_id> 获取结果；CLI 不可用时自动降级为 REST API 调用。内置 scripts/preflight.py 进行环境检测，scripts/invoke_and_poll.py 实现自动轮询与指数退避重试。
认证流程：采用严格的密钥生命周期管理——先发现（会话/用户级环境变量）→ 缺失时请求 → 默认会话级使用 → 用户明确要求时才持久化到用户级环境。支持密钥轮换，替换后自动重新验证。
模型选择：通过 references/REFERENCE.md 或官方 llms.txt 索引查询，必须读取具体模型的 .md 文档以确认真实 API 路径（如 minimax/hailuo-2.3-t2v），禁止从文件名猜测 slug。内置默认模型：T2I 用 bytedance/seedream-5.0-lite，I2V 用 bytedance/seedance-2.0-fast-i2v。
显著优点
1. 官方可信，来源明确：Modellix 官方维护，信任等级 T2，非第三方封装，API 行为与官方文档保持一致。
2. 统一接口，多模型覆盖：单一 Skill 整合 Seedream、Seedance、Kling、Hailuo、MiniMax、Qwen、Wan 等主流模型，无需为每个模型单独集成。
3. CLI 优先，开发体验佳：modellix-cli 提供流式输出、机器可读格式（--json）、本地调试能力，显著优于纯 REST 调用。
4. 安全设计严谨：密钥默认会话级、不自动持久化；TLS 1.3 加密传输；无第三方依赖，纯 Python 标准库实现，供应链攻击面为零。
5. 自动化辅助脚本：内置预检测、自动轮询、标准化输出脚本，降低开发者接入门槛。
潜在缺点与局限性
1. 异步模式增加复杂度：必须实现轮询逻辑（或依赖脚本），无法像同步 API 直接返回结果，实时交互场景需额外处理。
2. CLI 依赖 Node.js：CLI 工具需 npm 环境，纯 Python/其他语言环境用户可能遇到安装障碍。
3. 资源 24 小时过期：生成结果 URL 有效期短，需及时下载持久化，长期项目需自建存储。
4. 模型参数差异大：不同模型（如 Hailuo vs Kling）的请求体结构、参数名称差异显著，必须查阅具体文档，无法完全通用。
5. REST 回退功能受限：部分 CLI 高级功能（如进度预览）在 REST 模式下不可用。
适合人群
- AI 应用开发者：需快速集成多厂商图像/视频生成能力的 SaaS、内容创作工具团队。
- 自动化工作流用户：通过 CLI 实现批量生成、CI/CD 集成的 DevOps 工程师。
- 原型验证团队：利用默认模型和快速示例，在数分钟内跑通生成 pipeline。
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| API Key 泄露 | 用户误将密钥写入代码或日志 | Skill 自动掩码输出，强制环境变量注入 |
| 余额不足中断 | 402 错误导致任务失败 | 预检查账户余额，设置消费告警 |
| 结果丢失 | 未及时下载导致 URL 过期 | 任务完成后立即下载，或配置自动同步到对象存储 |
| 模型参数错误 | 未读文档直接调用导致 400 | 强制要求先获取模型文档，验证参数模式 |
| 轮询过度 | 高频轮询触发 429 限流 | 内置指数退避，建议轮询间隔 ≥2 秒 |