---
canonical_url: "https://docs.composio.dev/toolkits/meshy"
markdown_url: "https://docs.composio.dev/toolkits/meshy.md"
product: "platform"
version: null
last_updated: null
---

# Meshy

Meshy provides generative 3D, image, motion, animation, model-processing, and Creative Lab APIs.

- **Category:** media generation
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 27
- **Triggers:** 0
- **Slug:** `MESHY`
- **Version:** 20261014_00

## Tools

### Cancel Creative Lab Task

**Slug:** `MESHY_CANCEL_CREATIVE_LAB_TASK`

Cancel a Creative Lab task only while it is PENDING or IN_PROGRESS. Terminal task history is retained. Canceling a PENDING task refunds its credits; canceling an IN_PROGRESS task does not refund credits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | ID of a PENDING or IN_PROGRESS Creative Lab task to cancel. |
| `task_type` | string ("creative_lab_keychain_prototype" | "creative_lab_keychain_build" | "creative_lab_fridge_magnet_prototype" | "creative_lab_fridge_magnet_build" | "creative_lab_figure_prototype" | "creative_lab_figure_build" | "creative_lab_vinyl_figure_prototype" | "creative_lab_vinyl_figure_build" | "creative_lab_brick_figure_prototype" | "creative_lab_brick_figure_build" | "creative_lab_lamp_prototype" | "creative_lab_lamp_build" | "creative_lab_keycap_prototype" | "creative_lab_keycap_build" | "creative_lab_fidget_pixel_prototype" | "creative_lab_fidget_pixel_build" | "creative_lab_fidget_collapsible") | Yes | Creative Lab task family that owns the ID; selects a fixed documented cancellation endpoint. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Animation Task

**Slug:** `MESHY_CREATE_ANIMATION_TASK`

Start a 3-credit task that applies either a selected library animation or a succeeded Text to Motion clip to a completed rigging task and return the animation task ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional task name. |
| `action_id` | integer | No | Identifier of the preset animation action to apply, returned by MESHY_LIST_ANIMATION_LIBRARY. Provide exactly one of action_id or motion_task_id. |
| `rig_task_id` | string | Yes | Completed Meshy rigging task ID whose model will be animated. |
| `post_process` | object | No | Optional post-processing operation for changing frame rate, converting FBX to USDZ, or extracting the armature. |
| `motion_task_id` | string | No | ID of a successfully completed Text to Motion task to apply instead of a preset action. The generated clip is retargeted onto the rigged character and snapshotted when this task is created. Source assets are retained for 3 days, so apply the clip before it expires. Requires a biped rig. Provide exactly one of action_id or motion_task_id. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Auto Split Task

**Slug:** `MESHY_CREATE_AUTO_SPLIT_TASK`

Split a succeeded untextured Meshy 6 or Meshy 7 model into separately printable parts and return the task ID. An accepted task costs 10 credits; failed tasks are refunded, as is a task deleted while still pending.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string ("auto" | "by_parts" | "by_color") | No | Split automatically, by named structural parts, or by named color regions. by_color requires an Image to 3D or Multi-Image to 3D source. |
| `layout` | string ("assembled" | "on_plate") | No | Keep parts assembled or lay them out separately on a build plate. |
| `prompt` | string | No | One to ten part names in any language, not a general description. Required for by_parts and by_color and ignored for auto. Meshy rejects prompts naming fewer than two parts; an unreadable prompt falls back to auto and the task reports prompt_ignored. |
| `connectors` | boolean | No | Add mortise-and-tenon connectors at each cut. |
| `input_task_id` | string | Yes | Succeeded, untextured Meshy 6 or Meshy 7 Image to 3D, Multi-Image to 3D, Text to 3D preview, Remesh, Convert, or Resize task whose model will be split. |
| `connector_size` | number | No | Connector size relative to the cut surface. Only valid when connectors is true. |
| `connector_type` | string ("cube" | "cylinder") | No | Connector shape. Only valid when connectors is true. |
| `target_formats` | array | No | Output formats. GLB is always produced; STL is not supported. |
| `connector_height` | number | No | Connector extension relative to the cut surface. Only valid when connectors is true. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Collapsible Fidget Task

**Slug:** `MESHY_CREATE_COLLAPSIBLE_FIDGET_TASK`

