ข้อความเป็น 3D API

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

ข้อความเป็น 3D ใช้กระบวนการทำงานสองขั้นตอน ขั้นแรก สร้างงาน พรีวิว (mode: "preview") เพื่อสร้างเมช 3D โดยไม่มีเท็กซ์เจอร์ เพื่อให้คุณสามารถประเมินรูปทรงได้ จากนั้น นำ ID ของงานพรีวิวที่เสร็จสมบูรณ์ไปใช้กับงาน ปรับปรุง (mode: "refine") เพื่อเพิ่มเท็กซ์เจอร์ให้กับเมช ทั้งสองขั้นตอนใช้เอนด์พอยต์เดียวกัน

POST/openapi/v2/text-to-3d

สร้างงาน Text to 3D Preview

เอนด์พอยต์นี้จะสร้างงาน Text to 3D preview ซึ่งจะสร้างเมช 3D ที่ยังไม่มีการลงพื้นผิว (จีออเมทรีเท่านั้น) จาก prompt ข้อความ นี่คือขั้นตอนแรกของขั้นตอนการทำงานแบบสองขั้นตอน เมื่อ preview สำเร็จแล้ว ให้ใช้ task ID ที่ได้รับกลับมาเพื่อ สร้างงาน refine สำหรับการลงพื้นผิว ดูข้อมูลเพิ่มเติมได้ที่ The Text to 3D Task Object สำหรับ response schema แบบเต็ม

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ฟิลด์นี้ควรตั้งค่าเป็น "preview" เมื่อสร้างงาน preview
Name
prompt
Type
string
จำเป็น
Description
อธิบายว่าโมเดล 3D นี้เป็นวัตถุประเภทใด สูงสุด 800 ตัวอักษร
Name
model_type
Type
string
ค่าเริ่มต้น standard
Description
ระบุประเภทของการสร้างเมช 3D
ค่าที่ใช้ได้:
- standard: การสร้างเมช 3D แบบละเอียดสูงตามปกติ
- smart-topology: เลือกโมเดล Smart Topology ด้วย ai_model (meshy-t2)
- lowpoly (เลิกใช้): สร้างเมชแบบโลว์โพลีที่ปรับให้เหมาะสมสำหรับโพลิกอนที่สะอาดยิ่งขึ้น เราแนะนำให้ใช้ smart-topology แทน
เมื่อเลือก smart-topology ค่า should_remesh และ decimation_mode จะถูกละเว้น และรับเฉพาะ topology: triangle เท่านั้น
เมื่อเลือก lowpoly ค่า ai_model, topology, target_polycount, และ should_remesh จะถูกละเว้น
Name
ai_model
Type
string
ค่าเริ่มต้น latest
Description
ID ของโมเดลที่จะใช้ ค่าที่ใช้ได้ขึ้นอยู่กับ model_type
การสร้างแบบ Standard (model_type: standard):
- meshy-5, meshy-6, meshy-7, latest (Meshy 7)
การสร้างแบบ Smart Topology (model_type: smart-topology):
- meshy-t2 (ค่าเริ่มต้น): โมเดล Smart Topology — topology ที่สะอาดกว่า มีการแยกส่วนต่าง ๆ ออกจากกันโดยธรรมชาติ ผลลัพธ์เป็นสามเหลี่ยม และสามารถกำหนดจำนวนหน้าได้ด้วย target_polycount
Name
ultra_mode
Type
boolean
ค่าเริ่มต้น false
Description
เปิดใช้งานการสร้างแบบ Ultra สำหรับจีออเมทรีที่มีความละเอียดสูงขึ้นพร้อมรายละเอียดพื้นผิวที่ละเอียดยิ่งขึ้น การสร้างจะใช้เวลานานขึ้นและเพิ่ม 5 เครดิต
รองรับเฉพาะเมื่อ ai_model เป็น meshy-7 (หรือ latest) และเฉพาะใน mode preview เท่านั้น
Name
should_remesh
Type
boolean
ค่าเริ่มต้น false (meshy-6, meshy-7), true (others)
Description
ควบคุมว่าจะเปิดใช้งานขั้นตอน remesh หรือไม่ สำหรับโมเดลคุณภาพสูงสุด เราแนะนำให้ตั้งค่า should_remesh เป็น false

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

