Retexture API

Retexture API 是一項功能，可讓你將 Meshy 的 AI 重新貼圖能力整合到你自己的應用程式中。在本節中，你將會找到開始使用此 API 所需的全部資訊。

POST/openapi/v1/retexture

建立 Retexture 任務

此端點允許你建立一個新的 Retexture 任務。請參閱 Retexture 任務物件以了解 Retexture 任務物件包含哪些屬性。

參數

input_task_id 和 model_url 中只有一個是必需的。如果兩者都提供了，input_task_id 優先。

Name
input_task_id
Type
string
必選
Description
你希望重新貼圖的已完成影象生成 3D 或文字生成 3D 任務的 ID。該任務必須是以下任務之一：Text to 3D Preview、Text to 3D Refine、影象生成 3D 或重構網格。此外，其狀態必須為 SUCCEEDED。

Name
model_url
Type
string
必選
Description
提供一個供 Meshy 貼圖的 3D 模型。支援的格式：.glb、.gltf、.obj、.fbx、.stl。
提供模型有兩種方式：
- 可公開存取的 URL：可從公共網際網路存取的 URL。
- Data URI：模型的 base64 編碼資料 URI。使用 MIME type application/octet-stream。範例：data:application/octet-stream;base64,<your base64-encoded model data>。

必須恰好提供一個樣式輸入：text_style_prompt、image_style_url 或 multiview_image_urls。multiview_image_urls 不能與另外兩者中的任何一個同時使用；如果同時提供了 text_style_prompt 和 image_style_url，則 image_style_url 優先。

Name
text_style_prompt
Type
string
必選
Description
使用文字描述你希望的物體貼圖樣式。最多 800 個字元。

Name
image_style_url
Type
string
必選
Description
提供一張 2D 圖片以指導貼圖過程。目前支援 .jpg、.jpeg 和 .png 格式。
提供圖片有兩種方式：
- 可公開存取的 URL：可從公共網際網路存取的 URL
- Data URI：圖片的 base64 編碼資料 URI。資料 URI 範例：data:image/jpeg;base64,<your base64-encoded image data>
如果原始資產與上傳圖片之間存在較大的 geometry 差異，圖片貼圖效果可能不理想。

Name
multiview_image_urls
Type
string[]
必選
Description
提供 1 到 4 張從不同視角展示同一物體的圖片以指導貼圖。第一張圖片為主視圖（正面），其餘視圖（左、後、右）的順序不做要求。
每個元素接受與 image_style_url 相同的格式（可公開存取的 URL 或 base64 data URI，.jpg/.jpeg/.png）。
需要明確指定 ai_model: "meshy-7"。

Name
ai_model
Type
string
預設值 latest
Description
用於重新貼圖的 AI 模型 ID。可用值：meshy-5、meshy-6、meshy-7、latest（Meshy 7）。
Name
enable_original_uv
Type
boolean
預設值 false
Description
保留模型現有的 UV 佈局，而不是產生新的佈局。
- 如果你要重新貼圖的是 Meshy 產生的模型（透過 input_task_id，或指向 Meshy 輸出的 model_url），將其設為 true 以重複使用其經過最佳化的 UV 佈局。
- 如果你要重新貼圖的是自行上傳的第三方模型，當它已經擁有你想保留的良好 UV 時設為 true；否則保留 false，讓 Meshy 重新展開全新的 UV（最適合缺乏合適 UV 映射的模型）。
Name
enable_pbr
Type
boolean
預設值 false
Description
除基礎顏色外，還產生 PBR 貼圖（金屬度、粗糙度、法線）。當 ai_model 為 meshy-6 時還會包含自發光貼圖，但 texture_resolution: 8k 時除外。meshy-7 和 latest 不產生自發光貼圖。
Name
texture_resolution
Type
string
預設值 2k
Description
基礎顏色 texture 解析度。可選 2k（2048×2048）、4k（4096×4096）或 8k（8192×8192）。解析度越高，擷取的表面細節越多。
4k 和 8k 需要 ai_model 為 meshy-6、meshy-7 或 latest。在 8k 下不會產生自發光貼圖。
Name
hd_texture
Type
boolean
⚠ 已棄用
預設值 false
Description
請改用 texture_resolution——等同於 texture_resolution: "4k"。當兩者同時設定時，以 texture_resolution 為準。
Name
remove_lighting
Type
boolean
預設值 true
Description
從基礎顏色 texture 中移除高光和陰影，產生更乾淨的效果，在自訂燈光設定下表現更佳。
僅當 ai_model 為 meshy-6 時支援。
Name
target_formats
Type
string[]
Description
指定輸出中要包含的 3D 檔案格式。僅會產生並回傳所請求的格式，這可以縮短任務完成時間。省略時，將包含所有支援的格式。
可用值：glb、obj、fbx、stl、usdz、3mf
省略時，會產生除 3mf 之外的所有格式。只有明確指定時才會包含 3mf。
Name
alpha_thumbnail
Type
boolean
預設值 false
Description
設為 true 時，任務會額外渲染一個透明背景（RGBA）版本的預覽圖，並在 GET 回應中以 alpha_thumbnail_url 回傳。現有的 thumbnail_url 欄位保持不變。

