Meshy V7.1 Image To 3d API Documentation

Playground

Meshy 7.1 Image-to-3D turns a single image into a textured 3D model. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Meshy 7.1 Image-to-3D generates a 3D model from a single image. Choose geometry-only or textured output, adjust mesh settings, and optionally add rigging or an animation to a humanoid character.

Why Choose This?

Flexible output — Generate geometry alone or add textures.
Mesh controls — Choose remeshing settings and a target face count.
Texture options — Guide texturing with a description or reference image.
Optional character animation — Add rigging and one animation action to a suitable humanoid model.

Parameters

Parameter	Required	Description
image	Yes	Image of the object to generate (JPEG, PNG or WebP).
model_type	No	Choose `standard` or `smart-topology`. Smart Topology creates a lower-poly, triangle-only mesh. Default: `standard`.
geometry_resolution	No	Geometry detail: `standard`, `2k` or `4k`. Default: `standard`. Use `standard` with Smart Topology.
should_texture	No	Generate textures for the model. Default: `true`. Turn off for geometry only.
texture_prompt	No	Optional text description to guide the texture.
texture_image	No	Optional image to guide the texture. If both texture references are supplied, `texture_prompt` takes priority.
enable_pbr	No	Request metallic, roughness and normal maps when generating textures. Default: `false`.
texture_resolution	No	Texture size: `2k`, `4k` or `8k`. Applies when textures are generated. Default: `2k`.
topology	No	Remeshed face type: `triangle` or `quad`. Default: `triangle`. Smart Topology uses triangles.
target_polycount	No	Target face count for remeshing: `100–300000`. Default: `30000`. Smart Topology uses `100–30000`.
should_remesh	No	Remesh toward the selected face count and topology. Default: `true`. Does not apply to Smart Topology.
symmetry_mode	No	Compatibility setting with no effect on the result. Options: `off`, `auto`, `on`. Default: `auto`.
pose_mode	No	Optional character pose: `a-pose` or `t-pose`.
remove_lighting	No	Optional lighting-removal setting. See Notes for availability.
auto_size	No	Estimate the object’s real-world size and scale it accordingly. Default: `false`.
image_enhancement	No	Optional input-image enhancement. Leave unset in Smart Topology mode.
enable_rigging	No	Add a skeleton to a textured humanoid character. Default: `false`.
rigging_height_meters	No	Approximate character height in meters for rigging. Default: `1.7`.
enable_animation	No	Rig the character and apply one action selected by `animation_action_id`. Default: `false`.
animation_action_id	No	Animation action ID to apply when animation is enabled. Default: `92`.

How to Use

Upload an image of the object you want to create.
Choose geometry-only or textured output and adjust the mesh settings.
For a humanoid character, optionally enable rigging or animation.
Submit the request and download the generated 3D files.

Pricing

Generation option	Price per request
Standard · Geometry only	$0.96
Standard · With 2k or 4k textures	$1.44
Standard · With 8k textures	$1.68
Smart Topology · Geometry only	$0.24
Smart Topology · With 2k or 4k textures	$0.72
Smart Topology · With 8k textures	$0.96

Optional addition	Extra charge
Ultra geometry in standard mode	$0.24
Rigging	$0.24
One animation action, excluding rigging	$0.144

Enabling animation also includes rigging, for a total extra charge of $0.384. Enabling both rigging and animation does not charge for rigging twice.

The total is the generation price plus the selected additions. Texture resolution does not add a charge when generating geometry only.

Notes

With should_texture=false, texture options are not applied.
Use either texture_prompt or texture_image to guide texturing. If both are provided, the text prompt takes priority.
The generated face count may differ from target_polycount.
Rigging and animation are intended for textured humanoid characters with clearly defined limbs. They are not suitable for untextured meshes or non-humanoid objects.
Rigging supports up to 380,000 triangles; each quad counts as two triangles.
When animation is enabled, one animation action is added to the character.
Smart Topology uses triangle faces and a target face count of 100–30,000. The target applies directly; should_remesh does not affect this mode.
Use geometry_resolution=standard with Smart Topology.
Leave remove_lighting unset for this model.
Leave image_enhancement and remove_lighting unset in Smart Topology mode.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "model_type": "standard",
  "geometry_resolution": "standard",
  "should_texture": true,
  "enable_pbr": false,
  "texture_resolution": "2k",
  "topology": "triangle",
  "target_polycount": 30000,
  "should_remesh": true,
  "symmetry_mode": "auto",
  "pose_mode": "a-pose",
  "auto_size": false,
  "enable_rigging": false,
  "rigging_height_meters": 1.7,
  "enable_animation": false,
  "animation_action_id": 92
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/meshy/v7.1/image-to-3d" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Retry temporary errors only while polling, never the submit request. Errors, retries and timeouts

