核心用法
Modellix 是 Model-as-a-Service (MaaS) 媒体生成平台，提供统一的异步图像/视频生成 API。标准流程为：提交任务 → 获取 task_id → 轮询至 success 或 failed 状态。执行策略遵循 CLI 优先原则：优先使用 modellix-cli，不可用时降级至 REST API，并优先采用机器可读输出（--json）。
密钥生命周期管理
采用四阶段策略：发现（session/user env → 请求 → 会话使用 → 可选持久化）。首次使用需用户从 Modellix Console 获取 API key；默认会话级使用，仅当用户明确要求时才持久化至 user-level 环境变量。支持密钥轮换：用户提供新 key 时替换现有值，重新验证后继续。
执行流程
1. 预检：运行 scripts/preflight.py 验证 CLI 可用性与凭证，返回推荐模式（cli/rest）
2. 选模：查阅 references/REFERENCE.md 获取模型参数文档
3. 调用轮询：首选 scripts/invoke_and_poll.py（CLI 优先，REST 兜底），内置指数退避与可重试错误处理
4. 资源消费：结果 URL 位于 result.resources，24 小时内有效，需及时下载
显著优点
- 统一多模型接口：整合 Qwen、Wan、Seedream、Seedance、Kling、Hailuo、MiniMax 等主流生成模型
- 确定性执行：预检脚本确保环境就绪，避免运行时失败
- 智能降级：CLI 不可用时自动切换 REST，保障任务连续性
- 安全密钥管理：默认会话级使用，持久化需显式授权，避免凭证泄露
- 完善的重试机制：429/500/503 自动指数退避，429 尊重
X-RateLimit-Reset
潜在局限
- 异步延迟：必须轮询获取结果，实时性弱于同步 API
- 结果时效性：生成资源 24 小时过期，需额外持久化逻辑
- CLI 依赖：部分环境可能缺失 CLI，需 REST 降级
- 模型参数差异：不同模型参数需查阅独立文档，无完全统一接口
适合人群
- 需快速接入多厂商 AI 图像/视频生成的开发者
- 追求 CLI 工作流与自动化脚本的技术团队
- 需要虚拟试衣、图像编辑等特定功能的应用构建者
常规风险
- 密钥泄露：需严格遵循「永不回显 key」规则，避免日志/截图暴露
- 成本失控：异步任务可能产生意外调用量，建议配合速率限制监控
- 结果丢失：24 小时过期机制可能导致未及时下载的资源失效
- 供应商锁定：深度整合后迁移至其他 MaaS 平台需适配成本