Meshy API Webhooks vs Polling: เมื่อไหร่ที่ผลลัพธ์พร้อมใช้งาน

งานการสร้างของ Meshy API (Text to 3D, Image to 3D, Rigging และอื่น ๆ) ทำงานแบบอะซิงโครนัส — คุณส่งงานแล้วจำเป็นต้องตรวจสอบว่างานเสร็จสิ้นเมื่อใดก่อนดึงผลลัพธ์ บทความนี้จะอธิบายวงจรชีวิตของงาน และวิธีที่รองรับสองวิธีในการทราบว่างานเสร็จสิ้นแล้ว ได้แก่ polling และ webhooks พร้อมวิธีหลีกเลี่ยงปัญหาที่พบบ่อยที่สุดคือ "เกิดข้อผิดพลาดในการดึงข้อมูลโมเดล"

งานการสร้างทุกงานจะเคลื่อนผ่านสถานะต่าง ๆ เพียงไม่กี่สถานะ ซึ่งแสดงผลในฟิลด์ status ของออบเจกต์งาน:

• PENDING — งานถูกจัดคิวแล้วแต่ยังไม่เริ่มประมวลผล

• IN_PROGRESS — งานกำลังถูกประมวลผลอยู่ ฟิลด์ progress (0-100) จะเพิ่มขึ้นเรื่อย ๆ ตามความคืบหน้าของงาน

• SUCCEEDED — งานเสร็จสิ้นสำเร็จและ progress เท่ากับ 100 URL ของผลลัพธ์ (ไฟล์โมเดล, เท็กซ์เจอร์, ตัวอย่าง) จะพร้อมใช้งานในการตอบกลับ

• FAILED — งานไม่สามารถเสร็จสิ้นได้ เครดิตของงานที่ล้มเหลวจะถูกคืนโดยอัตโนมัติ

• CANCELED — งานถูกยกเลิกก่อนเสร็จสิ้น

กฎที่สำคัญที่สุดเมื่อทำการเชื่อมต่อกับ API คือ อย่าพยายามดึงหรือใช้ URL ของผลลัพธ์จนกว่า status ของงานจะเป็น SUCCEEDED การอ่านผลลัพธ์ขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS เป็นสาเหตุที่พบบ่อยที่สุดของรายงาน "เกิดข้อผิดพลาดในการดึงข้อมูลโมเดล"

Polling หมายถึงการเรียก endpoint "get task" ซ้ำ ๆ ด้วย task ID ของคุณจนกว่างานจะเข้าสู่สถานะสุดท้าย (SUCCEEDED, FAILED หรือ CANCELED) ลูป polling แบบง่ายมีลักษณะดังนี้:

• ส่งคำขอการสร้างและจัดเก็บ task id ที่ได้รับกลับมา

• เรียก endpoint "retrieve task" ที่เกี่ยวข้อง (เช่น endpoint task-by-id ของ Text to 3D หรือ Image to 3D) เป็นระยะ ๆ — โดยทั่วไปคือทุกไม่กี่วินาที

• ตรวจสอบฟิลด์ status ในการตอบกลับแต่ละครั้ง ให้คงการ polling ต่อไปขณะที่สถานะเป็น PENDING หรือ IN_PROGRESS

• หยุด polling ทันทีที่ status เป็น SUCCEEDED (อ่าน URL ของผลลัพธ์), FAILED หรือ CANCELED

• เพิ่มการป้องกันแบบ timeout/max-attempts ที่เหมาะสมในโค้ดของคุณ เพื่อไม่ให้งานที่ค้างอยู่ถูก polling ไปเรื่อย ๆ ไม่สิ้นสุด

Polling เป็นวิธีที่ง่ายและเหมาะสำหรับสคริปต์ งานแบบกลุ่ม และการเชื่อมต่อที่มีปริมาณต่ำ สำหรับการเชื่อมต่อที่มีปริมาณสูงหรือที่ต้องการความเร็วในการตอบสนอง webhook มักเป็นตัวเลือกที่ดีกว่า

แทนที่จะถามซ้ำ ๆ ว่า "เสร็จหรือยัง?" คุณสามารถขอให้ Meshy แจ้งเตือนเซิร์ฟเวอร์ของคุณทันทีที่งานเสร็จสิ้น วิธีใช้ webhooks:

• กำหนดค่า webhook (callback) URL ที่ Meshy สามารถเข้าถึงได้ — โดยทั่วไปจะตั้งค่าที่ระดับบัญชี/การตั้งค่า API หรือส่งผ่านเป็นพารามิเตอร์ในคำขอการสร้าง ขึ้นอยู่กับ endpoint

