API Berbilang Imej ke 3D

API Berbilang Imej ke 3D ialah ciri yang membolehkan anda mengintegrasikan keupayaan Berbilang Imej ke 3D Meshy ke dalam aplikasi anda sendiri. Dalam bahagian ini, anda akan menemui semua maklumat yang anda perlukan untuk mula menggunakan API ini.

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

Create a Multi-Image to 3D Task

Endpoint ini membolehkan anda membuat tugasan Berbilang Imej ke 3D yang baharu. Rujuk The Multi-Image to 3D Task Object untuk melihat properti yang disertakan dengan objek tugasan Berbilang Imej ke 3D.

Tugasan ini berjalan di latar belakang. Untuk tempoh masa yang biasanya diambil, lihat Processing Times.

Parameter

Hanya salah satu daripada input_task_id atau image_urls yang diperlukan. Jika kedua-duanya diberikan, input_task_id akan diutamakan.

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugasan penjanaan imej yang telah selesai, di mana outputnya (1-4 imej) harus digunakan sebagai input. Tugasan ini mestilah salah satu daripada yang berikut: Teks ke Imej, Imej ke Imej, Teks ke Imej Berbilang Pandangan, atau Imej ke Imej Berbilang Pandangan. Selain itu, ia mestilah telah dijalankan melalui API dan mempunyai status SUCCEEDED.

Name
image_urls
Type
array
Diperlukan
Description
Berikan 1 hingga 4 imej untuk Meshy gunakan dalam penciptaan model. Kami kini menyokong format .jpg, .jpeg, .png, dan .webp. Semua imej harus menggambarkan objek yang sama dari sudut yang berbeza untuk hasil terbaik.
Saiz fail maksimum: 20 MB setiap imej.
Terdapat dua cara untuk menyediakan setiap imej:
- URL yang boleh diakses secara terbuka: URL yang boleh diakses dari internet awam.
- Data URI: Data URI yang dikodkan base64 bagi imej tersebut. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Untuk meshy-7.1 (atau latest), imej pertama digunakan sebagai pandangan utama (hadapan). Susunan imej selebihnya tidak penting.

Name
ai_model
Type
string
lalai latest
Description
ID model yang hendak digunakan.
Nilai yang tersedia:
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (lapuk): gunakan meshy-7.1 sebagai gantinya.
Name
geometry_resolution
Type
string
lalai standard
Description
Laluan penjanaan geometri. 2k menjalankan laluan Ultra pada 2048³. Memerlukan meshy-7.1 atau latest.
Nilai yang tersedia: standard, 2k
Name
ultra_mode
Type
boolean
⚠ lapuk
lalai false
Description
Gunakan geometry_resolution sebagai gantinya. ultra_mode: true adalah setara dengan geometry_resolution: "2k".
Name
should_texture
Type
boolean
lalai true
Description
Menentukan sama ada tekstur dijana. Menetapkannya kepada false akan melangkau fasa tekstur, menghasilkan jejaring tanpa tekstur.

Hanya berlaku apabila should_texture = true

