API Imej ke 3D

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

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

Cipta Tugasan Imej ke 3D

Endpoint ini membolehkan anda mencipta tugasan Imej ke 3D yang baharu. Rujuk The Image to 3D Task Object untuk melihat parameter yang disertakan dengan objek tugasan Imej ke 3D.

Parameter

Hanya salah satu daripada input_task_id atau image_url diperlukan. Jika kedua-duanya disediakan, input_task_id akan diutamakan.

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugasan penjanaan imej yang telah selesai, yang outputnya akan digunakan sebagai imej input. Tugasan ini mestilah salah satu daripada tugasan berikut: Teks ke Imej atau Imej ke Imej. Selain itu, ia mesti telah dijalankan melalui API, mempunyai status SUCCEEDED, dan menghasilkan tepat satu imej.

Name
image_url
Type
string
Diperlukan
Description
Sediakan imej untuk Meshy gunakan dalam penciptaan model. Kami buat masa ini menyokong format .jpg, .jpeg, dan .png.
Terdapat dua cara untuk menyediakan imej tersebut:
- URL yang boleh diakses secara awam: URL yang boleh diakses daripada internet awam.
- Data URI: Data URI imej yang dikodkan base64. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
model_type
Type
string
lalai standard
Description
Tentukan jenis penjanaan jejaring 3D.
Nilai yang tersedia:
- standard: Penjanaan jejaring 3D berkualiti tinggi biasa.
- smart-topology: Pilih model Smart Topology dengan ai_model (meshy-t2).
- lowpoly (lapuk, akan dihentikan pada 30 Oktober 2026): Menjana jejaring low-poly yang dioptimumkan untuk poligon yang lebih kemas. Kami mengesyorkan Meshy T2 sebagai gantinya: smart-topology dengan meshy-t2.
Apabila smart-topology dipilih, topology, should_remesh, dan save_pre_remeshed_model akan diabaikan.
lowpoly akan dihentikan pada 30 Oktober 2026. Selepas tarikh tersebut, permintaan dengan model_type: "lowpoly" akan memulangkan ralat. Kami mengesyorkan anda beralih kepada Meshy T2 (model_type: "smart-topology" dengan ai_model: "meshy-t2"). Apabila lowpoly dipilih, ai_model, topology, target_polycount, should_remesh, dan save_pre_remeshed_model akan diabaikan.
Name
ai_model
Type
string
lalai latest
Description
ID model yang hendak digunakan. Nilai yang tersedia bergantung pada model_type.
Penjanaan standard (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (lapuk): gunakan meshy-7.1 sebagai gantinya.
Penjanaan Smart Topology (model_type: smart-topology):
- meshy-t2 (lalai): model Smart Topology — topology yang lebih kemas, bahagian yang dipisahkan secara semula jadi, output segi tiga, dan bilangan muka yang boleh anda tetapkan dengan target_polycount.
Name
geometry_resolution
Type
string
lalai standard
Description
Laluan penjanaan geometri. 2k menjalankan laluan Ultra pada 2048³; 4k menjalankannya pada 4096³ untuk perincian permukaan yang paling halus.
Nilai yang tersedia: standard, 2k, 4k
Memerlukan meshy-7.1 atau latest.
Name
ultra_mode
Type
boolean
⚠ lapuk
lalai false
Description
Gunakan geometry_resolution sebagai gantinya. ultra_mode: true setara dengan geometry_resolution: "2k".
Name
should_texture
Type
boolean
lalai true
Description
Menentukan sama ada tekstur dijana. Menetapkannya kepada false 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) sebagai tambahan kepada 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 merakam perincian permukaan yang lebih banyak.
4k dan 8k tidak tersedia dengan ai_model meshy-6-lite. 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
Sediakan prompt teks untuk membimbing proses tekstur. Maksimum 800 aksara.
Name
texture_image_url
Type
string
Description
Sediakan imej 2D untuk membimbing proses tekstur. Kami buat masa ini menyokong format .jpg, .jpeg, dan .png.
Terdapat dua cara untuk menyediakan imej tersebut:
- URL yang boleh diakses secara awam: URL yang boleh diakses daripada internet awam
- Data URI: Data URI imej yang dikodkan base64. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>
Tekstur imej mungkin tidak berfungsi secara optimum jika terdapat perbezaan geometri yang ketara 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 disediakan, maka texture_prompt akan digunakan secara lalai untuk memberi tekstur pada model. Pemberian tekstur sama ada melalui teks atau imej akan dikenakan caj 10 kredit setiap tugasan.