Name
topology
Type
string
ค่าเริ่มต้น triangle
Description
ระบุ topology ของโมเดลที่สร้างขึ้น
ค่าที่ใช้ได้:
- quad: สร้างเมชที่ส่วนใหญ่เป็นรูปสี่เหลี่ยม
- triangle: สร้างเมชสามเหลี่ยมที่ลดจำนวนโพลิกอนแล้ว
ผลลัพธ์ของ Smart Topology เป็นสามเหลี่ยมเท่านั้น หากขอ quad พร้อมกับ ai_model: meshy-t2 ระบบจะส่งข้อผิดพลาดกลับมา
Name
decimation_mode
Type
integer
Description
เปิดใช้งานการลดจำนวนโพลิกอนแบบปรับตัวได้โดยตั้งค่าระดับจำนวนโพลิกอน เมื่อตั้งค่านี้ target_polycount จะถูกละเว้น
ค่าที่ใช้ได้:
- 1: ปรับตัวได้ — จำนวนโพลิกอนสูงมาก
- 2: ปรับตัวได้ — จำนวนโพลิกอนสูง
- 3: ปรับตัวได้ — จำนวนโพลิกอนปานกลาง
- 4: ปรับตัวได้ — จำนวนโพลิกอนต่ำ

Name
target_polycount
Type
integer
Description
จำนวนโพลิกอน (หน้า) เป้าหมายในผลลัพธ์ จำนวนจริงอาจแตกต่างจากเป้าหมายขึ้นอยู่กับจีออเมทรี
target_polycount จะมีผลใน 2 กรณีที่เป็นอิสระต่อกัน:
- Remesh — เมื่อ should_remesh: true บนโมเดล standard เมชจะถูกรีเมช (ลดจำนวนโพลิกอน) ให้ใกล้เคียงกับจำนวนนี้ ช่วงค่าคือ 100 ถึง 300,000 ค่าเริ่มต้น 30,000 หากมีการตั้งค่า decimation_mode ค่านั้นจะมีลำดับความสำคัญเหนือกว่าและ target_polycount จะถูกละเว้น
- Smart Topology — เมื่อ model_type: smart-topology และ ai_model: meshy-t2 โมเดลจะถูกสร้างขึ้นโดยตรงที่จำนวนหน้านี้ โดยไม่มีการรัน remesh และไม่จำเป็นต้องใช้ should_remesh ช่วงค่าคือ 100 ถึง 15,000 ค่าเริ่มต้น 4,000