Start an entitled 6-credit task that generates a collapsible fidget directly from an image and return the task ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional task name, up to 100 characters. |
| `image_url` | string | Yes | Public HTTP(S) URL or base64 data URI for a JPG, JPEG, PNG, or WebP source image. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Convert Task

**Slug:** `MESHY_CREATE_CONVERT_TASK`

Start a 1-credit task that converts a model into one or more requested formats; returns the task ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model_url` | string | No | Model HTTP(S) URL or data URI to convert. Required when input_task_id is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `input_task_id` | string | No | Prior Meshy task ID containing the model to convert. Required when model_url is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `target_formats` | array | Yes | One or more output formats: glb, obj, fbx, stl, usdz, blend, or 3mf. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Creative Lab Build

**Slug:** `MESHY_CREATE_CREATIVE_LAB_BUILD`

Start a 3D build from a succeeded matching Creative Lab prototype. Lamp builds cost 6 credits, keycap builds cost 50, and all other builds cost 30. The call returns a build task ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional task name. |
| `product` | string ("keychain" | "fridge_magnet" | "figure" | "vinyl_figure" | "brick_figure" | "lamp" | "keycap" | "fidget_pixel") | Yes | Creative Lab product to build. It must match the succeeded prototype task. |
| `build_options` | string | No | Required when product='keycap' and must include a non-empty candidate_id. Optional when product is 'keychain', 'fridge_magnet', 'lamp', or 'fidget_pixel'. Omit for figure, vinyl_figure, or brick_figure; build_options is rejected for those products. |
| `input_task_id` | string | Yes | Succeeded prototype task ID created for the selected product with the same Meshy API key. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Creative Lab Prototype

**Slug:** `MESHY_CREATE_CREATIVE_LAB_PROTOTYPE`

Start an entitled image-to-prototype task for a fixed Creative Lab product. Lamp prototypes cost 30 credits, keycap prototypes cost 12, and all other prototypes cost 6. The task ID can be passed to the matching build operation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional task name of at most 100 characters. |
| `product` | string ("keychain" | "fridge_magnet" | "figure" | "vinyl_figure" | "brick_figure" | "lamp" | "keycap" | "fidget_pixel") | Yes | Creative Lab product prototype to generate; selects one fixed documented endpoint. |
| `image_url` | string | Yes | Public image URL or base64 data URI containing a JPG, JPEG, PNG, or WebP image. |
| `product_options` | string | No | Required when product='fidget_pixel': set the nested product discriminator to 'fidget_pixel' and provide a non-empty type. Optional when product is 'keychain' or 'lamp', with the nested product discriminator matching the top-level product. Omit for fridge_magnet, figure, vinyl_figure, brick_figure, or keycap; product_options is rejected for those products. |
| `remove_background` | boolean | No | Whether Meshy should return a transparent prototype image. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Image to 3D Task

**Slug:** `MESHY_CREATE_IMAGE_TO_3D_TASK`

Start a 3D generation task from one to four views of one object or a prior task's input images. One image uses single-image generation and two to four use multi-image generation. Meshy-6/7 cost 20 credits without texture, 30 with texture, or 35 with 8K texture; single-image Meshy T2 costs 5, 15, or 20 respectively; other models cost 5 without or 15 with texture. Ultra on Meshy-7 adds 5 credits. Returns task_id and the exact task_type discriminator for GET_TASK, LIST_TASKS, or DELETE_TASK.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional task name, up to 100 characters. |
| `ai_model` | string ("meshy-5" | "meshy-6" | "meshy-7" | "latest" | "meshy-t2") | No | Meshy model to use. When omitted, Meshy selects the endpoint and model-type default. meshy-t2 is single-image only and requires model_type='smart-topology'; meshy-7 may require account entitlement. Pricing before add-ons: meshy-6 and meshy-7 cost 20 credits without texture or 30 with texture; meshy-t2 costs 5 without texture or 15 with texture; other models cost 5 without texture or 15 with texture. |
| `topology` | string ("quad" | "triangle") | No | Output mesh topology. Quad topology is not supported by meshy-t2. |
| `auto_size` | boolean | No | Whether to estimate the model's real-world size automatically. |
| `origin_at` | string ("bottom" | "center") | No | Place the model origin at its bottom or center. |
| `pose_mode` | string ("a-pose" | "t-pose") | No | Force an A-pose or T-pose for a character model. |
| `enable_pbr` | boolean | No | Whether to produce physically based rendering texture maps. |
| `image_urls` | array | No | One to four views of the same object. One image uses Meshy's single-image pipeline; two to four images use its multi-image pipeline. One of image_urls or input_task_id is required. If both are provided, input_task_id takes priority and image_urls is ignored. |
| `model_type` | string ("standard" | "lowpoly" | "smart-topology") | No | Single-image-only generation pipeline: standard, lowpoly, or smart-topology. |
| `moderation` | boolean | No | Whether to run content moderation. |
| `ultra_mode` | boolean | No | Enable the high-detail pass. Ultra adds 5 credits to the applicable meshy-7 price and requires account entitlement; it requires meshy-7 for single-image or meshy-7/latest for multi-image generation. |
| `experimental` | object | No | Single-image-only experimental generation options. |
| `input_task_id` | string | No | Prior task whose input image or images should be reused. One of input_task_id or image_urls is required; if both are provided, this task takes priority. Also provide input_image_count. |
| `should_remesh` | boolean | No | Whether to remesh after the draft stage. The default depends on the model. |
| `should_texture` | boolean | No | Whether to run the texture stage. Texturing adds 10 credits to the base 5- or 20-credit generation price. |
| `target_formats` | array | No | Additional output formats: glb, obj, fbx, stl, usdz, or 3mf. |
| `texture_prompt` | string | No | Optional texture description, up to 800 characters. If texture_image_url is also provided, texture_prompt takes priority and texture_image_url is ignored. For multi-image generation it is mutually exclusive with texture_image_urls. |
| `alpha_thumbnail` | boolean | No | Whether to produce a transparent-background preview. |
| `decimation_mode` | integer ("1" | "2" | "3" | "4") | No | Decimation algorithm selector from 1 through 4. |
| `remove_lighting` | boolean | No | Whether to remove baked lighting. Not supported with smart-topology. |
| `target_polycount` | integer | No | Target polygon count from 100 to 300000. When omitted, Meshy chooses the single-image default or 30000 for multi-image generation. |
| `image_enhancement` | boolean | No | Whether to enhance the input image(s). Not supported with smart-topology. |
| `input_image_count` | integer | No | Number of input images in input_task_id. Required only with input_task_id; 1 selects the single-image pipeline and 2-4 select the multi-image pipeline. |
| `texture_image_url` | string | No | Optional single texture reference as an HTTP(S) URL or data URI. For single- or multi-image generation, texture_prompt takes priority if both are provided. For multi-image generation it is mutually exclusive with texture_image_urls. |
| `texture_image_urls` | array | No | Multi-image-only texture reference views, with the primary view first. Requires should_texture and meshy-7/latest; mutually exclusive with texture_prompt and texture_image_url. |
| `texture_resolution` | string ("2k" | "4k" | "8k") | No | Texture resolution tier: 2k, 4k, or 8k. An 8K texture adds 5 credits for meshy-6, meshy-7, and single-image meshy-t2, making their textured prices 35, 35, and 20 credits respectively. Other textured models remain 15 credits; meshy-5 does not support 4K or 8K. |
| `multi_view_thumbnails` | boolean | No | Whether to render front, right, back, and left thumbnails. |
| `save_pre_remeshed_model` | boolean | No | Whether to include the model produced before remeshing in task outputs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Image to Image Task

**Slug:** `MESHY_CREATE_IMAGE_TO_IMAGE_TASK`

Start a credit-consuming task that edits or restyles one to five reference images from a text instruction. The task costs 3 to 12 credits depending on the model and returns a task ID for status checks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text instruction describing the transformation or edit to apply. |
| `ai_model` | string ("nano-banana" | "nano-banana-pro" | "nano-banana-2" | "gpt-image-2") | Yes | Meshy image-edit model to use. |
| `aspect_ratio` | string ("1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3") | No | Output aspect ratio. gpt-image-2 supports 1:1, 16:9, 9:16, 3:2, and 2:3; nano-banana models support 1:1, 16:9, 9:16, 4:3, and 3:4. Do not set this with generate_multi_view. |
| `remove_background` | boolean | No | Whether to return a transparent RGBA PNG with the background removed. Available only for single-image output. |
| `generate_multi_view` | boolean | No | Whether to generate a split image showing the subject from multiple angles. Cannot be combined with aspect_ratio or background removal. |
| `reference_image_urls` | array | Yes | One to five reference images to edit from, provided as public HTTP(S) URLs or JPEG/PNG data URIs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Multi-Color Print Task

**Slug:** `MESHY_CREATE_MULTI_COLOR_PRINT_TASK`

Start a 10-credit task that converts a GLB or FBX model from a prior Meshy task or direct URL into a limited-color 3MF for 3D printing, and return the task ID. When both sources are provided, input_task_id takes precedence.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `style` | string ("realistic" | "cartoon") | No | Color-placement algorithm to use. |
| `max_depth` | integer | No | Quadtree depth from 3 to 6; used by the realistic style. |
| `model_url` | string | No | HTTP(S) URL or data URI for a GLB or FBX model. Required when input_task_id is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `max_colors` | integer | No | Target number of colors, from 1 to 16. |
| `input_task_id` | string | No | Prior Meshy task containing the GLB model. Required when model_url is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Print Analysis Task

**Slug:** `MESHY_CREATE_PRINT_ANALYSIS_TASK`

Start a free task that analyzes a GLB, GLTF, OBJ, FBX, or STL model from a prior Meshy task or direct URL for printability defects and return the task ID. When both sources are provided, input_task_id takes precedence.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model_url` | string | No | GLB, GLTF, OBJ, FBX, or STL HTTP(S) URL or data URI. Required when input_task_id is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `input_task_id` | string | No | Prior Meshy task ID containing the model to analyze. Required when model_url is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Print Repair Task