Name
enable_pbr
Type
boolean
lalai false
Description
Jana peta PBR (metallic, roughness, normal) selain warna asas. Peta emisi turut disertakan apabila ai_model ialah meshy-6, kecuali pada texture_resolution: 8k. meshy-6-lite, meshy-7.1 dan latest tidak menghasilkan peta emisi.
Name
texture_resolution
Type
string
lalai 2k
Description
Resolusi tekstur warna asas. Salah satu daripada 2k (2048×2048), 4k (4096×4096), atau 8k (8192×8192). Resolusi yang lebih tinggi menangkap lebih banyak perincian permukaan.
4k dan 8k memerlukan ai_model meshy-6, meshy-7.1 atau latest. Pada 8k, tiada peta emisi dihasilkan.
Name
hd_texture
Type
boolean
⚠ lapuk
lalai false
Description
Gunakan texture_resolution sebagai gantinya — setara dengan texture_resolution: "4k". Apabila kedua-duanya ditetapkan, texture_resolution akan diutamakan.
Name
texture_prompt
Type
string
Description
Berikan prompt teks untuk membimbing proses tekstur. Maksimum 800 aksara.
Name
texture_image_url
Type
string
Description
Berikan imej 2d untuk membimbing proses tekstur. Kami kini menyokong format .jpg, .jpeg, .png, dan .webp.
Saiz fail maksimum: 20 MB.
Terdapat dua cara untuk menyediakan imej tersebut:
- URL yang boleh diakses secara terbuka: URL yang boleh diakses dari internet awam
- Data URI: Data URI yang dikodkan base64 bagi imej tersebut. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>
Pemberian tekstur imej mungkin tidak berfungsi secara optimum jika terdapat perbezaan geometri yang besar antara aset asal dan imej yang dimuat naik. Hanya salah satu daripada texture_image_url atau texture_prompt boleh digunakan untuk membimbing proses tekstur. Jika kedua-dua parameter diberikan, maka texture_prompt akan digunakan secara lalai untuk memberi tekstur pada model.
Name
texture_image_urls
Type
string[]
Description
Berikan 1 hingga 4 imej yang menunjukkan objek yang sama dari pandangan berbeza untuk membimbing tekstur. Imej pertama adalah pandangan utama (hadapan); susunan pandangan selebihnya (kiri, belakang, kanan) tidak penting.
Setiap elemen menerima format yang sama seperti texture_image_url (URL yang boleh diakses secara terbuka atau data URI base64, .jpg/.jpeg/.png/.webp).
Saiz fail maksimum: 20 MB setiap imej.
Imej-imej ini hanya membimbing tekstur, dan tidak bergantung kepada image_urls — kedua-dua senarai boleh mengandungi imej yang berbeza dan bilangan imej yang berbeza.
Memerlukan ai_model meshy-7.1 atau latest. Tidak boleh digabungkan dengan texture_image_url atau texture_prompt.

Name
should_remesh
Type
boolean
lalai false (Meshy 6 and Meshy 7 models), true (others)
Description
Mengawal sama ada untuk mengaktifkan fasa remesh. Untuk model berkualiti tertinggi, kami mengesyorkan menetapkan should_remesh kepada false.

Hanya berlaku apabila should_remesh = true

Name
topology
Type
string
lalai triangle
Description
Nyatakan topology bagi model yang dijana.
Nilai yang tersedia:
- quad: Jana jejaring yang didominasi oleh quad.
- triangle: Jana jejaring segitiga yang didesimasi.
Name
target_polycount
Type
integer
lalai 30,000
Description
Nyatakan sasaran bilangan poligon dalam model yang dijana. Bilangan poligon sebenar mungkin berbeza daripada sasaran bergantung pada kerumitan geometri.
Julat yang sah ialah 100 hingga 300,000 (termasuk).
Name
decimation_mode
Type
integer
Description
Aktifkan desimasi adaptif dengan menetapkan tahap bilangan poligon. Apabila ditetapkan, target_polycount akan diabaikan.
Nilai yang tersedia:
- 1: Adaptif — bilangan poligon ultra.
- 2: Adaptif — bilangan poligon tinggi.
- 3: Adaptif — bilangan poligon sederhana.
- 4: Adaptif — bilangan poligon rendah.
Name
save_pre_remeshed_model
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, Meshy turut menyimpan fail GLB tambahan sebelum fasa remesh selesai.

