Meshy CLI

Hasilkan, jejaki, dan muat turun model Meshy dari terminal anda. Satu arahan menukar prompt atau imej menjadi model bertekstur, dan kebanyakan endpoint API adalah arahan tersendiri.

Meshy CLI (meshy) memanggil REST API yang sama seperti selebihnya dokumentasi ini, pada harga yang sama. Anda log masuk sekali dalam pelayar anda, jadi anda tidak memerlukan kunci API. Dalam terminal ia memaparkan paparan yang mudah dibaca, dan dalam skrip, paip, CI, atau ejen AI ia memaparkan JSON.

Pasang

CLI memerlukan Node.js 22.12 atau lebih baharu. Ia berjalan pada macOS, Linux, dan Windows.

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

Pakej ini memasang dua arahan, meshy dan meshy-cli. Binaan yang sama turut diterbitkan sebagai @meshy-ai/cli. Pasang hanya salah satu daripada kedua-dua pakej ini, kerana kedua-duanya menyediakan arahan meshy dan npm akan menolak yang kedua dengan ralat EEXIST.

CLI ini adalah sumber terbuka. Kod sumbernya terdapat dalam repositori meshy-cli di GitHub.

Log Masuk

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

meshy auth login membuka halaman log masuk Meshy dalam pelayar anda dan menyimpan kelayakan pada komputer anda. Jika pelayar tidak terbuka, salin URL yang dipaparkan oleh CLI.

Mesin Jauh, SSH dan Kontena

Pada mesin tanpa pelayar, meshy auth login memaparkan pautan dan kod pendek sebagai gantinya. Buka pautan tersebut pada mana-mana peranti, seperti komputer riba atau telefon anda, log masuk, dan masukkan kod tersebut. CLI akan menyelesaikan proses log masuk dengan sendirinya.

CLI memilih aliran ini apabila ia mengesan SSH, kontena, CI, Linux tanpa paparan, atau tiada terminal interaktif, seperti apabila ejen AI menjalankan arahan tersebut. Ia juga memilih aliran ini apabila MESHY_CLI_NO_BROWSER ditetapkan. Untuk memilihnya sendiri, jalankan meshy auth login --device.

meshy auth login --device

Kunci API dan CI

Untuk CI dan tugas-tugas automatik lain, gunakan kunci API sebagai ganti log masuk pelayar. Tetapkannya dalam pembolehubah persekitaran MESHY_API_KEY. Ia mempunyai keutamaan berbanding log masuk yang disimpan.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Anda juga boleh menyimpan kunci dengan meshy auth login --with-key msy_YOUR_API_KEY.

CLI menggunakan kelayakan pertama yang dijumpainya, mengikut turutan ini: --api-key, MESHY_API_KEY, --api-key-file, kemudian log masuk yang disimpan. Jika CLI menggunakan akaun yang berbeza daripada yang anda jangkakan, jalankan meshy auth status untuk melihat kelayakan yang sedang digunakan.

Laman China

Satu akaun Meshy berfungsi di kedua-dua laman. Untuk menggunakan meshy.cn, log masuk dengan meshy auth login --region cn. CLI menyimpan rantau bersama log masuk anda, jadi arahan seterusnya memanggil api.meshy.cn tanpa flag. Untuk kembali bertukar, log masuk dengan --region global.

Buat model pertama anda

meshy make menjalankan keseluruhan aliran dalam satu arahan. Prompt teks menjalankan pratonton Teks ke 3D dan kemudian satu refine. Imej menjalankan satu tugas Imej ke 3D bertekstur.

Mula-mula, semak apa yang akan dilakukan oleh sesuatu larian dan berapa banyak kredit yang akan dibelanjakan, tanpa membelanjakan sebarang kredit:

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

Kemudian jalankannya, dan simpan model ke dalam folder dengan -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

Folder itu kini menyimpan model, imej kecilnya, dan fail meta.json. Untuk mula daripada foto sebaliknya, berikan laluan atau URL fotonya: meshy make ./cat.png -o out/cat/.

Perintah

