Meshy 3D generation
Meshy is a hosted generative-3D service. You give it text or images; it returns
a textured mesh (GLB/FBX/OBJ/USDZ/STL/3MF), with optional PBR maps, remeshing,
UV, auto-rigging, and library animations. Everything runs as
asynchronous
jobs: you POST a task, get a task ID, then poll, stream (SSE), or receive a
webhook until
.
This skill covers driving Meshy well: choosing the right generation mode,
writing prompts that separate geometry from texture, controlling topology and
poly count, texturing and re-texturing, rigging and animating, exporting into a
game/film/print pipeline, and judging whether the output is usable.
Evidence labels used below
- [Doc] — stated in official Meshy documentation, API reference, or help
center (URLs in Sources). Volatile items carry a verification date.
- [1P-claim] — a first-party Meshy claim (marketing/blog/help) not
independently verified. Treat as a claim, not a guarantee.
- [Heuristic] — production judgment from how generative-3D pipelines behave;
verify against your own output.
Volatile facts (model IDs, credit costs, limits, formats) were verified
2026-07-10 against docs.meshy.ai. Re-check the changelog and pricing pages
before quoting numbers to a user, because Meshy ships model versions and
adjusts credit costs and promotions frequently.
When to use Meshy — and when not to
Use Meshy when you need:
- A single, coherent prop, character, or creature fast from a prompt or a
reference image (concept-to-asset, game jam, previz, background dressing,
crowd fillers, marketplace assets, 3D-print blanks). [Heuristic]
- A textured starting mesh you will clean up downstream rather than a
final production hero asset. [Heuristic]
- Bulk asset generation where throughput and cost per asset matter more
than authored topology. [Heuristic]
Do not reach for Meshy when:
- You need exact real-world dimensions or CAD tolerances (mechanical parts,
enclosures, mounting brackets). Generative meshes are approximate; use CAD.
[Heuristic]
- You need guaranteed-watertight, manifold geometry for manufacturing. Meshy
offers printability analysis/repair and remesh, but does not guarantee a
manifold result; validate in a slicer/mesh-repair tool. [Heuristic]
- You must edit the geometry of an existing hand-authored asset — Meshy
regenerates, it does not surgically edit your mesh.
- The subject is a full scene (room, environment, multiple interacting
objects). Text-to-3D and image-to-3D reconstruct one subject best; build the
scene from separately generated parts in your engine. [Doc/Heuristic]
- You require clean animation-ready quad topology with edge loops around
deformation areas authored to spec. Meshy's remesh is quad-dominant
reconstruction, not artist-placed edge flow. [Heuristic]
- Licensing forbids AI-generated assets, or your reference images are
copyrighted in a way that would taint ownership (see Rights & licensing).
Model versions and mode selection
accepts
,
, or
;
resolves to the
current generation, which is
Meshy-6 as of 2026-07-10.
[Doc, verified
2026-07-10] Meshy-4 was retired and its API requests are no longer supported.
[Doc] Pin an explicit version (
or
) when you need
reproducible behavior across a batch; use
only when you want Meshy's
newest default and can tolerate behavior changes. [Heuristic]
selects
(default) or
.
[Doc]
produces stylized low-polygon output and, per the image-to-3D reference,
overrides remesh, PBR, and poly-count settings, so do not combine it with
fine topology control.
[Doc, verified 2026-07-10]
Meshy-6-only / latest-only texture features:
(4K base color),
(bakes out captured shadows/highlights), and, for
image-to-3D,
.
[Doc, verified 2026-07-10]
Deprecated parameters — do not use
- (Text-to-3D preview) — unsupported by Meshy-6; formerly
/ . [Doc]
- — no longer functional. [Doc]
- — replaced by (, , or ).
[Doc]
- Remesh , , , —
documented as deprecated on the remesh endpoint. [Doc]
Passing deprecated params generally no-ops; prefer the current replacements so
your integration survives cleanups.
The async job model
Base URL https://api.meshy.ai/openapi/v1
(Text-to-3D uses the
path
; other endpoints are
).
[Doc, verified
2026-07-10]
Auth Bearer token:
Authorization: Bearer $MESHY_API_KEY
. Create the key
at meshy.ai/settings/api; it is shown once — store it (env var, secret
manager), never hardcode.
API access requires a Pro tier or higher
subscription; the free tier cannot create API tasks.
[Doc]
Task lifecycle Every generation POST returns a task
immediately. Status
progresses
PENDING → IN_PROGRESS → SUCCEEDED
(or
/
), with
0–100 and, while
,
(queue position).
[Doc]
Three ways to learn a task finished [Doc]:
- Poll
GET /openapi/v1/<endpoint>/:id
on an interval until terminal
status. Simplest; use a backoff (e.g. 2–5 s) and stop on
//. [Heuristic]
- Stream — SSE / events; partial
frames carry only , , .
- Webhook — register a callback to be notified on completion. Prefer for
server integrations to avoid poll load. [Heuristic]
Rate limits (verified 2026-07-10) [Doc]: 20 requests/second on Pro,
Premium, Ultra, Studio; 100/s on Enterprise. Concurrent "queue" tasks (Text to
3D, Image to 3D, Text to Texture, Remesh): Pro
10, Studio
20, Premium
30, Ultra
100, Enterprise
50 (customizable). Exceeding rps →
; exceeding concurrency →
429 NoMoreConcurrentTasks
.
Design a client-side concurrency gate to your tier's queue limit and retry 429s
with backoff. [Heuristic]
Error codes [Doc]:
bad/invalid params or over-limit prompt,
bad key,
insufficient credits,
unknown task,
rate/queue.
Failed tasks return
;
is
on failure.
Asset retention Generated files are retained ~3 days on non-Enterprise
plans. [Doc, verified 2026-07-10] Download and re-host output URLs
promptly; do not treat Meshy CDN URLs as permanent storage. [Heuristic]
Text-to-3D: the two-step preview → refine workflow
Text-to-3D is deliberately two calls so you can approve geometry before paying
to texture it. [Doc]
Step 1 — preview (geometry only). POST /openapi/v2/text-to-3d
with
and a
(≤ 600 chars). Key controls:
[Doc, verified
2026-07-10]
- | |
- |
- (default) |
- 100–300,000 (default 30,000); or 1–4
(adaptive; overrides )
- (default on Meshy-6, otherwise)
- | | — request an A/T pose when the mesh
will be rigged
- any of
glb, obj, fbx, stl, usdz, 3mf
(all except by
default)
- + (/) for real-world scale
- ,
Step 2 — refine (texture). POST again with
and
= the succeeded preview's ID. Texture controls:
(metallic/roughness/normal/emission maps),
(4K base color, Meshy-6),
(≤ 600 chars),
(URL or base64 style
reference),
(default
, Meshy-6).
[Doc]
Outputs include
(per format),
(array with
and, under PBR,
/
/
/
),
.
[Doc]
Because these are separate billed steps, iterate cheaply: regenerate or
re-prompt at preview until the silhouette/topology is right, then refine once.
[Heuristic]
Image-to-3D and Multi-Image-to-3D
POST /openapi/v1/image-to-3d
reconstructs one subject from
one image
(
as public URL or base64 data URI,
), or from a
prior text-to-image / image-to-image task via
.
[Doc]
Texturing and topology params mirror text-to-3D refine plus:
(default true),
(Meshy-6, default true),
,
.
[Doc, verified
2026-07-10]
POST /openapi/v1/multi-image-to-3d
accepts
1–4 images of the same object
from different angles (
) for better reconstruction.
[Doc]
Reference-image guidance [Heuristic]:
- Use a clean subject on a plain background, well lit, minimal occlusion,
the whole object in frame. Busy backgrounds bleed into reconstruction.
- For multi-image, shoot/collect consistent, non-conflicting views (e.g.
front, side, back) of the same object at the same scale and lighting;
contradictory views produce fused or averaged geometry.
- Image-to-3D infers unseen sides — expect invention on the back of a
single-front-view input; add views (multi-image) to constrain it.
- and guide texture, not shape; text is
prioritized if both are given (per the image-to-3D reference). [Doc]
Texturing, PBR, and re-texturing
Texture quality is separable from geometry. Options across the texturing-capable
endpoints [Doc]:
- — produce metallic/roughness/normal (+ emission on Meshy-6) maps
for physically based rendering in Unity/Unreal/Blender. Leave off for flat
base-color-only assets.
- — 4K (4096²) base color; PBR maps stay 2K. Meshy-6/latest
only. Use for hero assets seen close up; skip for background props to save
credits/time. [Doc/Heuristic]
- — bakes out captured highlights/shadows so your engine can
relight; default , Meshy-6/latest. Keep on when the asset must react to
scene lighting. [Doc]
Retexture / restyle an existing mesh: POST /openapi/v1/retexture
with
or
(
.glb/.gltf/.obj/.fbx/.stl
) plus a style via
(≤ 600 chars) or
; if both are given,
wins.
[Doc, verified 2026-07-10] Key flag:
— reuse the model's existing UV layout instead of
generating new UVs (preserves existing textures; if the model has no UVs,
quality suffers). Also supports
,
,
,
,
.
[Doc] Use retexture to re-skin one mesh into
many variants (color/material swaps) without regenerating geometry. [Heuristic]
Topology, poly count, and remesh
- — default; fine for static props, rendering, and most
engine import. — quad-dominant reconstruction, friendlier to
subdivision and some DCC workflows, but not artist-authored edge loops.
[Doc/Heuristic]
- (100–300,000): pick to budget. As rough starting targets
[Heuristic]: background/mobile props ~1k–10k; standard game assets ~10k–50k;
film/close-up hero or 3D-print masters higher (tens–hundreds of thousands).
These are budgets, not quality guarantees — a high count can still hide bad
topology.
- 1–4 gives adaptive reduction and overrides
. [Doc]
Remesh re-topologizes/exports an existing task or
uploaded model (
or
;
.glb/.gltf/.obj/.fbx/.stl
).
Params:
(adds
),
,
(100–300,000, default 30,000),
1–4.
[Doc, verified
2026-07-10] Reach for remesh when the raw generation has
too many faces,
messy topology, or you need a watertight-oriented mesh for printing, and
before rigging if the mesh exceeds 300,000 faces (the rigging cap). [Doc]
Recommended post-processing order (Meshy's own guidance):
Remesh → Unwrap UV → AI Texturing → Rigging → Animate → export. [Doc]
Rigging and animation
rigs a
textured humanoid GLB.
[Doc, verified
2026-07-10] Requirements and params:
- Input: (a textured model task) or (GLB /
only, public URL or data URI). [Doc]
- (default 1.7, must be positive); optional
(UV-unwrapped base-color PNG). [Doc]
- Constraints: humanoid with clearly defined limbs; character must face the
+Z axis (glTF forward); ≤ 300,000 faces when using
(remesh first if larger). Untextured meshes, non-humanoids,
and unclear limb structure are unsuitable. [Doc]
- Output: rigged character in FBX and GLB, plus basic walk/run animations
(skinned and armature-only variants). [Doc]
Animation POST /openapi/v1/animations
applies a library clip to a rigged
model via
. The library holds
500+ animations (categories like
DailyActions, WalkAndRun, Fighting, Dancing, BodyMovements); look up the
in the Animation Library reference.
[Doc, verified 2026-07-10]
For custom or non-humanoid motion, rig/animate in Blender/Maya instead. [Heuristic]
Export and engine import
Formats:
glb, obj, fbx, stl, usdz, 3mf
(remesh adds
). Request only
what you need via
to keep responses small.
[Doc]
Practical routing [Heuristic]:
- Unity / Unreal / three.js / web: (or for skinned rigs). GLB
carries PBR maps in one file. Assign ///
from if you re-import maps separately.
- Blender / DCC editing: or, from remesh, ; for rigs.
- AR (iOS Quick Look): .
- 3D printing: or ; run remesh first for topology/scale, then
validate manifoldness and wall thickness in a slicer.
- Set real scale with + , or at rigging,
so the asset imports at usable size rather than arbitrary units.
Prompt construction: separate geometry from texture
Geometry is decided at preview / generation; surface look is decided at
refine / texture. Write for each stage. [Doc/Heuristic]
Geometry prompt (subject + form + a few concrete features). One object, ~3–6
key details. Name the object type first, then defining shape/parts, then scale
and intended use. Prefer singular nouns — plurals ("warriors") invite fused or
extra limbs. Avoid full scenes, abstract concepts, and micro-detail like
individual hair strands. [1P-claim, Meshy prompt guide]
Texture prompt (materials, colors, finish, style) belongs in
/ retexture: e.g. "brushed brass and dark oak, matte finish"
rather than restating the shape. Concrete material words ("smooth gold metal")
beat vague praise ("looks beautiful").
[1P-claim]
Render-quality buzzwords ("8k, Unreal Engine, Octane, cinematic lighting") are
image-model habits; they mainly affect Meshy's texture/albedo, not geometry —
use them in the texture stage, not to try to improve the mesh. [Heuristic]
Quality review: is the mesh usable?
Inspect before accepting. Check [Heuristic]:
- Silhouette / proportions from multiple angles (use
or open the GLB). Generative meshes often look right
from the front and wrong from behind or top.
- Topology & poly count — is it within budget? Is it a dense blob that
needs remesh? requested where subdivision/deformation is needed?
- UVs & seams — visible seams or stretched texels? If you must hand-paint,
Unwrap UV first; for restyles, preserves layout.
- Watertightness / manifold for print — do not assume; verify in a mesh
tool. Meshy provides printability analysis/repair but no guarantee. [Doc]
- Texture artifacts — baked-in lighting (turn on ),
smeared or hallucinated detail on unseen faces, resolution (upgrade to
only where it shows).
- Rig readiness — humanoid, +Z facing, ≤ 300k faces, in A/T pose, textured
before you send it to rigging.
- Symmetry/limbs — extra/fused limbs or asymmetry from ambiguous prompts or
conflicting reference views → re-prompt or add views.
Iteration and repair workflow
- Preview cheaply, refine once. Approve geometry before texturing. [Doc]
- Wrong shape? Re-prompt geometry (singular noun, clearer form, add
reference image / more views). Small wording changes shift results. [1P]
- Right shape, wrong surface? Keep the mesh; re-run
refine/retexture with a better or
. Don't regenerate geometry to fix a texture. [Heuristic]
- Too heavy / bad topology? Remesh to target poly count / . [Doc]
- Seams / hand-paint needed? Unwrap UV before texturing. [Doc]
- Needs animation? Ensure textured + A/T pose + ≤ 300k faces (remesh if
not) → rig → animate by . [Doc]
- Batch: gate concurrency to your tier's queue limit; retry 429s; download
outputs within the retention window. [Heuristic]
Credits and pricing (verified 2026-07-10)
API usage bills per operation in credits (Pro+ subscription required). Costs
depend on model: Meshy-6 and low-poly cost more than legacy models. [Doc]
| Operation | Meshy-6 / low-poly | Other models |
|---|
| Text-to-3D preview | 20 | 5 |
| Text-to-3D refine (texture) | 10 | 10 |
| Image-to-3D (no texture / with texture) | 20 / 30 | 5 / 15 |
| Multi-Image-to-3D (no texture / with texture) | 20 / 30 | 5 / 15 |
| Retexture / Text-to-Texture | 10 | 10 |
| Remesh | 5 | 5 |
| Auto-rigging | 5 | 5 |
| Animation | 3 | 3 |
[Doc, docs.meshy.ai/en/api/pricing, verified 2026-07-10] A full textured
Meshy-6 text-to-3D via API is therefore ~30 credits (20 preview + 10 refine).
Failed tasks charge 0. Promotions and per-model costs change — re-read the
pricing page before quoting. Web-app pricing can differ from API per-operation
pricing. [Doc/Heuristic]
Rights and licensing (verified 2026-07-10)
- Paid plans: you retain full private ownership of assets you create and
may distribute/sell them, provided (a) you did not use materials that infringe
others' copyright as input, and (b) you do not publish the model to the
public Meshy Community — publishing to the community removes that private
ownership protection. [Doc, Meshy help center]
- Free plan: models are licensed CC BY 4.0 — you may use, modify, and
even sell them, but must give attribution (Meshy suggests "Model created with
Meshy – CC BY 4.0 License"). [Doc]
- Input hygiene: feeding copyrighted/trademarked reference images (a
character, a logo, a real person) can taint ownership and create infringement
risk regardless of plan. Use references you have rights to. [Heuristic]
- Confirm current terms at meshy.ai/terms-of-use before shipping commercially;
these terms are volatile.
Complete examples (illustrative — not fixed formulas)
Example A — Textured game prop, text-to-3D, Meshy-6
Intent: a game-ready treasure chest, ~20k tris, PBR, GLB for Unity.
Preview (geometry):
bash
curl -s https://api.meshy.ai/openapi/v2/text-to-3d \
-H "Authorization: Bearer $MESHY_API_KEY" -H 'Content-Type: application/json' \
-d '{
"mode": "preview",
"prompt": "a sturdy wooden treasure chest with iron banding and a domed lid, ornate lock plate, medieval fantasy style",
"ai_model": "meshy-6",
"topology": "triangle",
"target_polycount": 20000,
"target_formats": ["glb"]
}'
# -> { "result": "<preview_id>" } then poll GET /openapi/v2/text-to-3d/<preview_id>
Refine (texture) once preview is
:
bash
curl -s https://api.meshy.ai/openapi/v2/text-to-3d \
-H "Authorization: Bearer $MESHY_API_KEY" -H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "<preview_id>",
"enable_pbr": true,
"texture_prompt": "aged oak planks, dark iron fittings, worn brass lock, matte finish"
}'
Why: geometry words in preview, material words in the texture stage; PBR for
engine relighting; poly budget set at preview. Expected: a chest GLB with
base-color + metallic/roughness/normal maps. Failure modes: over-detailed prompt
→ mushy carving; skipping
→ flat look in Unreal. Variation: add
for a close-up hero chest.
Example B — Character from concept art, then rig + walk
Intent: reference image → riggable humanoid → walking animation.
bash
# 1) multi-image reconstruction (front + side + back of the SAME character)
curl -s https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-H "Authorization: Bearer $MESHY_API_KEY" -H 'Content-Type: application/json' \
-d '{ "image_urls": ["https://.../front.png","https://.../side.png","https://.../back.png"],
"ai_model":"meshy-6", "should_texture": true, "pose_mode": "a-pose" }'
# poll -> SUCCEEDED, note <model_task_id>; confirm faces <= 300000 (remesh if not)
# 2) rig the textured humanoid
curl -s https://api.meshy.ai/openapi/v1/rigging \
-H "Authorization: Bearer $MESHY_API_KEY" -H 'Content-Type: application/json' \
-d '{ "input_task_id": "<model_task_id>", "height_meters": 1.8 }'
# poll -> <rig_task_id>
# 3) apply a walk animation by action_id (look up in Animation Library)
curl -s https://api.meshy.ai/openapi/v1/animations \
-H "Authorization: Bearer $MESHY_API_KEY" -H 'Content-Type: application/json' \
-d '{ "input_task_id": "<rig_task_id>", "action_id": 1 }'
Why:
at generation makes rigging reliable; multi-image constrains the
back so the rig binds a real mesh, not a hallucinated one; rig needs a textured
humanoid ≤ 300k faces facing +Z. Failure modes: single front image → bad back +
failed rig; non-humanoid subject → rig rejects it; > 300k faces → remesh first.
Example C — Restyle one mesh into color variants (retexture)
Intent: reuse an approved sword mesh as three material variants without
regenerating geometry.
bash
curl -s https://api.meshy.ai/openapi/v1/retexture \
-H "Authorization: Bearer $MESHY_API_KEY" -H 'Content-Type: application/json' \
-d '{ "input_task_id": "<sword_task_id>",
"text_style_prompt": "corroded bronze blade, verdigris patina, leather-wrapped grip",
"enable_original_uv": true, "enable_pbr": true }'
Why:
preserves the existing UV layout so variants stay
UV-consistent; only the surface changes; 10 credits per variant vs. re-running a
full generation. Failure mode: model lacking UVs → weaker result (unwrap first).
Sources (verified 2026-07-10)