• ตรวจสอบให้แน่ใจว่า endpoint ของคุณสามารถเข้าถึงได้แบบสาธารณะผ่าน HTTPS และตอบกลับอย่างรวดเร็ว (ส่งคืนสถานะ 2xx ทันที แล้วจึงประมวลผล payload แบบอะซิงโครนัส)

• เมื่องานเข้าสู่สถานะสุดท้าย Meshy จะส่ง payload ไปยัง endpoint ของคุณ ซึ่งมี task id และ status สุดท้ายของงาน

• เมื่อได้รับแล้ว ให้ค้นหารายละเอียดงานทั้งหมดด้วย id ผ่าน API แทนที่จะเชื่อเนื้อหาของ webhook เพียงอย่างเดียว เพื่อให้แน่ใจว่าคุณมีผลลัพธ์ที่ถูกต้องและเป็นปัจจุบันที่สุด

Webhooks ช่วยลดการเรียก API ที่ไม่จำเป็นและให้การแจ้งเตือนแบบเกือบทันที แต่คุณควรยังคงมีระบบ polling สำรองเป็นระยะ ๆ สำหรับงานที่การส่ง webhook อาจสูญหายหรือล่าช้า (เช่น เนื่องจากปัญหาเครือข่ายชั่วคราวในฝั่งของคุณ)

ไม่ว่าคุณจะใช้ polling หรือ webhooks โค้ดจัดการผลลัพธ์ของคุณควรเป็นแบบ idempotent — ปลอดภัยที่จะรันซ้ำหลายครั้งสำหรับงานเดียวกันโดยไม่เกิดผลข้างเคียง ข้อควรระวังนี้สำคัญเพราะ:

• Webhook หนึ่งรายการอาจถูกส่งมากกว่าหนึ่งครั้งสำหรับงานเดียวกัน (การลองใหม่ฝั่งผู้ส่ง การซ้ำซ้อนของเครือข่าย ฯลฯ)

• ลูป polling และ webhook handler อาจพยายามประมวลผลงานที่เสร็จสิ้นแล้วเดียวกันพร้อมกัน หากทั้งสองทำงานอยู่

เพื่อรักษาความเป็น idempotent ให้กำหนดตรรกะการประมวลผลของคุณโดยอ้างอิงจาก task id — ตัวอย่างเช่น ตรวจสอบก่อนว่าคุณได้จัดเก็บ/ดาวน์โหลดผลลัพธ์สำหรับ id นั้นไปแล้วหรือไม่ก่อนทำซ้ำ และทำให้การ "ทำเครื่องหมายว่าประมวลผลแล้ว" เป็นขั้นตอนเดียวแบบ atomic ในฐานข้อมูลของคุณเอง

การตอบกลับที่มี "status": "SUCCEEDED" และ "progress": 100 เป็นสัญญาณเดียวที่รับประกันว่า payload ของผลลัพธ์ (URL โมเดล, เท็กซ์เจอร์, ภาพย่อ) สมบูรณ์และปลอดภัยต่อการใช้งาน โดยเฉพาะอย่างยิ่ง ในโค้ดของคุณ:

• ตรวจสอบ status === "SUCCEEDED" ก่อนอ่านข้อมูลใด ๆ จากฟิลด์ result/URL ของโมเดล

• อย่าพึ่งพา progress เพียงอย่างเดียว — ให้ตรวจสอบ status ด้วยเสมอ เนื่องจาก progress อาจแสดงค่าที่สูงชั่วขณะก่อนที่งานจะถูกสรุปสมบูรณ์

• ดาวน์โหลดไฟล์ผลลัพธ์ทันทีเมื่อ SUCCEEDED — ไฟล์ที่สร้างขึ้นจะถูกเก็บไว้บนเซิร์ฟเวอร์ของ Meshy เป็นระยะเวลาจำกัดเท่านั้น หลังจากนั้น URL จะไม่สามารถใช้งานได้อีก

รายงาน "ฉันดึงข้อมูลโมเดลไม่ได้" ส่วนใหญ่ย้อนกลับไปที่สาเหตุใดสาเหตุหนึ่งต่อไปนี้:

• การดึงข้อมูลเร็วเกินไป เรียกใช้ URL ของผลลัพธ์หรืออ่านฟิลด์ของโมเดลก่อนที่ status จะเป็น SUCCEEDED นี่เป็นสาเหตุที่พบบ่อยที่สุดอย่างชัดเจน

• ไฟล์หมดอายุ รอนานเกินไปหลังจาก SUCCEEDED ก่อนดาวน์โหลด — URL ของผลลัพธ์จะหยุดทำงานหลังจากช่วงเวลาการเก็บรักษาของงานประเภทนั้นสิ้นสุดลง

