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

สร้างโมเดล 3D จากข้อความที่ป้อนในแอปพลิเคชันของคุณเอง

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

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

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

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

งานนี้ทำงานในเบื้องหลัง สำหรับระยะเวลาที่งานมักใช้ ดู เวลาในการประมวลผล

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 Ultra 4K geometry, 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",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

พารามิเตอร์

Name
mode
Type
string
จำเป็น
Description
ขั้นตอนของเวิร์กโฟลว์สองขั้นตอน ส่ง preview เพื่อสร้างงาน preview
Name
prompt
Type
string
จำเป็น
Description
ข้อความที่อธิบายวัตถุที่จะสร้าง ความยาวไม่เกิน 800 ตัวอักษร ข้อความที่ยาวกว่านี้จะคืนค่า 400
Name
model_type
Type
string
ค่าเริ่มต้น standard
Description
ประเภทของเมช 3D ที่จะสร้าง
ค่าที่ใช้ได้:
- standard: เมช 3D ที่มีรายละเอียดสูง
- smart-topology: เมช Smart Topology เลือกโมเดลด้วย ai_model (meshy-t2 หรือ meshy-t2.5)
เมื่อใช้ smart-topology, Meshy จะไม่สนใจ should_remesh และ decimation_mode และยอมรับเฉพาะ topology: triangle
Name
ai_model
Type
string
ค่าเริ่มต้น latest
Description
โมเดล AI ที่สร้างโมเดล 3D ค่าที่ใช้ได้ขึ้นอยู่กับ model_type
โมเดล Standard (model_type: standard):
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (เลิกใช้): ให้ส่ง meshy-7.1 แทน
โมเดล Smart Topology (model_type: smart-topology):
- meshy-t2: topology ที่สะอาดกว่า มีชิ้นส่วนที่แยกตามธรรมชาติ ผลลัพธ์เป็นสามเหลี่ยม และจำนวนหน้าที่คุณกำหนดเองด้วย target_polycount
- meshy-t2.5 (ค่าเริ่มต้น): รายละเอียดที่คมชัดขึ้นสำหรับ asset ในเกม ผลลัพธ์เป็นสามเหลี่ยม และจำนวนหน้าที่คุณกำหนดเองด้วย target_polycount
Name
geometry_resolution
Type
string
ค่าเริ่มต้น standard
Description
รอบการสร้างจีออเมทรี ใช้ได้เฉพาะกับงาน preview เท่านั้น การ refine ที่มีพารามิเตอร์นี้จะคืนค่า 400
ค่าที่ใช้ได้:
- standard
- 2k: รัน Ultra pass ที่ 2048³
- 4k: รัน Ultra pass ที่ 4096³ เพื่อรายละเอียดพื้นผิวที่ละเอียดขึ้น
2k ต้องใช้ meshy-7.1, latest, หรือ meshy-7 ที่เลิกใช้แล้ว 4k ต้องใช้ meshy-7.1 หรือ latest โมเดลอื่นจะคืนค่า 400
Name
ultra_mode
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
ให้ส่ง geometry_resolution แทน ultra_mode: true มีผลเหมือนกับ geometry_resolution: "2k"
Name
should_remesh
Type
boolean
ค่าเริ่มต้น true (meshy-6-lite), false (other models)
Description
ว่าจะรีเมชโมเดลหลังจากสร้างหรือไม่ สำหรับโมเดล 3D ที่มีคุณภาพสูงสุด ให้ส่ง false

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

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

Name
target_polycount
Type
integer
Description
จำนวนหน้าที่ต้องการ ผลลัพธ์อาจแตกต่างจากเป้าหมาย ขึ้นอยู่กับจีออเมทรี พารามิเตอร์นี้ใช้ได้ในสองกรณีแยกกัน:
- รีเมช: กับ should_remesh: true บนโมเดล standard Meshy จะรีเมช (ลดจำนวนหน้า) เมชให้ใกล้เคียงจำนวนนี้ ถ้าคุณกำหนด decimation_mode Meshy จะใช้ค่านั้นแทนและไม่สนใจ target_polycount
- Smart Topology: กับ model_type: smart-topology และ ai_model เป็น meshy-t2 หรือ meshy-t2.5 Meshy จะสร้างโมเดลที่จำนวนหน้านี้โดยตรง จะไม่มีการรีเมช และคุณไม่จำเป็นต้องใช้ should_remesh
ตารางต่อไปนี้แสดงช่วงและค่าเริ่มต้นของแต่ละกรณี:
กรณี ช่วง ค่าเริ่มต้น
รีเมช 100 ถึง 300000 30000
meshy-t2 100 ถึง 15000 4000
meshy-t2.5 100 ถึง 30000 15000
ค่าที่อยู่นอกช่วงจะคืนค่า 400

