Meshy CLI

ターミナルから Meshy のモデルを生成、追跡、ダウンロードできます。1つのコマンドで prompt や画像をテクスチャ付きモデルに変換でき、ほとんどの API エンドポイントはそれぞれ独自のコマンドになっています。

Meshy CLI（meshy）は、このドキュメントの他の部分と同じ REST API を同じ価格で呼び出します。ブラウザで一度サインインするだけなので、APIキーは不要です。ターミナルでは読みやすい表示を出力し、スクリプトやパイプ、CI、AIエージェントの中では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 の2つのコマンドをインストールします。同じビルドは @meshy-ai/cli としても公開されています。両方とも meshy コマンドを提供するため、npm は2つ目を 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キーと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 を実行してどの認証情報が有効になっているか確認してください。

China site（中国サイト）

1つのMeshyアカウントは両方のサイトで利用できます。meshy.cn を使用するには、meshy auth login --region cn でサインインしてください。CLIはサインイン時にリージョンを保存するため、以降のコマンドはフラグなしで api.meshy.cn を呼び出します。元に戻すには --region global でサインインしてください。

Make your first model

meshy make は一連の流れを1つのコマンドで実行します。テキストのpromptを指定するとテキストから3Dのpreviewが実行され、その後refineが行われます。画像を指定すると、テクスチャ付きの画像から3Dタスクが1回実行されます。

まず、クレジットを消費せずに、実行内容と消費クレジット数を確認します。

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 を受け取ります。専用コマンドを持たないエンドポイントには 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 を実行してください。各エンドポイントのパラメータと積分コストについては、Text to 3D のように、本ドキュメント内の該当ページを参照してください。

このCLIには、meshy inspect faces、meshy mesh prepare-print、meshy slicer など、3Dプリント向けのローカルヘルパーも用意されています。これらはお使いのコンピュータ上で実行され、APIを呼び出すことはありません。すべてのコマンドについては Using meshy-cli を参照してください。

スクリプト、エージェント、CI

JSON出力

出力先がパイプ、ファイル、スクリプト、またはAIエージェントの場合、CLIはJSONを出力します。ターミナルでは読みやすい表示形式で出力します。常にJSONを取得するには --format json（または --json）を渡してください。

すべてのコマンドは、同じ6つのキーを持つJSONドキュメントを標準出力にちょうど1つ出力します。進行状況とメッセージは標準エラー出力に送られます。

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は各作成リクエストを一度だけ送信し、自動的に再試行することはありません。そのため、ネットワークエラーによって2つ目のタスクが作成され、二重に課金されることはありません。

終了コード

終了コードは、何が起きたかをスクリプトに伝えます：

コード 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エージェント

シェルコマンドを実行できるエージェントであれば、Claude Code、Cursor、Codexを含め、どれでもCLIを使用できます。エージェントは自動的にJSONを取得します。

エージェントにMeshyのワークフローを教えるには、オープンソースのmeshy-3d-agentスキルパックをインストールしてください。これはCLI上で動作します。

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

リファレンス

グローバルフラグ

これらのフラグはすべてのコマンドで使用できます。

環境変数

CLIは以下の変数を読み取ります：

認証情報の保存場所

CLIは認証情報を~/.config/meshy/credentials.v2.jsonに保存し、これはあなたのみが読み取り可能です。その中の認証情報は、OSのキーホルダーに保管された鍵で暗号化されます。macOSではキーホルダー、Windowsでは DPAPI、Linuxでは Secret Service です。コンテナ内やSSH経由など、キーホルダーが利用できない場合は、鍵は認証情報の隣にあるファイルになります。

アップデートとアンインストール

CLIは1日に1回を上限としてnpmで新しいバージョンがないか確認し、stderrにその旨を表示します。stdoutが変更されることは一切ありません。各APIリクエストには、CLIのバージョン、あなたのOS、検出された場合はCLIを実行しているAIエージェントを含むUser-Agentヘッダーが付与されます。エージェント情報を除外するには、MESHY_CLI_AGENT=noneを設定してください。

npm install -g meshy-cli@latest

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

各バージョンでの変更点については、GitHubのreleasesをご覧ください。

トラブルシューティング

まず meshy doctor を実行してください。これはAPIを呼び出さずにセットアップを確認します。よくある問題は次のとおりです。

バグをレポートするには、meshy-cliリポジトリでissueを作成してください。

次のステップ

• 各エンドポイントのパラメータと費用については、APIリファレンスを参照してください。
• CLIとMCPサーバーの比較については、AI連携を参照してください。
• すべてのコマンドとフラグについては、Using meshy-cliをお読みください。