官方 CLI · npm 上的 modellix-cli

Modellix CLI

从终端到 Agent，运行全部 Modellix 模型

Modellix 官方命令行客户端，可完成鉴权、发现 100+ 图像和视频模型、运行异步任务，并将机器可读的 --json 输出接入脚本、CI、Cursor、Claude Code 和 Codex。

npm install --global modellix-cli

需要 Node.js 18.17 或更高版本。安装后运行 modellix-cli --version 验证。

从 npm 安装阅读 CLI 指南查看 GitHub

快速开始

三条命令即可开始

Modellix CLI 遵循与 API 相同的异步流程：提交任务，取得 task_id，再轮询或等待任务完成。

  1. 01 · 安装

    全局安装

    一次安装，即可在任意终端使用。需要 Node.js 18.17 或更高版本。

    npm install --global modellix-cli
  2. 02 · 鉴权

    保存 API Key

    交互式登录会先验证密钥，再保存到本地配置。请先前往 Modellix Console 获取密钥。

    Console → API Key
    modellix-cli init
  3. 03 · 查找

    查找可用模型

    浏览可用的图像和视频模型，再使用 model run 提交任务。需要在一条命令中等待最终结果时，可加上 --wait。

    modellix-cli model list

核心能力

为开发者、脚本与 Agent 而设计

提供稳定的自动化参数、本地任务历史，以及不会打印 API Key 的诊断信息。

  • 发现全部模型

    使用 model list 搜索和筛选模型目录，再用 model describe 查看输入参数；加上 --json，即可让 Agent 稳定读取结果。

  • 统一的运行流程

    使用 model run（别名 model invoke）通过 --body 或 --body-file 提交任务，再用 task get 或 task wait 查询并等待结果。

  • 批量提交与下载

    通过 JSONL 批量提交任务并控制并发，再使用 task download 将结果保存到本地；机器可读输出不会暴露临时签名下载地址。

  • 面向 Agent 的稳定输出

    --json 与 --quiet 提供稳定的 stdout，明确的退出码便于 CI 判断结果，告警与恢复提示则保留在 stderr。

  • 自动化前先运行 doctor

    modellix-cli doctor 会检查 Node.js 版本、API Key 来源但不显示密钥，并检查网络连通性与团队余额。

  • 团队多 Profile

    可保存多套鉴权配置，并通过 --profile 或 MODELLIX_PROFILE 切换，避免密钥进入 shell 历史。

终端工作流

一段真实的 CLI 会话

从浏览模型目录、提交任务到获取机器可读结果，这就是开发者的日常工作流程。

~/projects/marketing · modellix-cli
# 1. 浏览模型目录$ modellix-cli model list --type text-to-image --output slugs# 2. 提交任务$ modellix-cli model run \
  --model-slug bytedance/seedream-5.0-pro \
  --body '{"prompt":"一只在阳光花园里玩耍的可爱猫咪"}'# 3. 获取任务结果（也可在 model run 时加上 --wait）$ modellix-cli task get task-abc123 --json# 示例输出 → { "code": 0, "data": { "status": "success", "task_id": "task-abc123", ... } }

Agent 接入

接入你的编程 Agent

无需额外守护进程。任何能执行 shell 命令的 Agent 都可以直接调用 modellix-cli。建议先执行 model run，再执行 task get；当结果由程序读取时，请始终加上 --json。

适用于 Cursor、Claude Code、Codex，以及任何能够调用终端工具的 Agent。

自动化前先检查运行环境
modellix-cli doctor --json

帮助

常见问题

关于安装、鉴权、自动化与计费的常见问题。

什么是 Modellix CLI？

Modellix CLI（npm 包名为 modellix-cli）是 Modellix 官方命令行客户端。它用于管理鉴权、发现并运行 AI 图像和视频模型、等待异步任务、下载结果，并为脚本与编程 Agent 提供稳定的 JSON 输出。

如何安装 Modellix CLI？

Modellix CLI 需要 Node.js 18.17 或更高版本。运行 npm install --global modellix-cli 完成全局安装，再用 modellix-cli --version 验证。直接运行不带参数的 modellix-cli 只会显示本地快速入门，不会发起 API 请求。

如何完成 modellix-cli 鉴权？

先在 Modellix Console 获取 API Key，再运行 modellix-cli init 或 modellix-cli auth login。在 CI 中可以设置 MODELLIX_API_KEY，或配合 --yes 传入 --api-key。建议优先使用环境变量或隐藏输入，避免密钥留在 shell 历史中。

如何使用 Modellix CLI 生成图片？

先运行 modellix-cli model list 查找模型，再使用 modellix-cli model run 传入 provider/model 标识和提示词。使用 modellix-cli task get 获取结果，也可以在 model run 时加上 --wait。

编程 Agent 能使用 Modellix CLI 吗？

可以。--json 与 --quiet 能为 Cursor、Claude Code、Codex 等可执行终端命令的 Agent 提供稳定的 stdout。业务结果输出到 stdout，诊断与恢复提示输出到 stderr。

Modellix CLI 会替代 REST API 吗？

不会。CLI 封装的是同一套 Modellix REST API，主要面向终端与自动化场景。需要自定义 HTTP 客户端时使用 REST；需要鉴权管理、模型发现、任务等待与下载或 Agent 友好输出时使用 CLI。

CLI 任务如何计费，失败后可以直接重试吗？

CLI 任务与 REST API 任务采用相同的模型定价。任务成功提交后可能产生费用，因此遇到超时或网络错误时不要盲目重试；如果已经取得任务 ID，请先查询任务状态，再决定是否重新提交。

Modellix CLI

安装 CLI，即刻开始构建

从 npm 安装并完成一次鉴权，即可在终端运行 Modellix 模型，也可以将同样的命令交给你的 Agent。

从 npm 安装获取 API Key查看完整 CLI 文档