Meshy Relief API Documentation

Playground

Meshy Relief converts photos into embossed or engraved 3D reliefs, making it suitable for decorative models, plaques, medallions, 3D printing, and design workflows, with support for standard 3D and depth-map outputs. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Meshy Relief turns a photo into a relief: a flat plate with the subject raised (emboss) or cut in (engrave), for 3D printing and CNC workflows. Download a GLB, a binary STL in millimeters, and the 16-bit depth map.

Why Choose This?

Photo to relief — Create a relief model from one image.
Carving controls — Emboss or engrave, with depth, size and base thickness in millimeters.
Cut-out and bend — Remove the background plate, or curl the relief into a convex or concave arc.
Depth map only — Skip the model and get just the depth map at the same price.

Parameters

Parameter	Required	Description
image	Yes	Photo to convert (JPEG, PNG or WebP, at least 32 x 32 px, up to 20 MB).
variant	No	`low` or `high` relief style; sets the default carving depth (3 mm or 6 mm). Default: `low`.
should_generate_model	No	Set to `false` to return only the depth map. Default: `true`.
size_mm	No	Length of the photo’s longer side on the model, `20-250` mm. Default: `60`.
carving_mode	No	`emboss` or `engrave`. Default: `emboss`.
carving_depth_mm	No	Carving depth, `0-60` mm.
remove_base	No	Cut away the background and build no base plate. Default: `false`.
removal_threshold	No	Depth below which the background is cut, `0.01-1`. Used with `remove_base`. Default: `0.01`.
base_thickness_mm	No	Base plate thickness, `0.1-10` mm. Leave unset with `remove_base`.
bend_mode	No	`off`, `convex` or `concave`. Default: `off`.
bend_axis	No	`xz` curls the left and right edges; `yz` the top and bottom. Default: `xz`.
bend_angle	No	Arc of the bend in degrees, `0-360`. Default: `60`.
mesh_resolution	No	Mesh points along the longer side, `512-2048`. Default: `1024`.

How to Use

Upload the photo you want to turn into a relief.
Choose emboss or engrave, the size and the carving depth.
Optionally cut away the background or bend the plate.
Submit the request and download the GLB, STL and depth map.

Pricing

Output	Price per request
Relief (model and depth map, or depth map only)	$0.80

Notes

The outputs are the GLB (no texture, in meters), the STL (millimeters, Z up) and the 16-bit grayscale depth map. A depth-map-only request returns only the depth map.
Higher mesh_resolution makes much larger files: about 40-50 MB GLB and 80-105 MB STL at 1024, and about 150 MB and 300 MB at 2048. A bend can push the STL much higher.
With remove_base on, a carving depth of 0 gives an empty model that still succeeds and is charged.

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",
  "variant": "low",
  "should_generate_model": true,
  "size_mm": 60,
  "carving_mode": "emboss",
  "remove_base": false,
  "removal_threshold": 0.01,
  "bend_mode": "off",
  "bend_axis": "xz",
  "bend_angle": 60,
  "mesh_resolution": 1024
}
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/relief" \
  -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		-	Photo to turn into a relief (JPEG, PNG or WebP, at least 32 x 32 px, up to 20 MB).
variant	string	No	low	low, high	Relief style; sets the default carving depth (low 3 mm, high 6 mm).
should_generate_model	boolean	No	true	-	Turn off to get only the 16-bit depth map, with no model files. The price is the same.
size_mm	number	No	60	20 ~ 250	Length of the photo's longer side on the model, in mm, measured flat before any bend.
carving_mode	string	No	emboss	emboss, engrave	emboss raises the subject from the plate; engrave cuts the nearer parts in.
carving_depth_mm	number	No	-	0 ~ 60	Carving depth in mm (0-60). Default follows variant.
remove_base	boolean	No	false	-	Cut away the background and build no base plate.
removal_threshold	number	No	0.01	0.01 ~ 1	Depth below which the background is cut (used with remove_base).
base_thickness_mm	number	No	-	0.1 ~ 10	Base plate thickness in mm (0.1-10). Leave unset with remove_base.
bend_mode	string	No	off	off, convex, concave	Bend the relief: convex bulges the front outward, concave curves it inward.
bend_axis	string	No	xz	xz, yz	xz curls the left and right edges, yz the top and bottom (with bend_mode convex or concave).
bend_angle	number	No	60	0 ~ 360	Arc the bend spans, in degrees (0-360).
mesh_resolution	integer	No	1024	512 ~ 2048	Mesh points along the longer side (512-2048). Higher keeps more detail and makes larger files.

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