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

這個資料夾現在包含模型、其縮圖，以及一個 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 以了解每個命令和參數。