Name
symmetry_mode
Type
string
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น auto
Description
เลิกใช้ พารามิเตอร์นี้ไม่มีผลต่อผลลัพธ์อีกต่อไป
ฟิลด์ symmetry_mode ควบคุมพฤติกรรมของสมมาตรระหว่างกระบวนการสร้างโมเดล
ค่าที่ใช้ได้มีดังนี้:
- off: ปิดใช้งานสมมาตร
- auto: กำหนดและใช้สมมาตรโดยอัตโนมัติตามจีออเมทรีที่ป้อนเข้ามา
- on: บังคับใช้สมมาตรระหว่างการสร้าง
Name
pose_mode
Type
string
ค่าเริ่มต้น ""
Description
ระบุ pose mode สำหรับโมเดลที่สร้างขึ้น
ค่าที่ใช้ได้:
- a-pose: สร้างโมเดลในท่า A
- t-pose: สร้างโมเดลในท่า T
- "" (สตริงว่าง): ไม่มีการกำหนดท่าใด ๆ
Name
is_a_t_pose
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
ใช้ pose_mode แทน ว่าจะสร้างโมเดลในท่า A/T หรือไม่
Name
art_style
Type
string
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น realistic
Description
ไม่รองรับใน Meshy-6 คำขอที่ใช้ Meshy-6 จะละเว้น art_style และบางการรวมกันอาจทำให้เกิดข้อผิดพลาด ค่าที่ใช้ได้: realistic, sculpture
ควรตั้งค่า enable_pbr เป็น false เมื่อใช้สไตล์ Sculpture เนื่องจากสไตล์ Sculpture จะสร้างชุด PBR แมปของตัวเอง
Name
moderation
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true เนื้อหาที่ป้อนเข้ามาจะถูกตรวจสอบโดยอัตโนมัติเพื่อหาเนื้อหาที่อาจเป็นอันตราย หากตรวจพบเนื้อหาที่เป็นอันตราย งานจะไม่ดำเนินต่อไปยังขั้นตอนการสร้าง
ข้อความจาก prompt จะถูกตรวจสอบ
Name
target_formats
Type
string[]
Description
ระบุรูปแบบไฟล์ 3D ที่จะรวมไว้ในผลลัพธ์ จะมีการสร้างและส่งกลับเฉพาะรูปแบบที่ร้องขอเท่านั้น ซึ่งสามารถลดเวลาที่ใช้ในการทำงานให้เสร็จสมบูรณ์ได้ หากไม่ระบุ จะรวมทุกรูปแบบที่รองรับ
ค่าที่ใช้ได้: glb, obj, fbx, stl, usdz, 3mf
หากไม่ระบุ จะสร้างทุกรูปแบบยกเว้น 3mf โดย 3mf จะรวมอยู่ด้วยก็ต่อเมื่อมีการระบุอย่างชัดเจนเท่านั้น
Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true งานจะเรนเดอร์เวอร์ชันที่มีพื้นหลังโปร่งใส (RGBA) ของ preview เพิ่มเติม และส่งกลับเป็น alpha_thumbnail_url ใน response ของ GET ฟิลด์ thumbnail_url เดิมจะไม่มีการเปลี่ยนแปลง
Name
auto_size
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true บริการจะใช้ AI vision เพื่อประมาณความสูงจริงของวัตถุโดยอัตโนมัติ และปรับขนาดโมเดลให้สอดคล้องกัน จุดกำเนิดจะเป็น bottom โดยค่าเริ่มต้น เว้นแต่จะมีการตั้งค่า origin_at อย่างชัดเจน

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

Name
origin_at
Type
string
ค่าเริ่มต้น bottom
Description
ตำแหน่งของจุดกำเนิดเมื่อเปิดใช้งาน auto_size
ค่าที่ใช้ได้: bottom, center

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

พร็อพเพอร์ตี้ result ของ response จะมี id ของงาน Text to 3D ที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:
- ขาดพารามิเตอร์: พารามิเตอร์ที่จำเป็น (เช่น prompt, mode) หายไป
- พารามิเตอร์ไม่ถูกต้อง: art_style ไม่ใช่หนึ่งในค่าที่อนุญาต
- prompt ยาวเกินไป: prompt เกินขีดจำกัดจำนวนตัวอักษร
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการทำงานนี้
Name
429 - Too Many Requests
Description
คุณเกินขีดจำกัดการจำกัดอัตราของคุณแล้ว

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with remesh and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

POST/openapi/v2/text-to-3d

สร้างงาน Text to 3D Refine

