API Gambar ke 3D

API Gambar ke 3D adalah fitur yang memungkinkan Anda mengintegrasikan kemampuan Gambar ke 3D dari Meshy ke dalam aplikasi Anda sendiri. Di bagian ini, Anda akan menemukan semua informasi yang Anda butuhkan untuk memulai dengan API ini.

POST/openapi/v1/image-to-3d

Membuat Tugas Gambar ke 3D

Endpoint ini memungkinkan Anda membuat tugas Gambar ke 3D baru. Lihat The Image to 3D Task Object untuk mengetahui properti apa saja yang disertakan dalam objek tugas Gambar ke 3D.

Tugas berjalan di latar belakang. Untuk mengetahui berapa lama waktu yang biasanya dibutuhkan, lihat Processing Times.

Parameter

Hanya salah satu dari input_task_id atau image_url yang wajib diisi. Jika keduanya disediakan, input_task_id akan diprioritaskan.

Name
input_task_id
Type
string
Wajib
Description
ID dari tugas pembuatan gambar yang telah selesai, yang outputnya akan digunakan sebagai gambar input. Tugas ini harus merupakan salah satu dari tugas berikut: Teks ke Gambar atau Gambar ke Gambar. Selain itu, tugas tersebut harus dijalankan melalui API, memiliki status SUCCEEDED, dan menghasilkan tepat satu gambar.

