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 một khóa API. Việc tạo khóa chỉ mất vài giây.
Tạo khóa API của bạnBốn bước để tạo mô hình 3D đầu tiên của bạn, sử dụng Meshy REST API.
Đang sử dụng trợ lý lập trình AI? Xem trang Tích hợp AI — cài đặt Meshy MCP server để 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 trò chuyện thông thường đến llms.txt.
1Lấy khóa API của bạn
Tạo một khóa API từ trang API Keys trong Developer Platform — bạn sẽ không thể xem lại khóa này sau màn hình này, vì vậy hãy lưu trữ nó ở nơi an toàn. Mọi yêu cầu đều xác thực bằng token Bearer trong header Authorization — xem Xác thực.
Việc tạo và quản lý khóa API yêu cầu gói trả phí. Tài khoản miễn phí được cấp một khóa tích hợp sẵn dành riêng để thử nghiệm trong Playground, nhưng không thể tự tạo hoặc quản lý khóa của riêng mình.

Mẹo bảo mật: tránh dán khóa của bạn trực tiếp vào script — thay vào đó hãy lưu nó dưới dạng biến môi trường: export MESHY_API_KEY="msy_...".
2Thực hiện yêu cầu Ảnh sang 3D đầu tiên của bạn
Xuất khóa của bạn, sau đó tạo tác vụ đầu tiên với Ảnh sang 3D. Bạn đang làm việc từ một prompt văn bản hay nhiều ảnh thay vào đó? Xem Văn bản sang 3D hoặc Nhiều ảnh sang 3D.
Xuất khóa của bạn
export MESHY_API_KEY="<your-api-key>"
Chạy lệnh này trong terminal của bạn (Terminal trên macOS, Command Prompt hoặc PowerShell trên Windows) — không phải trong trình duyệt.
Mọi ví dụ dưới đây đều sử dụng ảnh này — thay bằng image_url của riêng bạn để thử thứ khác.

Yêu cầu
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ụ
Các yêu cầu trả về ID tác vụ ngay lập tức. Hãy poll cùng một endpoint cho đến khi status là SUCCEEDED — thay <task_id> bên dưới bằng ID được trả về ở bước 2.
Yêu cầu
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": {
"message": ""
}
}
Không thích poll? Hãy dùng SSE streaming hoặc webhook để được thông báo ngay khi tác vụ hoàn tất.
4Tải xuống mô hình của bạn
Lấy mô hình từ model_urls trong phản hồi ở trên. Mỗi định dạng (GLB, FBX, OBJ, USDZ, STL) là một URL có chữ ký, giới hạn thời gian — hoặc bạn có thể bỏ qua dòng lệnh và dán URL trực tiếp vào thanh địa chỉ trình duyệt để tải xuống.
Tải xuống
curl -L "<model_urls.glb from the response above>" -o model.glb

Các tệp được lưu giữ trong 3 ngày đối với các gói không thuộc Enterprise — xem Lưu giữ tài nguyên.
Kết hợp tất cả lại
Bạn muốn có một script duy nhất thực hiện toàn bộ quy trình: tạo, poll, tải xuống?
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 },
);
const taskId = created.result;
// 2. Poll until it finishes
let task;
while (true) {
const { data } = await axios.get(`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`, { headers });
task = data;
if (task.status === 'SUCCEEDED' || task.status === 'FAILED') break;
await new Promise((resolve) => setTimeout(resolve, 5000));
}
// 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
Rig một lưới hình người với khung xương để nó sẵn sàng để hoạt hình hóa trong Unity hoặc Unreal.
Learn more →Tài nguyên Lowpoly
Đặt model_type thành lowpoly trên Ảnh sang 3D để có một lưới sạch, sẵn sàng cho game.
Mô hình in 3D
Chuyển đổi một 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 →Bước tiếp theo
- Bạn thích giao diện người dùng hơn? Mở Developer Platform — chạy các yêu cầu trong Playground, theo dõi mức sử dụng và nhật ký yêu cầu, và quản lý webhook.
- Duyệt qua toàn bộ tài liệu tham khảo API cho mọi endpoint.
- Kiểm tra Giá, Giới hạn tần suất, và Lỗi trước khi đưa vào sản xuất.
- Theo dõi nhật ký thay đổ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 mong được lắng nghe bạn!