Text to 3D API

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

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

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

สร้าง Task ตัวอย่าง (Preview) สำหรับข้อความเป็น 3D

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

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ฟิลด์นี้ควรตั้งค่าเป็น "preview" เมื่อสร้าง preview task
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
ควบคุมว่าจะเปิดใช้งานขั้นตอนรีเมชหรือไม่ สำหรับโมเดลคุณภาพสูงสุด เราแนะนำให้ตั้งค่า should_remesh เป็น false

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

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

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 โมเดลจะถูกสร้างขึ้นโดยตรงด้วยจำนวนหน้านี้ จะไม่มีการรีเมชเกิดขึ้น และไม่จำเป็นต้องใช้ 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 pose
- t-pose: สร้างโมเดลในท่า T pose
- "" (สตริงว่าง): ไม่มีการกำหนดท่าเฉพาะ
Name
is_a_t_pose
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
ใช้ pose_mode แทน กำหนดว่าจะสร้างโมเดลในท่า A/T pose หรือไม่
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 เนื้อหาที่ป้อนเข้ามาจะถูกตรวจสอบเนื้อหาที่อาจเป็นอันตรายโดยอัตโนมัติ หากตรวจพบเนื้อหาที่เป็นอันตราย task จะไม่ดำเนินการสร้างต่อ
ข้อความจาก prompt จะถูกตรวจสอบ
Name
target_formats
Type
string[]
Description
ระบุรูปแบบไฟล์ 3D ที่จะรวมอยู่ในผลลัพธ์ เฉพาะรูปแบบที่ร้องขอเท่านั้นที่จะถูกสร้างและส่งคืน ซึ่งสามารถลดเวลาในการทำ task ให้เสร็จสมบูรณ์ได้ หากไม่ระบุ จะรวมรูปแบบทั้งหมดที่รองรับ
ค่าที่ใช้ได้: glb, obj, fbx, stl, usdz, 3mf
หากไม่ระบุ จะสร้างทุกรูปแบบยกเว้น 3mf โดย 3mf จะรวมอยู่ด้วยเมื่อระบุอย่างชัดเจนเท่านั้น
Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true task จะเรนเดอร์ preview เวอร์ชันพื้นหลังโปร่งใส (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 ของ task ข้อความเป็น 3D ที่สร้างขึ้นใหม่

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

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

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

เอนด์พอยต์นี้สร้างงาน refine ข้อความเป็น 3D ซึ่งจะใส่เท็กซ์เจอร์ให้กับเมชพรีวิวที่เสร็จสมบูรณ์แล้ว คุณต้องระบุ 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: data 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
ค่าเริ่มต้น inherited from the preview task
Description
รหัสของโมเดลที่จะใช้สำหรับการ refine ค่าที่ใช้ได้: meshy-5, meshy-6, meshy-7, latest (Meshy 7)
ละเว้นพารามิเตอร์นี้เพื่อสืบทอดโมเดลที่ใช้โดยงานพรีวิว ซึ่งจะทำให้พรีวิวและ refine ของมันใช้โมเดลเดียวกันตลอดกระบวนการ ระบุค่าอย่างชัดเจนเพื่อลบล้างการสืบทอดนั้น
การระบุ 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 ของงานข้อความเป็น 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

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

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

เอนด์พอยต์นี้ใช้งานได้กับทั้ง task ประเภท preview และ refine

พารามิเตอร์

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

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

การตอบกลับจะประกอบด้วย Text to 3D task object ดูรายละเอียดเพิ่มเติมได้ที่ส่วน The Text to 3D Task Object

ตัวอย่าง

Mode	โมเดลตัวอย่าง
Preview
Refine

Request

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

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=***",
    "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

ลบงาน Text to 3D

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

Path Parameters

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

Returns

คืนค่า 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

List Text to 3D Tasks

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงาน ข้อความเป็น 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 ที่ต้องการสตรีม

ผลลัพธ์ที่ส่งคืน

ส่งคืนสตรีมของ The Text to 3D Task Objects ในรูปแบบ 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
}

The Text to 3D Task Object

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

อ็อบเจ็กต์นี้มีคุณสมบัติดังต่อไปนี้