เอนด์พอยต์นี้สร้างงาน Text to 3D refine ซึ่งจะนำเท็กซ์เจอร์ไปใช้กับพรีวิวเมชที่เสร็จสมบูรณ์แล้ว คุณต้องระบุ preview_task_id จากงานพรีวิวที่สำเร็จ ขั้นตอนนี้เป็นขั้นตอนที่สองของกระบวนการทำงานสองขั้นตอน

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ฟิลด์นี้ควรตั้งค่าเป็น "refine" เมื่อสร้างงาน refine
Name
preview_task_id
Type
string
จำเป็น
Description
รหัสงานพรีวิวที่เกี่ยวข้อง
สถานะของงานพรีวิวที่ระบุต้องเป็น SUCCEEDED
Name
enable_pbr
Type
boolean
ค่าเริ่มต้น false
Description
สร้าง PBR แมป (metallic, roughness, normal) เพิ่มเติมจากสีพื้นฐาน จะมีการรวม emission map ด้วยเมื่อ ai_model เป็น meshy-6 ยกเว้นที่ texture_resolution: 8k (จะไม่สร้าง emission map) ส่วน meshy-7 (และ latest) จะไม่สร้าง emission map
Name
texture_resolution
Type
string
ค่าเริ่มต้น 2k
Description
ความละเอียดเท็กซ์เจอร์สีพื้นฐาน หนึ่งใน 2k (2048×2048), 4k (4096×4096) หรือ 8k (8192×8192) ความละเอียดที่สูงกว่าจะจับรายละเอียดพื้นผิวได้มากกว่า ใช้ได้เฉพาะกับ mode refine เท่านั้น
4k และ 8k ต้องใช้ ai_model เป็น meshy-6, meshy-7 หรือ latest ที่ 8k จะไม่สร้าง emission map
Name
hd_texture
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
ใช้ texture_resolution แทน — เทียบเท่ากับ texture_resolution: "4k" เมื่อตั้งค่าทั้งสองอย่าง texture_resolution จะมีความสำคัญกว่า
Name
texture_prompt
Type
string
Description
ระบุ prompt ข้อความเพิ่มเติมเพื่อชี้นำกระบวนการทำเท็กซ์เจอร์ สูงสุด 800 ตัวอักษร
Name
texture_image_url
Type
string
Description
ระบุภาพ 2 มิติเพื่อชี้นำกระบวนการทำเท็กซ์เจอร์ ปัจจุบันรองรับรูปแบบ .jpg, .jpeg และ .png
มีสองวิธีในการระบุภาพ:
- URL ที่เข้าถึงได้แบบสาธารณะ: URL ที่สามารถเข้าถึงได้จากอินเทอร์เน็ตสาธารณะ
- Data URI: ข้อมูล URI ของภาพที่เข้ารหัสแบบ base64 ตัวอย่างของ data URI: data:image/jpeg;base64,<your base64-encoded image data>
การทำเท็กซ์เจอร์จากภาพอาจไม่ทำงานได้อย่างเหมาะสมหากมีความแตกต่างของจีออเมทรีอย่างมากระหว่างแอสเซ็ทต้นฉบับกับภาพที่อัปโหลด สามารถใช้ได้เพียงหนึ่งใน texture_image_url หรือ texture_prompt เพื่อชี้นำกระบวนการทำเท็กซ์เจอร์ หากระบุทั้งสองพารามิเตอร์ ระบบจะใช้ texture_prompt เป็นค่าเริ่มต้นในการทำเท็กซ์เจอร์ให้กับโมเดล
Name
ai_model
Type
string
ค่าเริ่มต้น latest
Description
ID ของโมเดลที่จะใช้สำหรับการ refine ค่าที่ใช้ได้: meshy-5, meshy-6, meshy-7, latest (Meshy 7)
latest จะแปลผลในที่นี้เหมือนกับที่ใช้ในงานพรีวิวทุกประการ (ปัจจุบันคือ Meshy 7) ดังนั้นพรีวิวแบบ latest และงาน refine แบบ latest ของมันจะตกที่โมเดลเท็กซ์เจอร์เดียวกันเสมอ
Name
moderation
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true เนื้อหาที่ป้อนเข้ามาจะถูกตรวจสอบโดยอัตโนมัติเพื่อหาเนื้อหาที่อาจเป็นอันตราย หากตรวจพบเนื้อหาที่เป็นอันตราย งานจะไม่ดำเนินการต่อไปยังขั้นตอนการสร้าง
ทั้งข้อความจาก texture_prompt และภาพจาก texture_image_url จะถูกตรวจสอบ
Name
remove_lighting
Type
boolean
ค่าเริ่มต้น true
Description
ลบไฮไลต์และเงาออกจากเท็กซ์เจอร์สีพื้นฐาน ให้ผลลัพธ์ที่สะอาดขึ้นซึ่งทำงานได้ดีกว่าภายใต้การตั้งค่าแสงแบบกำหนดเอง
จะมีผลก็ต่อเมื่อ ai_model เป็น meshy-6 เท่านั้น สำหรับ meshy-7 (และ latest) พารามิเตอร์นี้จะถูกรับเข้ามาแต่จะถูกเพิกเฉย
Name
target_formats
Type
string[]
Description
ระบุว่าจะรวมรูปแบบไฟล์ 3D ใดไว้ในผลลัพธ์ จะสร้างและส่งคืนเฉพาะรูปแบบที่ร้องขอเท่านั้น ซึ่งสามารถลดเวลาในการทำงานให้เสร็จสมบูรณ์ได้ หากไม่ระบุ ระบบจะรวมรูปแบบที่รองรับทั้งหมด
ค่าที่ใช้ได้: glb, obj, fbx, stl, usdz, 3mf
หากไม่ระบุ ระบบจะสร้างทุกรูปแบบยกเว้น 3mf โดย 3mf จะรวมอยู่ด้วยก็ต่อเมื่อมีการระบุอย่างชัดเจนเท่านั้น
Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true งานจะแสดงผลภาพพรีวิวเวอร์ชันพื้นหลังโปร่งใส (RGBA) เพิ่มเติม และส่งคืนเป็น alpha_thumbnail_url ในการตอบกลับของ GET ฟิลด์ thumbnail_url ที่มีอยู่เดิมจะไม่มีการเปลี่ยนแปลง
Name
auto_size
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true บริการจะใช้ AI vision เพื่อประมาณความสูงจริงของวัตถุโดยอัตโนมัติ และปรับขนาดโมเดลให้เหมาะสม จุดกำเนิดจะเป็นค่าเริ่มต้นที่ bottom เว้นแต่จะมีการตั้งค่า origin_at อย่างชัดเจน

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

