Bắt đầu nhanh
Đây là tài liệu tham chiếu API để tương tác với Meshy theo cách lập trình.
Đang sử dụng trợ lý lập trình AI? Xem trang Tích hợp AI của chúng tôi — cài đặt Meshy MCP server để có quyền truy cập gọi công cụ từ Claude Code, Cursor, Windsurf và các công cụ tương thích MCP khác, hoặc trỏ một tác nhân chat thông thường tới llms.txt.
Meshy API cung cấp một giao diện đơn giản để tạo mô hình 3D và texture từ prompt văn bản và hình ảnh. Làm theo hướng dẫn này để bắt đầu nhanh chóng.
Tạo khóa API
Tạo khóa API trong trang cài đặt API tại đây, bạn sẽ dùng khóa này để xác thực các yêu cầu của mình một cách an toàn. Định dạng của khóa API là msy-<random-string>.
Sau khi đã tạo khóa API, hãy lưu trữ nó ở một vị trí an toàn.
khóa API chế độ thử nghiệm
Trong quá trình phát triển và kiểm thử, bạn có thể dùng khóa API chế độ thử nghiệm của chúng tôi để khám phá API mà không tiêu thụ tín dụng của bạn:
msy_dummy_api_key_for_test_mode_12345678
Khóa API đặc biệt này có các đặc điểm sau:
- Có thể dùng để gửi yêu cầu tới tất cả endpoint Meshy API
- Không tiêu thụ tín dụng khi sử dụng khóa này
- Tất cả yêu cầu hợp lệ sẽ trả về cùng một kết quả tác vụ mẫu, bất kể các tham số đầu vào
- Cấu trúc dữ liệu phản hồi sẽ khớp chính xác với API production
- Hoàn hảo để kiểm thử tích hợp API của bạn trước khi chuyển sang khóa API thật
khóa API chế độ thử nghiệm chỉ dành cho mục đích phát triển. Đối với môi trường production, vui lòng sử dụng khóa API của riêng bạn.
Thực hiện yêu cầu API "Văn bản sang 3D" đầu tiên của bạn
Trong ví dụ này, chúng ta sẽ tạo một mô hình 3D từ một prompt văn bản bằng cách sử dụng text-to-3d endpoint. Quy trình gồm hai giai đoạn: giai đoạn preview và giai đoạn refine. Trong giai đoạn preview, một lưới cơ sở được tạo mà không áp dụng texture, cho phép bạn đánh giá hình học. Trong giai đoạn refine, lưới preview được áp texture dựa trên prompt văn bản.
Chúng tôi sẽ chỉ cho bạn cách thực hiện các yêu cầu này trong một script Python.
Preview
Meshy cung cấp một tập hợp các endpoint REST API. Bạn có thể sử dụng chúng với bất kỳ HTTP client nào bạn chọn. Bất kể bạn gọi API nào, khóa API luôn được truyền dưới dạng một header có tên Authorization. Hãy nhớ export khóa API của bạn dưới dạng biến môi trường có tên MESHY_API_KEY trước khi sử dụng script này.
Các tham số chính cho yêu cầu preview là mode, luôn là "preview", và prompt, phần mô tả mô hình bạn cần. Trong ví dụ này, chúng tôi cũng đã chỉ định should_remesh, nhưng tham số này là tùy chọn.
api_request.py
import requests
import os
import time
headers = {
"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}
# 1. Generate a preview model and get the task ID
generate_preview_request = {
"mode": "preview",
"prompt": "a monster mask",
"should_remesh": True,
}
generate_preview_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_preview_request,
)
generate_preview_response.raise_for_status()
preview_task_id = generate_preview_response.json()["result"]
print("Preview task created. Task ID:", preview_task_id)
Thao tác này hoàn tất lệnh gọi API preview.
Hãy lưu ý rằng Meshy API áp dụng mô hình thực thi bất đồng bộ, nghĩa là khi bạn tạo một tác vụ, API endpoint chỉ trả về một ID tác vụ. Sau đó, bạn phải thăm dò endpoint trạng thái tác vụ bằng ID này để kiểm tra xem tác vụ đã hoàn tất hay chưa.
api_request.py
# 2. Poll the preview task status until it's finished
preview_task = None
while True:
preview_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
headers=headers,
)
preview_task_response.raise_for_status()
preview_task = preview_task_response.json()
if preview_task["status"] == "SUCCEEDED":
print("Preview task finished.")
break
print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
Sau khi tác vụ hoàn tất, bạn sẽ có thể truy cập các URL mô hình từ phản hồi của nó. Hãy tải mô hình xuống từ trường model_urls trong phản hồi.
api_request.py
# 3. Download the preview model in glb format
preview_model_url = preview_task["model_urls"]["glb"]
preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()
with open("preview_model.glb", "wb") as f:
f.write(preview_model_response.content)
print("Preview model downloaded.")
Nếu mọi thứ đến giờ đều hoạt động tốt, preview_model.glb của bạn sẽ trông tương tự như thế này. Nó sẽ không khớp hoàn toàn, do tính ngẫu nhiên nội tại trong pipeline AI.
Refine
Hãy tiếp tục đến giai đoạn refine. Để khởi tạo yêu cầu refine, hãy cung cấp ID tác vụ preview làm tham số đầu vào.
api_request.py
# 4. Generate a refined model and get the task ID
generate_refined_request = {
"mode": "refine",
"preview_task_id": preview_task_id,
}
generate_refined_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_refined_request,
)
generate_refined_response.raise_for_status()
refined_task_id = generate_refined_response.json()["result"]
print("Refined task created. Task ID:", refined_task_id)
# 5. Poll the refined task status until it's finished
refined_task = None
while True:
refined_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
headers=headers,
)
refined_task_response.raise_for_status()
refined_task = refined_task_response.json()
if refined_task["status"] == "SUCCEEDED":
print("Refined task finished.")
break
print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
# 6. Download the refined model in glb format
refined_model_url = refined_task["model_urls"]["glb"]
refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()
with open("refined_model.glb", "wb") as f:
f.write(refined_model_response.content)
print("Refined model downloaded.")
Mô hình 3D refined_model.glb hiện đã được áp đầy đủ texture ✨.
Ghép tất cả lại
Dưới đây là mã hoàn chỉnh để sử dụng API Văn bản sang 3D.
api_request.py
import requests
import os
import time
headers = {
"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}
# 1. Generate a preview model and get the task ID
generate_preview_request = {
"mode": "preview",
"prompt": "a monster mask",
"should_remesh": True,
}
generate_preview_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_preview_request,
)
generate_preview_response.raise_for_status()
preview_task_id = generate_preview_response.json()["result"]
print("Preview task created. Task ID:", preview_task_id)
# 2. Poll the preview task status until it's finished
preview_task = None
while True:
preview_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
headers=headers,
)
preview_task_response.raise_for_status()
preview_task = preview_task_response.json()
if preview_task["status"] == "SUCCEEDED":
print("Preview task finished.")
break
print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
# 3. Download the preview model in glb format
preview_model_url = preview_task["model_urls"]["glb"]
preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()
with open("preview_model.glb", "wb") as f:
f.write(preview_model_response.content)
print("Preview model downloaded.")
# 4. Generate a refined model and get the task ID
generate_refined_request = {
"mode": "refine",
"preview_task_id": preview_task_id,
}
generate_refined_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_refined_request,
)
generate_refined_response.raise_for_status()
refined_task_id = generate_refined_response.json()["result"]
print("Refined task created. Task ID:", refined_task_id)
# 5. Poll the refined task status until it's finished
refined_task = None
while True:
refined_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
headers=headers,
)
refined_task_response.raise_for_status()
refined_task = refined_task_response.json()
if refined_task["status"] == "SUCCEEDED":
print("Refined task finished.")
break
print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
# 6. Download the refined model in glb format
refined_model_url = refined_task["model_urls"]["glb"]
refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()
with open("refined_model.glb", "wb") as f:
f.write(refined_model_response.content)
print("Refined model downloaded.")
Sao chép và dán mã vào một script Python rồi chạy nó.
Run the script
python api_request.py
Bạn sẽ thấy đầu ra trong terminal của mình tương tự như sau:
Các bước tiếp theo
- Muốn thử các endpoint trước mà không cần viết mã? Hãy dùng API Playground để cấu hình và chạy một yêu cầu, sau đó sao chép snippet được tạo.
- Bạn có thể tìm thấy tài liệu tham chiếu API đầy đủ trong phần "Endpoint API", nơi cung cấp thông tin chi tiết về từng API.
- Khám phá chi tiết về Giá, Giới hạn tốc độ, và cách khắc phục lỗi phổ biến.
- Đừng quên thường xuyên xem nhật ký thay đổi của chúng tôi để cập nhật và sửa lỗi.
- Có phản hồi hoặc gặp sự cố? Tham gia cộng đồng Discord của chúng tôi - chúng tôi rất muốn lắng nghe ý kiến từ bạn!