Name
should_remesh
Type
boolean
lalai false (Meshy 6 and Meshy 7 models), true (others)
Description
Mengawal sama ada untuk mendayakan 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
Tentukan topology model yang dijana.
Nilai yang tersedia:
- quad: Jana jejaring yang didominasi quad.
- triangle: Jana jejaring segi tiga yang didesimasi.
Name
decimation_mode
Type
integer
Description
Dayakan 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
target_polycount
Type
integer
Description
Bilangan sasaran poligon (muka) dalam output. Bilangan sebenar mungkin berbeza daripada sasaran bergantung pada geometri.
target_polycount berkuat kuasa dalam dua kes bebas:
- Remesh — dengan should_remesh: true pada model standard. Jejaring akan di-remesh (didesimasi) kepada kira-kira bilangan ini. Julat 100 hingga 300,000, lalai 30,000. Jika decimation_mode ditetapkan, ia diutamakan dan target_polycount akan diabaikan.
- Smart Topology — dengan model_type: smart-topology dan ai_model: meshy-t2. Model dijana secara terus pada bilangan muka ini; tiada remesh dijalankan dan should_remesh tidak diperlukan. Julat 100 hingga 15,000, lalai 4,000.

Name
symmetry_mode
Type
string
⚠ lapuk
lalai auto
Description
Lapuk. Parameter ini tidak lagi menjejaskan output.
Medan symmetry_mode mengawal tingkah laku simetri semasa proses penjanaan model.
Nilai yang sah ialah:
- off: Melumpuhkan simetri.
- auto: Menentukan dan menerapkan simetri secara automatik berdasarkan geometri input.
- on: Menguatkuasakan simetri semasa penjanaan.
Name
pose_mode
Type
string
lalai ""
Description
Tentukan mode pose untuk 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 diterapkan.
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.
Name
remove_lighting
Type
boolean
lalai true
Description
Membuang sorotan dan bayang-bayang daripada tekstur warna asas, menghasilkan output yang lebih kemas yang berfungsi lebih baik di bawah persediaan pencahayaan tersuai.
Hanya disokong apabila ai_model ialah meshy-6.
Name
moderation
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, kandungan input akan disaring secara automatik untuk kandungan yang berpotensi membahayakan. Jika kandungan berbahaya dikesan, tugasan tidak akan diteruskan ke peringkat penjanaan.
Kandungan daripada input image_url, texture_image_url, dan 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 dipulangkan, yang boleh mengurangkan masa penyelesaian tugasan. Apabila ditinggalkan, semua format yang disokong akan disertakan.
Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf
Apabila ditinggalkan, 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 objek di dunia sebenar dan mengubah saiz model mengikutnya. Titik asal akan lalai kepada bottom melainkan origin_at ditetapkan secara jelas.
Name
alpha_thumbnail
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, tugasan ini turut merender versi pratonton latar belakang telus (RGBA) dan memulangkannya 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 ini turut merender empat thumbnail pandangan kardinal (depan, kanan, belakang, kiri) dan memulangkannya di bawah thumbnail_urls pada respons GET. Medan thumbnail_url yang sedia ada tidak berubah dan terus menunjuk kepada pandangan depan, 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 didayakan.
Nilai yang tersedia: bottom, center.

Pulangan

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

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Parameter tiada: Sama ada image_url atau input_task_id mesti disediakan.
- Tugasan input tidak sah: input_task_id mesti merujuk kepada tugasan Teks ke Imej atau Imej ke Imej yang berstatus SUCCEEDED dan menghasilkan tepat satu imej.
- Format imej tidak sah: image_url yang disediakan bukan format yang disokong (.jpg, .jpeg, .png).
- URL tidak dapat dicapai: image_url tidak dapat dimuat turun (404 atau timeout).
- Data URI tidak sah: Rentetan base64 tidak sah dari segi format.
- Gabungan parameter tidak sah: enable_pbr hanya disokong apabila should_texture bernilai true.
- Model tidak disokong untuk low poly: ai_model: "meshy-6-lite" tidak menyokong model_type: "lowpoly".
- Model tidak disokong untuk Ultra: geometry_resolution memerlukan meshy-7.1 atau latest.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk menjalankan tugasan ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar 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

