lowpoly dihentikan pada 30 Okt 2026. Ganti model sebelum tanggal-tanggal ini agar permintaan tidak error. Lihat semua penghentian

Mulai cepat

Mulai dengan membuat kunci API Anda

Setiap permintaan dalam panduan ini membutuhkannya. Membuat kunci hanya butuh beberapa detik.

Buat kunci API Anda

Buat model 3D pertama Anda dengan Meshy REST API dalam empat langkah, mulai dari membuat kunci API hingga mengunduh model.


1Dapatkan kunci API Anda

Buat kunci API di halaman API Keys pada Developer Platform. Anda tidak dapat melihat kunci tersebut lagi setelah meninggalkan layar itu, jadi simpanlah di tempat yang aman. Kirimkan kunci itu di setiap permintaan sebagai token Bearer dalam header Authorization. Lihat Autentikasi.

Anda memerlukan paket berbayar untuk membuat dan mengelola kunci API. Pada paket Free, Anda tidak dapat membuat kunci Anda sendiri, dan Playground menggunakan kunci bawaan untuk pengujian.

Buka halaman API Keys di Developer Platform, lalu buat kunci Anda


2Buat tugas Gambar ke 3D

Kirim gambar ke Gambar ke 3D. Untuk memulai dari prompt teks atau beberapa foto, gunakan Teks ke 3D atau Multi-Gambar ke 3D.

Pertama, simpan kunci Anda dalam variabel lingkungan:

Export your key

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

Semua contoh berikut menggunakan foto ini. Untuk mencoba gambar lain, ubah image_url.

Ilustrasi karakter fantasi contoh yang digunakan sebagai input Gambar ke 3D dalam panduan ini
Contoh 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"
  }'

3Periksa status tugas

Tugas berjalan di latar belakang dan biasanya memakan waktu beberapa menit. Ambil tugas dari endpoint yang sama hingga status bernilai SUCCEEDED, FAILED, atau CANCELED. Pada permintaan berikut, ganti <task_id> dengan ID yang dikembalikan oleh langkah 2. Di antara permintaan, tunggu selama jumlah detik yang tertera di header Retry-After.

Untuk waktu pemrosesan umum, dan berapa lama harus menunggu sebelum menyerah, lihat Siklus hidup tugas.

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
}

Jika tugas gagal, status bernilai FAILED, dan task_error menjelaskan alasannya. Perbaiki input tersebut atau buat tugas lain. Lihat Kesalahan.


4Unduh model Anda

Berkas-berkas tersebut berada di model_urls pada respons sebelumnya. Setiap format (GLB, FBX, OBJ, USDZ, dan STL) memiliki URL bertanda tangan yang berlaku untuk waktu terbatas. Anda juga dapat menempelkan URL tersebut ke browser Anda untuk mengunduh berkasnya.

Download

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
Model 3D hasil yang dihasilkan dari foto karakter fantasi contoh
Hasil Anda

Menggabungkan semuanya

Skrip ini membuat tugas, menunggu hingga selesai, dan mengunduh modelnya.

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

Jelajahi alur kerja umum


Langkah selanjutnya