Name
symmetry_mode
Type
string
⚠ lapuk
lalai auto
Description
Lapuk. Parameter ini tidak lagi mempengaruhi output.
Medan symmetry_mode mengawal tingkah laku simetri semasa proses penjanaan model.
Nilai yang sah ialah:
- off: Melumpuhkan simetri.
- auto: Menentukan dan menggunakan simetri secara automatik berdasarkan geometri input.
- on: Menguatkuasakan simetri semasa penjanaan.
Name
pose_mode
Type
string
lalai ""
Description
Nyatakan mode pose bagi model yang dijana.
Nilai yang tersedia:
- a-pose: Jana model dalam pose A.
- t-pose: Jana model dalam pose T.
- "" (rentetan kosong): Tiada pose khusus digunakan.
Name
is_a_t_pose
Type
boolean
⚠ lapuk
lalai false
Description
Gunakan pose_mode sebagai gantinya. Sama ada hendak menjana model dalam pose A/T.
Name
image_enhancement
Type
boolean
lalai true
Description
Mengoptimumkan imej input untuk hasil yang lebih baik. Tetapkan kepada false untuk mengekalkan rupa sebenar imej input tanpa sebarang pemprosesan gaya.
Hanya disokong apabila ai_model ialah meshy-6, meshy-7.1 atau latest. Menetapkannya dengan meshy-6-lite akan mengembalikan ralat.
Name
remove_lighting
Type
boolean
lalai true
Description
Membuang sorotan dan bayang-bayang daripada tekstur warna asas, menghasilkan output yang lebih bersih yang berfungsi dengan lebih baik di bawah persediaan pencahayaan tersuai.
Hanya disokong apabila ai_model ialah meshy-6, meshy-7.1 atau latest. Menetapkannya dengan meshy-6-lite akan mengembalikan ralat.
Name
moderation
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, kandungan input akan disaring secara automatik untuk kandungan yang berpotensi memudaratkan. Jika kandungan berbahaya dikesan, tugasan tidak akan diteruskan ke peringkat penjanaan.
Setiap imej daripada image_urls dan teks daripada texture_prompt akan disaring.
Name
target_formats
Type
string[]
Description
Menentukan format fail 3D yang hendak disertakan dalam output. Hanya format yang diminta akan dijana dan dikembalikan, yang boleh mengurangkan masa penyiapan tugasan.
Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf
Apabila ditiadakan, semua format kecuali 3mf akan dijana. 3mf hanya disertakan apabila dinyatakan secara jelas.
Name
auto_size
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, perkhidmatan ini menggunakan penglihatan AI untuk menganggarkan secara automatik ketinggian sebenar objek tersebut dan mengubah saiz model mengikutnya. Titik asal akan menjadi lalai kepada bottom melainkan origin_at ditetapkan secara jelas.
Name
alpha_thumbnail
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, tugasan tersebut turut merender versi pratonton berlatar belakang lutsinar (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Medan thumbnail_url yang sedia ada tidak berubah.
Name
multi_view_thumbnails
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, tugasan tersebut turut merender empat lakaran kecil pandangan utama (hadapan, kanan, belakang, kiri) dan mengembalikannya di bawah thumbnail_urls pada respons GET. Medan thumbnail_url yang sedia ada tidak berubah dan terus menunjuk kepada pandangan hadapan, jadi klien sedia ada tidak terjejas.
Menambah kira-kira 3 saat kepada kependaman tugasan.

Hanya berlaku apabila auto_size = true

Name
origin_at
Type
string
lalai bottom
Description
Kedudukan titik asal apabila auto_size diaktifkan. Nilai yang tersedia: bottom, center.

Returns

Properti result dalam respons mengandungi id tugasan bagi tugasan Berbilang Imej ke 3D yang baharu dicipta.

Failure Modes

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Punca biasa:
- Parameter hilang: Sama ada image_urls atau input_task_id mesti diberikan.
- Tugasan input tidak sah: input_task_id mestilah merujuk kepada tugasan Teks ke Imej, Imej ke Imej, atau varian berbilang pandangan yang berstatus SUCCEEDED.
- Bilangan imej tidak sah: image_urls mesti mengandungi antara 1 hingga 4 imej, dan texture_image_urls antara 1 hingga 4.
- Format imej tidak sah: Satu atau lebih imej dalam image_urls bukan format yang disokong.
- Input tekstur bercanggah: texture_image_urls tidak boleh digabungkan dengan texture_image_url atau texture_prompt, dan memerlukan should_texture: true.
- Model tidak disokong untuk tekstur berbilang pandangan: texture_image_urls memerlukan ai_model meshy-7.1 atau latest.
- URL tidak boleh dicapai: Satu atau lebih elemen image_urls atau texture_image_urls tidak dapat dimuat turun.
- Imej terlalu besar: Satu atau lebih imej image_urls, texture_image_url atau texture_image_urls melebihi 20 MB.
- Resolusi tidak disokong untuk input berbilang imej: geometry_resolution: "4k" tidak tersedia pada endpoint ini; gunakan 2k atau standard.
- Model tidak disokong untuk opsyen imej: image_enhancement atau remove_lighting ditetapkan bersama ai_model: "meshy-6-lite".
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugasan ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda.

Request

POST

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

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

# With Ultra 2K geometry, PBR texturing and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "geometry_resolution": "2k",
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

Response

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

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

Dapatkan Semula Tugas Berbilang Imej ke 3D

Endpoint ini membolehkan anda mendapatkan semula tugas Berbilang Imej ke 3D dengan id tugas yang sah. Rujuk The Multi-Image to 3D Task Object untuk melihat sifat-sifat yang disertakan dengan objek tugas Berbilang Imej ke 3D.

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas Berbilang Imej ke 3D yang hendak didapatkan semula.

Pulangan

Respons mengandungi objek tugas Berbilang Imej ke 3D. Semak bahagian The Multi-Image to 3D Task Object untuk maklumat lanjut.

Request

GET

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

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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/multi-image-to-3d/:id

Padam Tugasan Berbilang Imej ke 3D

Endpoint ini memadam secara kekal tugasan Berbilang Imej ke 3D, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh diundurkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugasan Berbilang Imej ke 3D yang hendak dipadam.

Status Tugasan

Tugasan yang masih PENDING akan dipadam dan kredit yang digunakan semasa penciptaan akan dikembalikan.

Tugasan yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugasan akan terus berjalan. Kredit untuk tugasan yang sudah pun dimulakan oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan menyebabkan anda kehilangan kedua-dua kredit dan hasilnya. Tunggu sehingga ia mencapai SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugasan yang berada dalam status terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa sebarang pemulangan kredit.

Pulangan

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila tugasan dalam status IN_PROGRESS.

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/multi-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/multi-image-to-3d

Senarai Tugas Berbilang Imej ke 3D

Endpoint ini membolehkan anda mendapatkan semula senarai tugas Berbilang Imej ke 3D.

Parameter

Atribut pilihan

Name
page_num
Type
integer
Description
Nombor halaman untuk penomboran halaman. Bermula dan lalai kepada 1.
Name
page_size
Type
integer
Description
Had saiz halaman. Lalai kepada 10 item. Maksimum yang dibenarkan ialah 100 item.
Name
sort_by
Type
string
Description
Medan untuk diisih mengikut. Nilai yang tersedia:
- +created_at: Isih mengikut masa penciptaan secara menaik.
- -created_at: Isih mengikut masa penciptaan secara menurun.

Pulangan

Mengembalikan senarai bernomboran halaman bagi Objek Tugas Berbilang Imej ke 3D.

Request

GET

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

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "multi-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/multi-image-to-3d/:id/stream

Strim Tugasan Berbilang Imej ke 3D

Endpoint ini menstrim kemas kini masa nyata untuk tugasan Berbilang Imej ke 3D menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugasan Berbilang Imej ke 3D yang hendak distrim.

Nilai pulangan

Mengembalikan strim Objek Tugasan Berbilang Imej ke 3D sebagai Server-Sent Events.

Untuk tugasan PENDING atau IN_PROGRESS, strim respons hanya akan menyertakan medan progress dan status yang diperlukan.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/multi-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": "multi-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
}

