API Tukar

Tukar model 3D kepada format fail lain, daripada tugasan Meshy atau daripada fail model.

POST/openapi/v1/convert

Cipta tugasan Convert

Mencipta tugasan Convert. Tugasan berjalan di latar belakang. Untuk tempoh biasa sesuatu tugasan, lihat Masa pemprosesan.

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

Parameter

Name
input_task_id
Type
string
Diperlukan
Description
Diperlukan kecuali anda menghantar model_url. ID bagi tugasan yang menghasilkan model 3D, contohnya tugasan Teks ke 3D, Imej ke 3D, Remesh, Ubah saiz, atau Retekstur. Tugasan itu mesti berasal daripada API dan berstatus SUCCEEDED.

Name
model_url
Type
string
Diperlukan
Description
Diperlukan kecuali anda menghantar input_task_id. Model yang hendak ditukar, sebagai URL awam atau data URI. Jika anda menghantar kedua-duanya, Meshy menggunakan input_task_id.
Model itu mestilah fail GLB, glTF, OBJ, FBX, atau STL bersaiz maksimum 400 MB daripada URL http atau https, atau 100 MB sebagai data URI. Untuk data URI, gunakan MIME type application/octet-stream.
Fail yang melebihi 100 MB juga mesti mematuhi peraturan berikut:
- Fail GLB, glTF, FBX, atau OBJ boleh mempunyai sehingga 10,000,000 muka sahaja. Meshy mengira muka sebagai segi tiga, jadi segi empat dikira sebagai 2, dan jejaring yang dilukis lebih daripada sekali dikira sekali bagi setiap salinan.
- Fail FBX mesti dalam bentuk binari FBX 7.1 atau lebih baharu.
- Fail GLB atau glTF tidak boleh menggunakan pemampatan Draco.

Name
target_formats
Type
string[]
Diperlukan
Description
Format fail yang akan dijana. Senaraikan sekurang-kurangnya satu. Senarai yang kosong atau tiada akan mengembalikan 400.
Nilai yang tersedia:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Nilai pulangan

Medan result dalam respons menyimpan ID bagi tugasan Convert yang baharu.

Mod kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Mesej ralat menyatakan masalah yang dijumpai. Contohnya:
- Parameter hilang: Baik model_url mahupun input_task_id tidak dihantar.
- target_formats hilang: target_formats hilang atau tidak menyenaraikan sebarang format.
- Tugasan input tidak sah: input_task_id bukan tugasan API yang berjaya dengan fail model.
- Format model tidak sah: Fail model_url mempunyai sambungan yang tidak disokong.
- URL tidak dapat dicapai: Meshy tidak dapat memuat turun fail model_url.
- Fail model terlalu besar: Fail model_url melebihi 400 MB daripada URL http atau https, atau melebihi 100 MB sebagai data URI.
- Terlalu banyak muka: Fail model_url melebihi 100 MB dan mempunyai lebih daripada 10,000,000 muka. Kurangkan bilangan muka, kemudian hantar semula fail tersebut.
- FBX ASCII melebihi 100 MB: Fail model_url ialah FBX ASCII yang melebihi 100 MB. Hantar sebagai FBX binari atau GLB.
- Fail model tidak boleh dibaca: Fail model_url melebihi 100 MB, dan Meshy tidak dapat membaca pengepalanya. Contohnya, ia adalah GLB atau glTF yang dimampatkan Draco, atau FBX binari yang lebih lama daripada 7.1.
- Pengepala model terlalu kompleks: Fail model_url melebihi 100 MB, dan pengepalanya mempunyai terlalu banyak jejaring, nod, atau rekod untuk disemak. Kurangkan bilangan objek dalam fail, kemudian hantar semula.
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
Contohnya:
- Kredit tidak mencukupi: Akaun tidak mempunyai kredit yang mencukupi untuk tugasan ini, atau akaun telah mencapai had kredit. Semak baki kredit anda, kemudian cuba semula.
- Pelan percuma: Mencipta tugasan memerlukan pelan berbayar. Naik taraf pelan anda di tetapan langganan anda, kemudian cuba semula.
Name
403 - Forbidden
Description
input_task_id ialah model relief rendah, yang tidak dapat ditukar oleh endpoint ini. Mesejnya ialah This model type does not support this operation. Hantar model yang lain.
Name
404 - Not Found
Description
input_task_id tidak sepadan dengan mana-mana tugasan anda. Semak ID tugasan, 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/convert/:id

