核心用法
Modellix 提供 Model-as-a-Service 平台能力，通过统一 API 封装多家顶尖 AI 图像与视频生成模型（如 ByteDance Seedream/Seedance、Kling、Hailuo、MiniMax、Wan 等）。核心交互模式为异步任务流：提交任务获取 task_id → 轮询状态直至 success 或 failed。
执行策略（CLI 优先）：
1. 首选 modellix-cli 命令行工具执行 model invoke 与 task get
2. CLI 不可用时自动降级至 REST API
3. 支持 scripts/invoke_and_poll.py 自动轮询与指数退避重试
API 密钥生命周期：遵循「发现 → 请求 → 会话使用 →（可选）持久化」策略。默认仅会话级使用，持久化需用户明确授权且仅限用户级环境变量。
默认模型映射：
| 任务类型 | 默认模型 |
|---------|---------|
| 文生图 (T2I) | `bytedance/seedream-5.0-lite` |
| 图生图/编辑 | `bytedance/seedream-5.0-lite-edit` |
| 文生视频/图生视频 | `bytedance/seedance-2.0-fast-i2v` |
| 视频生视频 | `bytedance/seedance-2.0-v2v` |
显著优点
- 统一接口：单 API Key 对接十余家主流模型提供商，无需分别对接 Kling、Wan、MiniMax 等独立接口
- CLI 优先设计：本地命令行工具提供比 REST 更高效的开发与调试体验
- 完善的模型路由：内置默认模型映射与能力矩阵，降低选型成本
- 标准化输出：统一任务状态模型与资源 URL 格式，24 小时有效期便于资产托管
- 企业级错误处理：明确的重试策略（429/500/503 指数退避，401/402/404 立即失败）
潜在缺点与局限性
- 异步必须轮询：无 Webhook 回调机制，需客户端实现 polling 逻辑（虽提供辅助脚本）
- 资源时效限制：生成资源 24 小时后失效，需及时下载持久化
- CLI 依赖 Node.js：非 Node 环境需降级至 REST，失去部分便利性
- 商业成本敏感：402 错误直接终止，需预充值余额管理
- 模型参数差异：统一 API 下层各模型参数不尽相同，仍需查阅具体模型文档
适合人群
- 需快速集成多厂商 AI 视觉能力的应用开发者
- 偏好命令行工作流的技术团队
- 构建文生图/视频产品的 SaaS 或内容平台团队
- 希望避免直接与各模型商单独签约的中小创业团队
常规风险
- 密钥泄露风险：
MODELLIX_API_KEY控制账户余额与模型访问权限，需严格遵循「不日志输出、不截图、不提交至版本控制」的秘钥卫生规范 - 余额耗尽导致服务中断：402 错误不触发重试，生产环境需监控余额与告警
- 资源下载遗漏：24 小时失效窗口若未及时消费，可能导致生成内容永久丢失
- 模型厂商政策变动：底层模型（如 Kling、Wan）的合规与可用性受原厂商约束，Modellix 仅做路由封装
- 数据出境合规：用户 prompt 与输入图片需传输至
https://api.modellix.ai，涉及跨境数据流动合规评估