Objek Tugas Berbilang Imej ke 3D

Objek Tugas Berbilang Imej ke 3D ialah unit kerja yang dijejaki oleh Meshy untuk menjana model 3D daripada berbilang imej (antara 1 hingga 4 inklusif). Imej tersebut harus bagi objek yang sama, idealnya daripada pandangan atau sudut yang berbeza. Objek ini mempunyai ciri-ciri berikut:

Ciri-ciri

Name
id
Type
string
Description
Pengenal unik untuk tugas tersebut. Walaupun kami menggunakan UUID yang boleh disusun-k sebagai perincian pelaksanaan untuk id tugas, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas Berbilang Imej ke 3D. Nilainya ialah multi-image-to-3d.
Name
model_urls
Type
object
Description
URL boleh muat turun kepada fail model 3D bertekstur yang dijana oleh Meshy. Ciri bagi sesuatu format akan ditinggalkan jika format tersebut tidak dijana, dan bukannya memulangkan rentetan kosong.
- Name
  glb
  Type
  string
  Description
  URL boleh muat turun kepada fail GLB.
- Name
  fbx
  Type
  string
  Description
  URL boleh muat turun kepada fail FBX.
- Name
  obj
  Type
  string
  Description
  URL boleh muat turun kepada fail OBJ.
- Name
  usdz
  Type
  string
  Description
  URL boleh muat turun kepada fail USDZ.
- Name
  mtl
  Type
  string
  Description
  URL boleh muat turun kepada fail MTL, dipulangkan bersama eksport OBJ apabila terdapat tekstur.
- Name
  stl
  Type
  string
  Description
  URL boleh muat turun kepada fail STL.
- Name
  3mf
  Type
  string
  Description
  URL boleh muat turun kepada fail 3MF. Hanya hadir apabila 3mf diminta melalui target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL boleh muat turun kepada output GLB asal sebelum remesh.
  Hanya tersedia apabila tugas dicipta dengan kedua-dua should_remesh: true dan save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL boleh muat turun kepada imej kecil fail model. Setara dengan thumbnail_urls.front apabila hadir, dikekalkan untuk keserasian ke belakang.
