Meshy CLI

在终端中生成、跟踪和下载 Meshy 模型。一条命令即可将 prompt 或图像转换为带纹理的模型，并且大多数 API 端点都有对应的命令。

Meshy CLI（meshy）调用的 API 与本文档其余部分所使用的 REST API 相同，价格也相同。你只需在浏览器中登录一次，因此无需 API key。在终端中它会打印易读的视图，而在脚本、管道、CI 或 AI agent 中，它会打印 JSON。

安装

CLI 需要 Node.js 22.12 或更高版本。它可以在 macOS、Linux 和 Windows 上运行。

npm install -g meshy-cli
meshy doctor    # checks your environment, without calling the API

该软件包会安装两个命令，meshy 和 meshy-cli。同一个构建版本也以 @meshy-ai/cli 的名义发布。请只安装这两个软件包中的一个，因为它们都提供 meshy 命令，npm 会以 EEXIST 拒绝安装第二个。

该 CLI 是开源的。其源代码位于 GitHub 上的 meshy-cli 仓库中。

登录

meshy auth login     # opens your browser
meshy auth status    # shows which account and credential are in use

meshy auth login 会在你的浏览器中打开 Meshy 登录页面，并将凭据存储在你的计算机上。如果浏览器没有自动打开，请复制 CLI 打印出的 URL。

远程机器、SSH 和容器

在没有浏览器的机器上，meshy auth login 会改为打印一个链接和一个短代码。在任意设备（例如你的笔记本电脑或手机）上打开该链接，登录，然后输入代码。CLI 会自动完成登录过程。

CLI 在检测到 SSH、容器、CI、没有显示器的 Linux，或没有交互式终端（例如由 AI 代理运行该命令）时会选择此流程。当设置了 MESHY_CLI_NO_BROWSER 时，它也会选择此流程。若要自行选择该流程，请运行 meshy auth login --device。

meshy auth login --device

API key 与 CI

对于 CI 和其他无人值守的任务，请使用 API key 而不是浏览器登录。将其设置在 MESHY_API_KEY 环境变量中。它的优先顺序高于已存储的登录信息。

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

你也可以使用 meshy auth login --with-key msy_YOUR_API_KEY 存储一个 key。

CLI 会按以下顺序使用它找到的第一个凭证：--api-key、MESHY_API_KEY、--api-key-file，然后是已存储的登录信息。如果 CLI 使用了与你预期不同的账户，请运行 meshy auth status 查看当前生效的凭证。

中国站点

一个 Meshy 账户可在两个站点上使用。如需使用 meshy.cn，请使用 meshy auth login --region cn 登录。CLI 会将区域信息与你的登录信息一起保存，之后的命令会自动调用 api.meshy.cn，无需再加标志。如需切换回全球站点，请使用 --region global 登录。

制作你的第一个模型

meshy make 用一条命令运行整个流程。文本 prompt 会运行一次 Text to 3D 预览，然后进行一次 refine。图片则会运行一次带纹理的 Image to 3D 任务。

首先，在不花费任何积分的情况下，检查某次运行会做什么、将花费多少积分：

meshy make "a lovely baby husky" --dry-run

然后运行它，并使用 -o 将模型保存到某个文件夹：

meshy make "a lovely baby husky" -o out/husky/

✓ [1/2] text-to-3d preview (geometry)                 01a0c94c-…   1m 27s
✓ [2/2] text-to-3d refine (textures)                  01a0c94d-…   5m 36s

✓ SUCCEEDED  text-to-3d-refine
Task     01a0c94d-eaba-710e-b5b7-da5b2f620c95
Created  2026-11-13 10:02
Took     7m 03s
Credits  ~30 (estimate for the whole chain)
Assets   glb, fbx · textures: base_color, metallic, normal, roughness · thumbnail
Saved    out/husky/model.glb
         out/husky/thumbnail.png
         out/husky/meta.json

该文件夹现在包含模型、其 thumbnail，以及一个 meta.json 文件。如果想改为从照片开始，请传入其路径或 URL：meshy make ./cat.png -o out/cat/。

Commands

大多数 API 端点都各自对应一个命令，每个任务命令都支持相同的动词：create、get、list、wait、stream 和 delete。对于没有专属命令的 endpoint，可以使用 meshy api。

以下命令涵盖了常见任务：

