# meshy/relief

> 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.

## Overview

- **Endpoint**: `https://api.wavespeed.ai/api/v3/meshy/relief`
- **Polling/result URL**: `https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result`
- **Model ID**: `meshy/relief`
- **Category**: image-to-3d

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
The API is asynchronous: submit a prediction, then poll its result URL until it completes.

### Input Schema

The API accepts the following input parameters:

- **`image`** (`string`, _required_):
  Photo to turn into a relief (JPEG, PNG or WebP, at least 32 x 32 px, up to 20 MB).

- **`variant`** (`string`, _optional_):
  Relief style; sets the default carving depth (low 3 mm, high 6 mm).
  - Default: `"low"`
  - Options: "low", "high"

- **`should_generate_model`** (`boolean`, _optional_):
  Turn off to get only the 16-bit depth map, with no model files. The price is the same.
  - Default: `true`

- **`size_mm`** (`number`, _optional_):
  Length of the photo's longer side on the model, in mm, measured flat before any bend.
  - Default: `60`
  - Range: `20` to `250`

- **`carving_mode`** (`string`, _optional_):
  emboss raises the subject from the plate; engrave cuts the nearer parts in.
  - Default: `"emboss"`
  - Options: "emboss", "engrave"

- **`carving_depth_mm`** (`number`, _optional_):
  Carving depth in mm (0-60). Default follows variant.
  - Range: `0` to `60`

- **`remove_base`** (`boolean`, _optional_):
  Cut away the background and build no base plate.
  - Default: `false`

- **`removal_threshold`** (`number`, _optional_):
  Depth below which the background is cut (used with remove_base).
  - Default: `0.01`
  - Range: `0.01` to `1`

- **`base_thickness_mm`** (`number`, _optional_):
  Base plate thickness in mm (0.1-10). Leave unset with remove_base.
  - Range: `0.1` to `10`

- **`bend_mode`** (`string`, _optional_):
  Bend the relief: convex bulges the front outward, concave curves it inward.
  - Default: `"off"`
  - Options: "off", "convex", "concave"

- **`bend_axis`** (`string`, _optional_):
  xz curls the left and right edges, yz the top and bottom (with bend_mode convex or concave).
  - Default: `"xz"`
  - Options: "xz", "yz"

- **`bend_angle`** (`number`, _optional_):
  Arc the bend spans, in degrees (0-360).
  - Default: `60`
  - Range: `0` to `360`

- **`mesh_resolution`** (`integer`, _optional_):
  Mesh points along the longer side (512-2048). Higher keeps more detail and makes larger files.
  - Default: `1024`
  - Range: `512` to `2048`



**Required Parameters Example**:

```json
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
}
```

**Full Example**:

```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",
  "carving_depth_mm": 0,
  "remove_base": false,
  "removal_threshold": 0.01,
  "base_thickness_mm": 0.1,
  "bend_mode": "off",
  "bend_axis": "xz",
  "bend_angle": 60,
  "mesh_resolution": 1024
}
```

### Result Data Schema

The `data` object returned by the API has the following fields:

- **`created_at`** (`string (date-time)`, _optional_):
  ISO timestamp of when the request was created (e.g., "2023-04-01T12:34:56.789Z").

- **`id`** (`string`, _optional_):
  Unique identifier for the prediction, the ID of the prediction to get.

- **`model`** (`string`, _optional_):
  Model ID used for the prediction.

- **`outputs`** (`array of string | object`, _optional_):
  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.

- **`status`** (`string`, _optional_):
  Status of the task: created, processing, completed, or failed.

- **`urls`** (`object`, _optional_):
  Object containing related API endpoints.



**Example `data` Object**:

```json
{
  "created_at": "example",
  "id": "example",
  "model": "example",
  "outputs": [],
  "status": "example",
  "urls": {}
}
```

## Usage Examples

The examples use `jq` to read JSON. Set your API key first:

```bash
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
```

### 1. Submit a prediction

```bash
REQUEST_BODY=$(cat <<'JSON'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.wavespeed.ai/api/v3/meshy/relief \
  --header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "${REQUEST_BODY}")

printf '%s\n' "${SUBMIT_RESPONSE}" | jq .
```

The response contains the prediction ID in `data.id`.

### 2. Poll until complete and read `outputs`

```bash
PREDICTION_ID=$(printf '%s' "${SUBMIT_RESPONSE}" | jq -r '.data.id')
if [ -z "${PREDICTION_ID}" ] || [ "${PREDICTION_ID}" = "null" ]; then
  printf 'Submission response did not contain data.id\n' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    --request GET \
    --url "${RESULT_URL}" \
    --header "Authorization: Bearer ${WAVESPEED_API_KEY}")

  RESULT=$(printf '%s' "${RESPONSE}" | jq -e '.data')
  STATUS=$(printf '%s' "${RESULT}" | jq -er '.status')
  case "${STATUS}" in
    completed)
      # Generated files are returned in the outputs array.
      printf '%s\n' "${RESULT}" | jq '.outputs'
      break
      ;;
    failed|cancelled|timeout|deleted)
      printf '%s\n' "${RESULT}" | jq '{status, error, code}'
      exit 1
      ;;
    *)
      sleep 2
      ;;
  esac
done
```

## Additional Resources

### Documentation

- [Model Playground](https://wavespeed.ai/models/meshy/relief)
- [API Documentation](https://wavespeed.ai/docs/docs-api/meshy/meshy-relief)