• MESHY_API_KEY

  — API authentication token sent in HTTP

  Authorization: Bearer

  header only. Never logged, never written to any file except

  .env

  in the current working directory when explicitly requested by the user.

• https://api.meshy.ai

  — Meshy AI API (task creation, status polling, model/image downloads)

• Read:

  .env

  /

  .env.local

  in the current working directory only (API key lookup)
• Write:

  .env

  in the current working directory only (API key storage, only on user request)
• Write:

  ./meshy_output/

  in the current working directory (downloaded model files, metadata)
• Read: files explicitly provided by the user (e.g., local images passed for image-to-3D conversion), accessed only at the exact path the user specifies
• No access to home directories, shell profiles, or any path outside the above

• API requests to

  api.meshy.ai

  include the

  MESHY_API_KEY

  in the Authorization header and user-provided text prompts or image URLs. No other local data is transmitted. Downloaded model files are saved locally only.

scripts/meshy_task.py

scripts/slicers.py

scripts/fix_obj.py

All generated files will be saved to

meshy_output/

in the current working directory. Each project gets its own folder (

{YYYYMMDD_HHmmss}_{prompt}_{id}/

) with model files, textures, thumbnails, and metadata. History is tracked in

meshy_output/history.json

.

meshy_output/

• Each project:

  meshy_output/{YYYYMMDD_HHmmss}_{prompt_slug}_{task_id_prefix}/

• Chained tasks (preview → refine → rig) reuse the same

  project_dir

• Track tasks in

  metadata.json

  per project, and global

  history.json

• Auto-download thumbnails alongside models

project-dir

record

thumbnail

• READY: key=...

  → Proceed to Step 1.

• READY: NO_KEY_FOUND

  → Go to Step 0a.

• PYTHON_REQUESTS: MISSING

  → Run

  pip install requests

  .

I'll generate a 3D model of "<prompt>" using the following plan:

  1. Preview (mesh generation) — 20 credits
  2. Refine (texturing with PBR) — 10 credits
  3. Download as .glb

  Total cost: 30 credits
  Current balance: <N> credits

  Shall I proceed?

Note: Rigging automatically includes walking + running animations at no extra cost. Only add

Animate

(3 credits) for custom animations beyond those.

1. Detect installed slicers first:

   python3 scripts/slicers.py detect

2. Ask the user: "White model (single-color) or multicolor?"
3. If multicolor: check for multicolor-capable slicer (OrcaSlicer, Bambu Studio, Creality Print, Elegoo Slicer, Anycubic Slicer Next), ask max_colors (1-16, default 4) and max_depth (3-6, default 4), confirm cost: 40 credits (+10 if repair is needed)
4. (Recommended) After generation, run a printability analysis (

   POST /openapi/v1/print/analyze

   , FREE). Run

   POST /openapi/v1/print/repair

   (10 credits) only if status = error.

• White Model Pipeline (20 credits): generate untextured (

  target_formats: ["obj"]

  ) → download OBJ →

  scripts/fix_obj.py

  (Y-up→Z-up, scale to mm, center, bottom at Z=0) → open in slicer
• Multicolor Pipeline (40 credits): generate + texture (refine/retexture REQUIRED) → multi-color API → download 3MF → open in multicolor slicer. The multi-color API outputs 3MF directly — no coordinate conversion, no

  target_formats

  needed at generation.
• Creative Lab (36 credits): photo →

  prototype

  (6) →

  build

  (30) → textured GLB, ready to print; multicolor via

  model_url

  .
• Print-quality checklist (wall thickness, overhangs, base stability, …) is in references/printing.md.

error

warning

1. Downloaded file paths and sizes
2. Task IDs (for follow-up: refine, rig, retexture)
3. Available formats (list

   model_urls

   keys)
4. Credits consumed + current balance (task JSON has

   consumed_credits

   ; run

   balance

   )
5. Suggested next steps:
   • Preview done → "Want to refine (add textures)?"
   • Model done → "Want to rig this character?"
   • Rigged → "Want to apply a custom animation?"
   • Any textured model → "Want to 3D print this? Multicolor printing is available!"
   • Any model → "Want to 3D print this?"

• 99% stall: Normal finalization (30–120s). Do NOT interrupt.
• Asset retention: Files deleted after 3 days (non-Enterprise). Download immediately.
• PBR maps: Must set

  enable_pbr: true

  explicitly.
• Refine: Works with

  meshy-5

  ,

  meshy-6

  , or

  latest

  — pick the same family as your preview for consistency. 10 credits regardless of model. (

  meshy-4

  is retired → 400.)
• Deprecated params:

  symmetry_mode

  no longer affects output;

  art_style

  is ignored by Meshy-6; use

  pose_mode

  instead of the old

  is_a_t_pose

  flag; use

  texture_resolution

  (

  "2k"

  /

  "4k"

  /

  "8k"

  ) instead of

  hd_texture

  ; on image-to-3d use

  model_type: "smart-topology"

  (with

  ai_model: "meshy-t2"

  ) instead of the deprecated

  "lowpoly"

  . Smart Topology is image-to-3d only — Text to 3D and Multi-Image to 3D don't have it.
• Rigging needs textures: rig the textured task (text-to-3d refine, or image-to-3d with

  should_texture: true

  ) — untextured meshes are unsupported, so a mesh-only preview fails. Also: bipedal humanoid only, ≤300k faces via

  input_task_id

  , and a

  model_url

  model must face +Z.
• Inspect before downloading: pass

  multi_view_thumbnails: true

  on image-to-3d / multi-image-to-3d and read

  thumbnail_urls

  (front/right/back/left, 512×512 PNG) instead of pulling a 50–200 MB GLB just to check the result. ~3s extra latency.
• Never hardcode

  action_id

  : fetch

  GET https://api.meshy.ai/web/public/animations/resources

  (public, no key,

  ?category=

  to narrow) and match the user's intent against

  name

  /

  category

  . IDs are not

  1..N

  — the catalog includes

  -2

  ,

  -1

  ,

  0

  .

• consumed_credits

  : Every task GET response includes

  consumed_credits

  — read it to report the real credits spent rather than estimating. A

  FAILED

  task reports

  0

  (credits are refunded), so a transient failure can be retried without re-approving the spend.
• Rigging: Humanoid bipedal only, polycount ≤ 300,000 (enforced by

  check-faces

  ).
• Printing formats: White model → OBJ with

  scripts/fix_obj.py

  . Multicolor → 3MF from Multi-Color Print API. Always detect slicer first.
• Download format: Ask the user which format they need before downloading. GLB (viewing), OBJ (printing), 3MF (multicolor), FBX (games), USDZ (AR). Do NOT download all formats.
• 3MF for multicolor: Multi-Color Print API outputs 3MF directly — no need to request 3MF from generate/refine. For non-print use cases needing 3MF, pass

  "3mf"

  in

  target_formats

  .
• Timestamps: All API timestamps are Unix epoch milliseconds.

• Ran API key detection (

  check-env

  , Step 0) — checked env var and

  .env

  /

  .env.local

  only
• API key verified (never printed in full)
• Presented cost summary and got user confirmation
• Composed the workflow from bundled script calls (never retyped the helpers)
• Followed the matching recipe in references/pipelines.md or references/printing.md
• Reported file paths, formats, task IDs, and balance
• Suggested next steps