Dapatkan Semula Tugas Imej ke 3D

Endpoint ini membolehkan anda mendapatkan semula tugas Imej ke 3D berdasarkan id tugas yang sah. Rujuk Objek Tugas Imej ke 3D untuk melihat sifat-sifat yang disertakan dengan objek tugas Imej ke 3D.

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Imej ke 3D yang ingin didapatkan semula.

Nilai Pulangan

Respons mengandungi objek tugas Imej ke 3D. Semak bahagian Objek Tugas Imej ke 3D untuk maklumat lanjut.

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

Padam Tugasan Imej ke 3D

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

Parameter Laluan

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

Status Tugasan

Tugasan yang masih PENDING akan dipadamkan dan kredit yang digunakan semasa ia dicipta akan dikembalikan.

Tugasan yang sudah IN_PROGRESS tidak boleh dipadamkan: permintaan akan ditolak dengan 409 Conflict dan tugasan itu terus berjalan. Kredit untuk tugasan yang worker sudah mula proses tidak boleh dikembalikan, jadi memadamkannya semasa ia sedang berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugasan yang berada dalam status akhir (SUCCEEDED, FAILED atau CANCELED) akan dipadamkan tanpa bayaran balik.

Nilai Pulangan

Mengembalikan 200 OK jika berjaya, atau 409 Conflict apabila tugasan itu 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

Senaraikan Tugas Imej ke 3D

Endpoint ini membolehkan anda mendapatkan senarai tugas 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 disusun mengikut. Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan secara menaik.
- -created_at: Susun mengikut masa penciptaan secara menurun.

Pemulangan

Memulangkan senarai bernombor halaman bagi Objek Tugas Imej ke 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

Strim Tugas Imej ke 3D

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

Parameter

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

Nilai Kembalian

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

Untuk tugas PENDING atau IN_PROGRESS, strim respons hanya akan mengandungi medan 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

Objek Image to 3D Task adalah unit kerja yang dijejaki oleh Meshy untuk menghasilkan model 3D daripada input imej. Objek ini mempunyai sifat-sifat berikut:

Properties

Name
id
Type
string
Description
Pengenal unik untuk tugas ini. Walaupun kami menggunakan UUID yang boleh disusun-k (k-sortable) untuk id tugas sebagai perincian pelaksanaan, anda tidak sepatutnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas Imej ke 3D. Nilainya adalah image-to-3d.
Name
model_urls
Type
object
Description
URL yang boleh dimuat turun untuk fail model 3D bertekstur yang dihasilkan oleh Meshy. Sifat untuk sesuatu format akan ditinggalkan jika format tersebut tidak dihasilkan, sebagai ganti mengembalikan rentetan kosong.
- Name
  glb
  Type
  string
  Description
  URL yang boleh dimuat turun untuk fail GLB.
- Name
  fbx
  Type
  string
  Description
  URL yang boleh dimuat turun untuk fail FBX.
- Name
  obj
  Type
  string
  Description
  URL yang boleh dimuat turun untuk fail OBJ.
- Name
  usdz
  Type
  string
  Description
  URL yang boleh dimuat turun untuk fail USDZ.
- Name
  mtl
  Type
  string
  Description
  URL yang boleh dimuat turun untuk fail MTL, dikembalikan bersama-sama eksport OBJ apabila tekstur wujud.
- Name
  stl
  Type
  string
  Description
  URL yang boleh dimuat turun untuk fail STL.
- Name
  3mf
  Type
  string
  Description
  URL yang boleh dimuat turun untuk fail 3MF. Hanya wujud apabila 3mf diminta melalui target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL yang boleh dimuat turun untuk output GLB asal sebelum remesh.
  Hanya tersedia apabila tugas ini dicipta dengan kedua-dua should_remesh: true dan save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL yang boleh dimuat turun untuk imej kecil bagi fail model. Bersamaan dengan thumbnail_urls.front apabila wujud, dikekalkan untuk keserasian ke belakang.
