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

Bốn bước để tạo 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 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.

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

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

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.

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

Yêu cầu

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ụ

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

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

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

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


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!