meshy text-to-3d create --mode preview --prompt "a red sports car"
meshy image-to-3d create --image-url ./cat.png --async    # returns the task ID at once
meshy image-to-3d wait <task-id> -o out/cat/
meshy text-to-3d list
meshy download --resource text-to-3d --task-id <task-id> --list
meshy balance

要查看某个命令的参数标志，请运行 meshy <resource> --help。关于每个 endpoint 的参数和积分消耗，请参阅本文档中对应的页面，例如 Text to 3D。

CLI 还提供了一些用于 3D 打印的本地辅助工具，例如 meshy inspect faces、meshy mesh prepare-print 和 meshy slicer。它们在你的本地计算机上运行，不会调用 API。完整命令列表请参见 Using meshy-cli。

脚本、agent 与 CI

JSON 输出

当输出被定向到管道、文件、脚本或 AI agent 时，CLI 会打印 JSON。在终端中，它会打印一个易读的视图。传入 --format json（或 --json）可以始终获取 JSON。

每个命令都会在 stdout 上恰好打印一份 JSON 文档，包含相同的六个键。progress 和消息会输出到 stderr。

meshy text-to-3d create --mode preview --prompt "a cactus" --async --format json \
  | jq -r .result.submission.task_id

{
  "schema_version": "meshy.cli/v1",
  "command": "image-to-3d.get",
  "ok": true,
  "result": { "task": { "task_id": "…", "status": "IN_PROGRESS", "progress": 52 } },
  "error": null,
  "warnings": []
}

ok 表示该 CLI 命令是否执行成功。任务自身的状态在 result.task.status 中。例如，对一个失败的任务执行 get 会返回 ok: true，因为请求本身是成功的。

CLI 只会发送一次创建请求，并且不会自行重试，因此网络错误不会导致创建并产生第二个任务的费用。

退出代码

退出代码用于告知脚本发生了什么情况：

有关代码 11 到 14 以及完整的输出格式，请参阅 脚本与代理。

GitHub Actions

将你的 API key 存储为名为 MESHY_API_KEY 的仓库密钥，然后在任务中运行 CLI：

name: Generate a model
on: workflow_dispatch

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g meshy-cli
      - run: meshy make "a low-poly treasure chest" -o assets/chest/ --format json
        env:
          MESHY_API_KEY: ${{ secrets.MESHY_API_KEY }}
      - uses: actions/upload-artifact@v4
        with:
          name: chest
          path: assets/chest/

当 CLI 以非零代码退出时，该步骤将失败。

AI 代理

任何可以运行 shell 命令的代理都可以使用该 CLI，包括 Claude Code、Cursor 和 Codex。代理会自动获取 JSON。

要让你的代理学会 Meshy 的工作流程，请安装开源的 meshy-3d-agent 技能包。它运行在 CLI 之上。

npx skills add meshy-dev/meshy-3d-agent

参考

全局标志

这些标志适用于每个命令：

环境变量

CLI 会读取以下变量：

凭据存储位置

CLI 将凭据存储在 ~/.config/meshy/credentials.v2.json 中，仅你本人可读。其中的凭据使用操作系统密钥链（keychain）中保存的密钥加密：macOS 上为 Keychain，Windows 上为 DPAPI，Linux 上为 Secret Service。如果没有可用的密钥链（例如在容器中或通过 SSH 连接时），则密钥会作为一个文件存放在凭据文件旁边。

更新与卸载

CLI 每天最多向 npm 检查一次新版本，并通过 stderr 提示你。它绝不会改变你的 stdout。每个 API 请求都会携带一个 User-Agent 请求头，其中包含 CLI 版本、你的操作系统，以及运行该 CLI 的 AI 代理（如果检测到的话）。若要不包含代理信息，请设置 MESHY_CLI_AGENT=none。

npm install -g meshy-cli@latest

meshy auth logout --all       # deletes the stored credentials
npm uninstall -g meshy-cli

要查看每个版本的变更内容，请参阅 GitHub 上的发布记录。

Troubleshooting

请先运行 meshy doctor。它会在不调用 API 的情况下检查你的配置。以下是常见问题：

如需报告 Bug，请在 meshy-cli repository 中提交 issue。

Next steps

• 在 API reference 中查看每个 endpoint 的参数和费用。
• 在 AI integration 中比较 CLI 与 MCP server。
• 阅读 Using meshy-cli 以了解每个命令和参数。