lowpoly sẽ ngừng hoạt động vào 30 thg 10, 2026. Hãy chuyển sang mô hình khác trước các ngày này để tránh lỗi yêu cầu.

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ạn

Bốn bước để tạo ra mô hình 3D đầu tiên của bạn, sử dụng Meshy REST API.


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.

Mở trang API Keys trong Developer Platform, sau đó tạo khóa của bạn


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>"

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.

Sample fantasy character illustration used as the Image to 3D input in this guide
Sample input

Request

POST
/openapi/v1/image-to-3d
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

GET
/openapi/v1/image-to-3d/:id
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": ""
  }
}

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

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
Mô hình 3D kết quả được tạo từ ảnh mẫu nhân vật giả tưởng
Kết quả của bạ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


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!