meshy-3d — Claude Code skill: 3D generation and setup
meshy-3d is a Claude Code skill that creates 3D assets from text and images through Meshy. It handles generation jobs, textures, rigging, and exports.
MIT 142 installs ★ 252 updated 2026-07-14
npx skills add calesthio/generative-media-skills --skill meshy-3d -a claude-codeWhat meshy-3d does
meshy-3d creates 3D assets through Meshy’s REST API and web platform, using text prompts, one image, or several reference images. It covers mode selection, polygon and topology controls, PBR texturing, UV work, humanoid rigging, animation, and exports to GLB, FBX, OBJ, USDZ, or STL.
Meshy runs each request as an asynchronous job. The skill can follow completion through polling, an SSE stream, or a webhook. API tasks require a Bearer token in MESHY_API_KEY and a Pro-tier-or-higher subscription. Meshy is not a CAD replacement for exact dimensions and does not guarantee watertight geometry for manufacturing.
What it helps with
- generate a 3D asset from a text prompt
- turn a reference image into a mesh
- control an asset’s polygon count and topology
- apply PBR materials and create UVs
- prepare a character for rigging and export
Example prompts for the agent
- Create a 3D character from this description and start the Meshy generation job.
- Turn
reference.pnginto a 3D mesh, keep the polygon count low, and export it asGLB. - Track the Meshy job with a webhook and report when the asset is ready for Blender.
How to install meshy-3d
1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill meshy-3d -a claude-code2Manually: put the files in place
~/.claude/skills/meshy-3d/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/meshy-3d/
1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill meshy-3d -a codex2Manually: put the files in place
.agents/skills/meshy-3d/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill meshy-3d -a cursor2Manually: put the files in place
.cursor/skills/meshy-3d/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install calesthio/generative-media-skills skills/providers/3d-generation/meshy-3d2Manually: put the files in place
.github/skills/meshy-3d/SKILL.md1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill meshy-3d -a gemini-cli2Platform CLI
gemini skills install https://github.com/calesthio/generative-media-skills --path skills/providers/3d-generation/meshy-3dManually: put the files in place
.devin/skills/meshy-3d/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill meshy-3d -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about meshy-3d
How do I install meshy-3d in Claude Code?
Run npx skills add calesthio/generative-media-skills --skill meshy-3d -a claude-code, then use ~/.claude/skills/meshy-3d/SKILL.md.
What does meshy-3d do?
The skill drives Meshy generation from text and images, with controls for textures, remeshing, UVs, rigging, animation, and export formats.
What does meshy-3d require?
It requires a Bearer token stored in MESHY_API_KEY, created at meshy.ai/settings/api, plus a Pro-tier-or-higher subscription. The key is shown once and should be kept in an environment variable or secret manager.
Source text
SKILL.md · MIT
---
name: meshy-3d
description: >-
Produce 3D assets with Meshy (meshy.ai) through its REST API and web
platform — text-to-3D, image-to-3D, multi-image-to-3D, AI texturing/PBR,
remesh/topology control, UV, and auto-rigging/animation. Use this skill when
an agent must generate a mesh from a prompt or reference image, control
polygon count and topology, apply or restyle textures, rig a humanoid for
animation, export to GLB/FBX/OBJ/USDZ/STL for Unity/Unreal/Blender, drive
Meshy's asynchronous job API (auth, polling, streaming, webhooks, credits,
rate limits), review generated meshes for game/film/print readiness, or
decide whether Meshy is the right tool at all. Not for editing an existing
hand-modeled asset's geometry, hard-surface CAD with exact dimensions, or
guaranteed-watertight manufacturing parts.
---
# 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 `SUCCEEDED`.
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 `quad` 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
`ai_model` accepts `meshy-6`, `meshy-5`, or `latest`; `latest` 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 (`meshy-5` or `meshy-6`) when you need
reproducible behavior across a batch; use `latest` only when you want Meshy's
newest default and can tolerate behavior changes. [Heuristic]
`model_type` selects `standard` (default) or `lowpoly`. **[Doc]** `lowpoly`
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: `hd_texture` (4K base color),
`remove_lighting` (bakes out captured shadows/highlights), and, for
image-to-3D, `image_enhancement`. **[Doc, verified 2026-07-10]**
## Deprecated parameters — do not use
- `art_style` (Text-to-3D preview) — unsupported by Meshy-6; formerly
`realistic` / `sculpture`. **[Doc]**
- `symmetry_mode` — no longer functional. **[Doc]**
- `is_a_t_pose` — replaced by `pose_mode` (`a-pose`, `t-pose`, or `""`).
**[Doc]**
- Remesh `resize_height`, `resize_longest_side`, `auto_size`, `origin_at` —
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 `v2` path
`/openapi/v2/text-to-3d`; other endpoints are `v1`). **[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 `id` immediately. Status
progresses `PENDING → IN_PROGRESS → SUCCEEDED` (or `FAILED` / `CANCELED`), with
`progress` 0–100 and, while `PENDING`, `preceding_tasks` (queue position).
**[Doc]**
**Three ways to learn a task finished** [Doc]:
1. **Poll** `GET /openapi/v1/<endpoint>/:id` on an interval until terminal
status. Simplest; use a backoff (e.g. 2–5 s) and stop on
`SUCCEEDED`/`FAILED`/`CANCELED`. [Heuristic]
2. **Stream** `GET .../:id/stream` — SSE `message`/`error` events; partial
frames carry only `id`, `progress`, `status`.
3. **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 →
`429 RateLimitExceeded`; 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]: `400` bad/invalid params or over-limit prompt, `401`
bad key, `402` insufficient credits, `404` unknown task, `429` rate/queue.
Failed tasks return `task_error.message`; `consumed_credits` is `0` 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
`mode: "preview"` and a `prompt` (≤ 600 chars). Key controls: **[Doc, verified
2026-07-10]**
- `ai_model` `meshy-6` | `meshy-5` | `latest`
- `model_type` `standard` | `lowpoly`
- `topology` `triangle` (default) | `quad`
- `target_polycount` 100–300,000 (default 30,000); or `decimation_mode` 1–4
(adaptive; overrides `target_polycount`)
- `should_remesh` (default `false` on Meshy-6, `true` otherwise)
- `pose_mode` `""` | `a-pose` | `t-pose` — request an A/T pose when the mesh
will be rigged
- `target_formats` any of `glb, obj, fbx, stl, usdz, 3mf` (all except `3mf` by
default)
- `auto_size` + `origin_at` (`bottom`/`center`) for real-world scale
- `alpha_thumbnail`, `moderation`
**Step 2 — refine (texture).** POST again with `mode: "refine"` and
`preview_task_id` = the succeeded preview's ID. Texture controls: `enable_pbr`
(metallic/roughness/normal/emission maps), `hd_texture` (4K base color, Meshy-6),
`texture_prompt` (≤ 600 chars), `texture_image_url` (URL or base64 style
reference), `remove_lighting` (default `true`, Meshy-6). **[Doc]**
Outputs include `model_urls` (per format), `texture_urls` (array with
`base_color` and, under PBR, `metallic`/`normal`/`roughness`/`emission`),
`thumbnail_url`. **[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
(`image_url` as public URL or base64 data URI, `.jpg/.jpeg/.png`), or from a
prior text-to-image / image-to-image task via `input_task_id`. **[Doc]**
Texturing and topology params mirror text-to-3D refine plus:
`should_texture` (default true), `image_enhancement` (Meshy-6, default true),
`save_pre_remeshed_model`, `multi_view_thumbnails`. **[Doc, verified
2026-07-10]**
`POST /openapi/v1/multi-image-to-3d` accepts **1–4 images of the same object
from different angles** (`image_urls`) 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.
- `texture_prompt` and `texture_image_url` 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]:
- `enable_pbr` — 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.
- `hd_texture` — 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]
- `remove_lighting` — bakes out captured highlights/shadows so your engine can
relight; default `true`, Meshy-6/latest. Keep on when the asset must react to
scene lighting. [Doc]
**Retexture / restyle an existing mesh:** `POST /openapi/v1/retexture` with
`input_task_id` or `model_url` (`.glb/.gltf/.obj/.fbx/.stl`) plus a style via
`text_style_prompt` (≤ 600 chars) or `image_style_url`; if both are given,
`image_style_url` wins. **[Doc, verified 2026-07-10]** Key flag:
`enable_original_uv` — 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 `enable_pbr`, `hd_texture`, `remove_lighting`,
`ai_model`, `target_formats`. **[Doc]** Use retexture to re-skin one mesh into
many variants (color/material swaps) without regenerating geometry. [Heuristic]
## Topology, poly count, and remesh
- `topology: triangle` — default; fine for static props, rendering, and most
engine import. `topology: quad` — quad-dominant reconstruction, friendlier to
subdivision and some DCC workflows, but **not** artist-authored edge loops.
[Doc/Heuristic]
- `target_polycount` (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.
- `decimation_mode` 1–4 gives adaptive reduction and **overrides**
`target_polycount`. [Doc]
**Remesh** `POST /openapi/v1/remesh` re-topologizes/exports an existing task or
uploaded model (`input_task_id` or `model_url`; `.glb/.gltf/.obj/.fbx/.stl`).
Params: `target_formats` (adds `blend`), `topology`, `target_polycount`
(100–300,000, default 30,000), `decimation_mode` 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
`POST /openapi/v1/rigging` rigs a **textured humanoid** GLB. **[Doc, verified
2026-07-10]** Requirements and params:
- Input: `input_task_id` (a textured model task) **or** `model_url` (GLB /
`.glb` only, public URL or data URI). [Doc]
- `height_meters` (default 1.7, must be positive); optional
`texture_image_url` (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
`input_task_id` (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 `action_id`. The library holds **500+ animations** (categories like
DailyActions, WalkAndRun, Fighting, Dancing, BodyMovements); look up the
`action_id` 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 `blend`). Request only
what you need via `target_formats` to keep responses small. **[Doc]**
Practical routing [Heuristic]:
- **Unity / Unreal / three.js / web:** `glb` (or `fbx` for skinned rigs). GLB
carries PBR maps in one file. Assign `metallic`/`roughness`/`normal`/
`emission` from `texture_urls` if you re-import maps separately.
- **Blender / DCC editing:** `glb` or, from remesh, `blend`; `fbx` for rigs.
- **AR (iOS Quick Look):** `usdz`.
- **3D printing:** `stl` or `3mf`; run remesh first for topology/scale, then
validate manifoldness and wall thickness in a slicer.
- Set real scale with `auto_size` + `origin_at`, or `height_meters` 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
`texture_prompt` / 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
`multi_view_thumbnails` 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? `quad` requested where subdivision/deformation is needed?
- **UVs & seams** — visible seams or stretched texels? If you must hand-paint,
Unwrap UV first; for restyles, `enable_original_uv` 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 `remove_lighting`),
smeared or hallucinated detail on unseen faces, resolution (upgrade to
`hd_texture` 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
1. **Preview cheaply, refine once.** Approve geometry before texturing. [Doc]
2. **Wrong shape?** Re-prompt geometry (singular noun, clearer form, add
reference image / more views). Small wording changes shift results. [1P]
3. **Right shape, wrong surface?** Keep the mesh; re-run
**refine**/**retexture** with a better `texture_prompt` or
`image_style_url`. Don't regenerate geometry to fix a texture. [Heuristic]
4. **Too heavy / bad topology?** **Remesh** to target poly count / `quad`. [Doc]
5. **Seams / hand-paint needed?** **Unwrap UV** before texturing. [Doc]
6. **Needs animation?** Ensure textured + A/T pose + ≤ 300k faces (remesh if
not) → **rig** → **animate** by `action_id`. [Doc]
7. **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 `SUCCEEDED`:
```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 `enable_pbr` → flat look in Unreal. Variation: add
`hd_texture: true` 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: `a-pose` 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: `enable_original_uv` 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)
- Text-to-3D API — https://docs.meshy.ai/en/api/text-to-3d
- Image-to-3D API — https://docs.meshy.ai/en/api/image-to-3d
- Multi-Image-to-3D API — https://docs.meshy.ai/en/api/multi-image-to-3d
- Retexture / Text-to-Texture API — https://docs.meshy.ai/en/api/retexture
- Remesh API — https://docs.meshy.ai/en/api/remesh
- Rigging & Animation API — https://docs.meshy.ai/en/api/rigging-and-animation
- Animation Library — https://docs.meshy.ai/en/api/animation-library
- Quickstart / auth — https://docs.meshy.ai/en/api/quick-start
- Rate limits — https://docs.meshy.ai/en/api/rate-limits
- API pricing — https://docs.meshy.ai/en/api/pricing
- Changelog — https://docs.meshy.ai/en/api/changelog
- Post-processing decision guide — https://docs.meshy.ai/en/webapp/guides/choosing/post-processing
- Prompt best practices — https://help.meshy.ai/en/articles/11972484-best-practices-for-creating-a-text-prompt
and https://www.meshy.ai/blog/meshy-5-text-to-3d
- Ownership — https://help.meshy.ai/en/articles/10137554-what-is-the-ownership-of-the-generated-models
- Commercial use — https://help.meshy.ai/en/articles/9992001-can-i-use-my-generated-assets-for-commercial-projects
- Credit costs (help) — https://help.meshy.ai/en/articles/10000507-how-many-credits-does-each-generation-task-cost
- Plans/pricing — https://www.meshy.ai/pricing
© calesthio · MIT · calesthio/generative-media-skills