Name
origin_at
Type
string
ค่าเริ่มต้น bottom
Description
ตำแหน่งของจุดกำเนิดเมื่อเปิดใช้งาน auto_size
ค่าที่ใช้ได้: bottom, center

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

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของงาน Text to 3D ที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:
- รหัสงานไม่ถูกต้อง: preview_task_id ไม่ถูกต้องหรือไม่มีอยู่
- งานยังไม่พร้อม: งานพรีวิวยังไม่สำเร็จ
- โมเดลไม่ตรงกัน: AI model ของงานพรีวิวไม่เข้ากันกับโมเดล refine ที่ร้องขอ
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการดำเนินงานนี้
Name
404 - Not Found
Description
ไม่พบงานพรีวิวที่ระบุโดย preview_task_id
Name
429 - Too Many Requests
Description
คุณเกินขีดจำกัดอัตราการใช้งานแล้ว

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v2/text-to-3d/:id

ดึงงานข้อความเป็น 3D

เอนด์พอยต์นี้ช่วยให้คุณดึงงานข้อความเป็น 3D โดยใช้ id ของงานที่ถูกต้อง ดูที่ วัตถุงานข้อความเป็น 3D เพื่อดูว่ามีคุณสมบัติอะไรบ้างที่รวมอยู่ในวัตถุงานข้อความเป็น 3D

เอนด์พอยต์นี้ใช้ได้ทั้งงานพรีวิวและงานปรับปรุง

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงานข้อความเป็น 3D ที่จะดึง

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

การตอบกลับจะมีวัตถุงานข้อความเป็น 3D ตรวจสอบ ส่วน วัตถุงานข้อความเป็น 3D สำหรับรายละเอียด

ตัวอย่าง

โหมด	โมเดลตัวอย่าง
พรีวิว
ปรับปรุง

คำขอ

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

การตอบกลับ

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}

DELETE/openapi/v2/text-to-3d/:id

ลบงานข้อความเป็น 3D

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

พารามิเตอร์ในเส้นทาง

Name
id
Type
path
Description
ID ของงานข้อความเป็น 3D ที่จะลบ

การส่งคืน

ส่งคืน 200 OK เมื่อสำเร็จ

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v2/text-to-3d

รายการงาน ข้อความเป็น 3D

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

พารามิเตอร์

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

ผลลัพธ์

