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 cần một khóa. Tạo một khóa mất chưa đến một phút.

Tạo khóa API của bạn

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


1Nhận khóa API của bạn

Tạo khóa API từ cài đặt tài khoản của bạn — bạn sẽ không thể xem lại nó 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 xác thực với một mã Bearer trong tiêu đề Authorization — xem Xác thực.

Mở Cài đặt API từ menu API, 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 của bạn với Ảnh sang 3D. Làm việc từ một prompt văn bản hoặc nhiều ảnh thay thế? 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 sử dụng bức ảnh này — thay thế bằng image_url của riêng bạn để thử điều gì khác.

Minh họa nhân vật giả tưởng mẫu được sử 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.cn/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ề một ID tác vụ ngay lập tức. Thăm dò cùng endpoint cho đến khi statusSUCCEEDED — thay thế <task_id> dưới đây bằng ID được trả về trong 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}"

Phản hồi — 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ỉ của trình duyệt của bạn để 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 từ bức ảnh nhân vật giả tưởng mẫu
Kết quả của bạn

Tổng hợp tất cả

Thích một tập lệnh thực hiện toàn bộ — tạo, thăm dò, tải xuống?

Tập lệnh đầy đủ

import axios from 'axios';
import fs from 'fs';

const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.cn/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


Các bước tiếp theo

  • Thích giao diện người dùng? Thử API Playground — cấu hình một yêu cầu, chạy nó và sao chép mã được tạo.
  • Duyệt qua tài liệu tham khảo API đầy đủ cho mọi endpoint.
  • Kiểm tra Giá, Giới hạn Tốc độ, và Lỗi trước khi bạn đi 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 vấn đề? Tham gia cộng đồng Discord của chúng tôi — chúng tôi rất mong nhận được phản hồi từ bạn!