API Cetakan Pelbagai Warna

Tukar model 3D kepada format 3MF pelbagai warna untuk pencetakan 3D, dengan palet warna boleh dikonfigurasi sehingga 16 warna.

Cipta Tugas Cetakan 3D Berbilang Warna

Endpoint ini mencipta tugas cetakan 3D berbilang warna yang baharu. Tugas ini menukar model 3D kepada fail 3MF berbilang warna yang sesuai untuk pencetakan 3D.

Parameter

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

  • Name
    model_url
    Type
    string
    Diperlukan
    Description

    URL yang boleh diakses secara umum atau Data URI bagi model 3D. Kami kini menyokong format .glb dan .fbx.

  • Name
    max_colors
    Type
    integer
    lalai 4
    Description

    Bilangan maksimum warna dalam palet output.

    Julat sah: 1 hingga 16.

  • Name
    style
    Type
    string
    lalai realistic
    Description

    Gaya warna visual bagi fail 3MF yang dihasilkan.

    Nilai yang tersedia:

    • realistic: Mengambil sampel warna terus daripada tekstur model untuk perincian yang halus dan realistik seperti foto. Menghasilkan fail yang lebih besar.
    • cartoon: Meratakan warna kepada kawasan yang bersih dan seragam untuk penampilan bergaya. Menghasilkan fail yang lebih kecil.

    Input mesti membawa warna: realistic memerlukan satu tekstur warna asas dengan koordinat UV pada setiap bahagian jejaring; cartoon juga menerima warna setiap-verteks. Model tanpa tekstur (putih) akan ditolak — lihat model_missing_texture.

Nilai Pulangan

Sifat result bagi respons mengandungi id bagi tugas cetakan 3D yang baharu dicipta.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Punca biasa:

    • Parameter hilang: Sama ada model_url atau input_task_id mesti diberikan.
    • Format model tidak sah: model_url merujuk kepada fail dengan sambungan yang tidak disokong (hanya .glb dan .fbx disokong).
    • URL tidak dapat dicapai: model_url tidak dapat dimuat turun.
    • Tugas input tidak sah: input_task_id mesti merujuk kepada tugas yang berjaya.
    • max_colors tidak sah: Nilai mesti antara 1 dan 16.
    • style tidak sah: Nilai mesti realistic atau cartoon.
    • Tiada sumber warna: Model input tidak mempunyai tekstur warna asas (realistic memerlukan satu, dengan UV, pada setiap bahagian jejaring) dan tiada warna verteks (cartoon menerima kedua-duanya). Berikan tekstur pada model terlebih dahulu, atau gunakan cartoon untuk model berwarna verteks. Muat naik .fbx diperiksa selepas tugas menormalkannya dan akan gagal dengan model_missing_texture sebaliknya.
  • Name
    401 - Unauthorized
    Description

    Pengesahan gagal. Sila semak kunci API anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melaksanakan tugas ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi had kadar anda.

Request

POST
/openapi/v1/print/multi-color
# Convert a 3D model to multi-color 3MF for printing
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/multi-color/:id

Dapatkan Semula Tugas Cetakan 3D Berbilang Warna

Endpoint ini mendapatkan semula tugas cetakan 3D berbilang warna berdasarkan ID-nya.

Parameter

  • Name
    id
    Type
    path
    Description

    ID tugas cetakan 3D yang hendak didapatkan semula.

Pemulangan

Objek Tugas Cetakan 3D.

Request

GET
/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}
DELETE/openapi/v1/print/multi-color/:id

Padam Tugas Cetakan 3D Pelbagai Warna

Endpoint ini memadam secara kekal tugas cetakan 3D pelbagai warna, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh diundur.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    ID tugas cetakan 3D pelbagai warna yang hendak dipadam.

Status Tugas

Tugas yang masih PENDING akan dipadam dan kredit yang digunakan pada masa penciptaan akan dikembalikan.

Tugas yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugas itu akan terus berjalan. Kredit untuk tugas yang telah pun dimulakan oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugas yang berada dalam keadaan terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

Pemulangan

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

Request

DELETE
/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -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/print/multi-color

Senaraikan Tugas Cetakan 3D Multi-Warna

Endpoint ini membolehkan anda mendapatkan senarai tugas cetakan 3D multi-warna.

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 isih mengikut. Nilai yang tersedia:

    • +created_at: Isih mengikut masa penciptaan secara menaik.
    • -created_at: Isih mengikut masa penciptaan secara menurun.

Pemulangan

Memulangkan senarai berhalaman Objek Tugas Cetakan 3D.

Request

GET
/openapi/v1/print/multi-color
curl https://api.meshy.ai/openapi/v1/print/multi-color?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]
GET/openapi/v1/print/multi-color/:id/stream

Alirkan Tugas Cetakan 3D Berbilang Warna

Endpoint ini mengalirkan kemas kini masa nyata untuk tugas cetakan 3D berbilang warna menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugas cetakan 3D berbilang warna yang hendak dialirkan.

Pemulangan

Memulangkan aliran Objek Tugas Cetakan 3D sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan mengandungi medan progress dan status yang diperlukan.

Request

GET
/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

Objek Tugas Cetakan 3D

  • Name
    id
    Type
    string
    Description

    Pengecam unik untuk tugas tersebut. Walaupun kami menggunakan UUID yang boleh disusun-k (k-sortable) untuk id tugas sebagai butiran pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis tugas Cetakan 3D. Nilainya adalah print-multi-color.

  • Name
    model_urls
    Type
    object
    Description

    URL yang boleh dimuat turun untuk fail model 3D yang dijana oleh Meshy. Sifat untuk sesuatu format akan diabaikan jika format itu tidak dijana, dan bukannya mengembalikan rentetan kosong.

    • Name
      3mf
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail 3MF pelbagai warna.

  • Name
    progress
    Type
    integer
    Description

    Progress tugas tersebut. Jika tugas belum dimulakan, sifat ini akan menjadi 0. Sebaik sahaja tugas berjaya, ia akan menjadi 100.

  • Name
    status
    Type
    string
    Description

    Status tugas tersebut. Nilai yang mungkin adalah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugas yang mendahului.

    Nilai medan ini hanya bermakna jika status tugas adalah PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa bila tugas tersebut dicipta, dalam milisaat.

  • Name
    started_at
    Type
    timestamp
    Description

    Cap masa bila tugas tersebut dimulakan, dalam milisaat. Jika tugas belum dimulakan lagi, sifat ini akan menjadi 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa bila tugas tersebut selesai, dalam milisaat. Jika tugas belum selesai lagi, sifat ini akan menjadi 0.

  • Name
    task_error
    Type
    object
    Description

    Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan lengkap 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).

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}