核心用法
Modellix 是一个 Model-as-a-Service (MaaS) 平台，提供统一的异步图像和视频生成 API。核心工作流遵循 提交任务 → 获取 task_id → 轮询至完成 的固定模式。
执行策略（CLI 优先）：
1. 优先使用 modellix-cli（如可用且已认证）
2. 否则回退到 REST API
3. CLI 流程优先使用 --json 机器可读输出
预检与确定性执行：
scripts/preflight.py：验证 CLI 可用性和 API key，推荐执行模式scripts/invoke_and_poll.py：CLI 优先执行，支持 REST 回退，内置指数退避轮询
核心流程四步走：
1. 获取 API key（Modellix Console 生成，保存为 MODELLIX_API_KEY）
2. 选型：查阅 references/REFERENCE.md 确认模型参数
3. 执行：使用封装脚本或手动 CLI/REST 流程
4. 消费：从 result.resources 获取媒体 URL，24 小时内持久化
支持模型厂商：Qwen、Wan、Seedream、Seedance、Kling、Hailuo、MiniMax 等
显著优点
- 统一接口：单一 API 集成多家顶级生成模型，降低多供应商接入成本
- 异步设计：任务提交后立即释放，适合长时生成场景
- CLI 优先：本地工具链支持，便于开发调试和自动化流水线
- 完善的降级机制：CLI 不可用时自动回退 REST，保障可靠性
- 丰富的预检脚本：内置可用性验证和智能模式推荐
- 标准化输出：统一 JSON 结果格式，简化下游处理
潜在缺点与局限性
- 结果有效期短：生成资源 URL 仅保留约 24 小时，需及时持久化
- 异步复杂性：必须实现轮询逻辑，增加集成复杂度（相比同步 API）
- CLI 依赖：CLI 优先策略在部分受限环境（如无安装权限的容器）可能失效
- 成本控制：402 错误直接提示余额不足，无自动充值机制
- 错误码处理：400/401/402/404 为不可重试错误，需人工介入
适合人群
- 需要快速集成多厂商 AI 生成能力的开发者
- 构建自动化内容生成流水线的工程团队
- 偏好 CLI 工具链进行本地开发和调试的技术用户
- 对图像/视频生成任务有时效性要求（能接受异步模式）的应用场景
常规风险
- 密钥管理：
MODELLIX_API_KEY为唯一凭证，泄露将导致账户被盗用 - 数据外泄：用户提示词、上传图片、媒体 URL 均发送至
https://api.modellix.ai - 轮询风暴：未正确实现指数退避可能导致 429 后持续高频请求
- 资源丢失：未及时下载生成结果导致 24 小时后不可恢复
- 余额中断：402 错误直接阻断服务，生产环境需监控余额并设置告警