Name
image_url
Type
string
Wajib
Description
Sediakan gambar untuk digunakan Meshy dalam pembuatan model. Kami saat ini mendukung format .jpg, .jpeg, .png, dan .webp.
Ukuran file maksimum: 20 MB.
Ada dua cara untuk menyediakan gambar:
- URL yang dapat diakses publik: URL yang dapat diakses dari internet publik.
- Data URI: Data URI gambar yang dikodekan dalam base64. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
model_type
Type
string
default standard
Description
Tentukan jenis pembuatan mesh 3D.
Nilai yang tersedia:
- standard: Pembuatan mesh 3D detail tinggi biasa.
- smart-topology: Pilih model Smart Topology dengan ai_model (meshy-t2).
- lowpoly (usang, akan dihentikan pada 30 Oktober 2026): Menghasilkan mesh low-poly yang dioptimalkan untuk poligon yang lebih bersih. Kami merekomendasikan Meshy T2 sebagai gantinya: smart-topology dengan meshy-t2.
Saat smart-topology dipilih, should_remesh, save_pre_remeshed_model, dan decimation_mode diabaikan, dan hanya topology: triangle yang diterima.
lowpoly akan dihentikan pada 30 Oktober 2026. Setelah tanggal tersebut, permintaan dengan model_type: "lowpoly" akan menghasilkan error. Kami merekomendasikan beralih ke Meshy T2 (model_type: "smart-topology" dengan ai_model: "meshy-t2"). Saat lowpoly dipilih, ai_model, topology, target_polycount, should_remesh, dan save_pre_remeshed_model diabaikan.
Name
ai_model
Type
string
default latest
Description
ID model yang akan digunakan. Nilai yang tersedia bergantung pada model_type.
Pembuatan standar (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (usang): gunakan meshy-7.1 sebagai gantinya.
Pembuatan Smart Topology (model_type: smart-topology):
- meshy-t2 (default): model Smart Topology — topology yang lebih bersih, bagian yang secara native terpisah, output triangle, dan jumlah face yang dapat Anda atur dengan target_polycount.
Name
geometry_resolution
Type
string
default standard
Description
Pass pembuatan geometri. 2k menjalankan pass Ultra pada 2048³; 4k menjalankannya pada 4096³ untuk detail permukaan paling halus.
Nilai yang tersedia: standard, 2k, 4k
Memerlukan meshy-7.1 atau latest.
Name
ultra_mode
Type
boolean
⚠ usang
default false
Description
Gunakan geometry_resolution sebagai gantinya. ultra_mode: true setara dengan geometry_resolution: "2k".
Name
should_texture
Type
boolean
default true
Description
Menentukan apakah tekstur dihasilkan. Mengaturnya ke false akan melewati fase tekstur, menghasilkan mesh tanpa tekstur.

Hanya berlaku ketika should_texture = true

Name
enable_pbr
Type
boolean
default false
Description
Menghasilkan peta PBR (metallic, roughness, normal) selain warna dasar. Peta emisi juga disertakan saat ai_model adalah meshy-6, kecuali pada texture_resolution: 8k. meshy-6-lite, meshy-7.1, meshy-t2, dan latest tidak menghasilkan peta emisi.
Name
texture_resolution
Type
string
default 2k
Description
Resolusi tekstur warna dasar. Salah satu dari 2k (2048×2048), 4k (4096×4096), atau 8k (8192×8192). Resolusi yang lebih tinggi menangkap lebih banyak detail permukaan.
4k dan 8k tidak tersedia dengan ai_model meshy-6-lite. Pada 8k, tidak ada peta emisi yang dihasilkan.
Name
hd_texture
Type
boolean
⚠ usang
default false
Description
Gunakan texture_resolution sebagai gantinya — setara dengan texture_resolution: "4k". Jika keduanya diatur, texture_resolution akan diprioritaskan.
Name
texture_prompt
Type
string
Description
Berikan prompt teks untuk memandu proses pembuatan tekstur. Maksimum 800 karakter.
Name
texture_image_url
Type
string
Description
Sediakan gambar 2d untuk memandu proses pembuatan tekstur. Kami saat ini mendukung format .jpg, .jpeg, .png, dan .webp.
Ukuran file maksimum: 20 MB.
Ada dua cara untuk menyediakan gambar:
- URL yang dapat diakses publik: URL yang dapat diakses dari internet publik
- Data URI: Data URI gambar yang dikodekan dalam base64. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>
Pembuatan tekstur gambar mungkin tidak bekerja secara optimal jika terdapat perbedaan geometri yang signifikan antara aset asli dan gambar yang diunggah. Hanya salah satu dari texture_image_url atau texture_prompt yang dapat digunakan untuk memandu proses pembuatan tekstur. Jika kedua parameter disediakan, maka texture_prompt akan digunakan secara default untuk membuat tekstur model. Pembuatan tekstur baik melalui teks maupun gambar akan dikenakan biaya 10 kredit per tugas.

Name
should_remesh
Type
boolean
default false (Meshy 6 and Meshy 7 models), true (others)
Description
Mengontrol apakah fase remesh diaktifkan. Untuk model dengan kualitas tertinggi, kami merekomendasikan mengatur should_remesh ke false.

Hanya berlaku ketika should_remesh = true

Name
topology
Type
string
default triangle
Description
Tentukan topology model yang dihasilkan.
Nilai yang tersedia:
- quad: Menghasilkan mesh yang didominasi quad.
- triangle: Menghasilkan mesh triangle yang telah didesimasi.
Output Smart Topology hanya berupa triangle. Meminta quad bersamaan dengan ai_model: meshy-t2 akan menghasilkan error.
Name
decimation_mode
Type
integer
Description
Aktifkan desimasi adaptif dengan mengatur level jumlah poligon. Jika diatur, target_polycount akan diabaikan.
Nilai yang tersedia:
- 1: Adaptif — jumlah poligon ultra.
- 2: Adaptif — jumlah poligon tinggi.
- 3: Adaptif — jumlah poligon sedang.
- 4: Adaptif — jumlah poligon rendah.
Name
save_pre_remeshed_model
Type
boolean
default false
Description
Saat diatur ke true, Meshy juga menyimpan file GLB tambahan sebelum fase remesh selesai.

Name
target_polycount
Type
integer
Description
Jumlah target poligon (face) dalam output. Jumlah sebenarnya dapat menyimpang dari target tergantung pada geometri.
target_polycount berlaku dalam dua kasus independen:
- Remesh — dengan should_remesh: true pada model standard. Mesh di-remesh (didesimasi) ke jumlah ini kurang lebih. Rentang 100 hingga 300.000, default 30.000. Jika decimation_mode diatur, parameter tersebut diprioritaskan dan target_polycount diabaikan.
- Smart Topology — dengan model_type: smart-topology dan ai_model: meshy-t2. Model dihasilkan langsung dengan jumlah face ini; tidak ada remesh yang dijalankan dan should_remesh tidak diperlukan. Rentang 100 hingga 15.000, default 4.000.

Name
symmetry_mode
Type
string
⚠ usang
default auto
Description
Usang. Parameter ini tidak lagi memengaruhi output.
Bidang symmetry_mode mengontrol perilaku simetri selama proses pembuatan model.
Nilai yang valid adalah:
- off: Menonaktifkan simetri.
- auto: Secara otomatis menentukan dan menerapkan simetri berdasarkan geometri input.
- on: Menerapkan simetri secara paksa selama pembuatan.
Name
pose_mode
Type
string
default ""
Description
Tentukan mode pose untuk model yang dihasilkan.
Nilai yang tersedia:
- a-pose: Menghasilkan model dalam pose A.
- t-pose: Menghasilkan model dalam pose T.
- "" (string kosong): Tidak ada pose khusus yang diterapkan.
Name
is_a_t_pose
Type
boolean
⚠ usang
default false
Description
Gunakan pose_mode sebagai gantinya. Apakah akan menghasilkan model dalam pose A/T.
Name
surface_mode
Type
string
⚠ usang
Description
Tidak lagi memengaruhi output. Parameter ini memilih pembuatan model yang sejak itu telah dihentikan; gunakan ai_model sebagai gantinya.
Nilai yang diterima adalah organic dan hard; nilai lainnya akan menghasilkan 400.
Name
image_enhancement
Type
boolean
default true
Description
Mengoptimalkan gambar input untuk hasil yang lebih baik. Atur ke false untuk mempertahankan tampilan asli gambar input tanpa pemrosesan gaya apa pun.
Hanya didukung saat ai_model adalah meshy-6, meshy-7.1, atau latest. Mengaturnya dengan meshy-6-lite atau dengan model_type: smart-topology akan menghasilkan error.
Name
remove_lighting
Type
boolean
default true
Description
Menghapus highlight dan bayangan dari tekstur warna dasar, menghasilkan hasil yang lebih bersih dan bekerja lebih baik dengan pengaturan pencahayaan kustom.
Hanya berlaku saat ai_model adalah meshy-6. meshy-7.1 dan latest menerimanya namun mengabaikannya. Mengaturnya dengan meshy-6-lite atau dengan model_type: smart-topology akan menghasilkan error.
Name
moderation
Type
boolean
default false
Description
Saat diatur ke true, konten input akan secara otomatis diperiksa untuk konten yang berpotensi berbahaya. Jika konten berbahaya terdeteksi, tugas tidak akan dilanjutkan ke proses pembuatan.
Konten dari input image_url, texture_image_url, dan texture_prompt akan diperiksa.
Name
target_formats
Type
string[]
Description
Menentukan format file 3D mana yang akan disertakan dalam output. Hanya format yang diminta yang akan dihasilkan dan dikembalikan, yang dapat mengurangi waktu penyelesaian tugas. Jika dihilangkan, semua format yang didukung akan disertakan.
Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf
Jika dihilangkan, semua format kecuali 3mf akan dihasilkan. 3mf hanya disertakan jika ditentukan secara eksplisit.
Name
auto_size
Type
boolean
default false
Description
Saat diatur ke true, layanan menggunakan AI vision untuk secara otomatis memperkirakan tinggi objek di dunia nyata dan mengubah ukuran model sesuai dengan itu. Titik asal akan default ke bottom kecuali origin_at diatur secara eksplisit.
Name
alpha_thumbnail
Type
boolean
default false
Description
Saat diatur ke true, tugas juga akan merender versi pratinjau dengan latar belakang transparan (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Bidang thumbnail_url yang sudah ada tidak berubah.
Name
multi_view_thumbnails
Type
boolean
default false
Description
Saat diatur ke true, tugas juga akan merender empat thumbnail tampilan kardinal (depan, kanan, belakang, kiri) dan mengembalikannya di bawah thumbnail_urls pada respons GET. Bidang thumbnail_url yang sudah ada tidak berubah dan tetap mengarah ke tampilan depan, sehingga klien yang sudah ada tidak terpengaruh.
Menambah sekitar 3 detik pada latensi tugas.

Hanya berlaku ketika auto_size = true

Name
origin_at
Type
string
default bottom
Description
Posisi titik asal saat auto_size diaktifkan.
Nilai yang tersedia: bottom, center.

Hasil

Properti result pada respons berisi id tugas dari tugas Gambar ke 3D yang baru dibuat.

Mode Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Parameter hilang: Salah satu dari image_url atau input_task_id harus disediakan.
- Tugas input tidak valid: input_task_id harus merujuk pada tugas Teks ke Gambar atau Gambar ke Gambar yang SUCCEEDED dan menghasilkan tepat satu gambar.
- Format gambar tidak valid: image_url yang diberikan bukan format yang didukung (.jpg, .jpeg, .png, .webp).
- URL tidak dapat dijangkau: image_url tidak dapat diunduh (404 atau timeout).
- Gambar terlalu besar: Gambar image_url atau texture_image_url melebihi 20 MB.
- Data URI tidak valid: String base64 salah format.
- Kombinasi parameter tidak valid: enable_pbr hanya didukung saat should_texture bernilai true.
- Model tidak didukung untuk low poly: ai_model: "meshy-6-lite" tidak mendukung model_type: "lowpoly".
- Model tidak didukung untuk Ultra: geometry_resolution memerlukan meshy-7.1 atau latest.
- Model tidak didukung untuk opsi gambar: image_enhancement atau remove_lighting diatur dengan ai_model: "meshy-6-lite" atau model_type: "smart-topology".
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak cukup untuk melakukan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi batas laju Anda.

Request

POST

/openapi/v1/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/image-to-3d/:id

Mengambil Task Image to 3D

Endpoint ini memungkinkan Anda mengambil task Gambar ke 3D berdasarkan id task yang valid. Lihat The Image to 3D Task Object untuk melihat properti apa saja yang termasuk dalam objek task Gambar ke 3D.

Parameter

Name
id
Type
path
Description
Pengidentifikasi unik untuk task Gambar ke 3D yang ingin diambil.

Returns

Respons berisi objek task Gambar ke 3D. Lihat bagian The Image to 3D Task Object untuk detailnya.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

DELETE/openapi/v1/image-to-3d/:id

Menghapus Task Gambar ke 3D

Endpoint ini menghapus secara permanen sebuah task Gambar ke 3D, termasuk semua model dan data yang terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Jalur

Name
id
Type
path
Description
ID dari task Gambar ke 3D yang akan dihapus.

Status Task

Task yang masih berstatus PENDING akan dihapus dan kredit yang terpakai saat pembuatan akan dikembalikan.

Task yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan task akan terus berjalan. Kredit untuk task yang sudah mulai dikerjakan oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga task mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Task dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) akan dihapus tanpa pengembalian kredit.

Returns

Mengembalikan 200 OK jika berhasil, atau 409 Conflict jika task sedang berstatus IN_PROGRESS.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/image-to-3d

Menampilkan Daftar Task Image to 3D

Endpoint ini memungkinkan Anda untuk mengambil daftar task Gambar ke 3D.

Parameter

Atribut opsional

Name
page_num
Type
integer
Description
Nomor halaman untuk paginasi. Dimulai dan defaultnya adalah 1.
Name
page_size
Type
integer
Description
Batas jumlah item per halaman. Defaultnya adalah 10 item. Maksimum yang diizinkan adalah 100 item.
Name
sort_by
Type
string
Description
Kolom untuk pengurutan. Nilai yang tersedia:
- +created_at: Urutkan berdasarkan waktu pembuatan secara menaik (ascending).
- -created_at: Urutkan berdasarkan waktu pembuatan secara menurun (descending).

Hasil Kembalian

Mengembalikan daftar berpaginasi dari Objek Task Image to 3D.

Request

GET

/openapi/v1/image-to-3d

curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "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=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

Stream Tugas Image to 3D

endpoint ini melakukan streaming pembaruan secara real-time untuk tugas Gambar ke 3D menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Gambar ke 3D yang akan di-stream.

Returns

Mengembalikan stream dari The Image to 3D Task Objects sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan kolom progress dan status yang diperlukan.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
  "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
  "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

The Image to 3D Task Object

Image to 3D Task object adalah unit kerja yang dilacak oleh Meshy untuk menghasilkan model 3D dari input gambar. Objek ini memiliki properti berikut:

Properties

Name
id
Type
string
Description
Pengenal unik untuk task. Meskipun kami menggunakan k-sortable UUID untuk id task sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.
Name
type
Type
string
Description
Jenis task Image to 3D. Nilainya adalah image-to-3d.
Name
model_urls
Type
object
Description
URL yang dapat diunduh untuk file model 3D bertekstur yang dihasilkan oleh Meshy. Properti untuk suatu format akan dihilangkan jika format tersebut tidak dihasilkan, alih-alih mengembalikan string kosong.
- Name
  glb
  Type
  string
  Description
  URL yang dapat diunduh untuk file GLB.
- Name
  fbx
  Type
  string
  Description
  URL yang dapat diunduh untuk file FBX.
- Name
  obj
  Type
  string
  Description
  URL yang dapat diunduh untuk file OBJ.
- Name
  usdz
  Type
  string
  Description
  URL yang dapat diunduh untuk file USDZ.
- Name
  mtl
  Type
  string
  Description
  URL yang dapat diunduh untuk file MTL, dikembalikan bersama ekspor OBJ ketika tekstur tersedia.
- Name
  stl
  Type
  string
  Description
  URL yang dapat diunduh untuk file STL.
- Name
  3mf
  Type
  string
  Description
  URL yang dapat diunduh untuk file 3MF. Hanya ada jika 3mf diminta melalui target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL yang dapat diunduh untuk output GLB asli sebelum remesh.
  Hanya tersedia ketika task dibuat dengan should_remesh: true dan save_pre_remeshed_model: true sekaligus.
Name
thumbnail_url
Type
string
Description
URL yang dapat diunduh untuk gambar thumbnail dari file model. Setara dengan thumbnail_urls.front jika ada, dipertahankan untuk kompatibilitas ke belakang.
Name
alpha_thumbnail_url
Type
string
Description
URL yang dapat diunduh untuk versi latar belakang transparan (RGBA) dari thumbnail_url. Hanya ada ketika task dibuat dengan alpha_thumbnail: true dan pratinjau transparan berhasil dirender; jika tidak, kolom ini dihilangkan.
Name
thumbnail_urls
Type
object
Description
URL yang dapat diunduh untuk empat thumbnail tampilan dari arah mata angin utama dari model 3D yang dihasilkan. Setiap nilai adalah URL bertanda tangan ke PNG 512×512 yang dirender dengan material dan pencahayaan yang sama seperti thumbnail_url. Berguna untuk melihat pratinjau model dari berbagai sudut dalam pipeline batch tanpa perlu mengunduh GLB.
Hanya ada ketika task dibuat dengan multi_view_thumbnails: true dan telah mencapai SUCCEEDED. Task lama dan task yang dibuat tanpa opt-in ini tidak akan menyertakan kolom ini.
- Name
  front
  Type
  string
  Description
  Tampilan depan, rotasi 0° pada sumbu vertikal (sesuai dengan thumbnail_url).
- Name
  right
  Type
  string
  Description
  Tampilan kanan, rotasi 90°.
- Name
  back
  Type
  string
  Description
  Tampilan belakang, rotasi 180°.
- Name
  left
  Type
  string
  Description
  Tampilan kiri, rotasi 270°.
Name
texture_prompt
Type
string
Description
Teks prompt yang digunakan untuk memandu proses pembuatan tekstur.
Name
texture_image_url
Type
string
Description
URL yang dapat diunduh untuk gambar tekstur yang digunakan untuk memandu proses pembuatan tekstur.
Name
ultra_mode
Type
boolean
⚠ usang
Description
Usang; gunakan geometry_resolution sebagai gantinya.
Name
geometry_resolution
Type
string
Description
Tingkatan Ultra yang digunakan task ini (2k atau 4k); dihilangkan untuk standard.
Name
progress
Type
integer
Description
Progress dari task. Jika task belum dimulai, properti ini akan bernilai 0. Setelah task berhasil, ini akan menjadi 100.
Name
started_at
Type
timestamp
Description
Stempel waktu saat task dimulai, dalam milidetik. Jika task belum dimulai, properti ini akan bernilai 0.
Stempel waktu merepresentasikan jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Misalnya, Jumat, 1 September 2023 pukul 12:00:00 WIB GMT direpresentasikan sebagai 1693569600000. Ini berlaku untuk semua stempel waktu di Meshy API.
Name
created_at
Type
timestamp
Description
Stempel waktu saat task dibuat, dalam milidetik.
Name
expires_at
Type
timestamp
Description
Stempel waktu saat hasil task kedaluwarsa, dalam milidetik.
Name
finished_at
Type
timestamp
Description
Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini akan bernilai 0.
Name
status
Type
string
Description
Status dari task. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Sebuah array objek URL tekstur yang dihasilkan dari task. Biasanya ini hanya berisi satu objek URL tekstur. Setiap URL tekstur memiliki properti berikut:
- Name
  base_color
  Type
  string
  Description
  URL yang dapat diunduh untuk gambar peta warna dasar.
- Name
  metallic
  Type
  string
  Description
  URL yang dapat diunduh untuk gambar peta metalik.
  Jika task dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
- Name
  normal
  Type
  string
  Description
  URL yang dapat diunduh untuk gambar normal map.
  Jika task dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
- Name
  roughness
  Type
  string
  Description
  URL yang dapat diunduh untuk gambar peta kekasaran.
  Jika task dibuat dengan enable_pbr: false, properti ini akan dihilangkan.
- Name
  emission
  Type
  string
  Description
  URL yang dapat diunduh untuk gambar peta emisi.
  Jika task dibuat dengan enable_pbr: false, atau ai_model bernilai meshy-6-lite, meshy-7.1, meshy-t2, atau latest, properti ini akan dihilangkan.
Name
preceding_tasks
Type
integer
Description
Jumlah task yang mendahului.
Nilai kolom ini hanya bermakna jika status task adalah PENDING.
Name
task_error
Type
object
Description
Detail kesalahan untuk task yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang terpakai oleh task ini. Ada ketika status task adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk task FAILED (kredit dikembalikan jika gagal).

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}