API Rigging

Tambah rangka (rangka) pada model 3D humanoid dan ikat jejaring kepadanya, supaya watak sedia untuk dianimasikan. Untuk menggunakan animasi pada watak yang telah dirig, lihat API Animasi.

Rigging hanya berfungsi dengan baik untuk watak humanoid (berkaki dua) piawai yang mempunyai struktur anggota badan dan tubuh yang jelas.

POST/openapi/v1/rigging

Cipta tugas Rigging

Mencipta tugas Rigging untuk model 3D. Apabila tugas berjaya, ia mengembalikan watak yang telah di-rig dalam format standard dan, secara pilihan, animasi berjalan dan berlari asas.

Tugas ini berjalan di latar belakang. Untuk tempoh biasa bagi sesuatu tugas, lihat Masa pemprosesan.

Rigging tidak sesuai untuk model-model berikut:

Jejaring tanpa tekstur
Aset bukan humanoid
Aset humanoid dengan struktur anggota badan dan tubuh yang tidak jelas

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

Parameter

Name
input_task_id
Type
string
Diperlukan
Description
Diperlukan kecuali anda menghantar model_url. ID bagi tugas yang modelnya ingin anda rig. Meshy menyokong model humanoid bertekstur.
Model boleh mempunyai paling banyak 380,000 segi tiga (satu quad dikira sebagai 2), dan model dengan lebih daripada itu mengembalikan 400. Untuk kekal di bawah had tersebut, jalankan API Remesh ke atasnya terlebih dahulu dengan target_polycount sebanyak 300000 atau kurang, atau 150000 atau kurang dengan topology: quad.

Name
model_url
Type
string
Diperlukan
Description
Diperlukan kecuali anda menghantar input_task_id. Model untuk di-rig, sama ada sebagai URL awam atau data URI. Jika anda menghantar kedua-duanya, Meshy menggunakan input_task_id.
Model mestilah fail GLB (.glb) tidak melebihi 400 MB daripada URL http atau https, atau 100 MB sebagai data URI. Rigging menyokong model humanoid bertekstur.
Model boleh mempunyai paling banyak 380,000 segi tiga (satu quad dikira sebagai 2), dan model dengan lebih daripada itu mengembalikan 400. Untuk kekal di bawah had tersebut, jalankan API Remesh ke atasnya terlebih dahulu dengan target_polycount sebanyak 300000 atau kurang, atau 150000 atau kurang dengan topology: quad.
Wajah watak mestilah menghadap ke paksi +Z, iaitu arah hadapan standard glTF. Anggaran pose akan gagal untuk model yang menghadap paksi lain.
Fail yang melebihi 100 MB juga mesti mematuhi peraturan berikut:
- Ia boleh mempunyai paling banyak 10,000,000 muka. Fail dengan lebih daripada itu mengembalikan 400. Meshy mengira muka sebagai segi tiga, dan jejaring yang dilukis lebih daripada sekali dikira sekali bagi setiap salinan.
- Ia tidak boleh menggunakan pemampatan Draco.

Name
height_meters
Type
number
lalai 1.7
Description
Anggaran ketinggian watak, dalam meter. Meshy menggunakannya untuk menskalakan dan merig model dengan lebih tepat. Nilai negatif mengembalikan 400.
Name
texture_image_url
Type
string
⚠ lapuk
Description
Tinggalkan ia apabila model mempunyai tekstur sendiri. Tanpanya, Meshy menggunakan tekstur yang terbenam dalam fail model_url, atau tekstur tugas input. Jika anda menghantarnya, imej ini menjadi satu-satunya tekstur model yang di-rig, dan model kehilangan peta PBR miliknya.
Tekstur warna asas model yang dibentangkan UV (UV-unwrapped), sebagai URL awam atau data URI. Imej mestilah fail PNG tidak melebihi 20 MB. Format imej lain mengembalikan 400.

Pulangan

Medan result bagi respons menyimpan ID bagi tugas Rigging yang baharu.

Mod kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Mesej ralat menyatakan masalah yang ditemui. Contohnya:
- Parameter hilang: Sama ada model_url atau input_task_id tidak dihantar.
- Format model tidak sah: Fail model_url mempunyai sambungan yang tidak disokong. Hanya .glb 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.
- Fail model tidak boleh dibaca: Fail model_url melebihi 100 MB, dan Meshy tidak dapat membaca pengepalanya. Contohnya, ia adalah GLB yang dimampatkan Draco.
- 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.
- Imej terlalu besar: Imej texture_image_url melebihi 20 MB.
- Format tekstur tidak sah: Imej texture_image_url bukan fail PNG.
- Ketinggian tidak sah: height_meters adalah negatif.
- Tugas input tidak sah: input_task_id tidak merujuk kepada tugas API yang sah.
- Tugas input belum sedia: Tugas input_task_id belum mencapai SUCCEEDED. Tunggu sehingga ia berjaya, kemudian cuba semula.
- Bilangan muka melebihi had: Model input mempunyai lebih daripada 380,000 segi tiga (satu quad dikira sebagai 2). Jalankan API Remesh ke atasnya dengan target_polycount sebanyak 300000 atau kurang, atau 150000 atau kurang dengan topology: quad, sebelum anda merig model tersebut.
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 cukup untuk tugas ini, atau akaun telah mencapai had kredit. Semak baki kredit anda, kemudian cuba semula.
- Pelan percuma: Mencipta tugas memerlukan pelan berbayar. Naik taraf pelan anda dalam tetapan langganan anda, kemudian cuba semula.
Name
403 - Forbidden
Description
input_task_id adalah model bas-relief, yang tidak dapat di-rig oleh endpoint ini. Mesejnya ialah This model type does not support this operation. Hantar model yang lain.
Name
404 - Not Found
Description
Meshy tidak dapat mencari fail bagi tugas input_task_id. Salah satu daripada yang berikut berlaku:
- Meshy memadam fail tugas tersebut selepas expires_at miliknya. Cipta semula tugas tersebut, kemudian hantar ID tugas itu.
- Tugas tersebut tidak mempunyai mana-mana fail yang diperlukan oleh rigging, seperti imej pratonton, contohnya tugas Convert. Rig tugas asal dari mana ia berasal, atau hantar model sebagai model_url.
Name
422 - Unprocessable Entity
Description
Anggaran pose gagal. Model mungkin bukan watak humanoid yang sah. Hantar model watak humanoid. Untuk model_url, semak juga sama ada watak menghadap paksi +Z.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda. Tunggu, kemudian cuba semula. Lihat Had kadar.

