Retexture API

Retexture API is a feature that allows you to integrate Meshy's AI retexturing capabilities into your own application. In this section, you'll find all the information you need to get started with this API.

POST/openapi/v1/retexture

Create a Retexture Task

This endpoint allows you to create a new Retexture task. Refer to The Retexture Task Object to see which properties are included with Retexture task object.

Parameters

Required attributes

Name
input_task_id
Type
string
Description
The ID of the completed Image to 3D or Text to 3D task you wish to retexture. This task must be one of the following tasks: Text to 3D Preview, Text to 3D Refine, Image to 3D or Remesh. In addition, it must be run using the meshy-4 or meshy-5 AI model and have a status of SUCCEEDED.
Required if model_url is not provided. If both model_url and input_task_id are provided, then input_task_id will be used by default.
Name
model_url
Type
string
Description
Provide a 3D model for Meshy to texture. Currently, we support .glb models (.glb format).
There are two ways to provide the model:
- Publicly accessible URL: A URL that is accessible from the public internet.
- Data URI: A base64-encoded data URI of the model. Example of a data URI: data:application/octet-stream;base64,<your base64-encoded model data>.
Required if input_task_id is not provided.
Meshy will validate and only accept 3D models in supported formats, passing an unsupported format with model_url will result in a 400 error.
Name
text_style_prompt
Type
string
Description
Describe your desired texture style of the object using text. Maximum 600 characters.
Required if image_style_url is not provided. If both image_style_url and text_style_prompt are provided, then image_style_url will be used to texture the model by default.
Name
image_style_url
Type
string
Description
Provide a 2d image to guide the texturing process. We currently support .jpg, .jpeg, and .png formats.
There are two ways to provide the image:
- Publicly accessible URL: A URL that is accessible from the public internet
- Data URI: A base64-encoded data URI of the image. Example of a data URI: data:image/jpeg;base64,<your base64-encoded image data>
Required if text_style_prompt is not provided. Image texturing may not work optimally if there are substantial geometry differences between the original asset and uploaded image.

Optional attributes

Name
ai_model
Type
string
Description
ID of the AI model to use for retexturing.
Available values:
- meshy-4
- meshy-5
Default to meshy-5 if not specified.
Name
enable_original_uv
Type
boolean
Description
Use the original UV of the model instead of generating new UVs. If the model has no original UV, the quality of the output might not be as good. Default to true if not specified.
Name
art_style
Type
string
Description
Describe your desired art style of the object. Default to realistic if not specified. Available values:
- realistic: Realistic style
- cartoon: Cartoon style

Returns

The result property of the response contains the task id of the newly created Retexture task.

Request

POST

/openapi/v1/retexture

## Using text texturing and input model example
curl https://api.meshy.ai/openapi/v1/retexture \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "https://cdn.meshy.ai/model/example_model_2.glb",
    "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
    "enable_original_uv": true,
    "art_style": "realistic"
  }'

 ## Using image texturing and input task example
curl https://api.meshy.ai/openapi/v1/retexture \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg",
    "enable_original_uv": true,
    "art_style": "realistic"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/retexture/:id

Retrieve a Retexture Task

This endpoint allows you to retrieve a Retexture task given a valid task id. Refer to The Retexture Task Object to see which properties are included with Retexture task object.

Parameters

Name
id
Type
path
Description
Unique identifier for the Retexture task to retrieve.

Returns

The response contains the Retexture task object. Check The Retexture Task Object section for details.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
  "texture_image_url": "",
  "art_style": "realistic",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
    }
  ],
  "task_error": {
    "message": ""
  }
}

DELETE/openapi/v1/retexture/:id

Delete a Retexture Task

This endpoint permanently deletes a retexture task, including all associated models and data. This action is irreversible.

Path Parameters

Name
id
Type
path
Description
The ID of the retexture task to delete.

Returns

Returns 200 OK on success.

Request

