UV Unwrap API

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

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

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

POST/openapi/v1/uv-unwrap

สร้างงาน UV Unwrap

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

พารามิเตอร์

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

  • Name
    input_task_id
    Type
    string
    จำเป็น
    Description

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

    หากเมชต้นทางมีจำนวนหน้ามากกว่า 40,000 หน้า คำขอจะถูกปฏิเสธด้วย 400 และคุณควรทำ รีเมช ก่อนเพื่อลดจำนวนโพลิกอน

  • Name
    model_url
    Type
    string
    จำเป็น
    Description

    ให้โมเดล 3D โดยตรงผ่าน URL ที่เข้าถึงได้สาธารณะหรือ Data URI รองรับเฉพาะ .glb — API อ่าน glTF binary และไม่แปลงรูปแบบอื่น หากต้องการทำ UV-unwrap โมเดลในรูปแบบอื่น (.fbx, .obj, .stl, .gltf) ให้แปลงเป็น .glb ก่อนผ่าน Convert API แล้วส่ง ID งานที่ได้เป็น input_task_id หรือ URL ของ GLB ที่นี่

    สำหรับ Data URIs ให้ใช้ MIME type application/octet-stream

    ข้อจำกัด 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
  • Name
    401 - Unauthorized
    Description

    การยืนยันตัวตนล้มเหลว กรุณาตรวจสอบ API คีย์ของคุณ

  • Name
    402 - Payment Required
    Description

    เครดิตไม่เพียงพอในการทำงานนี้ UV Unwrap มีค่าใช้จ่าย 5 เครดิตต่อการเรียก

  • Name
    404 - Not Found
    Description

    ฟีเจอร์นี้ไม่ได้เปิดใช้งานสำหรับบัญชีของคุณ UV Unwrap ถูกจำกัดโดย Statsig flag ระหว่างการเปิดตัว — ติดต่อ Meshy support หากคุณต้องการการเข้าถึง

  • 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

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

ดู ตัวอย่างวัตถุงาน ด้านล่าง

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

สมัครรับ progress ของงานเป็น Server-Sent Events แต่ละเหตุการณ์ message จะมี วัตถุงาน UV Unwrap; สตรีมจะปิดเมื่อถึงสถานะ 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

วัตถุงาน UV Unwrap

  • 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

    ไทม์สแตมป์ของการสร้างงาน, ในหน่วยมิลลิวินาที

  • 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 เครดิตเมื่อสำเร็จ

ตัวอย่างวัตถุงาน UV Unwrap

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