Remesh API

Remesh API ช่วยให้คุณสามารถรีเมชและส่งออกโมเดล 3D ที่มีอยู่ซึ่งสร้างขึ้นโดย Meshy API อื่น ๆ (เช่น รูปภาพเป็น 3D หรือ ข้อความเป็น 3D) ไปเป็นรูปแบบไฟล์ต่าง ๆ ได้ ส่วนนี้จะให้รายละเอียดเกี่ยวกับวิธีการใช้งาน Remesh API

POST/openapi/v1/remesh

สร้างงานรีเมช

เอนด์พอยต์นี้สร้างงานรีเมชใหม่

สำหรับการแปลงฟอร์แมตและการปรับขนาด ให้ใช้ Convert API และ Resize API โดยเฉพาะ พารามิเตอร์ที่เลิกใช้ด้านล่างนี้ยังคงทำงานได้ตามปกติ แต่เราแนะนำให้ใช้เอนด์พอยต์ใหม่สำหรับการผสานรวมใหม่ๆ

พารามิเตอร์

ต้องระบุ input_task_id หรือ model_url เพียงอย่างใดอย่างหนึ่งเท่านั้น หากระบุทั้งสองอย่าง input_task_id จะมีความสำคัญเหนือกว่า

Name
input_task_id
Type
string
จำเป็น
Description
ID ของงาน รูปภาพเป็น 3D หรือ ข้อความเป็น 3D ที่เสร็จสมบูรณ์แล้วซึ่งคุณต้องการรีเมช งานนี้ต้องเป็นหนึ่งในงานต่อไปนี้: Text to 3D Preview, Text to 3D Refine, Image to 3D หรือ Retexture นอกจากนี้ต้องมีสถานะเป็น SUCCEEDED

Name
model_url
Type
string
จำเป็น
Description
กรุณาระบุโมเดล 3D ให้ Meshy ทำการรีเมชผ่าน URL ที่เข้าถึงได้แบบสาธารณะ หรือ data URI รูปแบบที่รองรับ: .glb, .gltf, .obj, .fbx, .stl
สำหรับ Data URI ให้ใช้ MIME type: application/octet-stream

Name
target_formats
Type
string[]
ค่าเริ่มต้น ["glb"]
Description
รายการฟอร์แมตเป้าหมายสำหรับโมเดลที่รีเมชแล้ว หากไม่ระบุ จะสร้างเฉพาะ GLB เท่านั้น
ค่าที่ใช้ได้: glb, fbx, obj, usdz, blend, stl, 3mf
Name
topology
Type
string
ค่าเริ่มต้น triangle
Description
ระบุ topology ของโมเดลที่สร้างขึ้น
ค่าที่ใช้ได้:
- quad: สร้างเมชที่ส่วนใหญ่เป็นรูปสี่เหลี่ยม (quad-dominant)
- triangle: สร้างเมชสามเหลี่ยมที่ลดจำนวนโพลิกอนแล้ว
Name
target_polycount
Type
integer
ค่าเริ่มต้น 30,000
Description
ระบุจำนวนโพลิกอนเป้าหมายในโมเดลที่สร้างขึ้น จำนวนโพลิกอนจริงอาจแตกต่างจากค่าเป้าหมายขึ้นอยู่กับความซับซ้อนของจีออเมทรี
ช่วงค่าที่ใช้ได้จะแตกต่างกันไปตามระดับผู้ใช้:
- 100 ถึง 300,000 (รวมค่าทั้งสอง)
Name
decimation_mode
Type
integer
Description
เปิดใช้งานการลดจำนวนโพลิกอนแบบปรับตัว (adaptive decimation) โดยการตั้งค่าระดับจำนวนโพลิกอน เมื่อตั้งค่านี้ target_polycount จะถูกละเว้น
ค่าที่ใช้ได้:
- 1: Adaptive — จำนวนโพลิกอนสูงสุด
- 2: Adaptive — จำนวนโพลิกอนสูง
- 3: Adaptive — จำนวนโพลิกอนปานกลาง
- 4: Adaptive — จำนวนโพลิกอนต่ำ
Name
resize_height
Type
number
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น 0
Description
ปรับขนาดโมเดลให้มีความสูงตามที่กำหนดในหน่วยเมตร เราแนะนำให้ใช้ Resize API โดยเฉพาะแทน
auto_size, resize_height, และ resize_longest_side ไม่สามารถใช้ร่วมกันได้
Name
resize_longest_side
Type
number
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น 0
Description
ปรับขนาดโมเดลให้ด้านที่ยาวที่สุดของกล่องขอบเขต มีค่าเท่ากับค่าที่ระบุในหน่วยเมตร เราแนะนำให้ใช้ Resize API โดยเฉพาะแทน
auto_size, resize_height, และ resize_longest_side ไม่สามารถใช้ร่วมกันได้
Name
auto_size
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true บริการจะใช้ AI vision เพื่อประมาณความสูงของวัตถุในโลกจริงโดยอัตโนมัติ และปรับขนาดโมเดลให้สอดคล้องกัน เราแนะนำให้ใช้ Resize API โดยเฉพาะแทน
auto_size, resize_height, และ resize_longest_side ไม่สามารถใช้ร่วมกันได้

ใช้เฉพาะเมื่อ auto_size = true

Name
origin_at
Type
string
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น bottom
Description
ตำแหน่งของจุดกำเนิด เราแนะนำให้ใช้ Resize API โดยเฉพาะแทน
ค่าที่ใช้ได้: bottom, center

Name
convert_format_only
Type
boolean
⚠ เลิกใช้แล้ว
Description
หากเป็น true บริการจะเปลี่ยนเฉพาะฟอร์แมตของไฟล์โมเดลอินพุตเท่านั้น โดยไม่สนใจอินพุตอื่นๆ เช่น topology, resize_height, และ target_polycount เราแนะนำให้ใช้ Convert API โดยเฉพาะแทน
ต้องระบุ target_formats หาก convert_format_only ถูกตั้งค่าเป็น true

Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true งานจะแสดงผลตัวอย่างเวอร์ชันพื้นหลังโปร่งใส (RGBA) เพิ่มเติม และส่งคืนเป็น alpha_thumbnail_url ในการตอบกลับ GET ฟิลด์ thumbnail_url ที่มีอยู่เดิมจะไม่เปลี่ยนแปลง

ค่าที่ส่งคืน

คุณสมบัติ result ของการตอบกลับประกอบด้วย id ของงานรีเมชที่สร้างขึ้นใหม่

รูปแบบความล้มเหลว

Name
400 - Bad Request
Description
คำขอไม่เป็นที่ยอมรับ สาเหตุทั่วไป:
- ขาดพารามิเตอร์: ต้องระบุ model_url หรือ input_task_id อย่างใดอย่างหนึ่ง
- งานอินพุตไม่ถูกต้อง: input_task_id ต้องอ้างอิงถึงงานที่สำเร็จจากโมเดลที่รองรับ
- ฟอร์แมตโมเดลไม่ถูกต้อง: model_url ชี้ไปยังไฟล์ที่มีนามสกุลที่ไม่รองรับ
- URL ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด model_url ได้
- topology ไม่ถูกต้อง: พารามิเตอร์ topology ไม่ถูกต้อง
- พารามิเตอร์ที่ใช้ร่วมกันไม่ได้: auto_size และ resize_height ไม่สามารถตั้งค่าพร้อมกันได้
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว กรุณาตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการดำเนินงานนี้
Name
429 - Too Many Requests
Description
คุณดำเนินการเกินการจำกัดอัตราแล้ว

Request

POST

/openapi/v1/remesh

# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/remesh/:id

เรียกดูงานรีเมช (Remesh Task)

เอนด์พอยต์นี้ใช้เรียกดูงานรีเมชตาม ID

พารามิเตอร์

Name
id
Type
path
Description
ID ของงานรีเมชที่ต้องการเรียกดู

ค่าที่ส่งกลับ

ออบเจ็กต์ของงานรีเมช (Remesh Task)

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

DELETE/openapi/v1/remesh/:id

Delete a Remesh Task

เอนด์พอยต์นี้จะลบงานรีเมชอย่างถาวร รวมถึงโมเดลและข้อมูลทั้งหมดที่เกี่ยวข้อง การดำเนินการนี้ไม่สามารถย้อนกลับได้

Path Parameters

Name
id
Type
path
Description
ID ของงานรีเมชที่ต้องการลบ

Task Status

งานที่ยังอยู่ในสถานะ PENDING จะถูกลบและเครดิตที่ถูกใช้ไปตอนสร้างงาน จะได้รับการคืนเงิน

งานที่อยู่ในสถานะ IN_PROGRESS แล้วไม่สามารถลบได้ คำขอจะถูกปฏิเสธด้วย 409 Conflict และงานจะยังคงทำงานต่อไป เครดิตสำหรับงานที่ worker ได้เริ่ม ดำเนินการไปแล้วจะไม่สามารถขอคืนได้ ดังนั้นการลบงานระหว่างที่กำลังทำงานอยู่ จะทำให้คุณเสียทั้งเครดิตและผลลัพธ์ ให้รอจนกว่างานจะถึงสถานะ SUCCEEDED, FAILED หรือ CANCELED แล้วจึงลบ

งานที่อยู่ในสถานะสิ้นสุด (SUCCEEDED, FAILED หรือ CANCELED) จะถูกลบ โดยไม่มีการคืนเงิน

Returns

คืนค่า 200 OK เมื่อสำเร็จ หรือ 409 Conflict เมื่องานอยู่ในสถานะ IN_PROGRESS

Request

DELETE

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

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

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/remesh

List Remesh Tasks

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงานรีเมชได้

พารามิเตอร์

Name
page_num
Type
integer
ค่าเริ่มต้น 1
Description
หมายเลขหน้าสำหรับการแบ่งหน้า
Name
page_size
Type
integer
ค่าเริ่มต้น 10
Description
จำนวนรายการต่อหน้า สูงสุดที่อนุญาตคือ 100 รายการ
Name
sort_by
Type
string
Description
ฟิลด์ที่ใช้ในการเรียงลำดับ
ค่าที่สามารถใช้ได้:
- +created_at: เรียงลำดับตามเวลาที่สร้างจากน้อยไปมาก
- -created_at: เรียงลำดับตามเวลาที่สร้างจากมากไปน้อย

ค่าที่ส่งกลับ

ส่งกลับรายการแบบแบ่งหน้าของ The Remesh Task Objects

Request

GET

/openapi/v1/remesh

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]

GET/openapi/v1/remesh/:id/stream

สตรีมงานรีเมช

เอนด์พอยต์นี้จะสตรีมข้อมูลอัปเดตแบบเรียลไทม์สำหรับงานรีเมชโดยใช้ Server-Sent Events (SSE)

พารามิเตอร์

Name
id
Type
path
Description
รหัสเฉพาะสำหรับงานรีเมชที่ต้องการสตรีม

ผลลัพธ์ที่ได้

ส่งคืนสตรีมของ The Remesh Task Objects ในรูปแบบ Server-Sent Events

สำหรับงานที่มีสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะมีเพียงฟิลด์ progress และ status ที่จำเป็นเท่านั้น

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

The Remesh Task Object

ออบเจ็กต์ Remesh Task แสดงถึงหน่วยงานที่ Meshy ใช้ในการรีเมชและส่งออกโมเดล 3D ที่มีอยู่ไปเป็นรูปแบบต่างๆ ออบเจ็กต์นี้มีคุณสมบัติดังต่อไปนี้

Properties

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงานนี้ แม้ว่าเราจะใช้ k-sortable UUID สำหรับ task id เป็นรายละเอียดในการ implementation แต่คุณไม่ควรตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id นี้
Name
type
Type
string
Description
ประเภทของงาน Remesh ค่านี้คือ remesh
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดไฟล์โมเดล 3D ที่มีพื้นผิวซึ่งสร้างโดย Meshy คุณสมบัติสำหรับรูปแบบใดรูปแบบหนึ่งจะถูกละไว้หากไม่ได้สร้างรูปแบบนั้นขึ้นมา แทนที่จะคืนค่าเป็นสตริงว่าง
- Name
  glb
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ GLB
- Name
  fbx
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ FBX
- Name
  obj
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ OBJ
- Name
  usdz
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ USDZ
- Name
  blend
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ Blender
- Name
  stl
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ STL
- Name
  3mf
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ 3MF จะปรากฏก็ต่อเมื่อมีการร้องขอ 3mf ผ่าน target_formats
Name
thumbnail_url
Type
string
Description
URL สำหรับดาวน์โหลดภาพตัวอย่างที่เรนเดอร์จากโมเดลที่ผ่านการรีเมชแล้ว
Name
alpha_thumbnail_url
Type
string
Description
URL สำหรับดาวน์โหลดเวอร์ชันพื้นหลังโปร่งใส (RGBA) ของ thumbnail_url จะปรากฏก็ต่อเมื่องานถูกสร้างขึ้นด้วย alpha_thumbnail: true และภาพตัวอย่างแบบโปร่งใสถูกเรนเดอร์สำเร็จ มิฉะนั้นฟิลด์นี้จะถูกละไว้
Name
progress
Type
integer
Description
ความคืบหน้าของงาน หากงานยังไม่เริ่มดำเนินการ คุณสมบัตินี้จะเป็น 0 เมื่องานสำเร็จแล้ว ค่านี้จะกลายเป็น 100
Name
status
Type
string
Description
สถานะของงาน ค่าที่เป็นไปได้คือค่าใดค่าหนึ่งจาก PENDING, IN_PROGRESS, SUCCEEDED, FAILED
Name
preceding_tasks
Type
integer
Description
จำนวนของงานที่อยู่ก่อนหน้า
ค่าของฟิลด์นี้มีความหมายก็ต่อเมื่อสถานะของงานเป็น PENDING เท่านั้น
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่สร้างงาน มีหน่วยเป็นมิลลิวินาที
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานเริ่มดำเนินการ มีหน่วยเป็นมิลลิวินาที หากงานยังไม่เริ่มดำเนินการ คุณสมบัตินี้จะเป็น 0
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานเสร็จสิ้น มีหน่วยเป็นมิลลิวินาที หากงานยังไม่เสร็จสิ้น คุณสมบัตินี้จะเป็น 0
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับงานที่ล้มเหลว ดู ข้อผิดพลาด สำหรับข้อมูลอ้างอิงออบเจ็กต์ task_error แบบเต็ม
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ใช้ไปสำหรับงานนี้ มีให้เมื่อสถานะของงานเป็น PENDING, IN_PROGRESS, หรือ SUCCEEDED จะคืนค่า 0 สำหรับงานที่เป็น FAILED (เครดิตจะถูกคืนเมื่อเกิดความล้มเหลว)

Example Remesh Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}