API Gambar ke 3D

Ubah sebuah gambar menjadi model 3D, dengan tekstur atau tanpa tekstur, dalam format yang Anda pilih. Kirim gambarnya, atau gunakan output dari tugas Teks ke Gambar atau Gambar ke Gambar.

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

Membuat task Image to 3D

Membuat task Image to 3D. Task berjalan di latar belakang. Untuk mengetahui berapa lama biasanya sebuah task berjalan, lihat Processing times.

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

# Textured with Meshy N1 from the input image
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",
    "texture_model": "meshy-n1"
  }'

Response

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

Parameter

Name
input_task_id
Type
string
Wajib
Description
Wajib diisi kecuali Anda mengirim image_url. ID dari task Text to Image atau Image to Image yang gambarnya ingin Anda gunakan sebagai input. Task tersebut harus merupakan task yang Anda buat dengan API, memiliki status SUCCEEDED, dan menghasilkan tepat satu gambar.

Name
image_url
Type
string
Wajib
Description
Wajib diisi kecuali Anda mengirim input_task_id. Gambar yang akan diubah menjadi model 3D, berupa URL publik atau Data URI berenkode base64, seperti data:image/jpeg;base64,<data gambar berenkode base64 Anda>. Jika Anda mengirim keduanya, Meshy menggunakan input_task_id.
Gambar harus berupa file JPG, JPEG, PNG, atau WebP berukuran maksimal 20 MB, minimal 32 piksel pada setiap sisinya, dan maksimal 178.956.970 piksel (lebar × tinggi).

