lowpoly akan dihentikan pada 30 Okt 2026. Tukar model sebelum tarikh-tarikh ini untuk mengelakkan ralat permintaan.

Mula pantas

Mulakan dengan mencipta kunci API anda

Setiap permintaan dalam panduan ini memerlukannya. Mencipta kunci hanya mengambil masa beberapa saat.

Cipta kunci API anda

Empat langkah untuk mendapatkan model 3D pertama anda, menggunakan Meshy REST API.


1Dapatkan kunci API anda

Cipta kunci API daripada halaman API Keys di Developer Platform — anda tidak akan dapat melihatnya lagi selepas skrin ini, jadi simpan di tempat yang selamat. Setiap permintaan mengesahkan dengan token Bearer dalam header Authorization — lihat Authentication.

Buka halaman API Keys di Developer Platform, kemudian cipta kunci anda


2Buat permintaan Imej ke 3D pertama anda

Eksport kunci anda, kemudian buat tugasan pertama anda dengan Image to 3D. Bekerja daripada prompt teks atau beberapa foto sebaliknya? Lihat Text to 3D atau Multi-Image to 3D.

Export your key

export MESHY_API_KEY="<your-api-key>"

Setiap contoh di bawah menggunakan foto ini — gantikan dengan image_url anda sendiri untuk mencuba sesuatu yang lain.

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

3Semak status tugas

Tugas berjalan di latar belakang dan biasanya mengambil masa beberapa minit. Poll endpoint yang sama sehingga status adalah SUCCEEDED, FAILED atau CANCELED, dengan menggantikan <task_id> di bawah dengan ID yang dikembalikan dalam langkah 2. Untuk masa biasa dan berapa lama perlu menunggu, lihat Task Lifecycle.

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

4Muat turun model anda

Dapatkan model daripada model_urls dalam respons di atas. Setiap format (GLB, FBX, OBJ, USDZ, STL) adalah URL yang ditandatangani dan terhad masa — atau anda boleh langkau baris arahan dan tampal terus URL ke bar alamat pelayar anda untuk memuat turunnya.

Download

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
Model 3D hasil yang dijana daripada foto contoh watak fantasi
Hasil anda

Put it all together

Lebih suka satu skrip yang melakukan semuanya — create, poll, download?

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');

Terokai aliran kerja biasa


Langkah seterusnya

  • Lebih suka UI? Buka Developer Platform — jalankan permintaan dalam Playground, jejaki penggunaan dan log permintaan, serta urus webhooks.
  • Terokai rujukan API yang lengkap untuk setiap endpoint.
  • Belajar daripada contoh sebenar: ikuti resipi langkah demi langkah dalam Cookbook dan baca tutorial serta kisah pembinaan di Developer Blog.
  • Semak Harga, Rate Limits, dan Ralat sebelum anda beralih ke pengeluaran.
  • Pantau log perubahan untuk kemas kini dan pembetulan pepijat.
  • Ada maklum balas atau menghadapi masalah? Sertai komuniti Discord kami — kami amat berminat untuk mendengar daripada anda!