ส่งคืนรายการที่แบ่งหน้า The Text to 3D Task Objects

Request

GET

/openapi/v2/text-to-3d

curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

GET/openapi/v2/text-to-3d/:id/stream

สตรีมงานข้อความเป็น 3D

เอนด์พอยต์นี้สตรีมการอัปเดตแบบเรียลไทม์สำหรับงานข้อความเป็น 3D โดยใช้ Server-Sent Events (SSE)

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงานข้อความเป็น 3D ที่จะสตรีม

การส่งคืน

ส่งคืนสตรีมของ วัตถุงานข้อความเป็น 3D เป็น Server-Sent Events

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

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"texture_urls": [
  {
    "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
    "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
    "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
    "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
    "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
  }
],
"preceding_tasks": 0,
"task_error": {

  "message": ""

},

"consumed_credits": 20
}

วัตถุงาน ข้อความเป็น 3D

วัตถุงาน ข้อความเป็น 3D เป็นหน่วยงานที่ Meshy ใช้ติดตามเพื่อสร้างโมเดล 3D จากข้อมูล ข้อความ มีสองขั้นตอนของ Text to 3D API คือ preview และ refine ขั้นตอน preview ใช้สำหรับสร้างโมเดล 3D ที่มีเฉพาะเมช และขั้นตอน refine ใช้สำหรับสร้างโมเดล 3D ที่มีเท็กซ์เจอร์โดยอิงจากผลลัพธ์ของขั้นตอน preview

