API Imej ke 3D

Tukar imej kepada model 3D, bertekstur atau tanpa tekstur, dalam format pilihan anda. Hantar imej, atau gunakan output daripada tugas Teks ke Imej atau Imej ke Imej.

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

Create an Image to 3D task

Mencipta tugas Imej ke 3D. Tugas berjalan di latar belakang. Untuk tempoh biasa sesuatu tugas, lihat Masa pemprosesan.

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
Diperlukan
Description
Diperlukan kecuali anda menghantar image_url. ID bagi tugas Teks ke Imej atau Imej ke Imej yang imejnya ingin anda gunakan sebagai input. Tugas tersebut mestilah yang anda cipta dengan API, mempunyai status SUCCEEDED, dan telah menghasilkan tepat satu imej.

Name
image_url
Type
string
Diperlukan
Description
Diperlukan kecuali anda menghantar input_task_id. Imej untuk ditukar menjadi model 3D, sebagai URL awam atau Data URI yang dikodkan base64, seperti data:image/jpeg;base64,<data imej anda yang dikodkan base64>. Jika anda menghantar kedua-duanya, Meshy menggunakan input_task_id.
Imej tersebut mestilah fail JPG, JPEG, PNG, atau WebP bersaiz maksimum 20 MB, sekurang-kurangnya 32 piksel pada setiap sisi, dan maksimum 178,956,970 piksel (lebar × tinggi).