Dapatkan tugas Convert

Mengembalikan tugas Convert berdasarkan ID-nya.

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

Parameter

Name
id
Type
path
Description
ID tugas daripada respons pembuatan.

Kembalian

Objek tugas Convert.

DELETE/openapi/v1/convert/:id

Padam tugas Convert

Memadam tugas Convert secara kekal, termasuk model dan datanya. Anda tidak boleh membatalkan tindakan padam.

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 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 semula kredit yang digunakan semasa anda mencipta tugas tersebut.

Tugas IN_PROGRESS tidak boleh dipadam. Permintaan akan mengembalikan 409 Conflict, dan tugas itu terus berjalan. Meshy tidak memulangkan semula kredit bagi tugas yang telah bermula, jadi memadamnya akan menyebabkan anda rugi kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED, atau CANCELED, barulah padamkannya.

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

Pulangan

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

GET/openapi/v1/convert

Senaraikan tugas Convert

Mengembalikan senarai tugas Convert anda.

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

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

Nilai Pulangan

Senarai berhalaman bagi objek tugas Convert.

GET/openapi/v1/convert/:id/stream

Alirkan Tugas Convert

Mengalirkan kemas kini tugas Convert sebagai Server-Sent Events (SSE).

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
}

Parameter

Name
id
Type
path
Description
ID tugas daripada respons create.

Returns

Aliran objek tugas Convert sebagai Server-Sent Events.

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

The Convert task object

Objek tugas Convert menerangkan satu penukaran format bagi model 3D. Ia menyimpan status, progress, dan fail model apabila tugas berjaya.

Properties

Name
id
Type
string
Description
ID tugas. Anggap ia sebagai string legap, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, sentiasa convert.
Name
model_urls
Type
object
Description
URL muat turun untuk model yang ditukar, satu bagi setiap format fail. Hanya format dalam target_formats mempunyai URL. Format yang tidak anda minta tiada kunci, bukannya string kosong.
Name
progress
Type
integer
Description
Berapa banyak bahagian tugas yang telah selesai, dalam peratusan. Nilainya 0 sehingga tugas bermula dan 100 apabila ia berjaya.
Name
status
Type
string
Description
Status tugas, salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas di hadapan tugas ini dalam baris gilir. Nilai ini hanya bermakna semasa tugas berstatus PENDING.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
started_at
Type
timestamp
Description
Masa tugas bermula, dalam milisaat Unix. Nilainya 0 sehingga tugas bermula.
Name
finished_at
Type
timestamp
Description
Masa tugas selesai, dalam milisaat Unix. Nilainya 0 sehingga tugas selesai.
Name
expires_at
Type
timestamp
Description
Masa URL muat turun tugas tamat tempoh, dalam milisaat Unix. Nilainya 0 sehingga tugas selesai.
Name
texture_urls
Type
array
Description
URL muat turun untuk peta tekstur model, apabila tugas berjaya: satu tatasusunan objek, satu bagi setiap set tekstur. Setiap objek mempunyai URL base_color, dan juga boleh mempunyai URL metallic, roughness, normal, emission, dan metallic_roughness. Nilainya null sehingga tugas berjaya, dan tatasusunan kosong apabila model tiada peta tekstur.
Name
task_error
Type
object
Description
Butiran ralat apabila tugas gagal. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas, iaitu 1 bagi tugas Tukar. Nilainya 0 bagi tugas FAILED.