Meshy CLI

Tạo, theo dõi và tải xuống các model Meshy ngay từ terminal của bạn. Một lệnh duy nhất biến một prompt hoặc một hình ảnh thành model đã được áp texture, và hầu hết các endpoint API đều là những lệnh riêng của chúng.

Meshy CLI (meshy) gọi cùng một REST API như phần còn lại của tài liệu này, với cùng mức giá. Bạn chỉ cần đăng nhập một lần trên trình duyệt, nên bạn không cần khóa API. Trong terminal, nó hiển thị một giao diện dễ đọc, còn trong script, pipe, CI hoặc agent AI, nó in ra JSON.

Install

CLI yêu cầu Node.js 22.12 trở lên. Nó chạy trên macOS, Linux và Windows.

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

Gói này cài đặt hai lệnh, meshy và meshy-cli. Cùng một bản build cũng được phát hành dưới dạng @meshy-ai/cli. Chỉ cài đặt một trong hai gói, vì cả hai đều cung cấp lệnh meshy và npm sẽ từ chối gói thứ hai với lỗi EEXIST.

CLI là mã nguồn mở. Mã nguồn của nó nằm trong kho lưu trữ meshy-cli trên GitHub.

Đăng nhập

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

meshy auth login mở một trang đăng nhập Meshy trong trình duyệt của bạn và lưu thông tin xác thực trên máy tính của bạn. Nếu trình duyệt không mở, hãy sao chép URL mà CLI in ra.

Máy từ xa, SSH và container

Trên một máy không có trình duyệt, meshy auth login sẽ in ra một liên kết và một mã ngắn thay vào đó. Mở liên kết trên bất kỳ thiết bị nào, chẳng hạn như laptop hoặc điện thoại của bạn, đăng nhập và nhập mã. CLI sẽ tự hoàn tất quá trình đăng nhập.

CLI chọn luồng này khi nó phát hiện SSH, một container, CI, Linux không có màn hình hiển thị, hoặc không có terminal tương tác, chẳng hạn như khi một tác tử AI chạy lệnh này. Nó cũng chọn luồng này khi MESHY_CLI_NO_BROWSER được thiết lập. Để tự chọn luồng này, hãy chạy meshy auth login --device.

meshy auth login --device

Khóa API và CI

Đối với CI và các tác vụ không giám sát khác, hãy sử dụng khóa API thay vì đăng nhập bằng trình duyệt. Đặt nó trong biến môi trường MESHY_API_KEY. Nó có độ ưu tiên cao hơn thông tin đăng nhập đã lưu.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Bạn cũng có thể lưu một khóa bằng meshy auth login --with-key msy_YOUR_API_KEY.

CLI sử dụng thông tin xác thực đầu tiên mà nó tìm thấy, theo thứ tự sau: --api-key, MESHY_API_KEY, --api-key-file, sau đó là thông tin đăng nhập đã lưu. Nếu CLI sử dụng một tài khoản khác với bạn mong đợi, hãy chạy meshy auth status để xem thông tin xác thực nào đang có hiệu lực.

Trang web Trung Quốc

Một tài khoản Meshy hoạt động trên cả hai trang web. Để sử dụng meshy.cn, hãy đăng nhập bằng meshy auth login --region cn. CLI sẽ lưu khu vực cùng với thông tin đăng nhập của bạn, nên các lệnh sau đó sẽ gọi api.meshy.cn mà không cần thêm cờ (flag). Để chuyển về lại, hãy đăng nhập bằng --region global.

Tạo mô hình đầu tiên của bạn

meshy make chạy toàn bộ quy trình chỉ trong một lệnh. Một prompt văn bản sẽ chạy một preview Văn bản sang 3D và sau đó là một refine. Một hình ảnh sẽ chạy một tác vụ Ảnh sang 3D có texture.

Trước tiên, hãy kiểm tra xem một lần chạy sẽ làm gì và sẽ tốn bao nhiêu tín dụng, mà không tiêu tốn bất kỳ tín dụng nào:

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

Sau đó chạy nó, và lưu mô hình vào một thư mục bằng -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

Thư mục giờ đây chứa mô hình, ảnh thu nhỏ của nó, và một tệp meta.json. Để bắt đầu từ một bức ảnh thay vì vậy, hãy truyền vào đường dẫn hoặc URL của nó: meshy make ./cat.png -o out/cat/.

Commands