• ใช้ task ID ที่ล้าสมัยหรือผิด — ตัวอย่างเช่น การนำ ID จากคำขอก่อนหน้าที่ไม่เกี่ยวข้องกันมาใช้ซ้ำ

• เข้าใจผิดว่า FAILED เป็นสถานะชั่วคราว และคง polling งานที่ล้มเหลวไปแล้วต่อไป แทนที่จะส่งคำขอใหม่

• ปัญหาเครือข่าย/timeout ระหว่างเซิร์ฟเวอร์ของคุณกับ Meshy ที่ถูกเข้าใจผิดว่าเป็นปัญหาการสร้างโมเดล

หากผลลัพธ์การสร้างไม่เป็นไปตามความคาดหวังของคุณ หรือคำขอล้มเหลวทั้งหมด โปรดคำนึงถึงสิ่งต่อไปนี้:

• ปัจจุบัน Meshy API ไม่รองรับการลองใหม่ของงานที่มีอยู่ในตัว — หากต้องการลองอีกครั้ง ให้ส่งคำขอการสร้างใหม่ ซึ่งจะใช้เครดิตตามปกติ

• สำหรับความล้มเหลวของเครือข่ายชั่วคราวเมื่อเรียก API (timeout, การตอบกลับ 5xx) การใช้ exponential backoff ช่วงสั้น ๆ ก่อนส่งคำขอใหม่เป็นสิ่งที่สมเหตุสมผล

• สำหรับการ polling เอง ให้ลองเรียก "get task" ซ้ำเมื่อเกิดข้อผิดพลาดเครือข่ายชั่วคราว แต่อย่าถือว่าการ poll ที่ล้มเหลวเพียงครั้งเดียวเป็นความล้มเหลวของการสร้าง — ให้เชื่อฟิลด์ status เฉพาะเมื่อคุณได้รับการตอบกลับที่สำเร็จเท่านั้น

• หากคุณต้องการฟังก์ชันการลองใหม่ในตัวสำหรับการสร้าง โปรดติดต่อทีมขายของ Meshy เกี่ยวกับตัวเลือกแผน enterprise

สิ่งนี้เกิดขึ้นเกือบทุกครั้งเนื่องจากโค้ดพยายามอ่านผลลัพธ์ก่อนที่งานจะเสร็จสิ้น โปรดยืนยันเสมอว่า status เป็น SUCCEEDED (และ progress เท่ากับ 100) ก่อนดึง URL ของโมเดล

Polling ตั้งค่าง่ายกว่าและเหมาะสำหรับการใช้งานที่มีปริมาณต่ำหรือสคริปต์ครั้งเดียว ส่วน Webhooks เหมาะกว่าสำหรับการเชื่อมต่อระดับ production ที่มีงานพร้อมกันจำนวนมาก เนื่องจากช่วยหลีกเลี่ยงคำขอซ้ำที่ไม่จำเป็นและแจ้งเตือนคุณทันทีเมื่องานเสร็จสิ้น

จัดการแบบ idempotent — ตรวจสอบ task id เทียบกับสิ่งที่คุณประมวลผลไปแล้ว และข้ามการประมวลผลซ้ำหากจัดการไปแล้ว

ให้กลับไปใช้การ polling งานโดยตรงด้วย id พร้อมทั้งตรวจสอบว่า endpoint ของคุณสามารถเข้าถึงได้แบบสาธารณะผ่าน HTTPS และส่งคืนการตอบกลับ 2xx อย่างรวดเร็ว เนื่องจาก endpoint ที่ช้าหรือเข้าถึงไม่ได้สามารถทำให้เกิดปัญหาในการส่งข้อมูลได้

ปัจจุบันยังไม่รองรับ — คุณจะต้องส่งคำขอการสร้างใหม่ ซึ่งจะใช้เครดิตตามปกติ หากคุณต้องการการรองรับการลองใหม่ในตัว โปรดติดต่อฝ่ายขายเกี่ยวกับตัวเลือก enterprise

ไฟล์ผลลัพธ์จะถูกเก็บไว้บนเซิร์ฟเวอร์ของ Meshy เป็นระยะเวลาจำกัดหลังจากงานเสร็จสิ้นเท่านั้น ดังนั้นควรดาวน์โหลดผลลัพธ์ไปยังพื้นที่จัดเก็บของคุณเองทันทีที่งานสำเร็จ แทนที่จะรอ

• ทำไมฉันจึงพบข้อผิดพลาดอย่างต่อเนื่องเมื่อดึงข้อมูลโมเดลจากผลลัพธ์การสร้างโดยใช้ API?