GET/openapi/v1/rigging/:id

Dapatkan tugas Rigging

Mengembalikan tugas Rigging berdasarkan IDnya.

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": null,
  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  }
}

Parameter

Name
id
Type
path
Description
ID tugas daripada respons penciptaan.

Nilai Pulangan

Objek tugas Rigging.

DELETE/openapi/v1/rigging/:id

Padam tugas Rigging

Memadam tugas Rigging secara kekal, termasuk model dan datanya. Anda tidak boleh membatalkan padaman.

Request

DELETE

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -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 memulangkan 409 Conflict, dan tugas tersebut terus berjalan. Meshy tidak memulangkan semula kredit untuk tugas yang telah bermula, jadi memadamnya akan menyebabkan anda kehilangan kedua-dua kredit dan hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED, atau CANCELED, kemudian padamkannya.

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

Mengembalikan

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

GET/openapi/v1/rigging

Senarai Tugasan Rigging

Mengembalikan senarai tugasan Rigging anda yang telah dipaginasi, bermula dengan yang terbaharu. Untuk menyemak imbas senarai tersebut, gunakan page_num dan page_size.

Tugasan yang anda cipta melalui API kekal di dalam API dan tidak dipaparkan dalam My Assets pada aplikasi web. Untuk mencari tugasan yang ID-nya sudah tidak anda miliki, gunakan endpoint ini.

Request

GET

/openapi/v1/rigging

curl "https://api.meshy.ai/openapi/v1/rigging?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/rigging/:id/stream

Alirkan tugas Rigging

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

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/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.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task event, with the same fields as the Rigging task object
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": null,
  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  }
}

Parameter

Name
id
Type
path
Description
ID tugas daripada respons pembuatan (create).

Nilai pulangan

Aliran objek tugas Rigging sebagai Server-Sent Events.

Setiap acara (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.

Objek tugas Rigging

Objek tugas Rigging menerangkan rigging bagi satu karakter. Ia menyimpan status, progress, dan fail output apabila tugas berjaya.

Ciri-ciri

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": null,
  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  }
}

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 rig.
Name
status
Type
string
Description
Status tugas, salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
progress
Type
integer
Description
Berapa banyak tugas telah selesai, dalam bentuk peratusan. Ia adalah 0 sehingga tugas bermula dan 100 apabila ia berjaya.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
started_at
Type
timestamp
Description
Masa tugas bermula, dalam milisaat Unix. Ia adalah 0 sehingga tugas bermula.
Name
finished_at
Type
timestamp
Description
Masa tugas selesai, dalam milisaat Unix. Ia adalah 0 sehingga tugas selesai.
Name
expires_at
Type
timestamp
Description
Masa fail hasil tugas tamat tempoh, dalam milisaat Unix. Selepas masa ini, Meshy boleh memadam fail tersebut.
Name
task_error
Type
object
Description
Butiran ralat apabila tugas gagal. Ia adalah null kecuali status adalah FAILED. Lihat Ralat.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas. Hadir apabila status adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Ia adalah 0 untuk tugas FAILED, kerana Meshy memulangkan semula kredit apabila sesuatu tugas gagal.
Name
result
Type
object
Description
URL fail output. Sehingga tugas berjaya, setiap URL adalah string kosong, dan basic_animations adalah null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL muat turun untuk karakter yang dirig sebagai fail FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL muat turun untuk karakter yang dirig sebagai fail GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  URL muat turun untuk animasi berjalan dan berlari lalai.
  Name
  walking_glb_url
  Type
  string
  Description
  Animasi berjalan dengan kulit, sebagai fail GLB.
  Name
  walking_fbx_url
  Type
  string
  Description
  Animasi berjalan dengan kulit, sebagai fail FBX.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Rangka animasi berjalan, sebagai fail GLB.
  Name
  running_glb_url
  Type
  string
  Description
  Animasi berlari dengan kulit, sebagai fail GLB.
  Name
  running_fbx_url
  Type
  string
  Description
  Animasi berlari dengan kulit, sebagai fail FBX.
  Name
  running_armature_glb_url
  Type
  string
  Description
  Rangka animasi berlari, sebagai fail GLB.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului tugas ini dalam baris gilir. Nilai ini hanya bermakna semasa tugas adalah PENDING. Medan ini ditinggalkan apabila nilainya 0.