API Tukar

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

POST/openapi/v1/convert

Cipta Tugas Tukar

Endpoint ini mencipta tugas penukaran format baharu.

Parameter

Hanya salah satu daripada input_task_id atau model_url adalah diperlukan. Jika kedua-duanya diberikan, input_task_id mengambil keutamaan.

Name
input_task_id
Type
string
Diperlukan
Description
ID bagi tugas Meshy yang telah selesai yang modelnya ingin anda tukar. Tugas tersebut mesti 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.

Mengembalikan

Sifat result dalam respons mengandungi id bagi tugas tukar yang baru dicipta.

Mod Kegagalan

400 - Bad Request

Permintaan tidak dapat diterima. Punca lazim:

Parameter hilang: Sama ada model_url atau input_task_id mesti diberikan.
target_formats hilang: Sekurang-kurangnya satu format sasaran mesti ditentukan.
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 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 Tugas Tukar

endpoint ini mendapatkan semula tugas tukar mengikut ID-nya.

Parameter

Name
id
Type
path
Description
ID tugas tukar yang hendak didapatkan semula.

Mengembalikan

Objek Tugas Tukar.

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

Parameter Laluan

Name
id
Type
path
Description
ID tugas tukar yang hendak dipadamkan.

Pulangan

Mengembalikan 200 OK apabila berjaya.

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

// Returns 200 Ok on success.

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 ialah 50 item.

Name
sort_by
Type
string
Description
Medan untuk diisih mengikut. Nilai yang tersedia:
- +created_at: Isih mengikut masa penciptaan dalam tertib menaik.
- -created_at: Isih mengikut masa penciptaan dalam tertib menurun.

Pulangan

Mengembalikan senarai berpenomboran 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

Strim Tugas Tukar

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

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas tukar yang akan distrim.

Mengembalikan

Mengembalikan strim Objek Tugas Tukar sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, strim respons hanya akan menyertakan 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 Tugasan Tukar

Objek Tugasan Tukar mewakili kerja penukaran format.

Sifat

id · rentetan

Pengecam unik untuk tugasan.

type · rentetan

Jenis tugasan. Nilainya ialah convert.

model_urls · objek

URL 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 tugasan (0-100).

status · rentetan

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

preceding_tasks · integer

Bilangan tugasan terdahulu. Bermakna hanya apabila status ialah PENDING.

created_at · cap masa

Cap masa apabila tugasan dicipta, dalam milisaat.

started_at · cap masa

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

finished_at · cap masa

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

task_error · objek

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

consumed_credits · integer

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