UV Unwrap API

UV Unwrap API สร้างเลย์เอาต์ UV คุณภาพสูงให้กับโมเดล 3D ที่มีอยู่โดยอัตโนมัติ ใช้เป็นขั้นตอนที่จำเป็นก่อนการทำเท็กซ์เจอร์ — หรือใช้เมื่อใดก็ตามที่คุณต้องการเลย์เอาต์ UV ที่สะอาดและไม่ทับซ้อนกันสำหรับเครื่องมือปลายทาง (Blender, Substance Painter, Unreal)

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

ข้อจำกัด Auto UV ในปัจจุบันรองรับเมชที่มีจำนวนหน้าสูงสุด 40,000 หน้า — โมเดลที่ใหญ่กว่านี้จะถูกปฏิเสธด้วยรหัส 400 ให้รัน Remesh ก่อนเพื่อลดจำนวนโพลิกอน เมชแบบ quad และ n-gon จะถูก แปลงเป็นสามเหลี่ยม ระหว่างการสร้าง UV ดังนั้นผลลัพธ์ที่ได้จะเป็นเมชสามเหลี่ยมเสมอ

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

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

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

พารามิเตอร์

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

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

Name
model_url
Type
string
จำเป็น
Description
ระบุโมเดล 3D โดยตรงผ่าน URL ที่เข้าถึงได้แบบสาธารณะหรือ data URI รองรับเฉพาะ .glb เท่านั้น — API จะอ่านไฟล์ไบนารีของ glTF และไม่รองรับการแยกวิเคราะห์รูปแบบอื่น หากต้องการทำ UV-unwrap โมเดลในรูปแบบอื่น (.fbx, .obj, .stl, .gltf) ให้แปลงเป็น .glb ก่อนผ่าน Convert API จากนั้นส่ง task ID ที่ได้เป็น input_task_id หรือส่ง URL ผลลัพธ์ GLB มาที่นี่
สำหรับ Data URI ให้ใช้ MIME type เป็น application/octet-stream
ขนาดไฟล์สูงสุด: 400 MB สำหรับ URL แบบ http หรือ https, 100 MB สำหรับ data: URI ไฟล์ 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 ต้องอ้างอิงถึงงานที่สำเร็จและมีผลลัพธ์เป็น GLB
- จำนวนหน้าเกินกำหนด: เมชต้นทางมีจำนวนหน้ามากกว่าเพดานของ UV Unwrap ให้รัน รีเมช ก่อน
- รูปแบบโมเดลไม่ถูกต้อง: model_url ชี้ไปยังไฟล์ที่มีนามสกุลไม่รองรับ
- URL ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด model_url ได้
- ไฟล์โมเดลมีขนาดใหญ่เกินไป: ไฟล์ model_url มีขนาดเกิน 400 MB (URL แบบ http หรือ https) หรือ 100 MB (data: URI)
- จำนวนหน้ามากเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และมีจำนวนหน้ามากกว่า 10,000,000 หน้า ให้ลดจำนวนหน้าลงแล้วส่งไฟล์อีกครั้ง
- ไม่สามารถอ่านไฟล์โมเดลได้: ไฟล์ model_url มีขนาดเกิน 100 MB และไม่สามารถอ่านส่วนหัวได้ เช่น ไฟล์ GLB ที่บีบอัดแบบ Draco
- ส่วนหัวของโมเดลซับซ้อนเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และส่วนหัวมีเมช โหนด หรือเรคคอร์ดมากเกินกว่าจะตรวจสอบได้ ให้ลดจำนวนอ็อบเจ็กต์ในไฟล์ลงแล้วส่งอีกครั้ง
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการทำงานนี้ UV Unwrap มีค่าใช้จ่าย 5 เครดิตต่อการเรียกใช้หนึ่งครั้ง
Name
404 - Not Found
Description
ฟีเจอร์นี้ยังไม่ได้เปิดใช้งานสำหรับบัญชีของคุณ UV Unwrap ถูกควบคุมด้วย Statsig flag ในระหว่างการเปิดตัว — ติดต่อฝ่ายสนับสนุนของ Meshy หากคุณต้องการสิทธิ์เข้าถึง
Name
429 - Too Many Requests
Description
คุณใช้งานเกินการจำกัดอัตราที่กำหนดไว้

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"
}

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

เรียกดูงาน UV Unwrap

เอนด์พอยต์นี้ใช้เรียกดูสถานะปัจจุบันของงาน UV Unwrap ตาม ID

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

ส่งคืน UV Unwrap Task object

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}"

ดู ตัวอย่าง task object ด้านล่าง

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

Delete an UV Unwrap Task

ลบงาน UV Unwrap อย่างถาวร งานและผลลัพธ์ของงานจะไม่สามารถเข้าถึงได้อีกต่อไป

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

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

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

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}"

GET/openapi/v1/uv-unwrap

List UV Unwrap Tasks

ส่งคืนรายการงาน 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

สมัครรับ progress ของงานในรูปแบบ Server-Sent Events แต่ละ event 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

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

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
}