回傳值

回應的 result 屬性包含新建立的 Retexture 任務的 id。

失敗模式

Name
400 - Bad Request
Description
請求無法被接受。常見原因：
- 缺少參數：必須提供 model_url 或 input_task_id 之一。
- 缺少樣式：必須提供 text_style_prompt、image_style_url 或 multiview_image_urls 中的一個。
- 樣式輸入衝突：multiview_image_urls 不能與 text_style_prompt 或 image_style_url 同時使用。
- 多視圖不支援的模型：multiview_image_urls 需要明確指定 ai_model: "meshy-7"。
- 模型不可用：ai_model: "meshy-7" 正在逐步推出，你的帳戶尚未啟用該功能。
- 輸入任務無效：input_task_id 必須指向來自受支援模型的成功任務。
- 模型格式無效：model_url 指向的檔案副檔名不受支援。
- URL 無法存取：無法下載 model_url、image_style_url 或 multiview_image_urls 中的某個元素。
Name
401 - Unauthorized
Description
身份驗證失敗。請檢查你的 API 金鑰。
Name
402 - Payment Required
Description
積分不足，無法執行此任務。
Name
429 - Too Many Requests
Description
你已超出速率限制。

Request

POST

/openapi/v1/retexture

# Retexture with text prompt
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,
    "enable_pbr": true
  }'

# Retexture with image style and PBR
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",
    "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg",
    "ai_model": "latest",
    "enable_pbr": true,
    "enable_original_uv": true
  }'

Response

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

GET/openapi/v1/retexture/:id

取得一個 Retexture 任務

此 endpoint 允許你根據有效的任務 id 取得一個 Retexture 任務。請參閱 The Retexture Task Object 以了解 Retexture 任務物件包含哪些屬性。

參數

Name
id
Type
path
Description
要取得的 Retexture 任務的唯一識別碼。

回傳

回應內容包含 Retexture 任務物件。詳情請查看 The Retexture Task Object 部分。

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",
  "type": "retexture",
  "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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?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": "",
  "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=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "task_error": {

    "message": ""

  },

  "consumed_credits": 10
}

DELETE/openapi/v1/retexture/:id

刪除 Retexture 任務

此 endpoint 將永久刪除一個 retexture 任務，包括所有相關聯的模型和資料。此操作不可逆。

路徑參數

Name
id
Type
path
Description
要刪除的 retexture 任務的 ID。

回傳

成功時回傳 200 OK。

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

取得 Retexture 任務列表

此端點允許您取得 Retexture 任務的列表。

參數

Name
page_num
Type
integer
預設值 1
Description
用於分頁的頁碼。
Name
page_size
Type
integer
預設值 10
Description
每頁數量限制。允許的最大值為 50 項。
Name
sort_by
Type
string
Description
用於排序的欄位。
可用值：
- +created_at：依建立時間升冪排序。
- -created_at：依建立時間降冪排序。

回傳

回傳一個分頁的Retexture 任務物件列表。

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",
    "type": "retexture",
    "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",
    "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=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 10
  }
]

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

流式取得 Retexture 任務

該 endpoint 使用 Server-Sent Events（SSE）串流傳輸 Retexture 任務的即時更新。

參數

Name
id
Type
path
Description
要串流傳輸的 Retexture 任務的唯一識別碼。

回傳

以 Server-Sent Events 的形式回傳一個 Retexture 任務物件串流。

對於 PENDING 或 IN_PROGRESS 狀態的任務，回應串流將僅包含必要的 progress 和 status 欄位。

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",
  "type": "retexture",
  "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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 10
}

Retexture 任務物件

Retexture 任務物件是 Meshy 用於根據文字或圖像輸入產生 3D texture 的工作單元。此模型具有以下屬性：

屬性