Name
model_type
Type
string
lalai standard
Description
Jenis jejaring 3D yang hendak dijana.
Nilai yang tersedia:
- standard: jejaring berperincian tinggi
- smart-topology: jejaring daripada 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, dan hanya menerima topology: triangle.
Name
ai_model
Type
string
lalai latest
Description
Model AI yang menjana model 3D tersebut. Nilai yang tersedia bergantung pada model_type.
Model standard (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (lapuk): gunakan meshy-7.1 sebagai ganti
Model Smart Topology (model_type: smart-topology) menghasilkan segitiga, pada bilangan muka yang boleh anda tetapkan dengan target_polycount:
- meshy-t2: topology yang lebih bersih dan bahagian yang terasing secara semula jadi
- meshy-t2.5 (lalai): perincian yang lebih tajam untuk aset permainan
Name
geometry_resolution
Type
string
lalai standard
Description
Pas penjanaan geometri.
Nilai yang tersedia:
- standard
- 2k: menjalankan pas Ultra pada 2048³
- 4k: menjalankan pas Ultra pada 4096³, untuk perincian permukaan yang paling banyak
2k memerlukan meshy-7.1, latest, atau meshy-7 yang lapuk. 4k memerlukan meshy-7.1 atau latest.
Name
ultra_mode
Type
boolean
⚠ lapuk
lalai false
Description
Gunakan geometry_resolution sebagai ganti. ultra_mode: true adalah sama seperti geometry_resolution: "2k".
Name
should_texture
Type
boolean
lalai true
Description
Sama ada untuk menjana tekstur. true mengembalikan model bertekstur, dan false melangkau penteksturan dan mengembalikan jejaring tanpa tekstur.

Hanya berlaku apabila should_texture = true

Name
texture_model
Type
string
lalai bergantung pada ai_model
Description
Model AI yang menekstur model 3D tersebut, dalam tugas yang sama. Abaikan untuk menggunakan model tekstur lalai bagi ai_model anda. Ia tidak mengubah kos kredit.
Nilai yang tersedia:
- meshy-7: Meshy 7, dengan peta PBR dan tekstur sehingga 8K
- meshy-n1: Meshy N1, tekstur warna asas 2K hanya daripada imej rujukan
- meshy-6-lite: Meshy 6 Lite, tekstur 2K pada kos paling rendah
- meshy-6: Meshy 6, hanya sebagai lalai untuk ai_model: meshy-6
Setiap ai_model menerima meshy-7, meshy-n1, dan meshy-6-lite. Pilihan yang tidak disokong oleh model tekstur yang dipilih mengembalikan 400. Dengan meshy-n1, model yang dijana melebihi 7,999,999 segitiga menyebabkan tugas gagal, dan Meshy memulangkan kreditnya. Dengan should_texture: false, Meshy mengabaikan texture_model, tetapi nilai yang tidak dikenali tetap mengembalikan 400.
Lihat Models untuk apa yang dilakukan oleh setiap model tekstur dan yang mana hendak dipilih.
Name
enable_pbr
Type
boolean
lalai false
Description
Sama ada untuk turut menjana peta PBR (metallic, roughness, dan normal) selain warna asas. true memerlukan should_texture: true, dan mengembalikan 400 dengan should_texture: false. Dengan texture_model: meshy-n1, true mengembalikan 400.
Model tekstur Meshy 6 juga menjana peta emisi, kecuali pada texture_resolution: 8k.
Name
texture_resolution
Type
string
lalai 2k
Description
Saiz tekstur warna asas. Tekstur yang lebih besar menangkap lebih banyak perincian permukaan.
Nilai yang tersedia:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k dan 8k memerlukan model tekstur Meshy 7 atau Meshy 6, dan mengembalikan 400 dengan yang lain. Pada 8k, Meshy tidak menghasilkan peta emisi.
Name
hd_texture
Type
boolean
⚠ lapuk
lalai false
Description
Gunakan texture_resolution sebagai ganti. hd_texture: true adalah sama seperti texture_resolution: "4k". Jika anda menghantar kedua-duanya, Meshy menggunakan texture_resolution.
Name
texture_prompt
Type
string
Description
Teks yang membimbing tekstur, sehingga 800 aksara. Teks yang lebih panjang mengembalikan 400. Dengan texture_model: meshy-n1, menghantarnya mengembalikan 400.
Name
texture_image_url
Type
string
Description
Imej yang membimbing tekstur, sebagai URL awam atau Data URI yang dikodkan base64, seperti data:image/jpeg;base64,<data imej anda yang dikodkan base64>. Imej tersebut mestilah fail JPG, JPEG, PNG, atau WebP bersaiz maksimum 20 MB, sekurang-kurangnya 32 piksel pada setiap sisi, dan maksimum 178,956,970 piksel (lebar × tinggi).
Meshy membimbing tekstur dengan hanya satu daripada texture_prompt dan texture_image_url. Jika anda menghantar kedua-duanya, Meshy menggunakan texture_prompt. Untuk kos kredit bagi penteksturan, lihat Harga.
Dengan texture_model: meshy-n1, Meshy menekstur daripada imej ini sebagai pandangan depan, atau daripada imej input apabila anda mengabaikannya.
Penteksturan daripada imej mungkin tidak berfungsi dengan baik apabila bentuk imej berbeza jauh daripada geometri model 3D tersebut.

Name
should_remesh
Type
boolean
lalai true (meshy-6-lite), false (other models)
Description
Sama ada untuk menjalankan fasa remesh. Untuk model 3D berkualiti paling tinggi, tetapkan kepada false.

Hanya berlaku apabila should_remesh = true

Name
topology
Type
string
lalai triangle
Description
Jenis muka bagi model yang di-remesh.
Nilai yang tersedia:
- quad: jejaring dominan-quad
- triangle: jejaring segitiga yang dinyahkan (decimated)
Output Smart Topology hanya segitiga, jadi quad dengan meshy-t2 atau meshy-t2.5 mengembalikan 400. Dengan texture_model: meshy-n1, quad mengembalikan 400 apabila model di-remesh, yang dilakukan oleh meshy-6-lite secara lalai.
Name
decimation_mode
Type
integer
Description
Bilangan muka adaptif, mengikut tahap. Apabila anda menetapkannya, Meshy mengabaikan target_polycount.
Nilai yang tersedia:
- 1: ultra
- 2: tinggi
- 3: sederhana
- 4: rendah
Name
save_pre_remeshed_model
Type
boolean
lalai false
Description
Sama ada untuk turut menyimpan GLB bagi model sebelum fasa remesh. Meshy mengembalikannya dalam model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
Bilangan muka yang disasarkan. Hasilnya boleh berbeza daripada sasaran, bergantung pada geometri model tersebut.
Ia terpakai dalam dua kes berasingan:
- Remesh: Apabila should_remesh bernilai true pada model standard, Meshy menyahkan jejaring kepada kira-kira bilangan ini. Jika anda menetapkan decimation_mode, Meshy menggunakannya dan mengabaikan target_polycount.
- Smart Topology: Apabila model_type ialah smart-topology dan ai_model ialah meshy-t2 atau meshy-t2.5, Meshy menjana model pada bilangan muka ini. Tiada remesh dijalankan, dan anda tidak memerlukan should_remesh.
Julat dan nilai lalai bergantung pada kes:
Kes Julat Lalai
Remesh 100 hingga 300000 30000
meshy-t2 100 hingga 15000 4000
meshy-t2.5 100 hingga 30000 15000
Nilai di luar julat mengembalikan 400.

Kes	Julat	Lalai
Remesh	`100` hingga `300000`	`30000`
`meshy-t2`	`100` hingga `15000`	`4000`
`meshy-t2.5`	`100` hingga `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ lapuk
lalai auto
Description
Abaikan, kerana ia tidak menjejaskan output. Nilainya mengawal simetri semasa penjanaan:
- off: tiada simetri
- auto: simetri dipilih daripada geometri input
- on: simetri dikuatkuasakan
Name
pose_mode
Type
string
lalai ""
Description
Pose untuk model yang dijana.
Nilai yang tersedia:
- a-pose: pose A
- t-pose: pose T
- "" (rentetan kosong): tiada pose khusus
Name
is_a_t_pose
Type
boolean
⚠ lapuk
lalai false
Description
Gunakan pose_mode sebagai ganti. Sama ada untuk menjana model dalam pose A atau T.
Name
surface_mode
Type
string
⚠ lapuk
Description
Gunakan ai_model sebagai ganti. Ia tidak menjejaskan output, kerana penjanaan model yang dipilihnya telah dihentikan.
Nilai yang diterima ialah organic dan hard. Sebarang nilai lain mengembalikan 400.
Name
image_enhancement
Type
boolean
lalai true
Description
Sama ada untuk mengoptimumkan imej input sebelum penjanaan. false mengekalkan penampilan tepat imej input, tanpa sebarang pemprosesan gaya.
Ia hanya berfungsi dengan meshy-6, meshy-7.1, atau latest. Dengan meshy-6-lite atau model_type: smart-topology, ia mengembalikan 400.
Name
remove_lighting
Type
boolean
lalai true
Description
Sama ada untuk mengalih keluar sorotan (highlight) dan bayang daripada tekstur warna asas. Hasilnya lebih bersih dan berfungsi lebih baik di bawah pencahayaan anda sendiri.
Ia berkuat kuasa hanya dengan model tekstur Meshy 6, dan model tekstur yang tidak menyokongnya mengembalikan 400 untuk true. Dengan model_type: smart-topology, atau dengan ai_model: meshy-6-lite dan model tekstur lalainya, menghantarnya mengembalikan 400.
Name
moderation
Type
boolean
lalai false
Description
Sama ada untuk menapis input ini bagi kandungan berbahaya sebelum penjanaan:
- image_url
- texture_image_url
- texture_prompt
Jika Meshy mengesan kandungan berbahaya, permintaan mengembalikan 400 dan Meshy tidak mencipta tugas.
Name
target_formats
Type
string[]
Description
Format fail yang hendak dijana. Meshy menjana dan mengembalikan hanya format yang anda senaraikan, yang boleh memendekkan tugas tersebut. Jika anda mengabaikannya, Meshy menjana setiap format kecuali 3mf, yang hanya anda dapat apabila anda menyenaraikannya.
Nilai yang tersedia:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
lalai false
Description
Sama ada untuk menganggarkan ketinggian sebenar objek dengan penglihatan AI dan mengubah saiz model mengikutnya. Meshy meletakkan titik asal di bahagian bawah kecuali anda menetapkan origin_at.
Name
alpha_thumbnail
Type
boolean
lalai false
Description
Sama ada untuk turut menghasilkan pratonton dengan latar belakang lutsinar (RGBA), dikembalikan dalam alpha_thumbnail_url apabila anda mendapatkan tugas tersebut. thumbnail_url tidak berubah.
Name
multi_view_thumbnails
Type
boolean
lalai false
Description
Sama ada untuk turut menghasilkan pratonton depan, kanan, belakang, dan kiri, dikembalikan dalam thumbnail_urls apabila anda mendapatkan tugas tersebut. thumbnail_url tidak berubah dan masih menunjukkan pandangan depan. Ini menambah kira-kira 5 saat kepada tugas tersebut.

Hanya berlaku apabila auto_size = true

Name
origin_at
Type
string
lalai bottom
Description
Di mana hendak meletakkan titik asal model, bottom atau center.

Pulangan

Medan result bagi respons tersebut memegang ID bagi tugas Imej ke 3D yang baharu.

Mod kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Mesej ralat menyatakan masalah yang ditemuinya. Sebagai contoh:
- Parameter hilang: Sama ada image_url atau input_task_id tidak dihantar.
- Tugas input tidak sah: input_task_id bukan tugas Teks ke Imej atau Imej ke Imej yang berstatus SUCCEEDED yang menghasilkan tepat satu imej.
- Format imej tidak sah: Imej image_url bukan fail JPG, JPEG, PNG, atau WebP.
- URL tidak boleh dicapai: Meshy tidak dapat memuat turun imej image_url, kerana URL tersebut mengembalikan 404 atau tamat masa.
- Imej terlalu besar: Imej image_url atau texture_image_url melebihi 20 MB.
- Saiz imej tidak sah: Imej image_url atau texture_image_url mempunyai sisi yang lebih pendek daripada 32 piksel, atau melebihi 178,956,970 piksel (lebar × tinggi).
- Data URI tidak sah: Rentetan base64 tersebut cacat.
- Kombinasi parameter tidak sah: enable_pbr bernilai true, dan should_texture bernilai false.
- Model tidak disokong untuk Ultra: geometry_resolution bernilai 2k atau 4k, dengan ai_model yang tidak dapat menjalankannya.
- Model tidak disokong untuk pilihan imej: salah satu daripada ini:
  - image_enhancement dihantar dengan ai_model: "meshy-6-lite" atau model_type: "smart-topology".
  - remove_lighting dihantar dengan model_type: "smart-topology", atau dengan ai_model: "meshy-6-lite" dan model tekstur lalainya.
- Model tekstur tidak sah: texture_model bukan salah satu nilai yang tersedia.
- Model tekstur tidak tersedia: texture_model ialah meshy-6 dengan ai_model selain meshy-6. Hantar meshy-7, meshy-n1, atau meshy-6-lite, atau abaikan sahaja.
- Pilihan tidak disokong untuk model tekstur: Permintaan meminta model tekstur untuk pilihan yang tidak disokongnya, seperti enable_pbr: true dengan meshy-n1 atau tekstur 4k dengan meshy-6-lite. Lihat Models.
Betulkan permintaan, kemudian hantar semula. Lihat Ralat.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak sah. Semak header Authorization.
Name
402 - Payment Required
Description
Sebagai contoh:
- Kredit tidak mencukupi: Akaun tidak mempunyai kredit yang mencukupi untuk tugas ini, atau akaun telah mencapai had kredit. Semak baki kredit anda, kemudian cuba semula.
- Pelan percuma: Mencipta tugas memerlukan pelan berbayar. Naik taraf pelan anda dalam tetapan langganan anda, kemudian cuba semula.
Name
403 - Forbidden
Description
Moderation kandungan menyekat prompt atau imej input. Tukar input tersebut, kemudian cuba semula.
Name
404 - Not Found
Description
input_task_id tidak sepadan dengan mana-mana tugas anda. Semak ID tugas tersebut, kemudian hantar semula permintaan.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda. Tunggu, kemudian cuba semula. Lihat Had kadar.

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

Dapatkan tugas Imej ke 3D

Mengembalikan tugas Imej 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 daripada respons penciptaan.

Pulangan

Objek tugas Imej ke 3D.

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

Padam tugas Imej ke 3D

Memadam secara kekal tugas Imej ke 3D, termasuk model dan datanya. Anda tidak boleh membatalkan pemadaman.

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 laluan

Name
id
Type
path
Description
ID tugas yang hendak dipadam.

Status tugas

Memadam tugas PENDING akan memulangkan kredit yang digunakan semasa anda mencipta tugas tersebut.

Tugas IN_PROGRESS tidak boleh dipadam. Permintaan akan mengembalikan 409 Conflict, dan tugas tersebut terus berjalan. Meshy tidak memulangkan kredit untuk tugas yang telah bermula, jadi memadamnya akan merugikan anda kedua-dua kredit dan hasilnya. Tunggu sehingga ia mencapai SUCCEEDED, FAILED, atau CANCELED, kemudian padamkannya.

Memadam tugas yang berada dalam status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak memulangkan kreditnya.

Pulangan

200 OK apabila tugas berjaya dipadam, atau 409 Conflict apabila tugas berstatus IN_PROGRESS.

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

Senarai tugas Imej ke 3D

Mengembalikan senarai tugas Imej 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
lalai 1
Description
Nombor halaman yang hendak dikembalikan, sehingga 255. Nilai yang lebih besar akan mengembalikan 400.
Name
page_size
Type
integer
lalai 10
Description
Bilangan tugas setiap halaman, sehingga 100.
Name
sort_by
Type
string
Description
Susunan isihan.
Nilai yang tersedia:
- +created_at: paling lama dahulu
- -created_at: paling baharu dahulu

Mengembalikan

Senarai berhalaman bagi objek tugas Imej ke 3D.

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

Strim tugas Imej ke 3D

Menstrim kemas kini tugas Imej 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 daripada respons create.

Hasil

Satu strim objek tugas Imej ke 3D sebagai Server-Sent Events.

Setiap event memegang objek tugas yang lengkap, dalam bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Semasa tugas masih PENDING atau IN_PROGRESS, medan hasilnya belum lagi mempunyai nilai.

Objek tugas Imej ke 3D

Objek tugas Imej ke 3D menerangkan satu penjanaan model 3D daripada imej. Ia menyimpan status, progress, dan fail model apabila tugas berjaya.

Ciri-ciri

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 tugas. Anggap ia sebagai rentetan buram, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, sentiasa image-to-3d.
Name
model_urls
Type
object
Description
URL muat turun untuk model 3D yang dijana, satu bagi setiap format fail. Format yang tidak dijana oleh tugas tidak mempunyai kunci, berbanding rentetan kosong.
- Name
  glb
  Type
  string
  Description
  Fail GLB.
- Name
  fbx
  Type
  string
  Description
  Fail FBX.
- Name
  obj
  Type
  string
  Description
  Fail OBJ.
- Name
  usdz
  Type
  string
  Description
  Fail USDZ.
- Name
  mtl
  Type
  string
  Description
  Fail MTL, dikembalikan bersama fail OBJ apabila model mempunyai tekstur.
- Name
  stl
  Type
  string
  Description
  Fail STL.
- Name
  3mf
  Type
  string
  Description
  Fail 3MF. Hanya hadir apabila target_formats termasuk 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Fail GLB sebelum remesh. Hanya hadir apabila anda mencipta tugas dengan kedua-dua should_remesh: true dan save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL muat turun untuk imej pratonton model 3D. Apabila thumbnail_urls hadir, ia adalah imej yang sama dengan thumbnail_urls.front. Meshy mengekalkannya untuk keserasian ke belakang.
Name
alpha_thumbnail_url
Type
string
Description
URL muat turun untuk versi thumbnail_url dengan latar belakang lutsinar (RGBA). Hanya hadir apabila anda mencipta tugas dengan alpha_thumbnail: true dan Meshy menjana pratonton lutsinar tersebut.
Name
thumbnail_urls
Type
object
Description
URL muat turun untuk pratonton model 3D dari empat sisi. Setiap nilai ialah URL bertandatangan kepada PNG 512×512, dijanakan dengan bahan dan pencahayaan yang sama seperti thumbnail_url. Gunakannya untuk pratonton model dari pelbagai sudut, contohnya dalam saluran paip kelompok, tanpa memuat turun GLB.
Hanya hadir apabila anda mencipta tugas dengan multi_view_thumbnails: true dan tugas mencapai SUCCEEDED. Tugas yang dicipta tanpa multi_view_thumbnails: true tidak termasuk medan ini.
- Name
  front
  Type
  string
  Description
  Pandangan depan, pada 0° sekitar paksi menegak. Ia sepadan dengan thumbnail_url.
- Name
  right
  Type
  string
  Description
  Pandangan kanan, pada 90°.
- Name
  back
  Type
  string
  Description
  Pandangan belakang, pada 180°.
- Name
  left
  Type
  string
  Description
  Pandangan kiri, pada 270°.
Name
texture_prompt
Type
string
Description
Prompt teks yang memandu tekstur.
Name
texture_image_url
Type
string
Description
URL muat turun untuk imej yang memandu tekstur.
Name
ultra_mode
Type
boolean
⚠ lapuk
Description
Baca geometry_resolution sebaliknya.
Name
geometry_resolution
Type
string
Description
Peringkat Ultra yang dijalankan oleh tugas, 2k atau 4k. Tugas standard tidak termasuk medan ini.
Name
progress
Type
integer
Description
Berapa banyak tugas yang telah selesai, sebagai peratusan. Ia adalah 0 sehingga tugas bermula dan 100 apabila ia berjaya.
Name
started_at
Type
timestamp
Description
Masa tugas bermula, dalam milisaat Unix. Ia adalah 0 sehingga tugas bermula.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
expires_at
Type
timestamp
Description
Masa hasil tugas tamat tempoh, dalam milisaat Unix.
Name
finished_at
Type
timestamp
Description
Masa tugas selesai, dalam milisaat Unix. Ia adalah 0 sehingga tugas selesai.
Name
status
Type
string
Description
Status tugas, salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
texture_urls
Type
array
Description
Peta tekstur yang dijana oleh tugas, sebagai tatasusunan objek. Ia biasanya menyimpan satu objek, dengan medan-medan ini:
- Name
  base_color
  Type
  string
  Description
  URL muat turun untuk peta warna asas.
- Name
  metallic
  Type
  string
  Description
  URL muat turun untuk peta metalik. Medan ini tiada apabila anda mencipta tugas dengan enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  URL muat turun untuk peta normal. Medan ini tiada apabila anda mencipta tugas dengan enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  URL muat turun untuk peta kekasaran. Medan ini tiada apabila anda mencipta tugas dengan enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  URL muat turun untuk peta pancaran. Meshy hanya menyertakannya apabila anda mencipta tugas dengan kesemua perkara berikut:
  
  ai_model: meshy-6, dengan model tekstur lalainya
  
  enable_pbr: true
  
  texture_resolution sebanyak 2k atau 4k
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului tugas ini dalam baris gilir. Nilai ini hanya bermakna semasa tugas berada dalam status PENDING.
Name
task_error
Type
object
Description
Butiran ralat apabila tugas gagal. Ia adalah null melainkan statusnya FAILED. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas. Hadir apabila status adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Ia adalah 0 bagi tugas FAILED, kerana Meshy memulangkan semula kredit apabila tugas gagal.