Parameters

Task Submission Parameters

Request Parameters

Parameter	Type	Required	Default	Range	Description
image	string	Yes		-	Image of the object (JPEG, PNG or WebP).
model_type	string	No	standard	standard, smart-topology	smart-topology builds a clean low-poly mesh (Meshy T2.5); cheaper, no quad topology.
geometry_resolution	string	No	standard	standard, 2k, 4k	Geometry detail: standard or Ultra (2k / 4k).
should_texture	boolean	No	true	-	Texture the model. Turn off for an untextured mesh at a lower price.
texture_prompt	string	No	-	-	Optional description of the texture.
texture_image	string	No	-	-	Optional reference image for the texture. Takes priority over texture_prompt.
enable_pbr	boolean	No	false	-	Generate PBR maps (metallic, roughness, normal).
texture_resolution	string	No	2k	2k, 4k, 8k	Texture resolution: 2k, 4k or 8k (8k costs more).
topology	string	No	triangle	triangle, quad	Mesh topology.
target_polycount	integer	No	30000	100 ~ 300000	Target number of polygons (used when should_remesh is on).
should_remesh	boolean	No	true	-	Remesh to the target polycount and topology.
symmetry_mode	string	No	auto	off, auto, on	No longer has an effect; kept for compatibility.
pose_mode	string	No	-	a-pose, t-pose	Generate characters in an A-pose or T-pose (useful before rigging).
remove_lighting	boolean	No	-	-	Remove baked-in lighting from the textures.
auto_size	boolean	No	false	-	Estimate the real-world size of the object and scale the model to it.
image_enhancement	boolean	No	-	-	Enhance the input image before generation.
enable_rigging	boolean	No	false	-	Rig the generated character (humanoids). The rigged model is returned after the model.
rigging_height_meters	number	No	1.7	-	Character height in meters used for rigging.
enable_animation	boolean	No	false	-	Rig and animate the character with animation_action_id. The animated model is returned last.
animation_action_id	integer	No	92	-	Animation from the Meshy animation library (https://docs.meshy.ai/en/api/animation-library) applied when enable_animation is on.

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Parameter	Type	Description
code	integer	HTTP status code (e.g., 200 for success)
message	string	Status message (e.g., “success”)
data.id	string	Unique identifier for the prediction, Task Id
data.model	string	Model ID used for the prediction
data.outputs	array	Output values, usually URL strings; some models return text strings or structured result objects (empty when status is not `completed`)
data.urls	object	Object containing related API endpoints
data.status	string	Task status. `completed` is successful; `failed`, `cancelled`, `timeout`, and `deleted` are failure terminal statuses.
data.created_at	string	ISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”)
data.error	string	Error message (empty if no error occurred)
data.timings	object	Object containing timing details
data.timings.inference	integer	Inference time in milliseconds

Result Request Parameters

Parameter	Type	Required	Default	Description
id	string	Yes	-	Task ID

Result Response Parameters

Parameter	Type	Description
code	integer	HTTP status code (e.g., 200 for success)
message	string	Status message (e.g., “success”)
data	object	The prediction data object containing all details
data.id	string	Unique identifier for the prediction
data.model	string	Model ID used for the prediction
data.outputs	array<string \| object>	Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.
data.urls	object	Object containing related API endpoints
data.status	string	Status: `completed` is successful; `failed`, `cancelled`, `timeout`, and `deleted` are failure terminal statuses
data.created_at	string	ISO timestamp of when the request was created
data.error	string	Error message (empty if no error occurred)
data.timings	object	Object containing timing details
data.timings.inference	integer	Inference time in milliseconds

Overview