## Basic model info - Model name: meshy/meshy meshy-v7 - Model description: Meshy-7 generates textured, PBR-ready 3D meshes with smart topology, target polycount controls, and optional rigging and animation. - Endpoint name: image-to-3d ## Model schema The model schema is defined in the OpenAPI schema: [OpenAPI Schema](https://oapi.sunra.ai/main/meshy/meshy-v7/latest.json) ### Model input schema The model input schema is: ```json { "properties": { "animation_action_id": { "default": 92, "description": "Animation preset ID from Meshy's library. Only used when enable_animation is true; in that case it must be in [0, 696] (``0`` is the \"Idle\" preset) and is otherwise rejected with a 422. See https://docs.meshy.ai/en/api/animation-library for available action IDs.", "title": "Animation Action Id", "type": "integer", "x-sr-order": 408 }, "enable_animation": { "default": false, "description": "Apply an animation preset to the rigged model. Requires enable_rigging to be true.", "title": "Enable Animation", "type": "boolean", "x-sr-order": 502 }, "enable_pbr": { "default": false, "description": "Generate PBR Maps (metallic, roughness, normal) in addition to base color", "title": "Enable Pbr", "type": "boolean", "x-sr-order": 501 }, "enable_rigging": { "default": false, "description": "Automatically rig the generated model as a humanoid character. Includes basic walking and running animations. Best results with humanoid characters that have clearly defined limbs.", "title": "Enable Rigging", "type": "boolean", "x-sr-order": 506 }, "geometry_resolution": { "anyOf": [ { "enum": [ "standard", "2k" ], "type": "string" }, { "type": "null" } ], "description": "Geometry resolution. Meshy-7 supports standard and 2k.", "title": "Geometry Resolution", "x-sr-order": 403 }, "image": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "string" } ], "description": "Image URL or base64 data URI for 3D model creation. Supports .jpg, .jpeg, and .png formats. Also supports AVIF and HEIF formats which will be automatically converted.", "title": "Image", "x-sr-order": 302 }, "is_a_t_pose": { "default": false, "description": "Deprecated: use pose_mode instead. When true, generates a T-pose model.", "title": "Is A T Pose", "type": "boolean", "x-sr-order": 507 }, "model_type": { "default": "standard", "description": "Type of 3D mesh generation. 'standard' produces a regular high-detail mesh; 'lowpoly' is currently rejected by Meshy-7; 'smart-topology' uses Meshy-T2 for clean, natively separated parts. When set to 'lowpoly', the remesh controls (topology, target_polycount, should_remesh) are ignored by Meshy.", "enum": [ "standard", "lowpoly", "smart-topology" ], "title": "Model Type", "type": "string", "x-sr-order": 406 }, "pose_mode": { "default": "default", "description": "Pose mode for the generated model. 'a-pose' generates an A-pose, 't-pose' generates a T-pose, empty string for no specific pose.", "enum": [ "default", "a-pose", "t-pose" ], "title": "Pose Mode", "type": "string", "x-sr-order": 405 }, "rigging_height_meters": { "default": 1.7, "description": "Approximate height of the character in meters. Only used when enable_rigging is true.", "exclusiveMinimum": 0, "title": "Rigging Height Meters", "type": "number", "x-sr-order": 402 }, "should_remesh": { "default": true, "description": "Whether to enable the remesh phase", "title": "Should Remesh", "type": "boolean", "x-sr-order": 503 }, "should_texture": { "default": true, "description": "Whether to generate textures", "title": "Should Texture", "type": "boolean", "x-sr-order": 504 }, "symmetry_mode": { "default": "auto", "description": "Controls symmetry behavior during model generation. Off disables symmetry, Auto determines it automatically, On enforces symmetry.", "enum": [ "off", "auto", "on" ], "title": "Symmetry Mode", "type": "string", "x-sr-order": 401 }, "target_polycount": { "default": 30000, "description": "Target number of polygons in the generated model. When model_type is 'smart-topology' and this is left unset, Meshy's lower smart-topology default (4,000) is used instead; smart topology accepts at most 15,000.", "maximum": 300000, "minimum": 100, "title": "Target Polycount", "type": "integer", "x-sr-order": 404 }, "texture_image": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "string" }, { "type": "null" } ], "description": "2D image to guide the texturing process", "title": "Texture Image", "x-sr-order": 301 }, "texture_prompt": { "anyOf": [ { "maxLength": 600, "type": "string" }, { "type": "null" } ], "description": "Text prompt to guide the texturing process", "title": "Texture Prompt", "x-sr-order": 201 }, "topology": { "default": "triangle", "description": "Specify the topology of the generated model. Quad for smooth surfaces, Triangle for detailed geometry.", "enum": [ "quad", "triangle" ], "title": "Topology", "type": "string", "x-sr-order": 407 }, "ultra_mode": { "default": false, "description": "Deprecated: use geometry_resolution='2k'. If both fields are provided, geometry_resolution takes precedence.", "title": "Ultra Mode", "type": "boolean", "x-sr-order": 505 } }, "required": [ "image" ], "title": "ImageTo3DInput", "type": "object" } ``` ### Model output schema The model output schema is: ```json { "properties": { "animation": { "anyOf": [ { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" }, { "type": "null" } ] }, "model": { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" }, "rigged_model": { "anyOf": [ { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" }, { "type": "null" } ] }, "score": { "description": "Request cost in USD", "exclusiveMinimum": 0, "title": "Score", "type": "number" }, "thumbnail": { "anyOf": [ { "properties": { "content_type": { "description": "The mime type of the file.", "title": "Content Type", "type": "string" }, "file_name": { "description": "The name of the file. It will be auto-generated if not provided.", "title": "File Name", "type": "string" }, "file_size": { "description": "The size of the file in bytes.", "title": "File Size", "type": "integer" }, "url": { "description": "The URL where the file can be downloaded from.", "title": "Url", "type": "string" } }, "required": [ "content_type", "file_name", "file_size", "url" ], "title": "SunraFile", "type": "object" }, { "type": "null" } ] } }, "required": [ "model", "score" ], "title": "MeshyV7Output", "type": "object" } ``` ## Example inputs and outputs Use the following example inputs and outputs to understand the model. ### Input example ```json { "animation_action_id": 92, "enable_animation": false, "enable_pbr": false, "enable_rigging": false, "geometry_resolution": null, "image": "", "is_a_t_pose": false, "model_type": "standard", "pose_mode": "default", "rigging_height_meters": 1.7, "should_remesh": true, "should_texture": true, "symmetry_mode": "auto", "target_polycount": 30000, "texture_image": null, "texture_prompt": null, "topology": "triangle", "ultra_mode": false } ``` ### Output example ```json { } ``` ## Model code examples ### JavaScript ```javascript import { sunra } from "@sunra/client"; const result = await sunra.subscribe("meshy/meshy-v7/image-to-3d", { input: { texture_prompt: null, texture_image: null, image: '', symmetry_mode: 'auto', rigging_height_meters: 1.7, geometry_resolution: null, target_polycount: 30000, pose_mode: 'default', model_type: 'standard', topology: 'triangle', animation_action_id: 92, enable_pbr: false, enable_animation: false, should_remesh: true, should_texture: true, ultra_mode: false, enable_rigging: false, is_a_t_pose: false }, logs: true, onQueueUpdate: (update) => { console.log(`Status Update: ${update.status}, Request ID: ${update.request_id}`); }, }); console.log(result.data); console.log(result.requestId); ``` ### Python ```python import sunra_client result = sunra_client.subscribe( "meshy/meshy-v7/image-to-3d", arguments={ "texture_prompt": None, "texture_image": None, "image": "", "symmetry_mode": "auto", "rigging_height_meters": 1.7, "geometry_resolution": None, "target_polycount": 30000, "pose_mode": "default", "model_type": "standard", "topology": "triangle", "animation_action_id": 92, "enable_pbr": False, "enable_animation": False, "should_remesh": True, "should_texture": True, "ultra_mode": False, "enable_rigging": False, "is_a_t_pose": False }, with_logs=True, on_enqueue=print, on_queue_update=print, ) print(result) ``` ### Java ```java import ai.sunra.client.*; import java.util.Map; import com.google.gson.JsonObject; var client = SunraClient.withEnvCredentials(); var response = client.subscribe( "meshy/meshy-v7/image-to-3d", SubscribeOptions.builder() .input(Map.of( "texture_prompt", null, "texture_image", null, "image", "", "symmetry_mode", "auto", "rigging_height_meters", 1.7, "geometry_resolution", null, "target_polycount", 30000, "pose_mode", "default", "model_type", "standard", "topology", "triangle", "animation_action_id", 92, "enable_pbr", false, "enable_animation", false, "should_remesh", true, "should_texture", true, "ultra_mode", false, "enable_rigging", false, "is_a_t_pose", false)) .resultType(JsonObject.class) .onQueueUpdate(update -> System.out.printf( "\nStatus Update: %s, Request ID: %s%n", update.getStatus(), update.getRequestId() )) .logs(true) .build() ); System.out.println("Completed!"); System.out.println(response.getData()); ``` ### Kotlin ```kotlin import ai.sunra.client.kt.* import com.google.gson.JsonObject val client = createSunraClient() val response = client.subscribe( endpointId = "meshy/meshy-v7/image-to-3d", input = mapOf( "texture_prompt" to null, "texture_image" to null, "image" to "", "symmetry_mode" to "auto", "rigging_height_meters" to 1.7, "geometry_resolution" to null, "target_polycount" to 30000, "pose_mode" to "default", "model_type" to "standard", "topology" to "triangle", "animation_action_id" to 92, "enable_pbr" to false, "enable_animation" to false, "should_remesh" to true, "should_texture" to true, "ultra_mode" to false, "enable_rigging" to false, "is_a_t_pose" to false), options = ai.sunra.client.kt.SubscribeOptions(logs = true), onUpdate = { update -> println("\nStatus Update: ${update.status}, Request ID: ${update.requestId}") } ) println("Completed!") println(response.data) ``` ### Curl ```bash curl --request POST \ --url https://api.sunra.ai/v1/queue/meshy/meshy-v7/image-to-3d \ --header "Authorization: Key $SUNRA_KEY" \ --header "Content-Type: application/json" \ --data '{"texture_prompt":null,"texture_image":null,"image":"","symmetry_mode":"auto","rigging_height_meters":1.7,"geometry_resolution":null,"target_polycount":30000,"pose_mode":"default","model_type":"standard","topology":"triangle","animation_action_id":92,"enable_pbr":false,"enable_animation":false,"should_remesh":true,"should_texture":true,"ultra_mode":false,"enable_rigging":false,"is_a_t_pose":false}' ``` ## Model readme > Text, one image, or 1–4 views of one object. Set mode=preview for untextured text generation, or should_texture=false for untextured image generation. Meshy-7 currently rejects the upstream lowpoly option. Geometry resolution 2k requires standard model_type; smart-topology accepts at most 15,000 target polygons and uses a 4,000-polygon default when omitted. > > The model field prefers GLB. thumbnail is a preview image. With optional rigging/animation enabled, rigged_model and animation contain the corresponding GLB files when provided by the upstream model; an ordinary mesh does not contain a usable rig or animation. Animation requires enable_rigging=true. > > Submit with POST https://api.sunra.ai/v1/queue/meshy/meshy-v7/ and Authorization: Key . Poll GET /v1/queue/requests/{request_id}/status, then fetch GET /v1/queue/requests/{request_id}. Generation is asynchronous and can take several minutes; do not resubmit a pending request. Failed requests expose an error; correct invalid inputs before retrying. > > Every returned file has a download URL, content type, name, and size. Download and retain assets needed for long-term use; the API does not promise a permanent URL lifetime. score is the request's USD billing quantity; the settled billing block reports the actual charge. See the endpoint price ladder for generation options and add-ons.