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 для неудавшейся задачи возвращает 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 выходит с ненулевым кодом.

ИИ-агенты

Любой агент, который может выполнять команды 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, 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

Чтобы узнать, что изменилось в каждой версии, см. releases на GitHub.

Устранение неполадок

Сначала выполните meshy doctor. Эта команда проверяет вашу настройку без обращения к API. Вот распространённые проблемы:

Чтобы отправить отчёт об ошибке, создайте issue в репозитории meshy-cli.

Дальнейшие шаги

• Параметры и стоимость каждого эндпоинта см. в справочнике API.
• Сравните CLI с MCP server в разделе Интеграция с ИИ.
• Прочитайте Использование meshy-cli, чтобы узнать обо всех командах и флагах.