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. 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 ra 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ủa chúng tôi — cài đặt Meshy MCP server để có quyền truy cập gọi công cụ (tool-calling) 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 khi rời khỏi 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 sẽ xác thực bằng một token Bearer trong header Authorization — xem Authentication.
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í sẽ có một khóa chuyên dụng, tích hợp sẵn để thử nghiệm trong Playground, nhưng không thể 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 các đoạn 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
Export 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 với một prompt văn bản hoặc nhiều ảnh thay vì vậy? Xem Văn bản sang 3D hoặc Nhiều ảnh sang 3D.
Export your key
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ụ bên dưới đều sử dụng bức ảnh này — hãy thay bằng image_url của riêng bạn để thử điều gì đó khác.

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 gọi liên tục cùng một endpoint cho đến khi status là SUCCEEDED, FAILED hoặc CANCELED, thay <task_id> bên dưới bằng ID được trả về ở bước 2. Để biết thời gian điển hình và nên chờ bao lâu, 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": {
"message": ""
}
}
Không thích kiểu polling? Hãy dùng SSE streaming hoặc một 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ỏ qua dòng lệnh và dán URL trực tiếp vào thanh địa chỉ trình duyệt của bạn để tải xuống.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

Các tệp được giữ lại trong 3 ngày đối với các gói không thuộc Enterprise — xem Lưu giữ tài nguyên.
Ghép tất cả lại với nhau
Muốn dùng một script duy nhất để làm toàn bộ quy trình — tạo, kiểm tra trạng thái, 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, 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 phổ biến
Nhân vật sẵn sàng cho game
Gắn khung xương cho một lưới hình người để sẵn sàng tạo hoạt ảnh trong Unity hoặc Unreal.
Learn more →Asset lowpoly
Đặt model_type thành smart-topology 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 đa màu, sẵn sàng để cắt lớp và in.
Learn more →Bước tiếp theo
- Thích giao diện người dùng hơn? Mở Developer Platform — chạy các request trong Playground, theo dõi mức sử dụng và nhật ký request, đồng thời quản lý webhooks.
- Duyệt qua tài liệu tham khảo API đầy đủ cho mọi endpoint.
- Học hỏi từ các ví dụ thực tế: làm theo các hướng dẫn từng bước trong Cookbook và đọc các bài hướng dẫn cũng như câu chuyện xây dựng trên Developer Blog.
- Kiểm tra Giá, Rate Limits, và Lỗi trước khi đưa vào môi trường production.
- 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 vấn đề? 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!