Meshy CLI

Генеруйте, відстежуйте та завантажуйте моделі Meshy прямо з терміналу. Одна команда перетворює prompt або зображення на текстуровану модель, а більшість кінцевих точок API доступні як окремі команди.

Meshy CLI (meshy) викликає той самий REST API, що й решта цієї документації, за тими самими цінами. Ви входите один раз у браузері, тож вам не потрібен API-ключ. У терміналі він виводить зручний для читання вигляд, а у скрипті, конвеєрі, CI або ШІ-агенті — JSON.

Install

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 є відкритим програмним забезпеченням. Його вихідний код знаходиться у репозиторії meshy-cli на GitHub.

Увійти

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

meshy auth login відкриває сторінку входу в Meshy у вашому браузері та зберігає облікові дані на вашому комп'ютері. Якщо браузер не відкривається, скопіюйте URL-адресу, яку виводить CLI.

Віддалені машини, SSH та контейнери

На машині без браузера meshy auth login натомість виводить посилання та короткий код. Відкрийте посилання на будь-якому пристрої, наприклад на вашому ноутбуці чи телефоні, увійдіть у систему та введіть код. CLI самостійно завершить вхід.

CLI обирає цей потік, коли виявляє SSH, контейнер, CI, Linux без дисплея або відсутність інтерактивного терміналу, наприклад коли команду запускає ШІ-агент. Він також обирає цей варіант, коли встановлено MESHY_CLI_NO_BROWSER. Щоб обрати його самостійно, запустіть meshy auth login --device.

meshy auth login --device

API-ключі та CI

Для CI та інших автоматизованих завдань використовуйте API-ключ замість входу через браузер. Встановіть його у змінну середовища MESHY_API_KEY. Вона має пріоритет над збереженим входом.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Ви також можете зберегти ключ за допомогою meshy auth login --with-key msy_YOUR_API_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 запускає попередній перегляд Текст у 3D, а потім refine. Зображення запускає одне текстуроване завдання Зображення у 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/.

Команди

Більшість кінцевих точок API є окремими командами, і кожна команда задачі приймає однакові дієслова: create, get, list, wait, stream та delete. Для кінцевої точки без власної команди використовуйте 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. Параметри та вартість у кредитах для кожної кінцевої точки дивіться на відповідній сторінці цієї документації, наприклад Текст у 3D.

CLI також має локальні допоміжні інструменти для 3D-друку, такі як meshy inspect faces, meshy mesh prepare-print та meshy slicer. Вони виконуються на вашому комп'ютері та не викликають API. Усі команди дивіться в розділі Using meshy-cli.

Скрипти, агенти та CI

JSON-вивід

Коли вивід спрямовується в pipe, файл, скрипт або AI-агент, CLI друкує JSON. У терміналі він друкує зручне для читання подання. Передайте --format json (або --json), щоб завжди отримувати JSON.

Кожна команда друкує рівно один JSON-документ у stdout з тими самими шістьма ключами. 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 для задачі зі статусом FAILED поверне ok: true, тому що сам запит виконався успішно.

CLI надсилає кожен запит на створення один раз і ніколи не повторює його самостійно, тож помилка мережі не може призвести до створення — і оплати — другої задачі.

Коди завершення

Код завершення повідомляє скрипту, що сталося:

Коди 11–14 та повний формат виведення описані в розділі Scripts and agents.

GitHub Actions

Збережіть ваш API-ключ як секрет репозиторію з назвою 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-агенти

Будь-який агент, що може виконувати команди оболонки, може використовувати 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, DPAPI на Windows або Secret Service на Linux. Там, де брелок недоступний, наприклад у контейнері або при з'єднанні через SSH, ключ зберігається у файлі поруч із обліковими даними.

Оновлення та видалення

CLI перевіряє наявність нової версії на npm не частіше одного разу на день і повідомляє про це через stderr. Він ніколи не змінює ваш stdout. Кожен запит до API містить заголовок User-Agent із версією CLI, вашою ОС та ІІ-агентом, що запускає CLI, якщо такий виявлено. Щоб приховати агента, встановіть MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

Щоб переглянути, що змінилося в кожній версії, перегляньте релізи на GitHub.

Усунення несправностей

Спочатку запустіть meshy doctor. Він перевіряє ваше налаштування без звернення до API. Ось поширені проблеми:

Щоб повідомити про помилку, створіть issue в репозиторії meshy-cli.

Наступні кроки

• Перегляньте параметри та вартість кожної кінцевої точки у довіднику API.
• Порівняйте CLI з MCP server в розділі Інтеграція зі ШІ.
• Прочитайте Використання meshy-cli, щоб дізнатися про всі команди та прапорці.