กรณี	ช่วง	ค่าเริ่มต้น
รีเมช	`100` ถึง `300000`	`30000`
`meshy-t2`	`100` ถึง `15000`	`4000`
`meshy-t2.5`	`100` ถึง `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น auto
Description
ไม่ต้องใส่พารามิเตอร์นี้ มันไม่มีผลต่อผลลัพธ์
ค่าที่ใช้ได้:
- off: ปิดใช้งานสมมาตร
- auto: ใช้สมมาตรตามจีออเมทรีที่ป้อนเข้ามา
- on: บังคับใช้สมมาตรระหว่างการสร้าง
Name
pose_mode
Type
string
ค่าเริ่มต้น ""
Description
ท่าทางของโมเดลที่สร้างขึ้น
ค่าที่ใช้ได้:
- 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 จะไม่สนใจมัน
Name
moderation
Type
boolean
ค่าเริ่มต้น false
Description
ว่าจะตรวจสอบ prompt หาเนื้อหาที่เป็นอันตรายก่อนสร้างหรือไม่ ถ้า Meshy ตรวจพบเนื้อหาที่เป็นอันตราย คำขอจะคืนค่า 400 และ Meshy จะไม่สร้างงาน
Name
target_formats
Type
string[]
Description
รูปแบบไฟล์ที่จะสร้าง Meshy จะสร้างและส่งคืนเฉพาะรูปแบบเหล่านี้ ซึ่งสามารถลดเวลาของงานลงได้ ถ้าคุณไม่ใส่พารามิเตอร์นี้ Meshy จะสร้างทุกรูปแบบยกเว้น 3mf ซึ่งจะสร้างให้ก็ต่อเมื่อคุณร้องขอเท่านั้น
ค่าที่ใช้ได้:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
ว่าจะเรนเดอร์ preview ที่มีพื้นหลังโปร่งใส (RGBA) เพิ่มเติมหรือไม่ ซึ่งจะส่งคืนใน alpha_thumbnail_url เมื่อคุณดึงข้อมูลงาน thumbnail_url จะไม่เปลี่ยนแปลง
Name
auto_size
Type
boolean
ค่าเริ่มต้น false
Description
ว่าจะประมาณความสูงจริงของวัตถุด้วย AI vision แล้วปรับขนาดโมเดลให้ตรงกับความสูงนั้นหรือไม่ Meshy จะวางจุดกำเนิดไว้ที่ด้านล่าง เว้นแต่คุณจะกำหนด origin_at

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

Name
origin_at
Type
string
ค่าเริ่มต้น bottom
Description
ตำแหน่งที่จะวางจุดกำเนิดของโมเดล bottom หรือ center

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

ฟิลด์ result ของการตอบกลับจะเก็บ ID ของงานข้อความเป็น 3D ใหม่

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

Name
400 - Bad Request
Description
คำขอไม่สามารถทำงานได้ ข้อความแสดงข้อผิดพลาดจะบอกว่าพบปัญหาใด ตัวอย่างเช่น:
- พารามิเตอร์ขาดหาย: พารามิเตอร์ที่จำเป็น เช่น prompt หรือ mode ขาดหายไป
- Prompt ยาวเกินไป: prompt เกินขีดจำกัดจำนวนตัวอักษร
- โมเดลไม่รองรับ Ultra: geometry_resolution เป็น 2k หรือ 4k โดยใช้ ai_model ที่ไม่รองรับ
แก้ไขคำขอ แล้วส่งใหม่อีกครั้ง ดู ข้อผิดพลาด
Name
401 - Unauthorized
Description
API คีย์ขาดหายหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
ตัวอย่างเช่น:
- เครดิตไม่เพียงพอ: บัญชีมีเครดิตไม่เพียงพอสำหรับงานนี้ หรือบัญชีถึงขีดจำกัดเครดิตแล้ว ตรวจสอบยอดคงเหลือเครดิตของคุณ แล้วลองใหม่
- แผน Free: การสร้างงานต้องใช้แผนแบบชำระเงิน อัปเกรดแผนของคุณในการตั้งค่าการสมัครสมาชิก แล้วลองใหม่
Name
403 - Forbidden
Description
การตรวจสอบเนื้อหาได้บล็อก prompt หรือรูปภาพอินพุต เปลี่ยนอินพุต แล้วลองใหม่
Name
429 - Too Many Requests
Description
คุณเกินการจำกัดอัตราของคุณแล้ว รอสักครู่ แล้วลองใหม่ ดู การจำกัดอัตรา

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

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

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

งานนี้จะทำงานในเบื้องหลัง สำหรับระยะเวลาที่งานมักใช้ ดูที่ ระยะเวลาในการประมวลผล

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

# Refine with Meshy N1 from the preview's stored reference image
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",
  "ai_model": "meshy-n1"
}'

Response

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

พารามิเตอร์

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

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

Name
origin_at
Type
string
ค่าเริ่มต้น bottom
Description
ตำแหน่งที่จะวางจุดกำเนิดของโมเดล bottom หรือ center

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

ฟิลด์ result ของการตอบกลับจะเก็บ ID ของงานข้อความเป็น 3D ใหม่

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

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถทำงานได้ ข้อความแสดงข้อผิดพลาดจะระบุว่าพบปัญหาใด ตัวอย่างเช่น:
- Invalid task ID: preview_task_id ไม่ถูกต้อง หรือไม่ตรงกับงาน preview ใดๆ ของคุณ
- Task not ready: งาน preview ยังไม่สำเร็จ
- Model mismatch: โมเดล AI ของงาน preview ไม่สามารถใช้งานร่วมกับโมเดล refine ที่ร้องขอได้
- Unsupported model for remove_lighting: ส่ง remove_lighting มาพร้อมกับ ai_model: "meshy-6-lite"
- No reference image for Meshy N1: ส่ง ai_model: meshy-n1 มาโดยไม่มี texture_image_url และ preview ไม่มีภาพอ้างอิงที่ Meshy N1 สามารถใช้ได้ ให้ส่ง texture_image_url มาด้วย
- Quad preview for Meshy N1: ส่ง ai_model: meshy-n1 มาสำหรับ preview ที่ remesh เป็น quads ให้ refine ด้วย ai_model อื่น
- Too many triangles for Meshy N1: เมื่อใช้ ai_model: meshy-n1 preview มีสามเหลี่ยมมากกว่า 7,999,999 ชิ้น ให้ refine ด้วย ai_model อื่น
- Unsupported option for Meshy N1: ส่ง ai_model: meshy-n1 มาพร้อมกับตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้:
  - texture_prompt
  - enable_pbr: true
  - texture_resolution ที่เป็น 4k หรือ 8k
  - hd_texture: true โดยไม่มี texture_resolution
  - remove_lighting: true
แก้ไขคำขอ แล้วส่งใหม่อีกครั้ง ดูที่ ข้อผิดพลาด
Name
401 - Unauthorized
Description
ไม่มี API คีย์ หรือ API คีย์ไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
ตัวอย่างเช่น:
- Insufficient credits: บัญชีมีเครดิตไม่เพียงพอสำหรับงานนี้ หรือบัญชีถึงขีดจำกัดเครดิตแล้ว ตรวจสอบยอดคงเหลือเครดิตของคุณ แล้วลองใหม่
- Free plan: การสร้างงานต้องใช้แพ็กเกจแบบชำระเงิน อัปเกรดแพ็กเกจของคุณได้ที่การตั้งค่าการสมัครสมาชิก แล้วลองใหม่
Name
403 - Forbidden
Description
ระบบ moderation เนื้อหาได้บล็อก prompt หรือภาพอินพุต เปลี่ยนอินพุต แล้วลองใหม่
Name
429 - Too Many Requests
Description
คุณเกินการจำกัดอัตราแล้ว กรุณารอสักครู่ แล้วลองใหม่ ดูที่ การจำกัดอัตรา

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

รับ task ข้อความเป็น 3D

ส่งคืน task ข้อความเป็น 3D ตาม ID ของ task นั้น ใช้งานได้ทั้งกับ task ของ 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": null,

  "consumed_credits": 20
}

พารามิเตอร์

Name
id
Type
path
Description
ID ของ task จากการตอบกลับของการสร้าง

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

อ็อบเจ็กต์ task ข้อความเป็น 3D

ตัวอย่าง

ตารางต่อไปนี้แสดงตัวอย่างโมเดลสำหรับแต่ละ mode

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

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

ลบงาน Text to 3D

ลบงาน Text to 3D อย่างถาวร รวมถึงโมเดลและข้อมูลทั้งหมดของงานนั้น คุณไม่สามารถยกเลิกการลบได้

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

พารามิเตอร์ของ Path

Name
id
Type
path
Description
ID ของงานที่ต้องการลบ

สถานะของงาน

การลบงานที่มีสถานะ PENDING จะคืนเครดิตที่ใช้ไปตอนสร้างงานนั้น

งานที่มีสถานะ IN_PROGRESS ไม่สามารถลบได้ คำขอจะส่งคืน 409 Conflict และงานจะยังคงทำงานต่อไป Meshy ไม่คืนเครดิตให้กับงานที่เริ่มทำงานไปแล้ว ดังนั้นการลบงานนี้จะทำให้คุณเสียทั้งเครดิตและผลลัพธ์ ให้รอจนกว่างานจะ มีสถานะเป็น SUCCEEDED, FAILED หรือ CANCELED แล้วจึงค่อยลบ

การลบงานที่มีสถานะสุดท้าย (SUCCEEDED, FAILED หรือ CANCELED) จะไม่คืนเครดิต

Returns

200 OK เมื่อลบงานสำเร็จ หรือ 409 Conflict เมื่องานมีสถานะเป็น IN_PROGRESS

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

List Text to 3D tasks

คืนค่ารายการงาน ข้อความเป็น 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": null,

    "consumed_credits": 20
  }
]

พารามิเตอร์

Name
page_num
Type
integer
ค่าเริ่มต้น 1
Description
หมายเลขหน้าที่จะคืนค่า สูงสุดถึง 255 หากระบุค่าที่มากกว่านี้จะคืนค่า 400
Name
page_size
Type
integer
ค่าเริ่มต้น 10
Description
จำนวนงานต่อหน้า สูงสุดถึง 100
Name
sort_by
Type
string
Description
ลำดับการเรียง
ค่าที่ใช้ได้:
- +created_at: เก่าสุดก่อน
- -created_at: ใหม่สุดก่อน

ค่าที่คืนกลับ

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

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

สตรีมงาน Text to 3D

สตรีมการอัปเดตของงานข้อความเป็น 3D ในรูปแบบ Server-Sent Events (SSE)

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.
// These examples are shortened. Each event holds the full task object.
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": null,

"consumed_credits": 20
}

พารามิเตอร์

Name
id
Type
path
Description
รหัสงานจากการตอบกลับของการสร้าง

ค่าที่ส่งกลับ

สตรีมของ อ็อบเจ็กต์งานข้อความเป็น 3D ในรูปแบบ Server-Sent Events

แต่ละอีเวนต์จะมีอ็อบเจ็กต์งานฉบับเต็ม ในรูปแบบเดียวกับที่เอนด์พอยต์ Get ส่งกลับมา ขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์ของงานจะยังไม่มีค่า

The Text to 3D task object

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

Properties

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": null,

  "consumed_credits": 20
}

Name
id
Type
string
Description
ไอดีของงาน ให้ถือว่าเป็นสตริงทึบ (opaque string) และอย่าอ้างอิงรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของงาน text-to-3d-preview สำหรับงาน preview หรือ text-to-3d-refine สำหรับงาน refine
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดโมเดล 3D ที่สร้างขึ้น หนึ่งรายการต่อหนึ่งรูปแบบไฟล์ รูปแบบที่งานไม่ได้สร้างจะไม่มีคีย์นั้นเลย แทนที่จะเป็นสตริงว่าง
- Name
  glb
  Type
  string
  Description
  ไฟล์ GLB
- Name
  fbx
  Type
  string
  Description
  ไฟล์ FBX
- Name
  usdz
  Type
  string
  Description
  ไฟล์ USDZ
- Name
  obj
  Type
  string
  Description
  ไฟล์ OBJ
- Name
  mtl
  Type
  string
  Description
  ไฟล์ MTL
- Name
  stl
  Type
  string
  Description
  ไฟล์ STL
- Name
  3mf
  Type
  string
  Description
  ไฟล์ 3MF จะมีให้เฉพาะเมื่อ target_formats มี 3mf รวมอยู่ด้วย
Name
prompt
Type
string
Description
prompt ที่คุณส่งไปตอนสร้างงาน โดยไม่มีการแก้ไขใดๆ
Name
texture_prompt
Type
string
Description
prompt ข้อความที่คุณส่งไปเพื่อกำหนดทิศทางการทำเท็กซ์เจอร์ในสเตจ refine
Name
ultra_mode
Type
boolean
⚠ เลิกใช้แล้ว
Description
ให้อ่าน geometry_resolution แทน
Name
geometry_resolution
Type
string
Description
ระดับ Ultra ที่งาน preview ใช้รัน คือ 2k หรือ 4k ฟิลด์นี้จะไม่ปรากฏสำหรับ standard
Name
texture_image_url
Type
string
Description
URL สำหรับดาวน์โหลดภาพที่คุณส่งไปเพื่อกำหนดทิศทางการทำเท็กซ์เจอร์
Name
thumbnail_url
Type
string
Description
URL สำหรับดาวน์โหลดภาพย่อของโมเดล 3D
Name
alpha_thumbnail_url
Type
string
Description
URL สำหรับดาวน์โหลดเวอร์ชันของ thumbnail_url ที่มีพื้นหลังโปร่งใส (RGBA) จะมีให้เฉพาะเมื่อคุณสร้างงานด้วย alpha_thumbnail: true และ Meshy เรนเดอร์ภาพพรีวิวแบบโปร่งใสแล้ว
Name
progress
Type
integer
Description
ความคืบหน้าของงาน เป็นเปอร์เซ็นต์ โดยจะเป็น 0 จนกว่างานจะเริ่ม และเป็น 100 เมื่อสำเร็จ
Name
started_at
Type
timestamp
Description
เวลาที่งานเริ่มทำงาน ในหน่วยมิลลิวินาทีแบบ Unix จะเป็น 0 จนกว่างานจะเริ่ม
Name
created_at
Type
timestamp
Description
เวลาที่สร้างงาน ในหน่วยมิลลิวินาทีแบบ Unix
Name
finished_at
Type
timestamp
Description
เวลาที่งานเสร็จสิ้น ในหน่วยมิลลิวินาทีแบบ Unix จะเป็น 0 จนกว่างานจะเสร็จสิ้น
Name
status
Type
string
Description
สถานะของงาน หนึ่งในค่า PENDING, IN_PROGRESS, SUCCEEDED, FAILED, หรือ CANCELED
Name
texture_urls
Type
array
Description
URL สำหรับดาวน์โหลดแผนที่เท็กซ์เจอร์ที่สร้างขึ้น ในรูปแบบอาร์เรย์ของอ็อบเจ็กต์ โดยทั่วไปจะมี หนึ่ง อ็อบเจ็กต์ แต่ละอ็อบเจ็กต์มีฟิลด์ดังนี้:
- Name
  base_color
  Type
  string
  Description
  แผนที่สีพื้นฐาน (base color map)
- Name
  metallic
  Type
  string
  Description
  แผนที่ความเป็นโลหะ (metallic map) จะไม่ปรากฏเมื่อคุณสร้างงานด้วย enable_pbr: false
- Name
  normal
  Type
  string
  Description
  นอร์มัลแมป จะไม่ปรากฏเมื่อคุณสร้างงานด้วย enable_pbr: false
- Name
  roughness
  Type
  string
  Description
  แผนที่ความขรุขระ (roughness map) จะไม่ปรากฏเมื่อคุณสร้างงานด้วย enable_pbr: false
- Name
  emission
  Type
  string
  Description
  แผนที่การเปล่งแสง (emission map) จะไม่ปรากฏในกรณีใดกรณีหนึ่งต่อไปนี้:
  
  คุณสร้างงานด้วย enable_pbr: false
  
  ai_model เป็น meshy-6-lite, meshy-7, meshy-7.1, หรือ latest
  
  texture_resolution เป็น 8k
  
  งานนั้นเป็นการ refine พรีวิวแบบ meshy-t2 หรือ meshy-t2.5 โดยไม่ได้กำหนด ai_model
Name
preceding_tasks
Type
integer
Description
จำนวนงานที่อยู่ก่อนงานนี้ในคิว ค่านี้จะมีความหมายก็ต่อเมื่องานยังอยู่ในสถานะ PENDING
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดเมื่องานล้มเหลว จะเป็น null ยกเว้นเมื่อสถานะเป็น FAILED ดู ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่งานนี้ใช้ไป จะปรากฏเมื่อสถานะเป็น PENDING, IN_PROGRESS, หรือ SUCCEEDED และจะเป็น 0 สำหรับงานที่ FAILED เนื่องจาก Meshy จะคืนเครดิตเมื่องานล้มเหลว