**Slug:** `MESHY_CREATE_PRINT_REPAIR_TASK`

Start a 10-credit task that repairs a GLB, GLTF, OBJ, FBX, or STL model from a prior Meshy task or direct URL for 3D printing and return the task ID. When both sources are provided, input_task_id takes precedence. The repaired asset retains the input format.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model_url` | string | No | GLB, GLTF, OBJ, FBX, or STL model HTTP(S) URL or data URI. Required when input_task_id is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `input_task_id` | string | No | Prior Meshy task ID containing the GLB, STL, or OBJ model to repair. Required when model_url is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `alpha_thumbnail` | boolean | No | Generate a transparent-background preview thumbnail. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Remesh Task

**Slug:** `MESHY_CREATE_REMESH_TASK`

Start a 5-credit task that remeshes a model to the requested topology and polygon count, optionally resizes it, and exports the remeshed result in the requested formats. Use CREATE_CONVERT_TASK for format conversion without remeshing. Returns the remesh task ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `topology` | string ("quad" | "triangle") | No | Output mesh topology. |
| `auto_size` | boolean | No | Automatically estimate real-world size; mutually exclusive with explicit sizing fields. |
| `model_url` | string | No | Model HTTP(S) URL or data URI to remesh. Required when input_task_id is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `origin_at` | string ("bottom" | "center") | No | Place the model origin at its bottom or center. |
| `input_task_id` | string | No | Prior Meshy task ID containing the model to remesh. Required when model_url is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `resize_height` | number | No | Target height in meters; mutually exclusive with resize_longest_side and auto_size. |
| `target_formats` | array | No | Formats for the remeshed output. Defaults to glb. Use CREATE_CONVERT_TASK when only format conversion is needed. |
| `alpha_thumbnail` | boolean | No | Generate a transparent-background preview thumbnail. |
| `decimation_mode` | integer ("1" | "2" | "3" | "4") | No | Decimation algorithm selector from 1 through 4. |
| `target_polycount` | integer | No | Target polygon count from 100 to 300000. |
| `resize_longest_side` | number | No | Target longest side in meters; mutually exclusive with resize_height and auto_size. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Resize Task

**Slug:** `MESHY_CREATE_RESIZE_TASK`

Start a 1-credit task that scales a model by height, longest side, or automatic sizing and return the task ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `auto_size` | boolean | No | Automatically estimate real-world size; choose exactly one sizing method. |
| `model_url` | string | No | Model HTTP(S) URL or data URI to resize. Required when input_task_id is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `origin_at` | string ("bottom" | "center") | No | Place the resized model origin at its bottom or center. |
| `input_task_id` | string | No | Prior Meshy task ID containing the model to resize. Required when model_url is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `resize_height` | number | No | Target height in meters; choose exactly one sizing method. |
| `resize_longest_side` | number | No | Target longest side in meters; choose exactly one sizing method. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Retexture Task

**Slug:** `MESHY_CREATE_RETEXTURE_TASK`

Start a credit-consuming task that applies one text, image, or multiview style source to an existing 3D model. The task costs 10 credits at 2k or 4k resolution and 15 credits at 8k, and returns a task ID for status checks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional task name. |
| `ai_model` | string ("meshy-5" | "meshy-6" | "meshy-7" | "latest") | No | Meshy model to use. |
| `art_style` | string ("realistic" | "cartoon") | No | Art style to apply to the generated texture. |
| `model_url` | string | No | HTTP(S) URL or data URI for a GLB, GLTF, OBJ, FBX, or STL model. Required when input_task_id is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `enable_pbr` | boolean | No | Whether to produce PBR texture maps. |
| `input_task_id` | string | No | Prior Meshy task containing the model to retexture. Required when model_url is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `target_formats` | array | No | Additional model formats to export. |
| `alpha_thumbnail` | boolean | No | Whether to produce a transparent-background preview thumbnail. |
| `image_style_url` | string | No | HTTP(S) URL or data URI for one style reference image. Provide at least one style source. Takes precedence over text_style_prompt when both are provided; text_style_prompt is omitted from the request. Cannot be combined with multiview_image_urls. |
| `remove_lighting` | boolean | No | Whether to remove baked lighting from the texture; support depends on the selected model. |
| `text_style_prompt` | string | No | Text description of the desired style. Provide at least one style source. May be combined with image_style_url, which takes precedence and causes text_style_prompt to be omitted from the request. Cannot be combined with multiview_image_urls. |
| `enable_original_uv` | boolean | No | Whether to reuse the source model's UV coordinates. |
| `texture_resolution` | string ("2k" | "4k" | "8k") | No | Texture resolution tier. Meshy defaults to 2k when omitted; 8k consumes more credits. |
| `multiview_image_urls` | array | No | One to four style reference views of the same object, primary view first. Requires ai_model='meshy-7' and account entitlement; cannot be combined with text_style_prompt or image_style_url. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Rigging Task

**Slug:** `MESHY_CREATE_RIGGING_TASK`

Start a 5-credit task that rigs a GLB character with a biped or quadruped skeleton and return the task ID. Models above 300,000 faces must be remeshed first.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional task name. |
| `model_url` | string | No | HTTP(S) URL for the GLB model to rig. Required when input_task_id is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `height_meters` | number | No | Target character height in meters; must be greater than zero. |
| `input_task_id` | string | No | Prior Meshy task containing the GLB model to rig. Required when model_url is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `animation_type` | string ("biped" | "quadruped") | No | Skeleton type to create for the character. |
| `texture_image_url` | string | No | Optional PNG texture as an HTTP(S) URL or base64 data URI. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Text to 3D Task

**Slug:** `MESHY_CREATE_TEXT_TO_3D_TASK`

Start a new Text to 3D preview or fused geometry-and-texture task and return its task ID. Preview costs 20 credits for Meshy 6/7, 5 credits for Meshy T2 or other models, and Ultra adds 5 credits; fused generation costs 30 credits for Meshy 6/7 or 15 for Meshy T2 and other models. Use REFINE_TEXT_TO_3D_TASK to texture a succeeded preview.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Optional human-readable task name. |
| `seed` | integer | No | Non-negative random seed. Use 0 to let Meshy randomize it. |
| `count` | integer | No | Number of candidates to generate, from 2 to 4. Not supported by meshy-t2 or fused generation. |
| `prompt` | string | Yes | Description of the object to generate. |
| `ai_model` | string ("meshy-5" | "meshy-6" | "meshy-7" | "latest" | "meshy-t2") | No | Meshy model to use; meshy-7 and meshy-t2 require entitlement. |
| `model_id` | string | No | Optional client-supplied identifier for batch correlation. |
| `topology` | string ("quad" | "triangle") | No | Output mesh topology. quad is not supported by meshy-t2. |
| `art_style` | string | No | Art style for the generated model. |
| `auto_size` | boolean | No | Whether Meshy should estimate the model's real-world size. |
| `origin_at` | string ("bottom" | "center") | No | Place the generated model origin at its bottom or center. |
| `pose_mode` | string ("a-pose" | "t-pose") | No | Force an A-pose or T-pose for a character model. |
| `enable_pbr` | boolean | No | Whether to produce physically based rendering texture maps. |
| `model_type` | string ("standard" | "lowpoly" | "smart-topology") | No | Generation pipeline. smart-topology selects the meshy-t2 model family. |
| `moderation` | boolean | No | Whether to run content moderation on this task. |
| `ultra_mode` | boolean | No | Enable the entitled high-detail pass for a meshy-7 preview; this consumes additional credits. |
| `experimental` | object | No | Experimental fast-mode options that may change. |
| `should_remesh` | boolean | No | Whether to remesh after draft generation; the provider default depends on the model. |
| `target_formats` | array | No | Additional model formats to export. |
| `texture_prompt` | string | No | Description of the desired texture appearance. |
| `alpha_thumbnail` | boolean | No | Whether to produce a preview thumbnail with a transparent background. |
| `decimation_mode` | integer ("1" | "2" | "3" | "4") | No | Meshy decimation algorithm selector from 1 through 4. |
| `generation_path` | string ("preview" | "fused") | Yes | Required generation path. preview creates geometry only and costs 20 credits for Meshy 6/7 or 5 for Meshy T2 and other models; fused creates geometry and texture in one task and costs 30 or 15 credits, respectively. |
| `negative_prompt` | string | No | Features or visual qualities that the generated object should avoid. |
| `target_polycount` | integer | No | Target polygon count from 100 to 300000; the provider chooses a model-specific default when omitted. |
| `texture_richness` | string ("none" | "low" | "medium" | "high") | No | Texture detail level. |
| `texture_image_url` | string | No | HTTP(S) URL of an image to use as a texture reference. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Text to Image Task

**Slug:** `MESHY_CREATE_TEXT_TO_IMAGE_TASK`

Start a credit-consuming 2D image generation task from a text prompt. The task costs 3 to 9 credits depending on the model and returns a task ID for status checks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image to generate. |
| `ai_model` | string ("nano-banana" | "nano-banana-pro" | "nano-banana-2" | "gpt-image-2") | Yes | Meshy image model to use. |
| `pose_mode` | string ("a-pose" | "t-pose") | No | Force an A-pose or T-pose; this may upgrade the model and require a higher account tier. |
| `aspect_ratio` | string ("1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3") | No | Output aspect ratio. gpt-image-2 supports 1:1, 16:9, 9:16, 3:2, and 2:3; nano-banana models support 1:1, 16:9, 9:16, 4:3, and 3:4. Do not set this for multi-view generation. |
| `remove_background` | boolean | No | Whether to return a transparent RGBA cutout. Available only for single-image generation. |
| `generate_multi_view` | boolean | No | Whether to produce one four-view split image instead of a single image. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Text to Motion Task

**Slug:** `MESHY_CREATE_TEXT_TO_MOTION_TASK`

Start an entitled motion-generation task from a text prompt and return its task ID. Prime mode costs 10 credits and the completed task produces FBX; swift mode costs 3 credits and the completed task produces BVH.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string ("prime" | "swift") | No | Generation mode: prime costs 10 credits and the completed task produces FBX; swift costs 3 credits and the completed task produces BVH. |
| `prompt` | string | Yes | Description of the motion to generate, up to 400 characters. |
| `duration` | number | Yes | Motion length from 2 to 10 seconds in 0.5-second increments. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create UV Unwrap Task

**Slug:** `MESHY_CREATE_UV_UNWRAP_TASK`

Start a 5-credit task that generates UV coordinates for a GLB model and return the task ID. High-poly models may need to be remeshed first.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model_url` | string | No | GLB HTTP(S) URL or data URI. Required when input_task_id is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |
| `input_task_id` | string | No | Prior Meshy task containing the GLB model. Required when model_url is omitted. When both sources are provided, input_task_id takes precedence and model_url is omitted from the request. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Task

