Meshy N1 Retexture API Documentation

Playground

Meshy N1 Retexture applies new textures to existing 3D models using reference images, enabling reference-guided material and style transfer for game assets, product visualization, 3D design, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Meshy N1 Retexture generates a new texture for an existing 3D model from one to four reference images. Explore materials, colors and surface details that match a picture, and keep the model’s UV layout if you want.

Why Choose This?

Image-guided texturing — Match the look of one to four reference images.
Keep your UVs — Reuse the model’s existing UV layout or generate a new one.
Simple pricing — One price per request.

Parameters

Parameter	Required	Description
model	Yes	The 3D model to texture (GLB, GLTF, FBX, OBJ or STL).
texture_image	No	One reference image for the texture style. Use this or `images`.
images	No	One to four reference images of the object. Use this or `texture_image`.
enable_original_uv	No	Reuse the model’s existing UV layout. Default: `true`.

How to Use

Upload the 3D model you want to texture.
Provide one reference image (texture_image) or one to four (images).
Choose whether to reuse the model’s UV layout.
Submit the request and download the textured model.

Pricing

Output	Price per model
2k base color texture	$0.40

The reference images and the UV setting do not add separate charges.

Notes

N1 textures from images only: it does not take a text prompt, PBR maps or other texture sizes. The base color texture is 2k.
Provide either texture_image or images, not both.
For multiple reference images, use different views of the same object. The first image is the main front view; the remaining views can be in any order.
A reference image with a substantially different object shape may be harder to match to the model.

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'
{
  "model": "example",
  "enable_original_uv": true
}
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/n1/retexture" \
  -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
model	string	Yes	-	-	The 3D model to texture (GLB, GLTF, FBX, OBJ or STL).
texture_image	string	No	-	-	One reference image for the texture style. Use this or images.
images	array<string>	No	-	0 ~ 4 items	1 to 4 reference images of the object. Use this or texture_image.
enable_original_uv	boolean	No	true	-	Reuse the model's existing UV layout.

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