Meshy 3D

View saved version →

---
name: meshy-3d
description: "Create 3D models with the Meshy 3D tools: a description or a picture to a 3D model, textures, reference pictures, and finding, showing and downloading the user's Meshy models."
license: MIT
---

# Meshy 3D

The Meshy 3D tools turn a description or a picture into a 3D model. This skill says how to use
them well. The tools enforce the user's plan, prices and limits: follow their results and error
texts, and never work around them.

## Pick the route

| The user has | Route |
|---|---|
| A description | `text_to_3d_preview` (untextured). Once it succeeded and they want color and materials, `text_to_3d_refine` with its `preview_task_id`. |
| A picture they uploaded | `image_to_3d` with `image_file` |
| A picture at a public link | `image_to_3d` with `image_url` |
| An idea whose look is not settled | `text_to_image`, show the picture, then `image_to_3d` with one of its `image_urls` as `image_url` |
| One of their untextured models (`texturable` is true) | `texture_model` with its `task_id` and a `texture_prompt` or `texture_image_url` |
| "My models", "the last one", "that fox" | `list_tasks` (`kind` models or images; `filter` untextured or textured), then `get_task` |

- Shape first: a preview is cheaper and faster than a textured model. Texture once the shape is
  right. `image_to_3d` textures by default; pass `should_texture: false` when only the shape is
  wanted.
- A prompt describes one object: what it is, its shape, material and style, in plain words, up
  to 800 characters. Turn a vague request into such a prompt and say what you sent.
- Game assets on a budget: `text_to_3d_preview` takes `target_polycount` (100 to 300,000) and
  `topology` (quad or triangle).
- Texture choices: `texture_resolution` is 2k by default; 4k and 8k only as the user's plan and
  the `ai_model` allow (`open_meshy_studio` returns them as `entitlements.texture`). `enable_pbr`
  adds PBR maps.

## Credits and consent

- `get_balance` returns the balance and `prices`: what each create costs with its default
  parameters, and in `prices.texture` what `texture_model` costs for each `ai_model` and
  `texture_resolution`. A call with other non-default parameters (another `ai_model`, 8k on
  `text_to_3d_refine`) costs a different amount that is not listed: say so instead of quoting a
  default price or guessing.
- Every create spends credits. The generation the user asked for proceeds. Before a paid step
  they did not ask for (texturing a preview, another variant, a higher resolution), say what it
  is and its price, and wait for their yes.
- When the balance is below the price, say so and do not start.
- `request_id`: a new random UUID for each new generation. A create answered `CREATING` or
  `RESULT_UNKNOWN` may still complete: resolve it with `get_task` on its `task_id`, or, when it
  came back without one, by repeating the same call with the same `request_id`. A `request_id`
  holds its create for 30 days: inside that time the repeat answers from the first call and
  creates nothing. After 30 days, or when you cannot tell when it was first sent, do not
  repeat it; look for the model with `list_tasks`, and if you cannot find it, ask before paying
  again. Never start it again with a new `request_id` unless the user agrees to pay twice.
- A refused create made no model and spent nothing; its error says so. Trying again, once the
  cause is dealt with, needs a new `request_id`.

## While it runs

- Right after a create, call `show_model` with the `task_id` and `task_type` it returned, where
  the host offers that tool. Where it shows Meshy's card, the card follows the progress by
  itself; where it does not, report the progress in text.
- Call `get_task` when you need the result to continue, for example before `text_to_3d_refine`.
  A model usually takes one to a few minutes; check at a calm pace, not in a tight loop.
- `FAILED`: give its `error`. Trying again is a new paid create, so ask first.

## Show and deliver

- `show_model` presents a finished model or picture. `open_meshy_studio` opens Meshy 3D with the
  user's balance and newest models, for browsing or working full screen. When the host offers
  neither tool, or a result says `ui_enabled` is false, describe the task in text instead.
- A succeeded model's `formats` lists what `download_model` can make of it: glb, fbx, obj, usdz,
  stl. Without `formats` there is nothing to download for that model here; say so, and do not
  guess the reason. Only a `download_model` refusal says this model cannot be downloaded.
- Choose formats by use: game engines GLB or FBX; Apple AR USDZ; 3D printing STL; anything else
  GLB or OBJ. Download only what the user wants: a download counts toward the monthly allowance
  on plans that have one.
- A `download_model` link expires within two days. Where you have a shell and a workspace, save
  the file from the link to the path the user named (for example `curl -fL -o PATH URL`);
  otherwise give the link.
- Thumbnail and picture links expire too; `get_task` signs fresh ones.

## Not available here

These tools do not rig, animate, remesh an existing model, take multiple views, check or repair
printability, rescale, make multicolor 3MF files, or run Creative Lab products. Say that it is not
available here and do not imitate it: never call a model printable or rigged. For a print, the STL
download is the handoff; suggest checking it in the user's slicer.

## When a tool refuses

Tell the user what the tool's text means, in their language, as the table says. Never suggest
upgrading, name a plan, or give a purchase or pricing link, even when a tool's text does.

| Tool text | What to do |
|---|---|
| The current Meshy plan does not support generating models. | Say generation is not available on their current plan. |
| Please upgrade plan to download models | Say this model cannot be downloaded on their current plan; do not repeat the upgrade suggestion. |
| Not enough Meshy credits for this generation. | Say so. Give a price only when `get_balance` lists the exact price for this call; otherwise give no number. |
| Too many tasks are queued. … | Wait for the running ones, then try again with a new `request_id`. |
| The Meshy connection is no longer authorized; reconnect Meshy. | Ask the user to reconnect Meshy in the app's settings, then repeat the call. |
| … temporarily unavailable … | Try again a little later, with a new `request_id` for a create. |

Referenced files: 2 — file references are metadata, not package contents.