**Slug:** `MESHY_DELETE_TASK`

Permanently delete a GA or Text-to-Motion task and its retained outputs. Creative Lab tasks cannot be deleted with this action; use CANCEL_CREATIVE_LAB_TASK for an active Creative Lab task.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Provider task ID to permanently delete. |
| `task_type` | string ("text_to_3d" | "image_to_3d" | "multi_image_to_3d" | "retexture" | "remesh" | "convert" | "resize" | "uv_unwrap" | "rigging" | "animation" | "text_to_image" | "image_to_image" | "print_multi_color" | "print_repair" | "print_analyze" | "print_split" | "text_to_motion") | Yes | Permanently deletable GA or Text-to-Motion task family that owns the ID; selects a fixed documented endpoint. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Credit Balance

**Slug:** `MESHY_GET_CREDIT_BALANCE`

Return the connected Meshy account's available credit balance before starting paid generation tasks.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Task

**Slug:** `MESHY_GET_TASK`

Retrieve current status, errors, and available outputs for one task from a selected Meshy task family. This read does not consume credits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Meshy task ID returned by a create or list call. |
| `task_type` | string | Yes | Task family that owns the ID. This selects one fixed documented endpoint. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Animation Library

**Slug:** `MESHY_LIST_ANIMATION_LIBRARY`