Properties

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับ task แม้ว่าเราจะใช้ k-sortable UUID เป็นรายละเอียดการใช้งานสำหรับ task id แต่คุณ ไม่ควร ตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของ task Text to 3D ค่าที่เป็นไปได้คือ text-to-3d-preview สำหรับ task ในขั้นตอน preview และ text-to-3d-refine สำหรับ task ในขั้นตอน 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 ที่ไม่ถูกดัดแปลงซึ่งใช้ในการสร้าง task
Name
negative_prompt
Type
string
⚠ เลิกใช้แล้ว
Description
คงไว้เพื่อความเข้ากันได้แบบย้อนหลัง ฟิลด์นี้ไม่มีผลต่อการทำงานของโมเดลที่สร้างขึ้น
Name
art_style
Type
string
⚠ เลิกใช้แล้ว
Description
art_style ที่ไม่ถูกดัดแปลงซึ่งใช้ในการสร้าง preview task ไม่รองรับสำหรับ 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 task จะปรากฏเฉพาะสำหรับ preview task ของ 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 จะปรากฏเฉพาะเมื่อ task ถูกสร้างด้วย alpha_thumbnail: true และภาพตัวอย่างแบบโปร่งใสถูกเรนเดอร์สำเร็จเท่านั้น มิฉะนั้นฟิลด์นี้จะถูกละเว้น
Name
video_url
Type
string
⚠ เลิกใช้แล้ว
Description
URL สำหรับดาวน์โหลดวิดีโอตัวอย่าง จะถูกลบออกในรุ่นถัดไป
Name
progress
Type
integer
Description
ความคืบหน้าของ task หากยังไม่เริ่ม task คุณสมบัตินี้จะเป็น 0 เมื่อ task สำเร็จแล้ว ค่านี้จะกลายเป็น 100
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เริ่มทำงาน มีหน่วยเป็นมิลลิวินาที หากยังไม่เริ่ม task คุณสมบัตินี้จะเป็น 0
ไทม์สแตมป์แสดงจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 น. GMT จะแสดงเป็น 1693569600000 สิ่งนี้ใช้กับ ไทม์สแตมป์ ทั้งหมด ใน Meshy API
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่สร้าง task มีหน่วยเป็นมิลลิวินาที
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น มีหน่วยเป็นมิลลิวินาที หากยังไม่เสร็จสิ้น task คุณสมบัตินี้จะเป็น 0
Name
status
Type
string
Description
สถานะของ task ค่าที่เป็นไปได้คือ PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
texture_urls
Type
array
Description
อาร์เรย์ของอ็อบเจ็กต์ URL เท็กซ์เจอร์ที่สร้างขึ้นจาก task โดยปกติแล้วจะมีอ็อบเจ็กต์ URL เท็กซ์เจอร์เพียง หนึ่ง รายการเท่านั้น URL เท็กซ์เจอร์แต่ละรายการมีคุณสมบัติดังต่อไปนี้
- Name
  base_color
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแมปสีพื้นฐาน (base color map)
- Name
  metallic
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแมป metallic
  หาก task ถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละเว้น
- Name
  normal
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพนอร์มัลแมป
  หาก task ถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละเว้น
- Name
  roughness
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแมป roughness
  หาก task ถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละเว้น
- Name
  emission
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแมป emission
  หาก task ถูกสร้างด้วย enable_pbr: false หรือ ai_model เป็น meshy-5 คุณสมบัตินี้จะถูกละเว้น
Name
preceding_tasks
Type
integer
Description
จำนวน task ที่อยู่ก่อนหน้า
ค่าของฟิลด์นี้มีความหมายก็ต่อเมื่อสถานะของ task เป็น PENDING เท่านั้น
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับ task ที่ล้มเหลว ดูข้อมูลอ้างอิงอ็อบเจ็กต์ task_error ฉบับเต็มได้ที่ ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ถูกใช้ไปโดย task นี้ จะปรากฏเมื่อสถานะของ task เป็น PENDING, IN_PROGRESS, หรือ SUCCEEDED จะคืนค่าเป็น 0 สำหรับ task ที่ FAILED (เครดิตจะถูกคืนเมื่อล้มเหลว)

Example Text to 3D Task Object

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