Hầu hết các endpoint API đều là các lệnh riêng của chúng, và mỗi lệnh tác vụ đều dùng chung các động từ: create, get, list, wait, stream, và delete. Đối với endpoint không có lệnh riêng, hãy dùng meshy api.

Các lệnh sau đây bao phủ những tác vụ phổ biến:

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

Để xem các cờ (flags) của một lệnh, hãy chạy meshy <resource> --help. Để biết tham số và chi phí credit của từng endpoint, hãy xem trang tương ứng trong tài liệu này, chẳng hạn Văn bản sang 3D.

CLI cũng có các công cụ hỗ trợ cục bộ cho in 3D, chẳng hạn meshy inspect faces, meshy mesh prepare-print và meshy slicer. Chúng chạy trên máy tính của bạn và không gọi API. Xem Using meshy-cli để biết đầy đủ các lệnh.

Scripts, agents, and CI

Đầu ra JSON

Khi đầu ra của nó đi đến một pipe, một file, một script hoặc một AI agent, CLI sẽ in ra JSON. Trong terminal, nó in ra một chế độ xem dễ đọc. Truyền --format json (hoặc --json) để luôn nhận được JSON.

Mỗi lệnh in ra chính xác một tài liệu JSON trên stdout, với cùng sáu khóa. Progress và các thông báo được gửi đến 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 cho biết liệu lệnh CLI có hoạt động hay không. Trạng thái riêng của task nằm trong result.task.status. Ví dụ, get trên một task bị lỗi trả về ok: true, vì bản thân yêu cầu đó đã hoạt động thành công.

CLI gửi mỗi yêu cầu tạo một lần duy nhất và không bao giờ tự động thử lại, vì vậy một lỗi mạng không thể tạo ra, và tính phí cho, một task thứ hai.

Mã thoát (Exit codes)

Mã thoát cho script biết điều gì đã xảy ra:

Đối với các mã từ 11 đến 14 và định dạng đầu ra đầy đủ, xem Scripts and agents.

GitHub Actions

Lưu khóa API của bạn dưới dạng một repository secret có tên MESHY_API_KEY, sau đó chạy CLI trong một job:

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/

Bước này sẽ thất bại khi CLI thoát ra với một mã khác 0.

AI agents

Bất kỳ agent nào có thể chạy lệnh shell đều có thể sử dụng CLI, bao gồm Claude Code, Cursor và Codex. Agent sẽ nhận được JSON một cách tự động.

Để dạy cho agent của bạn các quy trình làm việc của Meshy, hãy cài đặt gói kỹ năng mã nguồn mở meshy-3d-agent. Nó chạy trên CLI.

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

Tài liệu tham khảo

Cờ toàn cục

Các cờ này hoạt động trên mọi lệnh:

Biến môi trường

CLI đọc các biến sau:

Nơi lưu trữ thông tin xác thực

CLI lưu trữ thông tin xác thực trong ~/.config/meshy/credentials.v2.json, chỉ có bạn mới đọc được. Thông tin xác thực trong đó được mã hóa bằng một khóa được lưu trong móc khóa của hệ điều hành: Keychain trên macOS, DPAPI trên Windows, hoặc Secret Service trên Linux. Khi không có móc khóa nào khả dụng, chẳng hạn như trong một container hoặc qua SSH, khóa này là một tệp nằm cạnh thông tin xác thực.

Cập nhật và gỡ cài đặt

CLI kiểm tra npm để tìm phiên bản mới tối đa một lần mỗi ngày và thông báo cho bạn qua stderr. Nó không bao giờ thay đổi stdout của bạn. Mỗi yêu cầu API mang theo một header User-Agent chứa phiên bản CLI, hệ điều hành của bạn, và AI agent đang chạy CLI, nếu nó phát hiện ra một agent như vậy. Để loại bỏ agent, hãy đặt MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

Để xem những gì đã thay đổi trong mỗi phiên bản, hãy xem releases trên GitHub.

Khắc phục sự cố

Hãy chạy meshy doctor trước tiên. Lệnh này kiểm tra thiết lập của bạn mà không gọi API. Đây là các vấn đề thường gặp:

Để báo cáo lỗi, hãy mở một issue trong kho lưu trữ meshy-cli.

Các bước tiếp theo

• Xem các tham số và chi phí của từng endpoint trong tài liệu tham khảo API.
• So sánh CLI với MCP server trong Tích hợp AI.
• Đọc Sử dụng meshy-cli để biết mọi lệnh và cờ (flag).