Search or filter Meshy's unpaginated animation catalog and return action IDs for use when creating animation tasks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Literal case-insensitive substring to match against animation names or keys. |
| `category` | string ("WalkAndRun" | "BodyMovements" | "DailyActions" | "Fighting" | "Dancing") | No | Exact animation category to return. |
| `action_ids` | array | No | One to 200 animation action IDs to return. Unknown IDs are omitted. |
| `sub_category` | string | No | Exact animation sub-category; the same name may occur in multiple categories. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Tasks

**Slug:** `MESHY_LIST_TASKS`

Return one page of tasks for one selected Meshy task family, with an opaque cursor for safe continuation. This read does not consume credits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sort_by` | string ("+created_at" | "-created_at") | No | Sort by creation time: +created_at for oldest first or -created_at for newest first. |
| `page_size` | integer | No | Tasks in this page. The maximum is 100 for 30 explicitly documented families. UV Unwrap, Rigging, Animation, and Text to Motion are capped at the documented and provider-accepted value 20; Text to Motion's exact provider maximum is not documented. |
| `task_type` | string | No | Exact Meshy task family to list. Required for the first page; omit it only when continuing with next_cursor. |
| `next_cursor` | string | No | Opaque cursor returned by a prior call. When continuing, send next_cursor as the only parameter. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Usage Records

**Slug:** `MESHY_LIST_USAGE_RECORDS`

Return one page of terminal API-task usage and consumed credits for the connected Meshy team. This endpoint is available only to Studio and Enterprise team API keys. Pass next_cursor alone to continue the same filtered export; split exports into windows of at most one year.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string ("SUCCEEDED" | "FAILED") | No | Terminal status to include: SUCCEEDED or FAILED. Omit to include both. |
| `sort_by` | string ("+created_at" | "-created_at") | No | Sort by creation time: +created_at for oldest first or -created_at for newest first. |
| `end_time` | string | No | End of the created_at window as an RFC3339 timestamp. Defaults to the current time. |
| `endpoints` | array | No | Endpoint families to include. Meshy receives these as one comma-separated endpoints filter; text-to-3d includes preview and refine. |
| `page_size` | integer | No | Usage records in this page, from 1 through 100. |
| `start_time` | string | No | Start of the created_at window as an RFC3339 timestamp. Defaults to 30 days before end_time. |
| `next_cursor` | string | No | Opaque cursor returned by a prior call. When continuing, send next_cursor as the only parameter; the original filters are restored from it. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Refine Text to 3D Task

**Slug:** `MESHY_REFINE_TEXT_TO_3D_TASK`

Apply texture to a succeeded Text to 3D preview and return the new refine task ID. Refinement costs 10 credits at 2k or 4k texture resolution and 15 credits at 8k.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ai_model` | string ("meshy-5" | "meshy-6" | "meshy-7" | "latest") | No | Texture model. Omit to inherit the preview task's model. |
| `auto_size` | boolean | No | Estimate the model's real-world height and resize it. |
| `origin_at` | string ("bottom" | "center") | No | Place the origin at the bottom or center when auto_size is enabled. |
| `enable_pbr` | boolean | No | Generate metallic, roughness, and normal maps in addition to base color. |
| `moderation` | boolean | No | Screen the texture prompt and reference image for harmful content. |
| `target_formats` | array | No | Model formats to generate for the textured output. |
| `texture_prompt` | string | No | Text guidance for the texture. If both texture guides are supplied, this takes precedence. |
| `alpha_thumbnail` | boolean | No | Also render a transparent-background preview thumbnail. |
| `preview_task_id` | string | Yes | ID of a succeeded Text to 3D preview task whose mesh will be textured. |
| `remove_lighting` | boolean | No | Remove highlights and shadows from base color; Meshy defaults this to true. |
| `texture_image_url` | string | No | Public HTTP(S) URL or image data URI used to guide the texture. |
| `texture_resolution` | string ("2k" | "4k" | "8k") | No | Texture resolution. Meshy defaults to 2k; 2k/4k cost 10 credits and 8k costs 15 credits. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |