UV Unwrap API

สร้าง UV Unwrap สำหรับโมเดล 3D ที่มีอยู่แล้ว รันคำสั่งนี้ก่อนที่จะใส่เท็กซ์เจอร์ให้กับโมเดล หรือเมื่อเครื่องมืออย่าง Blender, Substance Painter หรือ Unreal ต้องการเลย์เอาต์ UV ที่สะอาดและไม่มีการซ้อนทับกัน

ผลลัพธ์ที่ได้คือโมเดลขาว UV ซึ่งมีรูปทรงเหมือนกับอินพุต มีพิกัด UV ใหม่ และไม่มีเท็กซ์เจอร์จริง โดยจะมีแมททีเรียลสีเทาขนาด 2×2 เป็นตัวยึดตำแหน่ง เพื่อให้ช่องแมททีเรียลของ glTF ยังคงใช้งานได้ และเครื่องมือมาตรฐานทั่วไปจะมองว่ายังไม่ได้ใส่เท็กซ์เจอร์

UV Unwrap รองรับเมชที่มีจำนวนหน้าสูงสุด 40,000 หน้า หากโมเดลมีขนาดใหญ่กว่านี้ ระบบจะส่งค่า 400 กลับมา หากต้องการลดจำนวนหน้า ให้รัน Remesh ก่อน

Meshy จะแปลงเมชแบบ quad และ n-gon ให้เป็นสามเหลี่ยมในระหว่างการสร้าง UV ดังนั้นผลลัพธ์ที่ได้จะเป็นเมชสามเหลี่ยมเสมอ

POST/openapi/v1/uv-unwrap

สร้างงาน UV Unwrap

งานนี้ทำงานอยู่เบื้องหลัง สำหรับระยะเวลาที่งานมักใช้ โปรดดู เวลาในการประมวลผล

Request

POST

/openapi/v1/uv-unwrap

# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
    }'

# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "model_url": "https://example.com/path/to/model.glb"
    }'

Response

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}

พารามิเตอร์

Name
input_task_id
Type
string
จำเป็น
Description
จำเป็นต้องระบุ เว้นแต่คุณจะส่ง model_url คือ ID ของงาน Meshy API ที่มีผลลัพธ์ GLB ที่คุณต้องการ unwrap เช่น งานรูปภาพเป็น 3D, ข้อความเป็น 3D หรืองานรีเมช งานนั้นต้องมีสถานะ SUCCEEDED และต้องสร้างไฟล์ GLB ออกมาแล้ว
เมชสามารถมีได้สูงสุด 40,000 หน้า (faces) หากเมชมีมากกว่านี้จะได้รับการตอบกลับ 400 หากต้องการลดจำนวนหน้า ให้รัน รีเมช ก่อน

Name
model_url
Type
string
จำเป็น
Description
จำเป็นต้องระบุ เว้นแต่คุณจะส่ง input_task_id คือโมเดลที่ต้องการ unwrap ในรูปแบบ URL สาธารณะหรือ Data URI หากคุณส่งทั้งสองอย่าง Meshy จะใช้ input_task_id
โมเดลต้องเป็นไฟล์ .glb หากต้องการ unwrap รูปแบบอื่น ให้แปลงเป็น GLB ด้วย Convert API ก่อน
ไฟล์สามารถมีขนาดได้สูงสุด 400 MB หากมาจาก URL แบบ http หรือ https หรือ 100 MB หากเป็น Data URI สำหรับ Data URI ให้ใช้ MIME type application/octet-stream ไฟล์ GLB ที่มีขนาดเกิน 100 MB ต้องไม่ใช้การบีบอัดแบบ Draco
ข้อจำกัดจำนวนหน้าสูงสุด 40,000 หน้าเดียวกันนี้ใช้กับ input_task_id ด้วยเช่นกัน หากเมชมีมากกว่านี้จะได้รับการตอบกลับ 400 ดังนั้นให้รันรีเมชก่อน

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

ฟิลด์ result ของการตอบกลับจะเก็บ ID ของงาน UV Unwrap ใหม่

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

Name
400 - Bad Request
Description
ไม่สามารถดำเนินการตามคำขอได้ ข้อความแสดงข้อผิดพลาดจะระบุปัญหาที่พบ ตัวอย่างเช่น:
- ขาดพารามิเตอร์: ไม่ได้ส่งทั้ง input_task_id และ model_url
- งานอินพุตไม่ถูกต้อง: input_task_id ไม่ใช่งาน API ที่สำเร็จและมีผลลัพธ์เป็น GLB
- จำนวนหน้าเกินกำหนด: เมชมีจำนวนหน้ามากกว่าที่ UV Unwrap อนุญาต ให้รัน รีเมช ก่อน
- รูปแบบโมเดลไม่ถูกต้อง: ไฟล์ model_url มีนามสกุลที่ไม่รองรับ
- ไม่สามารถเข้าถึง URL ได้: Meshy ไม่สามารถดาวน์โหลดไฟล์ model_url ได้
- ไฟล์โมเดลมีขนาดใหญ่เกินไป: ไฟล์ model_url มีขนาดเกิน 400 MB จาก URL แบบ http หรือ https หรือเกิน 100 MB ในรูปแบบ Data URI
- จำนวนหน้ามากเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และมีจำนวนหน้ามากกว่า 10,000,000 หน้า ให้ลดจำนวนหน้าแล้วส่งไฟล์อีกครั้ง
- ไม่สามารถอ่านไฟล์โมเดลได้: ไฟล์ model_url มีขนาดเกิน 100 MB และ Meshy ไม่สามารถอ่านส่วนหัวของไฟล์ได้ ตัวอย่างเช่น เป็นไฟล์ GLB ที่บีบอัดแบบ Draco
- ส่วนหัวของโมเดลซับซ้อนเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และส่วนหัวของไฟล์มีเมช โหนด หรือเรกคอร์ดมากเกินกว่าจะตรวจสอบได้ ให้ลดจำนวนอ็อบเจ็กต์ในไฟล์แล้วส่งอีกครั้ง
แก้ไขคำขอ แล้วส่งอีกครั้ง ดู ข้อผิดพลาด
Name
401 - Unauthorized
Description
API คีย์หายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
ตัวอย่างเช่น:
- เครดิตไม่เพียงพอ: บัญชีไม่มีเครดิตเพียงพอสำหรับงานนี้ หรือบัญชีถึงขีดจำกัดเครดิตแล้ว งาน UV Unwrap มีค่าใช้จ่าย 5 เครดิต ตรวจสอบยอดคงเหลือเครดิตของคุณ แล้วลองใหม่
- แผนฟรี: การสร้างงานต้องใช้แผนแบบชำระเงิน อัปเกรดแผนของคุณได้ที่การตั้งค่าการสมัครสมาชิก แล้วลองใหม่
Name
403 - Forbidden
Description
input_task_id เป็นโมเดลแบบนูนต่ำ (bas-relief) ซึ่งเอนด์พอยต์นี้ไม่สามารถ unwrap ได้ ข้อความแสดงข้อผิดพลาดคือ This model type does not support this operation ให้ส่งโมเดลอื่นแทน
Name
404 - Not Found
Description
input_task_id ไม่ตรงกับงานใด ๆ ของคุณ ตรวจสอบ ID ของงาน แล้วส่งคำขออีกครั้ง
Name
429 - Too Many Requests
Description
คุณเกินการจำกัดอัตราการใช้งานของคุณแล้ว โปรดรอสักครู่แล้วลองใหม่ ดู การจำกัดอัตรา

GET/openapi/v1/uv-unwrap/:id

รับงาน UV Unwrap

ส่งคืนสถานะปัจจุบันของงาน UV Unwrap ตามรหัส ID ของงานนั้น

Request

GET

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

สำหรับตัวอย่างการตอบกลับ ดูที่ ตัวอย่างอ็อบเจกต์งาน UV Unwrap

ส่งคืนค่า

อ็อบเจกต์งาน UV Unwrap

DELETE/openapi/v1/uv-unwrap/:id

ลบงาน UV Unwrap

ลบงาน UV Unwrap อย่างถาวร รวมถึงผลลัพธ์ของงานนั้นด้วย คุณไม่สามารถย้อนกลับการลบได้

Request

DELETE

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"

สถานะของงาน

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

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

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

GET/openapi/v1/uv-unwrap

แสดงรายการงาน UV Unwrap

คืนค่ารายการงาน UV Unwrap ของคุณแบบแบ่งหน้า เรียงจากล่าสุดไปก่อน หากต้องการเลื่อนดูรายการ ให้ใช้ page_num และ page_size

Request

GET

/openapi/v1/uv-unwrap

curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap/:id/stream

สตรีมงาน UV Unwrap

สตรีมการอัปเดตของงาน UV Unwrap ในรูปแบบ Server-Sent Events (SSE) โดยแต่ละอีเวนต์ message จะมี UV Unwrap task object สตรีมจะปิดลงเมื่องานมีสถานะเป็น SUCCEEDED, FAILED, หรือ CANCELED

หากต้องการทราบทันทีว่างานเสร็จสิ้นแล้ว ให้ใช้เอนด์พอยต์นี้แทนการทำ polling ที่ GET /openapi/v1/uv-unwrap/:id

Request

GET

/openapi/v1/uv-unwrap/:id/stream

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

The UV Unwrap task object

ออบเจ็กต์งาน UV Unwrap อธิบายการทำ UV unwrap หนึ่งครั้งของโมเดล 3D โดยจะเก็บสถานะ progress และไฟล์โมเดลเมื่องานสำเร็จ

Example UV Unwrap Task Object

{
  "id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
  "type": "uv-unwrap",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1716579120000,
  "started_at": 1716579122000,
  "finished_at": 1716579180000,
  "expires_at": 1716665580000,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 5
}

Name
id
Type
string
Description
ไอดีของงาน ให้ถือว่าเป็นสตริงที่ไม่มีความหมายตายตัว และอย่าอ้างอิงรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของงาน ซึ่งเป็น uv-unwrap เสมอ
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดแบบมีลายเซ็นของโมเดลขาว UV โดย UV Unwrap จะส่งคืนคีย์ glb เพียงคีย์เดียวเสมอ โมเดลนี้จะคงจีออเมทรีดั้งเดิมไว้ มีพิกัด UV ใหม่ และใช้แมททีเรียลสีเทาเริ่มต้นแทนเท็กซ์เจอร์
Name
thumbnail_url
Type
string
Description
URL สำหรับดาวน์โหลดแบบมีลายเซ็นของภาพตัวอย่าง PNG ของโมเดลขาว UV
Name
progress
Type
integer
Description
ความคืบหน้าของงาน เป็นเปอร์เซ็นต์ตั้งแต่ 0 ถึง 100
Name
status
Type
string
Description
สถานะของงาน หนึ่งใน PENDING, IN_PROGRESS, SUCCEEDED, FAILED หรือ CANCELED
Name
preceding_tasks
Type
integer
Description
จำนวนงานที่อยู่ก่อนหน้างานนี้ในคิว จะปรากฏขณะที่งานมีสถานะ PENDING
Name
created_at
Type
timestamp
Description
เวลาที่สร้างงาน เป็นหน่วยมิลลิวินาทีแบบ Unix
Name
started_at
Type
timestamp
Description
เวลาที่งานเริ่มต้น เป็นหน่วยมิลลิวินาทีแบบ Unix โดยจะเป็น 0 จนกว่างานจะเริ่ม
Name
finished_at
Type
timestamp
Description
เวลาที่งานเสร็จสิ้น เป็นหน่วยมิลลิวินาทีแบบ Unix โดยจะเป็น 0 จนกว่างานจะเสร็จสิ้น
Name
expires_at
Type
timestamp
Description
เวลาที่ URL สำหรับดาวน์โหลดแบบมีลายเซ็นจะหมดอายุ เป็นหน่วยมิลลิวินาทีแบบ Unix
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดเมื่องานล้มเหลว ดู ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่งานนี้ใช้ไป งาน UV Unwrap ที่สำเร็จจะมีค่าใช้จ่าย 5 เครดิต โดยจะเป็น 0 สำหรับงานที่ FAILED เนื่องจาก Meshy จะคืนเครดิตให้เมื่องานล้มเหลว