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. Xem tất cả mục ngừng hỗ trợ

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

Tạ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.


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.

Mở trang API Keys trong Developer Platform, sau đó tạo khóa của bạ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>"

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.

Minh họa nhân vật giả tưởng mẫu được dùng làm đầu vào cho Ảnh sang 3D trong hướng dẫn này
Đầu vào mẫu

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

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


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

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 ra từ ảnh nhân vật giả tưởng mẫu
Kết quả của bạ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


Các bước tiếp theo