Name
model_type
Type
string
default standard
Description
Jenis mesh 3D yang akan dihasilkan.
Nilai yang tersedia:
- standard: mesh beresolusi tinggi
- smart-topology: mesh dari model Smart Topology, yang Anda pilih dengan ai_model (meshy-t2 atau meshy-t2.5)
Dengan smart-topology, Meshy mengabaikan should_remesh, save_pre_remeshed_model, dan decimation_mode, serta hanya menerima topology: triangle.
Name
ai_model
Type
string
default latest
Description
Model AI yang menghasilkan model 3D. Nilai yang tersedia bergantung pada model_type.
Model standar (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (usang): gunakan meshy-7.1 sebagai gantinya
Model Smart Topology (model_type: smart-topology) menghasilkan triangle, dengan jumlah face yang dapat Anda atur melalui target_polycount:
- meshy-t2: topology yang lebih rapi dan bagian-bagian yang sudah terpisah secara native
- meshy-t2.5 (default): detail yang lebih tajam untuk aset game
Name
geometry_resolution
Type
string
default standard
Description
Tahap pembuatan geometri.
Nilai yang tersedia:
- standard
- 2k: menjalankan tahap Ultra pada 2048³
- 4k: menjalankan tahap Ultra pada 4096³, untuk detail permukaan terbanyak
2k membutuhkan meshy-7.1, latest, atau meshy-7 yang sudah usang. 4k membutuhkan meshy-7.1 atau latest.
Name
ultra_mode
Type
boolean
⚠ usang
default false
Description
Gunakan geometry_resolution sebagai gantinya. ultra_mode: true sama dengan geometry_resolution: "2k".
Name
should_texture
Type
boolean
default true
Description
Apakah akan menghasilkan tekstur. true mengembalikan model bertekstur, dan false melewati proses pemberian tekstur dan mengembalikan mesh tanpa tekstur.

Hanya berlaku ketika should_texture = true

Name
texture_model
Type
string
default depends on ai_model
Description
Model AI yang memberi tekstur pada model 3D, dalam task yang sama. Kosongkan untuk menggunakan model tekstur default untuk ai_model Anda. Ini tidak mengubah biaya kredit.
Nilai yang tersedia:
- meshy-7: Meshy 7, dengan peta PBR dan tekstur hingga 8K
- meshy-n1: Meshy N1, tekstur warna dasar 2K hanya dari gambar referensi
- meshy-6-lite: Meshy 6 Lite, tekstur 2K dengan biaya terendah
- meshy-6: Meshy 6, hanya sebagai default untuk ai_model: meshy-6
Setiap ai_model menerima meshy-7, meshy-n1, dan meshy-6-lite. Opsi yang tidak didukung oleh model tekstur yang dipilih akan mengembalikan 400. Dengan meshy-n1, model yang dihasilkan dengan lebih dari 7.999.999 triangle menyebabkan task gagal, dan Meshy mengembalikan kreditnya. Dengan should_texture: false, Meshy mengabaikan texture_model, tetapi nilai yang tidak dikenal tetap mengembalikan 400.
Lihat Models untuk mengetahui fungsi masing-masing model tekstur dan mana yang sebaiknya dipilih.
Name
enable_pbr
Type
boolean
default false
Description
Apakah juga akan menghasilkan peta PBR (metallic, roughness, dan normal) selain warna dasar. true membutuhkan should_texture: true, dan mengembalikan 400 jika should_texture: false. Dengan texture_model: meshy-n1, true mengembalikan 400.
Model tekstur Meshy 6 juga menghasilkan peta emisi, kecuali pada texture_resolution: 8k.
Name
texture_resolution
Type
string
default 2k
Description
Ukuran tekstur warna dasar. Tekstur yang lebih besar menangkap lebih banyak detail permukaan.
Nilai yang tersedia:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k dan 8k membutuhkan model tekstur Meshy 7 atau Meshy 6, dan mengembalikan 400 dengan model lainnya. Pada 8k, Meshy tidak menghasilkan peta emisi.
Name
hd_texture
Type
boolean
⚠ usang
default false
Description
Gunakan texture_resolution sebagai gantinya. hd_texture: true sama dengan texture_resolution: "4k". Jika Anda mengirim keduanya, Meshy menggunakan texture_resolution.
Name
texture_prompt
Type
string
Description
Teks yang memandu tekstur, hingga 800 karakter. Teks yang lebih panjang mengembalikan 400. Dengan texture_model: meshy-n1, mengirimnya akan mengembalikan 400.
Name
texture_image_url
Type
string
Description
Gambar yang memandu tekstur, berupa URL publik atau Data URI berenkode base64, seperti data:image/jpeg;base64,<data gambar berenkode base64 Anda>. Gambar harus berupa file JPG, JPEG, PNG, atau WebP berukuran maksimal 20 MB, minimal 32 piksel pada setiap sisinya, dan maksimal 178.956.970 piksel (lebar × tinggi).
Meshy memandu tekstur hanya dengan salah satu dari texture_prompt atau texture_image_url. Jika Anda mengirim keduanya, Meshy menggunakan texture_prompt. Untuk biaya kredit pemberian tekstur, lihat Pricing.
Dengan texture_model: meshy-n1, Meshy memberi tekstur dari gambar ini sebagai tampilan depan, atau dari gambar input jika Anda mengosongkannya.
Pemberian tekstur dari sebuah gambar mungkin tidak bekerja dengan baik jika bentuk gambar berbeda jauh dari geometri model 3D.

Name
should_remesh
Type
boolean
default true (meshy-6-lite), false (other models)
Description
Apakah akan menjalankan tahap remesh. Untuk model 3D dengan kualitas tertinggi, atur ke false.

Hanya berlaku ketika should_remesh = true

Name
topology
Type
string
default triangle
Description
Jenis face dari model yang di-remesh.
Nilai yang tersedia:
- quad: mesh yang didominasi quad
- triangle: mesh triangle yang telah didesimasi
Output Smart Topology hanya berupa triangle, sehingga quad dengan meshy-t2 atau meshy-t2.5 mengembalikan 400. Dengan texture_model: meshy-n1, quad mengembalikan 400 ketika model di-remesh, yang secara default dilakukan oleh meshy-6-lite.
Name
decimation_mode
Type
integer
Description
Jumlah face adaptif, berdasarkan level. Saat Anda mengaturnya, Meshy mengabaikan target_polycount.
Nilai yang tersedia:
- 1: ultra
- 2: high
- 3: medium
- 4: low
Name
save_pre_remeshed_model
Type
boolean
default false
Description
Apakah juga akan menyimpan GLB dari model sebelum tahap remesh. Meshy mengembalikannya dalam model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
Jumlah face yang ditargetkan. Hasilnya dapat berbeda dari target, tergantung pada geometri model.
Ini berlaku dalam dua kasus terpisah:
- Remesh: Ketika should_remesh bernilai true pada model standard, Meshy mendesimasi mesh hingga mendekati jumlah ini. Jika Anda mengatur decimation_mode, Meshy menggunakannya dan mengabaikan target_polycount.
- Smart Topology: Ketika model_type adalah smart-topology dan ai_model adalah meshy-t2 atau meshy-t2.5, Meshy menghasilkan model dengan jumlah face ini. Tidak ada proses remesh yang berjalan, dan Anda tidak memerlukan should_remesh.
Rentang dan default bergantung pada kasusnya:
Kasus Rentang Default
Remesh 100 hingga 300000 30000
meshy-t2 100 hingga 15000 4000
meshy-t2.5 100 hingga 30000 15000
Nilai di luar rentang akan mengembalikan 400.

Kasus	Rentang	Default
Remesh	`100` hingga `300000`	`30000`
`meshy-t2`	`100` hingga `15000`	`4000`
`meshy-t2.5`	`100` hingga `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ usang
default auto
Description
Kosongkan, karena tidak memengaruhi output. Nilainya mengontrol simetri selama proses pembuatan:
- off: tanpa simetri
- auto: simetri dipilih berdasarkan geometri input
- on: simetri yang dipaksakan
Name
pose_mode
Type
string
default ""
Description
Pose untuk model yang dihasilkan.
Nilai yang tersedia:
- a-pose: pose A
- t-pose: pose T
- "" (string kosong): tanpa pose tertentu
Name
is_a_t_pose
Type
boolean
⚠ usang
default false
Description
Gunakan pose_mode sebagai gantinya. Apakah akan menghasilkan model dalam pose A atau T.
Name
surface_mode
Type
string
⚠ usang
Description
Gunakan ai_model sebagai gantinya. Ini tidak memengaruhi output, karena mode pembuatan model yang dipilihnya sudah tidak digunakan lagi.
Nilai yang diterima adalah organic dan hard. Nilai lainnya akan mengembalikan 400.
Name
image_enhancement
Type
boolean
default true
Description
Apakah akan mengoptimalkan gambar input sebelum proses pembuatan. false mempertahankan tampilan gambar input persis apa adanya, tanpa pemrosesan gaya.
Ini hanya berfungsi dengan meshy-6, meshy-7.1, atau latest. Dengan meshy-6-lite atau model_type: smart-topology, ini mengembalikan 400.
Name
remove_lighting
Type
boolean
default true
Description
Apakah akan menghapus highlight dan bayangan dari tekstur warna dasar. Hasilnya lebih bersih dan bekerja lebih baik di bawah pencahayaan Anda sendiri.
Ini hanya berlaku pada model tekstur Meshy 6, dan model tekstur yang tidak mendukungnya akan mengembalikan 400 untuk true. Dengan model_type: smart-topology, atau dengan ai_model: meshy-6-lite dan model tekstur defaultnya, mengirimnya akan mengembalikan 400.
Name
moderation
Type
boolean
default false
Description
Apakah akan memeriksa input berikut untuk konten berbahaya sebelum proses pembuatan:
- image_url
- texture_image_url
- texture_prompt
Jika Meshy mendeteksi konten berbahaya, request akan mengembalikan 400 dan Meshy tidak membuat task.
Name
target_formats
Type
string[]
Description
Format file yang akan dihasilkan. Meshy hanya menghasilkan dan mengembalikan format yang Anda cantumkan, yang dapat mempersingkat task. Jika Anda mengosongkannya, Meshy menghasilkan semua format kecuali 3mf, yang hanya Anda dapatkan jika Anda mencantumkannya.
Nilai yang tersedia:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
default false
Description
Apakah akan memperkirakan tinggi objek di dunia nyata menggunakan AI vision dan mengubah ukuran model sesuai dengan itu. Meshy menempatkan titik asal di bagian bawah kecuali Anda mengatur origin_at.
Name
alpha_thumbnail
Type
boolean
default false
Description
Apakah juga akan merender pratinjau dengan latar belakang transparan (RGBA), dikembalikan dalam alpha_thumbnail_url saat Anda mengambil task. thumbnail_url tidak berubah.
Name
multi_view_thumbnails
Type
boolean
default false
Description
Apakah juga akan merender pratinjau tampilan depan, kanan, belakang, dan kiri, dikembalikan dalam thumbnail_urls saat Anda mengambil task. thumbnail_url tidak berubah dan tetap menampilkan tampilan depan. Ini menambah sekitar 5 detik pada task.

Hanya berlaku ketika auto_size = true

Name
origin_at
Type
string
default bottom
Description
Tempat untuk menempatkan titik asal model, bottom atau center.

Hasil yang dikembalikan

Kolom result pada respons berisi ID dari task Image to 3D yang baru.

Mode kegagalan

Name
400 - Bad Request
Description
Request tidak dapat dijalankan. Pesan kesalahan menunjukkan masalah apa yang ditemukan. Misalnya:
- Parameter hilang: Baik image_url maupun input_task_id tidak dikirim.
- Task input tidak valid: input_task_id bukan task Text to Image atau Image to Image dengan status SUCCEEDED yang menghasilkan tepat satu gambar.
- Format gambar tidak valid: Gambar pada image_url bukan file JPG, JPEG, PNG, atau WebP.
- URL tidak dapat dijangkau: Meshy tidak dapat mengunduh gambar image_url, karena URL mengembalikan 404 atau time out.
- Gambar terlalu besar: Gambar pada image_url atau texture_image_url berukuran lebih dari 20 MB.
- Ukuran gambar tidak valid: Gambar pada image_url atau texture_image_url memiliki sisi lebih pendek dari 32 piksel, atau lebih dari 178.956.970 piksel (lebar × tinggi).
- Data URI tidak valid: String base64 tidak valid formatnya.
- Kombinasi parameter tidak valid: enable_pbr bernilai true, dan should_texture bernilai false.
- Model tidak didukung untuk Ultra: geometry_resolution bernilai 2k atau 4k, dengan ai_model yang tidak dapat menjalankannya.
- Model tidak didukung untuk opsi gambar: salah satu dari berikut:
  - image_enhancement dikirim dengan ai_model: "meshy-6-lite" atau model_type: "smart-topology".
  - remove_lighting dikirim dengan model_type: "smart-topology", atau dengan ai_model: "meshy-6-lite" dan model tekstur defaultnya.
- Model tekstur tidak valid: texture_model bukan salah satu nilai yang tersedia.
- Model tekstur tidak tersedia: texture_model bernilai meshy-6 dengan ai_model selain meshy-6. Kirim meshy-7, meshy-n1, atau meshy-6-lite, atau kosongkan.
- Opsi tidak didukung untuk model tekstur: Request meminta opsi dari model tekstur yang tidak didukungnya, seperti enable_pbr: true dengan meshy-n1 atau tekstur 4k dengan meshy-6-lite. Lihat Models.
Perbaiki request, lalu kirim lagi. Lihat Errors.
Name
401 - Unauthorized
Description
Kunci API tidak ada atau tidak valid. Periksa header Authorization.
Name
402 - Payment Required
Description
Misalnya:
- Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk task ini, atau akun telah mencapai batas kredit. Periksa saldo kredit Anda, lalu coba lagi.
- Paket gratis: Membuat task memerlukan paket berbayar. Tingkatkan paket Anda di pengaturan langganan, lalu coba lagi.
Name
403 - Forbidden
Description
Moderasi konten memblokir prompt atau gambar input. Ubah input, lalu coba lagi.
Name
404 - Not Found
Description
input_task_id tidak cocok dengan task mana pun milik Anda. Periksa ID task, lalu kirim request lagi.
Name
429 - Too Many Requests
Description
Anda melampaui batas laju Anda. Tunggu, lalu coba lagi. Lihat Rate limits.

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

Mendapatkan tugas Gambar ke 3D

Mengembalikan tugas Gambar ke 3D berdasarkan ID-nya.

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": null,
  "consumed_credits": 30
}

Parameter

Name
id
Type
path
Description
ID tugas dari respons pembuatan (create).

Hasil Kembalian

Objek tugas Gambar ke 3D.

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

Menghapus task Gambar ke 3D

Menghapus task Gambar ke 3D secara permanen, termasuk model dan datanya. Anda tidak dapat membatalkan penghapusan.

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 keeps 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."
}

Parameter path

Name
id
Type
path
Description
ID task yang akan dihapus.

Status task

Menghapus task PENDING akan mengembalikan kredit yang digunakan saat Anda membuatnya.

Task IN_PROGRESS tidak dapat dihapus. Permintaan akan mengembalikan 409 Conflict, dan task akan terus berjalan. Meshy tidak mengembalikan kredit untuk task yang sudah mulai berjalan, sehingga menghapusnya akan membuat Anda kehilangan baik kredit maupun hasilnya. Tunggu hingga task mencapai status SUCCEEDED, FAILED, atau CANCELED, lalu hapus.

Menghapus task dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak akan mengembalikan kreditnya.

Returns

200 OK ketika task berhasil dihapus, atau 409 Conflict ketika task berstatus IN_PROGRESS.

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

Daftar tugas Gambar ke 3D

Mengembalikan daftar tugas Gambar ke 3D Anda.

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": null,
    "consumed_credits": 30
  }
]

Parameter

Name
page_num
Type
integer
default 1
Description
Nomor halaman yang akan dikembalikan, hingga 255. Nilai yang lebih besar akan mengembalikan 400.
Name
page_size
Type
integer
default 10
Description
Jumlah tugas per halaman, hingga 100.
Name
sort_by
Type
string
Description
Urutan pengurutan.
Nilai yang tersedia:
- +created_at: yang terlama lebih dulu
- -created_at: yang terbaru lebih dulu

Pengembalian

Daftar berpaginasi dari objek tugas Gambar ke 3D.

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

Stream tugas Image to 3D

Melakukan streaming pembaruan tugas Gambar ke 3D sebagai Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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": null,
  "consumed_credits": 30
}

Parameter

Name
id
Type
path
Description
ID tugas dari respons pembuatan.

Returns

Sebuah stream objek tugas Gambar ke 3D sebagai Server-Sent Events.

Setiap event menyimpan objek tugas secara lengkap, dengan bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Selama tugas berstatus PENDING atau IN_PROGRESS, kolom hasilnya belum memiliki nilai.

The Image to 3D task object

Objek task Image to 3D menjelaskan satu proses pembuatan model 3D dari sebuah gambar. Objek ini menyimpan status, progress, dan file model ketika task berhasil.

Properties

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": null,
  "consumed_credits": 30
}

Name
id
Type
string
Description
ID task. Perlakukan ini sebagai string buram, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Tipe task, selalu image-to-3d.
Name
model_urls
Type
object
Description
URL unduhan untuk model 3D yang dihasilkan, satu per format file. Format yang tidak dihasilkan oleh task tidak memiliki kunci, bukan string kosong.
- Name
  glb
  Type
  string
  Description
  File GLB.
- Name
  fbx
  Type
  string
  Description
  File FBX.
- Name
  obj
  Type
  string
  Description
  File OBJ.
- Name
  usdz
  Type
  string
  Description
  File USDZ.
- Name
  mtl
  Type
  string
  Description
  File MTL, dikembalikan bersama file OBJ ketika model memiliki tekstur.
- Name
  stl
  Type
  string
  Description
  File STL.
- Name
  3mf
  Type
  string
  Description
  File 3MF. Hanya ada ketika target_formats menyertakan 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  File GLB dari sebelum remesh. Hanya ada ketika Anda membuat task dengan should_remesh: true dan save_pre_remeshed_model: true sekaligus.
Name
thumbnail_url
Type
string
Description
URL unduhan untuk gambar pratinjau model 3D. Ketika thumbnail_urls ada, gambar ini sama dengan thumbnail_urls.front. Meshy mempertahankannya untuk kompatibilitas ke belakang.
Name
alpha_thumbnail_url
Type
string
Description
URL unduhan untuk versi thumbnail_url dengan latar belakang transparan (RGBA). Hanya ada ketika Anda membuat task dengan alpha_thumbnail: true dan Meshy me-render pratinjau transparan tersebut.
Name
thumbnail_urls
Type
object
Description
URL unduhan untuk pratinjau model 3D dari empat sisi. Setiap nilai adalah URL bertanda tangan ke PNG 512×512, dirender dengan material dan pencahayaan yang sama seperti thumbnail_url. Gunakan ini untuk melihat pratinjau model dari beberapa sudut, misalnya dalam pipeline batch, tanpa harus mengunduh GLB.
Hanya ada ketika Anda membuat task dengan multi_view_thumbnails: true dan task mencapai SUCCEEDED. Task yang dibuat tanpa multi_view_thumbnails: true tidak menyertakan field ini.
- Name
  front
  Type
  string
  Description
  Tampilan depan, pada 0° di sekitar sumbu vertikal. Sama dengan thumbnail_url.
- Name
  right
  Type
  string
  Description
  Tampilan kanan, pada 90°.
- Name
  back
  Type
  string
  Description
  Tampilan belakang, pada 180°.
- Name
  left
  Type
  string
  Description
  Tampilan kiri, pada 270°.
Name
texture_prompt
Type
string
Description
Prompt teks yang memandu tekstur.
Name
texture_image_url
Type
string
Description
URL unduhan untuk gambar yang memandu tekstur.
Name
ultra_mode
Type
boolean
⚠ usang
Description
Gunakan geometry_resolution sebagai gantinya.
Name
geometry_resolution
Type
string
Description
Tingkat Ultra yang dijalankan task, 2k atau 4k. Task standard tidak menyertakan field ini.
Name
progress
Type
integer
Description
Seberapa banyak task yang sudah selesai, dalam persentase. Nilainya 0 sampai task dimulai dan 100 ketika berhasil.
Name
started_at
Type
timestamp
Description
Waktu task dimulai, dalam milidetik Unix. Nilainya 0 sampai task dimulai.
Name
created_at
Type
timestamp
Description
Waktu task dibuat, dalam milidetik Unix.
Name
expires_at
Type
timestamp
Description
Waktu hasil task kedaluwarsa, dalam milidetik Unix.
Name
finished_at
Type
timestamp
Description
Waktu task selesai, dalam milidetik Unix. Nilainya 0 sampai task selesai.
Name
status
Type
string
Description
Status task, salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
texture_urls
Type
array
Description
Peta tekstur yang dihasilkan task, sebagai array objek. Biasanya berisi satu objek, dengan field berikut:
- Name
  base_color
  Type
  string
  Description
  URL unduhan untuk peta warna dasar.
- Name
  metallic
  Type
  string
  Description
  URL unduhan untuk peta metallic. Field ini tidak ada ketika Anda membuat task dengan enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  URL unduhan untuk normal map. Field ini tidak ada ketika Anda membuat task dengan enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  URL unduhan untuk peta roughness. Field ini tidak ada ketika Anda membuat task dengan enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  URL unduhan untuk peta emission. Meshy hanya menyertakannya ketika Anda membuat task dengan semua kondisi berikut:
  
  ai_model: meshy-6, dengan model tekstur default-nya
  
  enable_pbr: true
  
  texture_resolution berupa 2k atau 4k
Name
preceding_tasks
Type
integer
Description
Jumlah task yang berada di depan task ini dalam antrean. Nilai ini hanya berarti selama task berstatus PENDING.
Name
task_error
Type
object
Description
Detail kesalahan ketika task gagal. Nilainya null kecuali statusnya FAILED. Lihat Kesalahan.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang digunakan task. Ada ketika statusnya PENDING, IN_PROGRESS, atau SUCCEEDED. Nilainya 0 untuk task FAILED, karena Meshy mengembalikan kredit ketika sebuah task gagal.