Name
alpha_thumbnail_url
Type
string
Description
URL yang boleh dimuat turun untuk versi latar belakang lut sinar (RGBA) daripada thumbnail_url. Hanya wujud apabila tugas dicipta dengan alpha_thumbnail: true dan pratonton lut sinar berjaya dirender; jika tidak, medan ini akan ditinggalkan.
Name
thumbnail_urls
Type
object
Description
URL yang boleh dimuat turun untuk empat imej kecil pandangan kardinal bagi model 3D yang dihasilkan. Setiap nilai adalah URL bertandatangan untuk PNG 512×512 yang dirender dengan bahan dan pencahayaan yang sama seperti thumbnail_url. Berguna untuk melihat pratonton model dari pelbagai sudut dalam saluran paip kelompok (batch) tanpa memuat turun GLB.
Hanya wujud apabila tugas dicipta dengan multi_view_thumbnails: true dan telah mencapai SUCCEEDED. Tugas lama dan tugas yang dicipta tanpa pilihan sertai ini tidak akan menyertakan medan ini.
- Name
  front
  Type
  string
  Description
  Pandangan hadapan, putaran 0° pada 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
Teks prompt yang digunakan untuk membimbing proses pembuatan tekstur.
Name
texture_image_url
Type
string
Description
URL yang boleh dimuat turun untuk imej tekstur yang digunakan untuk membimbing proses pembuatan tekstur.
Name
ultra_mode
Type
boolean
⚠ lapuk
Description
Sudah lapuk; bacalah geometry_resolution sebagai gantinya.
Name
geometry_resolution
Type
string
Description
Peringkat Ultra yang dijalankan oleh tugas ini (2k atau 4k); ditinggalkan untuk standard.
Name
progress
Type
integer
Description
Progress tugas ini. Jika tugas belum bermula, sifat ini akan menjadi 0. Sebaik sahaja tugas berjaya, ini akan menjadi 100.
Name
started_at
Type
timestamp
Description
Cap masa bagi bila tugas ini dimulakan, dalam milisaat. Jika tugas belum bermula, sifat ini akan menjadi 0.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, menurut 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 bagi bila tugas ini dicipta, dalam milisaat.
Name
expires_at
Type
timestamp
Description
Cap masa bagi bila hasil tugas ini tamat tempoh, dalam milisaat.
Name
finished_at
Type
timestamp
Description
Cap masa bagi bila tugas ini selesai, dalam milisaat. Jika tugas belum selesai lagi, sifat ini akan menjadi 0.
Name
status
Type
string
Description
Status tugas ini. Nilai yang mungkin adalah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Suatu tatasusunan objek URL tekstur yang dihasilkan daripada tugas ini. Biasanya ini hanya mengandungi satu objek URL tekstur. Setiap URL tekstur mempunyai sifat berikut:
- Name
  base_color
  Type
  string
  Description
  URL yang boleh dimuat turun untuk imej peta warna asas.
- Name
  metallic
  Type
  string
  Description
  URL yang boleh dimuat turun untuk imej peta logam (metallic).
  Jika tugas ini dicipta dengan enable_pbr: false, sifat ini akan ditinggalkan.
- Name
  normal
  Type
  string
  Description
  URL yang boleh dimuat turun untuk imej peta normal.
  Jika tugas ini dicipta dengan enable_pbr: false, sifat ini akan ditinggalkan.
- Name
  roughness
  Type
  string
  Description
  URL yang boleh dimuat turun untuk imej peta kekasaran.
  Jika tugas ini dicipta dengan enable_pbr: false, sifat ini akan ditinggalkan.
- Name
  emission
  Type
  string
  Description
  URL yang boleh dimuat turun untuk imej peta pancaran (emission).
  Jika tugas ini dicipta dengan enable_pbr: false, atau ai_model adalah meshy-6-lite, meshy-7.1, atau latest, sifat ini akan ditinggalkan.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului.
Nilai medan ini hanya bermakna jika status tugas adalah PENDING.
Name
task_error
Type
object
Description
Perincian 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. Wujud apabila status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan semula apabila 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
}