API Tukar

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

POST/openapi/v1/convert

Buat Tugas Tukar

Endpoint ini mencipta tugas penukaran format baru.

Parameter

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

Name
input_task_id
Type
string
Diperlukan
Description
ID tugas Meshy yang telah selesai yang modelnya anda ingin tukar. Tugas tersebut mesti mempunyai status SUCCEEDED.

Name
model_url
Type
string
Diperlukan
Description
URL atau Data URI yang boleh diakses secara umum yang menunjuk kepada fail model 3D. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl. Untuk Data URI, gunakan jenis MIME: 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

Properti result dalam respons mengandungi id tugas tukar yang baru dicipta.

Mod Kegagalan

400 - Bad Request

Permintaan tidak dapat diterima. Punca biasa:

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 mesti 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 periksa kunci API anda.

402 - Payment Required

Kredit tidak mencukupi untuk melaksanakan tugas ini.

429 - Too Many Requests

Anda telah melebihi had kadar anda.

Permintaan

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"]
  }'

Respons

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/convert/:id

Dapatkan Tugas Tukar

Endpoint ini mendapatkan tugas tukar berdasarkan ID-nya.

Parameter

Name
id
Type
path
Description
ID tugas tukar yang ingin didapatkan.

Pulangan

Objek Tugas Tukar.

Permintaan

GET

/openapi/v1/convert/:id

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

Respon

{
  "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 memadamkan tugas tukar secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh dipulihkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugas tukar untuk dipadamkan.

Pulangan

Mengembalikan 200 OK jika berjaya.

Permintaan

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}"

Respons

// Returns 200 Ok on success.

GET/openapi/v1/convert

Senarai Tugasan Tukar

Endpoint ini membolehkan anda mendapatkan senarai tugasan 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 50 item.

Name
sort_by
Type
string
Description
Medan untuk disusun. Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan dalam urutan menaik.
- -created_at: Susun mengikut masa penciptaan dalam urutan menurun.

Pulangan

Mengembalikan senarai berpenomboran halaman bagi Objek Tugasan Tukar.

Permintaan

GET

/openapi/v1/convert

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

Respons

[
  {
    "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

Strimkan Tugas Tukar

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

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas tukar yang hendak distrim.

Pulangan

Mengembalikan strim Objek Tugas Tukar sebagai Server-Sent Events.

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

Permintaan

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}"

Strim Respons

// 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 Tugasan Tukar

Objek Tugasan Tukar mewakili kerja penukaran format.

Ciri-ciri

id · string

Pengenal unik untuk tugasan.

type · string

Jenis tugasan. 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. Ciri format lain akan menjadi rentetan kosong.

progress · integer

Kemajuan tugasan (0-100).

status · string

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

preceding_tasks · integer

Bilangan tugasan terdahulu. Bermakna hanya apabila status adalah PENDING.

created_at · timestamp

Cap masa apabila tugasan dicipta, dalam milisaat.

started_at · timestamp

Cap masa apabila tugasan dimulakan, dalam milisaat. 0 jika tidak dimulakan.

finished_at · timestamp

Cap masa apabila tugasan selesai, dalam milisaat. 0 jika tidak selesai.

task_error · object

Objek ralat jika tugasan gagal. Lihat Ralat untuk maklumat lanjut.

consumed_credits · integer

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