API Tukar

API Tukar membolehkan anda menukar model 3D sedia ada kepada format fail yang berbeza.

POST/openapi/v1/convert

Create a Convert Task

Endpoint ini mencipta tugas penukaran format yang baharu.

Parameter

Hanya salah satu daripada input_task_id atau model_url yang diperlukan. Jika kedua-duanya disediakan, input_task_id diberi keutamaan.

  • Name
    input_task_id
    Type
    string
    Diperlukan
    Description

    ID bagi tugas Meshy yang telah selesai yang modelnya ingin anda tukar. Tugas tersebut mestilah mempunyai status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Diperlukan
    Description

    URL yang boleh diakses secara umum atau Data URI yang menunjuk kepada fail model 3D. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl. Untuk Data URI, gunakan MIME type: application/octet-stream.

  • Name
    target_formats
    Type
    string[]
    Diperlukan
    Description

    Senarai format output untuk model yang ditukar. Nilai yang tersedia: glb, fbx, obj, usdz, blend, stl, 3mf.

Pulangan

Sifat result bagi respons mengandungi id bagi tugas convert yang baharu dicipta.

Mod Kegagalan

  • 400 - Bad Request

Permintaan tidak boleh diterima. Punca lazim:

  • Parameter hilang: Sama ada model_url atau input_task_id mesti disediakan.
  • target_formats hilang: Sekurang-kurangnya satu format sasaran mesti dinyatakan.
  • Tugas input tidak sah: input_task_id mestilah merujuk kepada tugas yang berjaya.
  • Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
  • URL tidak dapat dicapai: model_url tidak dapat dimuat turun.
  • 401 - Unauthorized

Pengesahan gagal. Sila semak kunci API anda.

  • 402 - Payment Required

Kredit tidak mencukupi untuk melaksanakan tugas ini.

  • 429 - Too Many Requests

Anda telah melebihi had kadar anda.

Request

POST
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

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

Dapatkan Semula Tugas Convert

Endpoint ini mendapatkan semula tugas convert mengikut ID-nya.

Parameter

  • Name
    id
    Type
    path
    Description

    ID bagi tugas convert yang hendak didapatkan semula.

Nilai Pulangan

Objek Convert Task.

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}
DELETE/openapi/v1/convert/:id

Padam Tugas Tukar

Endpoint ini memadam tugas tukar secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh diterbalikkan.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    ID tugas tukar yang hendak dipadam.

Status Tugas

Tugas yang masih PENDING akan dipadam dan kredit yang digunakan semasa ia dicipta akan dikembalikan.

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

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

Pemulangan

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

Request

DELETE
/openapi/v1/convert/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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/convert

Senaraikan Tugas Tukar

Endpoint ini membolehkan anda mendapatkan senarai tugas tukar.

Parameter

  • Name
    page_num
    Type
    integer
    lalai 1
    Description

    Nombor halaman untuk penomboran halaman.

  • Name
    page_size
    Type
    integer
    lalai 10
    Description

    Had saiz halaman. Maksimum yang dibenarkan adalah 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.

Nilai Pulangan

Mengembalikan senarai bernomboran halaman bagi Objek Tugas Tukar.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]
GET/openapi/v1/convert/:id/stream

Alirkan Tugas Convert

Endpoint ini mengalirkan kemas kini masa nyata untuk tugas convert menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas convert yang hendak dialirkan.

Nilai Pulangan

Memulangkan aliran Objek Tugas Convert sebagai Server-Sent Events.

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

Request

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

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Objek Tugas Convert

Objek Tugas Convert mewakili satu tugas penukaran format.

Sifat-sifat

  • id · string

Pengenal unik untuk tugas tersebut.

  • type · string

Jenis tugas. Nilainya adalah convert.

  • model_urls · object

URL yang boleh dimuat turun untuk fail model yang telah ditukar. Hanya format yang dinyatakan dalam target_formats akan mempunyai URL. Sifat format lain akan menjadi rentetan kosong.

  • progress · integer

Progress tugas tersebut (0-100).

  • status · string

Status tugas tersebut. Nilai yang mungkin: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • preceding_tasks · integer

Bilangan tugas yang mendahului. Hanya bermakna apabila status adalah PENDING.

  • created_at · timestamp

Cap masa bila tugas tersebut dicipta, dalam milisaat.

  • started_at · timestamp

Cap masa bila tugas tersebut dimulakan, dalam milisaat. 0 jika belum dimulakan.

  • finished_at · timestamp

Cap masa bila tugas tersebut selesai, dalam milisaat. 0 jika belum selesai.

  • task_error · object

Objek ralat jika tugas tersebut gagal. Lihat Ralat untuk maklumat lanjut.

  • consumed_credits · integer

Bilangan kredit yang digunakan oleh tugas ini (1 kredit bagi setiap tugas convert). Mengembalikan 0 untuk tugas FAILED.