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

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

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

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

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

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

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ควรตั้งค่าฟิลด์นี้เป็น "preview" เมื่อสร้างงานพรีวิว
Name
prompt
Type
string
จำเป็น
Description
อธิบายว่าวัตถุของโมเดล 3D เป็นประเภทใด สูงสุด 600 อักขระ
Name
model_type
Type
string
ค่าเริ่มต้น standard
Description
ระบุประเภทของการสร้างเมช 3D
ค่าที่ใช้ได้:
- standard: การสร้างเมช 3D รายละเอียดสูงแบบปกติ
- lowpoly: สร้างเมชโลว์โพลีที่ปรับให้เหมาะกับโพลิกอนที่สะอาดขึ้น
เมื่อเลือก lowpoly ระบบจะไม่สนใจ ai_model, topology, target_polycount, should_remesh
Name
ai_model
Type
string
ค่าเริ่มต้น latest
Description
ID ของโมเดลที่จะใช้ ค่าที่ใช้ได้: meshy-5, meshy-6, latest (Meshy 6)
Name
should_remesh
Type
boolean
ค่าเริ่มต้น false (meshy-6), true (others)
Description
ควบคุมว่าจะเปิดใช้งานเฟสรีเมชหรือไม่ เมื่อตั้งค่าเป็น false API จะส่งคืนเมชสามเหลี่ยมความแม่นยำสูงสุดโดยตรง

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

Name
topology
Type
string
ค่าเริ่มต้น triangle
Description
ระบุ topology ของโมเดลที่สร้างขึ้น
ค่าที่ใช้ได้:
- quad: สร้างเมชที่มี quad เป็นหลัก
- triangle: สร้างเมชสามเหลี่ยมที่ถูกลดจำนวนแล้ว
Name
target_polycount
Type
integer
ค่าเริ่มต้น 30,000
Description
ระบุจำนวนโพลิกอนเป้าหมายในโมเดลที่สร้างขึ้น จำนวนโพลิกอนจริงอาจเบี่ยงเบนจากเป้าหมายได้ ขึ้นอยู่กับความซับซ้อนของจีออเมทรี
ช่วงค่าที่ถูกต้องจะแตกต่างกันไปตามระดับผู้ใช้:
- 100 ถึง 300,000 (รวม)
Name
decimation_mode
Type
integer
Description
เปิดใช้งานการลดจำนวนแบบปรับตัวได้โดยตั้งค่าระดับจำนวนโพลิกอน เมื่อตั้งค่าแล้ว ระบบจะไม่สนใจ target_polycount
ค่าที่ใช้ได้:
- 1: แบบปรับตัว — จำนวนโพลิกอนสูงมาก
- 2: แบบปรับตัว — จำนวนโพลิกอนสูง
- 3: แบบปรับตัว — จำนวนโพลิกอนปานกลาง
- 4: แบบปรับตัว — จำนวนโพลิกอนต่ำ

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) ของพรีวิวเพิ่มเติม และส่งคืนเป็น 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
คำขอไม่สามารถยอมรับได้ สาเหตุทั่วไป:
- พารามิเตอร์หายไป: พารามิเตอร์ที่จำเป็น (เช่น 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

สร้างงานปรับละเอียด ข้อความเป็น 3D

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

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ควรตั้งค่าฟิลด์นี้เป็น "refine" เมื่อสร้างงานปรับละเอียด
Name
preview_task_id
Type
string
จำเป็น
Description
id ของงาน preview ที่สอดคล้องกัน
สถานะของงาน preview ที่ระบุต้องเป็น SUCCEEDED
Name
enable_pbr
Type
boolean
ค่าเริ่มต้น false
Description
สร้าง PBR แมป (metallic, roughness, normal) เพิ่มเติมจากสีฐาน นอกจากนี้ยังรวมแมป emission เมื่อ ai_model เป็น meshy-6 หรือ latest
Name
hd_texture
Type
boolean
ค่าเริ่มต้น false
Description
สร้างเท็กซ์เจอร์สีฐานที่ความละเอียด 4K (4096×4096) เพื่อรายละเอียดที่สูงขึ้น
รองรับเฉพาะเมื่อ ai_model เป็น meshy-6 หรือ latest เท่านั้น PBR แมปจะถูกสร้างที่ 2K เสมอ
Name
texture_prompt
Type
string
Description
ระบุ prompt ข้อความเพิ่มเติมเพื่อชี้นำกระบวนการสร้างเท็กซ์เจอร์ สูงสุด 600 อักขระ
Name
texture_image_url
Type
string
Description
ระบุรูปภาพ 2D เพื่อชี้นำกระบวนการสร้างเท็กซ์เจอร์ ขณะนี้เรารองรับรูปแบบ .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
ค่าเริ่มต้น latest
Description
ID ของโมเดลที่จะใช้สำหรับการปรับละเอียด ค่าที่ใช้ได้: meshy-5, meshy-6, latest (Meshy 6)
Name
moderation
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true เนื้อหาอินพุตจะถูกตรวจคัดกรองโดยอัตโนมัติเพื่อหาเนื้อหาที่อาจเป็นอันตราย หากตรวจพบเนื้อหาที่เป็นอันตราย งานจะไม่ดำเนินการสร้างต่อ
ทั้งข้อความจาก texture_prompt และรูปภาพจาก texture_image_url จะถูกตรวจคัดกรอง
Name
remove_lighting
Type
boolean
ค่าเริ่มต้น true
Description
ลบไฮไลต์และเงาออกจากเท็กซ์เจอร์สีฐาน ทำให้ได้ผลลัพธ์ที่สะอาดขึ้นและทำงานได้ดีขึ้นภายใต้การตั้งค่าแสงแบบกำหนดเอง
รองรับเฉพาะเมื่อ ai_model เป็น meshy-6 หรือ 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) ของ preview เพิ่มเติม และส่งคืนเป็น 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
คำขอไม่สามารถยอมรับได้ สาเหตุทั่วไป:
- ID งานไม่ถูกต้อง: preview_task_id ไม่ถูกต้องหรือไม่มีอยู่
- งานยังไม่พร้อม: งาน preview ยังไม่สำเร็จ
- โมเดลไม่ตรงกัน: โมเดล AI ของงาน preview เข้ากันไม่ได้กับโมเดลปรับละเอียดที่ร้องขอ
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการทำงานนี้
Name
404 - Not Found
Description
ไม่พบงาน preview ที่ระบุโดย 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

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