Name
id
Type
string
Description
任務的唯一識別碼。雖然我們在實作細節上使用 k-可排序的 UUID 作為任務 id，但你不應對 id 的格式做任何假設。
Name
type
Type
string
Description
Retexture 任務的類型。此值為 retexture。
Name
model_urls
Type
object
Description
指向 Meshy 產生的帶貼圖 3D 模型檔案的可下載 URL。
- Name
  glb
  Type
  string
  Description
  指向 GLB 檔案的可下載 URL。
- Name
  fbx
  Type
  string
  Description
  指向 FBX 檔案的可下載 URL。
- Name
  obj
  Type
  string
  Description
  指向 OBJ 檔案的可下載 URL。
- Name
  usdz
  Type
  string
  Description
  指向 USDZ 檔案的可下載 URL。
- Name
  mtl
  Type
  string
  Description
  指向 MTL 檔案的可下載 URL，當存在 texture 時會隨 OBJ 匯出一併回傳。
- Name
  stl
  Type
  string
  Description
  指向 STL 檔案的可下載 URL。
- Name
  3mf
  Type
  string
  Description
  指向 3MF 檔案的可下載 URL。僅當透過 target_formats 要求了 3mf 時才會出現。
Name
text_style_prompt
Type
string
Description
這是用於建立此貼圖任務的文字 prompt。
Name
image_style_url
Type
string
Description
這是用於建立此貼圖任務的圖像輸入。
Name
multiview_image_urls
Type
string[]
Description
指向用於建立此貼圖任務的多視角參考圖像的可下載 URL。僅當任務是透過 multiview_image_urls 建立時才會出現。
Name
thumbnail_url
Type
string
Description
指向模型檔案縮圖的可下載 URL。
Name
alpha_thumbnail_url
Type
string
Description
指向 thumbnail_url 透明背景（RGBA）版本的可下載 URL。僅當任務是以 alpha_thumbnail: true 建立且透明預覽渲染成功時才會出現；否則此欄位將被省略。
Name
progress
Type
integer
Description
任務的進度。如果任務尚未開始，此屬性為 0。任務成功後，此值將變為 100。
Name
started_at
Type
timestamp
Description
任務開始時的時間戳，以毫秒為單位。如果任務尚未開始，此屬性為 0。
時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數，遵循 RFC 3339 標準。例如，2023 年 9 月 1 日星期五 GMT 時間 12:00:00 PM 表示為 1693569600000。這適用於 Meshy API 中的所有時間戳。
Name
created_at
Type
timestamp
Description
任務建立時的時間戳，以毫秒為單位。
Name
expires_at
Type
timestamp
Description
任務結果過期時的時間戳，以毫秒為單位。
Name
finished_at
Type
timestamp
Description
任務完成時的時間戳，以毫秒為單位。如果任務尚未完成，此屬性為 0。
Name
status
Type
string
Description
任務的狀態。可能的值為 PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED 之一。
Name
texture_urls
Type
array
Description
由此任務產生的 texture URL 物件陣列。通常這裡只包含一個 texture URL 物件。每個 texture URL 具有以下屬性：
- Name
  base_color
  Type
  string
  Description
  指向基礎顏色貼圖圖像的可下載 URL。
- Name
  metallic
  Type
  string
  Description
  指向金屬度貼圖圖像的可下載 URL。
  如果任務建立時設定了 enable_pbr: false，此屬性將被省略。
- Name
  normal
  Type
  string
  Description
  指向法線貼圖圖像的可下載 URL。
  如果任務建立時設定了 enable_pbr: false，此屬性將被省略。
- Name
  roughness
  Type
  string
  Description
  指向粗糙度貼圖圖像的可下載 URL。
  如果任務建立時設定了 enable_pbr: false，此屬性將被省略。
- Name
  emission
  Type
  string
  Description
  指向自發光貼圖圖像的可下載 URL。
  如果任務建立時設定了 enable_pbr: false，或 ai_model 為 meshy-5，此屬性將被省略。
Name
preceding_tasks
Type
integer
Description
前置任務的數量。
此屬性僅在任務狀態為 PENDING 時出現。
Name
task_error
Type
object
Description
失敗任務的錯誤詳情。完整的 task_error 物件說明請參見錯誤。
Name
consumed_credits
Type
integer
Description
此任務消耗的積分數量。當任務狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時會出現。對於 FAILED 任務回傳 0（失敗時積分會被退還）。

Example Retexture Task Model

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "retexture",
  "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=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "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=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 10
}