วัตถุนี้มีคุณสมบัติดังต่อไปนี้:

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงานนี้ ในขณะที่เราใช้ UUID ที่สามารถเรียงลำดับได้สำหรับ id ของงานเป็นรายละเอียดการใช้งาน คุณไม่ควรทำการคาดเดาใดๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของงาน ข้อความเป็น 3D ค่าที่เป็นไปได้คือ text-to-3d-preview สำหรับงานขั้นตอน preview และ text-to-3d-refine สำหรับงานขั้นตอน refine
Name
model_urls
Type
object
Description
URL ที่สามารถดาวน์โหลดได้สำหรับไฟล์โมเดล 3D ที่มีเท็กซ์เจอร์ที่สร้างโดย Meshy คุณสมบัติสำหรับรูปแบบจะถูกละเว้นหากรูปแบบนั้นไม่ได้ถูกสร้างแทนที่จะคืนค่าเป็นสตริงว่าง
- Name
  glb
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับไฟล์ GLB
- Name
  fbx
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับไฟล์ FBX
- Name
  usdz
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับไฟล์ USDZ
- Name
  obj
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับไฟล์ OBJ
- Name
  mtl
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับไฟล์ MTL
- Name
  stl
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับไฟล์ STL
- Name
  3mf
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับไฟล์ 3MF มีเฉพาะเมื่อ 3mf ถูกขอผ่าน target_formats
Name
prompt
Type
string
Description
นี่คือ prompt ที่ไม่ได้ถูกแก้ไขที่ใช้ในการสร้างงาน
Name
negative_prompt
Type
string
⚠ เลิกใช้แล้ว
Description
รักษาไว้เพื่อความเข้ากันได้ย้อนหลัง ฟิลด์นี้ไม่มีผลกระทบต่อโมเดลที่สร้างขึ้น
Name
art_style
Type
string
⚠ เลิกใช้แล้ว
Description
art_style ที่ไม่ได้ถูกแก้ไขที่ใช้ในการสร้างงาน preview ไม่รองรับโดย Meshy-6
Name
texture_richness
Type
string
⚠ เลิกใช้แล้ว
Description
รักษาไว้เพื่อความเข้ากันได้ย้อนหลัง ฟิลด์นี้ไม่มีผลกระทบต่อโมเดลที่สร้างขึ้น
Name
texture_prompt
Type
string
Description
ข้อความ prompt เพิ่มเติมที่ให้เพื่อเป็นแนวทางในกระบวนการเท็กซ์เจอร์ในขั้นตอน refine
Name
ultra_mode
Type
boolean
Description
สะท้อนค่า ultra_mode ที่สร้างงาน preview ด้วย มีเฉพาะสำหรับงาน preview meshy-7 (หรือ latest) ที่ตั้งค่า ultra_mode ไว้อย่างชัดเจน; ละเว้นในกรณีอื่น
Name
texture_image_url
Type
string
Description
URL ที่สามารถดาวน์โหลดได้สำหรับภาพเท็กซ์เจอร์ที่ใช้ในการนำทางกระบวนการเท็กซ์เจอร์
Name
thumbnail_url
Type
string
Description
URL ที่สามารถดาวน์โหลดได้สำหรับภาพย่อของไฟล์โมเดล
Name
alpha_thumbnail_url
Type
string
Description
URL ที่สามารถดาวน์โหลดได้สำหรับเวอร์ชันพื้นหลังโปร่งใส (RGBA) ของ thumbnail_url มีเฉพาะเมื่อสร้างงานด้วย alpha_thumbnail: true และการแสดงผลโปร่งใสสำเร็จ; มิฉะนั้นฟิลด์นี้จะถูกละเว้น
Name
video_url
Type
string
⚠ เลิกใช้แล้ว
Description
URL ที่สามารถดาวน์โหลดได้สำหรับวิดีโอตัวอย่าง จะถูกลบออกในรุ่นถัดไป
Name
progress
Type
integer
Description
ความคืบหน้าของงาน หากงานยังไม่เริ่มต้น คุณสมบัตินี้จะเป็น 0 เมื่อใดที่งานสำเร็จแล้ว จะกลายเป็น 100
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานเริ่มต้น ในหน่วยมิลลิวินาที หากงานยังไม่เริ่มต้น คุณสมบัตินี้จะเป็น 0
ไทม์สแตมป์แสดงถึงจำนวนมิลลิวินาทีที่ผ่านไปตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 PM GMT แสดงเป็น 1693569600000 สิ่งนี้ใช้กับไทม์สแตมป์ ทั้งหมด ใน Meshy API
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานถูกสร้างขึ้น ในหน่วยมิลลิวินาที
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานเสร็จสิ้น ในหน่วยมิลลิวินาที หากงานยังไม่เสร็จสิ้น คุณสมบัตินี้จะเป็น 0
Name
status
Type
string
Description
สถานะของงาน ค่าที่เป็นไปได้คือหนึ่งใน PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
texture_urls
Type
array
Description
อาร์เรย์ของวัตถุ URL เท็กซ์เจอร์ที่สร้างจากงาน โดยปกติจะมีเพียง หนึ่ง วัตถุ URL เท็กซ์เจอร์ แต่ละ URL เท็กซ์เจอร์มีคุณสมบัติดังต่อไปนี้:
- Name
  base_color
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับภาพแผนที่สีพื้นฐาน
- Name
  metallic
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับภาพแผนที่เมทัลลิก
  หากงานถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละเว้น
- Name
  normal
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับภาพนอร์มัลแมป
  หากงานถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละเว้น
- Name
  roughness
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับภาพแผนที่ความหยาบ
  หากงานถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละเว้น
- Name
  emission
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับภาพแผนที่การปล่อยแสง
  หากงานถูกสร้างด้วย enable_pbr: false หรือ ai_model เป็น meshy-5 คุณสมบัตินี้จะถูกละเว้น
Name
preceding_tasks
Type
integer
Description
จำนวนงานที่มาก่อน
ค่าของฟิลด์นี้มีความหมายเฉพาะเมื่อสถานะของงานคือ PENDING
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับงานที่ล้มเหลว ดู ข้อผิดพลาด สำหรับการอ้างอิงวัตถุ task_error ทั้งหมด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ใช้ไปกับงานนี้ มีเมื่อสถานะของงานคือ PENDING, IN_PROGRESS, หรือ SUCCEEDED คืนค่า 0 สำหรับงาน FAILED (เครดิตจะถูกคืนเมื่อเกิดความล้มเหลว)

ตัวอย่างวัตถุงาน ข้อความเป็น 3D

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}