Kebanyakan endpoint API adalah perintah tersendiri, dan setiap perintah tugas menggunakan kata kerja yang sama: create, get, list, wait, stream, dan delete. Untuk endpoint yang tiada perintah sendiri, gunakan meshy api.

Perintah-perintah ini merangkumi tugas-tugas umum:

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

Untuk flag sesuatu perintah, jalankan meshy <resource> --help. Untuk parameter dan kos kredit setiap endpoint, lihat halamannya dalam dokumentasi ini, seperti Teks ke 3D.

CLI ini juga mempunyai pembantu tempatan untuk pencetakan 3D, seperti meshy inspect faces, meshy mesh prepare-print dan meshy slicer. Ia berjalan di komputer anda dan tidak memanggil API. Lihat Using meshy-cli untuk setiap perintah.

Scripts, agents, and CI

Output JSON

Apabila outputnya dihantar ke paip, fail, skrip atau ejen AI, CLI mencetak JSON. Dalam terminal ia mencetak paparan yang mudah dibaca. Hantar --format json (atau --json) untuk sentiasa mendapatkan JSON.

Setiap arahan mencetak tepat satu dokumen JSON pada stdout, dengan enam kunci yang sama. Progress dan mesej dihantar ke 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 menyatakan sama ada arahan CLI berjaya. Keadaan task itu sendiri terdapat dalam result.task.status. Sebagai contoh, get pada task yang gagal mengembalikan ok: true, kerana permintaan itu sendiri berjaya.

CLI menghantar setiap permintaan create sekali sahaja dan tidak sekali-kali mencubanya semula dengan sendirinya, jadi ralat rangkaian tidak boleh mencipta, dan mengenakan caj untuk, task kedua.

Kod keluar (exit codes)

Kod keluar memberitahu skrip apa yang telah berlaku:

Untuk kod 11 hingga 14 dan format output penuh, lihat Scripts and agents.

GitHub Actions

Simpan kunci API anda sebagai rahsia repositori bernama MESHY_API_KEY, kemudian jalankan CLI dalam satu kerja (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/

Langkah ini akan gagal apabila CLI keluar dengan kod bukan sifar.

Ejen AI

Mana-mana ejen yang boleh menjalankan arahan shell boleh menggunakan CLI, termasuk Claude Code, Cursor, dan Codex. Ejen tersebut mendapat JSON secara automatik.

Untuk mengajar ejen anda aliran kerja Meshy, pasang pek kemahiran sumber terbuka meshy-3d-agent. Ia berjalan pada CLI.

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

Rujukan

Flag global

Flag ini berfungsi pada setiap arahan:

Pemboleh ubah persekitaran

CLI membaca pemboleh ubah berikut:

Lokasi penyimpanan kelayakan

CLI menyimpan kelayakan dalam ~/.config/meshy/credentials.v2.json, yang hanya boleh dibaca oleh anda. Kelayakan di dalamnya disulitkan dengan kunci yang disimpan dalam rantai kunci OS: Keychain pada macOS, DPAPI pada Windows, atau Secret Service pada Linux. Apabila tiada rantai kunci tersedia, seperti dalam bekas (container) atau melalui SSH, kunci tersebut adalah fail yang terletak di sebelah kelayakan.

Kemas kini dan nyahpasang

CLI menyemak npm untuk versi baharu paling banyak sekali sehari dan memaklumkan anda melalui stderr. Ia tidak sekali-kali mengubah stdout anda. Setiap permintaan API membawa header User-Agent dengan versi CLI, OS anda, dan ejen AI yang menjalankan CLI, jika ia mengesan satu. Untuk mengecualikan ejen tersebut, tetapkan MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

Untuk melihat apa yang berubah dalam setiap versi, lihat keluaran di GitHub.

Penyelesaian masalah

Jalankan meshy doctor terlebih dahulu. Ia menyemak persediaan anda tanpa memanggil API. Berikut adalah masalah yang biasa berlaku:

Untuk melaporkan pepijat, buka isu di repositori meshy-cli.

Langkah seterusnya

• Lihat parameter dan kos setiap endpoint dalam rujukan API.
• Bandingkan CLI dengan MCP server dalam Integrasi AI.
• Baca Menggunakan meshy-cli untuk setiap arahan dan flag.