Bắt đầu nhanh
Bắt đầu bằng cách tạo khóa API của bạn
Mọi yêu cầu trong hướng dẫn này đều cần có khóa này. Việc tạo khóa chỉ mất vài giây.
Tạo khóa API của bạnTạo mô hình 3D đầu tiên của bạn bằng Meshy REST API chỉ trong bốn bước, từ việc tạo khóa API đến tải xuống mô hình.
Đang sử dụng trợ lý lập trình AI? Để kết nối Claude Code, Cursor, Windsurf, hoặc một MCP client khác với Meshy, xem Tích hợp AI. Đối với tác tử trò chuyện không hỗ trợ MCP, hãy dùng llms.txt.
1Lấy khóa API của bạn
Tạo khóa API trên trang API Keys của Developer Platform. Bạn sẽ không thể xem lại khóa này sau khi rời khỏi màn hình đó, vì vậy hãy lưu trữ nó ở nơi an toàn. Gửi khóa này trong mỗi yêu cầu dưới dạng token Bearer trong header Authorization. Xem Xác thực.
Bạn cần có gói trả phí để tạo và quản lý khóa API. Với gói Free, bạn không thể tự tạo khóa riêng, và Playground sẽ sử dụng một khóa tích hợp sẵn để thử nghiệm.

Đừng để khóa này xuất hiện trong các script của bạn. Thay vào đó, hãy lưu nó trong một biến môi trường, như bước tiếp theo sẽ hướng dẫn.
2Tạo tác vụ Ảnh sang 3D
Gửi một ảnh đến Ảnh sang 3D. Để bắt đầu từ một prompt văn bản hoặc nhiều ảnh thay vì vậy, hãy dùng Văn bản sang 3D hoặc Nhiều ảnh sang 3D.
Trước tiên, hãy lưu khóa của bạn vào một biến môi trường:
Export your key
export MESHY_API_KEY="<your-api-key>"
Chạy lệnh này trong terminal (Terminal trên macOS, Command Prompt hoặc PowerShell trên Windows), không phải trong trình duyệt.
Tất cả các ví dụ sau đây đều sử dụng ảnh này. Để thử một ảnh khác, hãy thay đổi image_url.

Request
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${MESHY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://docs.meshy.ai/images/api/quick-start/source-photo.webp"
}'
3Kiểm tra trạng thái tác vụ
Tác vụ chạy ngầm và thường mất vài phút. Hãy lấy thông tin tác vụ từ cùng một endpoint cho đến khi status là SUCCEEDED, FAILED, hoặc CANCELED. Trong yêu cầu sau, thay thế <task_id> bằng ID mà bước 2 đã trả về. Giữa các yêu cầu, hãy chờ số giây được chỉ định trong header Retry-After.
Để biết thời gian xử lý thông thường và thời gian cần chờ trước khi từ bỏ, xem Vòng đời tác vụ.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
-H "Authorization: Bearer ${MESHY_API_KEY}"
Response: SUCCEEDED
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "SUCCEEDED",
"progress": 100,
"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=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"task_error": null
}
Nếu tác vụ thất bại, status sẽ là FAILED, và task_error sẽ cho biết lý do. Hãy sửa lại dữ liệu đầu vào hoặc tạo một tác vụ khác. Xem Lỗi.
Để được thông báo khi tác vụ hoàn tất thay vì phải liên tục kiểm tra, hãy truyền trực tuyến tác vụ hoặc sử dụng webhook.
4Tải xuống mô hình của bạn
Các tệp này nằm trong model_urls của phản hồi trước đó. Mỗi định dạng (GLB, FBX, OBJ, USDZ, và STL) có một URL đã ký, chỉ hoạt động trong một khoảng thời gian giới hạn. Bạn cũng có thể dán URL vào trình duyệt để tải tệp xuống.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

Với mọi gói ngoại trừ Enterprise, Meshy giữ tệp trong 3 ngày. Hãy tải xuống các tệp bạn cần trước thời hạn đó. Xem Lưu giữ tài nguyên.
Tổng hợp tất cả lại
Script này tạo tác vụ, chờ tác vụ hoàn tất, và tải xuống mô hình.
Full script
import axios from 'axios';
import fs from 'fs';
const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.ai/images/api/quick-start/source-photo.webp';
// 1. Create the task
const { data: created } = await axios.post(
'https://api.meshy.ai/openapi/v1/image-to-3d',
{ image_url: imageUrl },
{ headers, timeout: 60_000 },
);
const taskId = created.result;
// 2. Poll until it finishes, for up to 60 minutes
const deadline = Date.now() + 60 * 60 * 1000;
let task;
while (true) {
const { data, headers: resHeaders } = await axios.get(
`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`,
{ headers, timeout: 30_000 },
);
task = data;
if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(task.status)) break;
if (Date.now() > deadline) {
// The task is still running. Check it again later with the same task ID instead of creating a new one.
throw new Error(`Task ${taskId} is still ${task.status}; check it again later`);
}
const waitSeconds = Number(resHeaders['retry-after']) || 5;
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}
// 3. Download the result (only if the task succeeded)
if (task.status !== 'SUCCEEDED') {
throw new Error(`Task ${task.status}: ${task.task_error?.message || 'unknown error'}`);
}
const { data: model } = await axios.get(task.model_urls.glb, { responseType: 'arraybuffer' });
fs.writeFileSync('model.glb', model);
console.log('Saved model.glb');
Khám phá các quy trình làm việc phổ biến
Nhân vật sẵn sàng cho game
Gắn khung xương (rig) cho lưới hình người để sẵn sàng tạo hoạt ảnh trong Unity hoặc Unreal.
Learn more →Lưới Smart Topology
Đặt model_type thành smart-topology trên Ảnh sang 3D để có một lưới tam giác sạch, sẵn sàng cho game.
Mô hình in 3D
Chuyển đổi mô hình hoàn chỉnh thành tệp 3MF nhiều màu, sẵn sàng để cắt lớp và in.
Learn more →Các bước tiếp theo
- Duyệt qua mọi endpoint trong tài liệu tham khảo API.
- Trước khi đưa vào sản xuất, hãy kiểm tra Giá, Giới hạn tốc độ, và Lỗi.
- Theo dõi các công thức hướng dẫn từng bước trong Cookbook.