Name
alpha_thumbnail_url
Type
string
Description
URL boleh muat turun kepada versi latar belakang lutsinar (RGBA) bagi thumbnail_url. Hanya hadir apabila tugas dicipta dengan alpha_thumbnail: true dan pratonton lutsinar berjaya dirender; jika tidak, medan ini akan ditinggalkan.
Name
thumbnail_urls
Type
object
Description
URL boleh muat turun untuk empat imej kecil pandangan kardinal bagi model 3D yang dijana. Setiap nilai ialah URL bertandatangan kepada PNG 512×512 yang dirender dengan bahan dan pencahayaan yang sama seperti thumbnail_url. Berguna untuk pratonton model dari pelbagai sudut dalam saluran paip kelompok tanpa memuat turun GLB.
Hanya hadir apabila tugas dicipta dengan multi_view_thumbnails: true dan telah mencapai SUCCEEDED. Tugas lama dan tugas yang dicipta tanpa opt-in tidak akan menyertakan medan ini.
- Name
  front
  Type
  string
  Description
  Pandangan hadapan, putaran 0° di sekitar paksi menegak (sepadan dengan thumbnail_url).
- Name
  right
  Type
  string
  Description
  Pandangan kanan, putaran 90°.
- Name
  back
  Type
  string
  Description
  Pandangan belakang, putaran 180°.
- Name
  left
  Type
  string
  Description
  Pandangan kiri, putaran 270°.
Name
texture_prompt
Type
string
Description
Prompt teks yang digunakan untuk membimbing proses pembuatan tekstur.
Name
texture_image_urls
Type
string[]
Description
URL boleh muat turun kepada imej rujukan tekstur yang digunakan untuk mencipta tugas, mengikut susunan ia diberikan. Hanya hadir apabila tugas dicipta dengan texture_image_urls.
Name
ultra_mode
Type
boolean
⚠ lapuk
Description
Lapuk; bacalah geometry_resolution sebaliknya.
Name
geometry_resolution
Type
string
Description
Tahap Ultra yang digunakan oleh tugas (2k); ditinggalkan untuk standard.
Name
progress
Type
integer
Description
Progress tugas. Jika tugas belum bermula lagi, ciri ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.
Name
started_at
Type
timestamp
Description
Cap masa bila tugas dimulakan, dalam milisaat. Jika tugas belum bermula lagi, ciri ini akan menjadi 0.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut piawaian RFC 3339. Sebagai contoh, Jumaat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini terpakai kepada semua cap masa dalam Meshy API.
Name
created_at
Type
timestamp
Description
Cap masa bila tugas dicipta, dalam milisaat.
Name
expires_at
Type
timestamp
Description
Cap masa bila hasil tugas akan tamat tempoh, dalam milisaat.
Name
finished_at
Type
timestamp
Description
Cap masa bila tugas selesai, dalam milisaat. Jika tugas belum selesai lagi, ciri ini akan menjadi 0.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Satu tatasusunan objek URL tekstur yang dijana daripada tugas tersebut. Biasanya ini hanya mengandungi satu objek URL tekstur. Setiap URL tekstur mempunyai ciri-ciri berikut:
- Name
  base_color
  Type
  string
  Description
  URL boleh muat turun kepada imej peta warna asas.
- Name
  metallic
  Type
  string
  Description
  URL boleh muat turun kepada imej peta logam.
  Jika tugas dicipta dengan enable_pbr: false, ciri ini akan ditinggalkan.
- Name
  normal
  Type
  string
  Description
  URL boleh muat turun kepada imej peta normal.
  Jika tugas dicipta dengan enable_pbr: false, ciri ini akan ditinggalkan.
- Name
  roughness
  Type
  string
  Description
  URL boleh muat turun kepada imej peta kekasaran.
  Jika tugas dicipta dengan enable_pbr: false, ciri ini akan ditinggalkan.
- Name
  emission
  Type
  string
  Description
  URL boleh muat turun kepada imej peta pancaran.
  Jika tugas dicipta dengan enable_pbr: false, atau ai_model ialah meshy-6-lite, meshy-7.1, atau latest, ciri ini akan ditinggalkan.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu.
Nilai medan ini hanya bermakna jika status tugas ialah PENDING.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. Hadir apabila status tugas ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Memulangkan 0 untuk tugas FAILED (kredit dikembalikan apabila gagal).

Example Multi-Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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,
}