พารามิเตอร์

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

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

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

ตัวอย่าง

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

ลบงานข้อความเป็น 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: จัดเรียงตามเวลาที่สร้างจากมากไปน้อย

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

ส่งคืนรายการแบบแบ่งหน้าของ ออบเจ็กต์งานข้อความเป็น 3D

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 จากอินพุต ข้อความ API ข้อความเป็น 3D มีสองขั้นตอน ได้แก่ preview และ refine ขั้นตอนพรีวิวมีไว้สำหรับสร้างโมเดล 3D ที่มีเฉพาะเมช และขั้นตอนปรับแต่งมีไว้สำหรับสร้างโมเดล 3D ที่มีเท็กซ์เจอร์โดยอิงจากผลลัพธ์ของขั้นตอนพรีวิว

ออบเจ็กต์มีพร็อพเพอร์ตีดังต่อไปนี้:

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับงาน แม้ว่าเราจะใช้ UUID แบบ k-sortable สำหรับ id ของงานเป็น รายละเอียดการใช้งานจริง คุณ ไม่ควร ตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของงานข้อความเป็น 3D ค่าที่เป็นไปได้คือ text-to-3d-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 ที่ไม่มีการแก้ไข ซึ่งใช้ในการสร้างงานพรีวิว Meshy-6 ไม่รองรับ
Name
texture_richness
Type
string
⚠ เลิกใช้แล้ว
Description
คงไว้เพื่อความเข้ากันได้ย้อนหลัง ฟิลด์นี้ไม่มีผลเชิงฟังก์ชันต่อโมเดลที่สร้างขึ้น
Name
texture_prompt
Type
string
Description
prompt ข้อความเพิ่มเติมที่ให้ไว้เพื่อชี้นำกระบวนการใส่เท็กซ์เจอร์ระหว่างขั้นตอน refine
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
progress ของงาน หากงานยังไม่เริ่ม คุณสมบัตินี้จะเป็น 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 (เครดิตจะถูกคืนเมื่อเกิดความล้มเหลว)

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,
  "seed": 1234,
  "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
}