DELETE

/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/retexture

List Retexture Tasks

This endpoint allows you to retrieve a list of Retexture tasks.

Parameters

Optional attributes

Name
page_num
Type
integer
Description
Page number for pagination. Starts and defaults to 1.
Name
page_size
Type
integer
Description
Page size limit. Defaults to 10 items. Maximum allowed is 50 items.
Name
sort_by
Type
string
Description
Field to sort by. Available values:
- +created_at: Sort by creation time in ascending order.
- -created_at: Sort by creation time in descending order.

Returns

Returns a paginated list of The Retexture Task Objects.

Request

GET

/openapi/v1/retexture

curl https://api.meshy.ai/openapi/v1/retexture?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
    "art_style": "realistic",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      }
    ],
    "preceding_tasks": 0,
    "task_error": {
      "message": ""
    }
  }
]

GET/openapi/v1/retexture/:id/stream

Stream a Retexture Task

This endpoint streams real-time updates for a Retexture task using Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unique identifier for the Retexture task to stream.

Returns

Returns a stream of The Retexture Task Objects as Server-Sent Events.

For PENDING or IN_PROGRESS tasks, the response stream will only include necessary progress and status fields.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
  },
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  }
}

The Retexture Task Object

The Retexture Task object is a work unit that Meshy uses to generate a 3D texture from a either text or image inputs. The model has the following properties:

Properties

Name
id
Type
string
Description
Unique identifier for the task. While we use a k-sortable UUID for task ids as the implementation detail, you should not make any assumptions about the format of the id.
Name
model_urls
Type
object
Description
Downloadable URL to the textured 3D model file generated by Meshy.
- Name
  glb
  Type
  string
  Description
  Downloadable URL to the GLB file.
- Name
  fbx
  Type
  string
  Description
  Downloadable URL to the FBX file.
- Name
  usdz
  Type
  string
  Description
  Downloadable URL to the USDZ file.
Name
text_style_prompt
Type
string
Description
This is the text prompt that was used to create the texturing task.
Name
image_style_url
Type
string
Description
This is the image input that was used to create the texturing task.
Name
art_style
Type
string
Description
This is the art style that was used to guide the texturing task.
Name
thumbnail_url
Type
string
Description
Downloadable URL to the thumbnail image of the model file.
Name
progress
Type
integer
Description
Progress of the task. If the task is not started yet, this property will be 0. Once the task has succeeded, this will become 100.
Name
started_at
Type
timestamp
Description
Timestamp of when the task was started, in miliseconds. If the task is not started yet, this property will be 0.
A timestamp represents the number of milliseconds elapsed since January 1, 1970 UTC, following the RFC 3339 standard. For example, Friday, September 1, 2023 12:00:00 PM GMT is represented as 1693569600000. This applies to all timestamps in Meshy API.
Name
created_at
Type
timestamp
Description
Timestamp of when the task was created, in miliseconds.
Name
expires_at
Type
timestamp
Description
Timestamp of when the task result expires, in miliseconds.
Name
finished_at
Type
timestamp
Description
Timestamp of when the task was finished, in miliseconds. If the task is not finished yet, this property will be 0.
Name
status
Type
string
Description
Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
An array of texture URL objects that are generated from the task. Normally this only contains one texture URL object. Each texture URL has the following properties:
- Name
  base_color
  Type
  string
  Description
  Downloadable URL to the base color map image.
Name
preceding_tasks
Type
integer
Description
The count of preceding tasks.
This property only presents when the task status is PENDING.
Name
task_error
Type
object
Description
Error object that contains the error message if the task failed. The message property should be empty if the task succeeded.
- Name
  message
  Type
  string
  Description
  Detailed error message.

Example Retexture Task Model

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
  },
  "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
  "image_style_url": "https://assets.meshy.ai/***/image/example_image.jpg?Expires=***",
  "art_style": "realistic",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 1,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  }
}