API Rigging

API Rigging membolehkan anda menambah rangka secara programatik kepada model 3D humanoid, mengikat jejaring kepadanya supaya ia bersedia untuk animasi. Untuk mengenakan Animasi pada aksara yang telah dirig, lihat API Animasi.

Harap maklum bahawa rigging secara programatik pada masa ini hanya berfungsi dengan baik untuk aset humanoid standard (berkaki dua) yang mempunyai anggota badan dan struktur badan yang jelas ditakrifkan.

POST/openapi/v1/rigging

Create a Rigging Task

Endpoint ini membolehkan anda membuat tugas rigging baharu untuk model 3D tertentu. Setelah berjaya diselesaikan, ia menyediakan watak yang dirig dalam format standard dan secara pilihan animasi asas berjalan/berlari.

Tugas ini berjalan di latar belakang. Untuk tempoh biasanya, lihat Masa Pemprosesan.

Pada masa ini, auto-rigging tidak sesuai untuk model berikut:

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

Apabila menggunakan input_task_id, model dengan lebih daripada 300,000 muka tidak disokong untuk rigging. Sila gunakan Remesh API untuk mengurangkan bilangan muka sebelum rigging.

Apabila menggunakan model_url, muka watak mestilah menghadap ke arah paksi +Z (arah hadapan standard glTF). Model yang menghadap paksi lain akan gagal anggaran pose.

Parameter

Hanya salah 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
Tugas input yang perlu dirig. Kami kini menyokong model humanoid bertekstur.

Name
model_url
Type
string
Diperlukan
Description
Sila sediakan model 3D untuk Meshy rig melalui URL yang boleh diakses secara awam atau Data URI. Kami kini menyokong fail GLB humanoid bertekstur (format .glb).
Saiz fail maksimum: 400 MB untuk URL http atau https, 100 MB untuk Data URI data:.
Fail yang melebihi 100 MB dengan lebih daripada 10,000,000 muka akan mengembalikan 400. Muka dikira sebagai segi tiga, dan jejaring yang dilukis lebih daripada sekali dikira sekali bagi setiap salinan. GLB yang melebihi 100 MB tidak boleh menggunakan pemampatan Draco.

Name
height_meters
Type
number
lalai 1.7
Description
Anggaran ketinggian model watak dalam meter. Ini membantu ketepatan penskalaan dan rigging. Ia mestilah nombor positif.
Name
texture_image_url
Type
string
Description
Imej tekstur warna asas model yang dibuka-lilit UV. URL yang boleh diakses secara awam atau Data URI. Kami kini menyokong format .png.
Saiz fail maksimum: 20 MB.

Pulangan

Ciri result bagi respons mengandungi id tugas bagi tugas rigging yang baharu dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Punca biasa:
- Parameter hilang: Sama ada model_url atau input_task_id mesti disediakan.
- Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong (hanya .glb disokong).
- URL tidak dapat dicapai: model_url tidak dapat dimuat turun.
- Fail model terlalu besar: Fail model_url melebihi 400 MB (URL http atau https) atau 100 MB (Data URI data:).
- 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 headernya tidak dapat dibaca, contohnya GLB yang dimampatkan Draco.
- Header model terlalu kompleks: Fail model_url melebihi 100 MB dan headernya 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.
- Tugas input tidak sah: input_task_id tidak merujuk kepada tugas API yang sah.
- Bilangan muka melebihi had: Model input mempunyai lebih daripada 300,000 muka. Sila gunakan Remesh API untuk mengurangkan bilangan muka sebelum rigging.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugas ini.
Name
422 - Unprocessable Entity
Description
Anggaran pose gagal. Model yang disediakan mungkin bukan watak humanoid yang sah.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda.

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

GET/openapi/v1/rigging/:id

Dapatkan Tugas Rigging

endpoint ini membolehkan anda mendapatkan tugas rigging dengan id tugas yang sah. Rujuk The Rigging Task Object untuk melihat sifat-sifat yang disertakan.

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas rigging yang hendak didapatkan.

Hasil

Respons mengandungi objek Rigging Task. Semak bahagian The Rigging Task Object untuk maklumat lanjut.

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

    "message": ""

  },

  "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=..."
    }
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/rigging/:id

Padam Tugas Rigging

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

Parameter Laluan

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

Status Tugas

Tugas yang masih PENDING akan dipadamkan dan kredit yang digunakan semasa penciptaan akan dikembalikan.

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

Tugas yang berada dalam keadaan terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadamkan tanpa bayaran balik.

Pulangan

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

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 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/rigging

Senaraikan Tugas Rigging

Mengembalikan senarai tugas rigging pemanggil yang dipenomborhalamankan, yang terbaharu dahulu. Penomboran halaman standard melalui page_num dan page_size.

Perhatikan bahawa tugas yang dicipta melalui API diuruskan melalui API — tugas tersebut tidak muncul dalam My Assets pada aplikasi web. Gunakan endpoint ini untuk mencari tugas yang ID-nya tidak lagi anda miliki.

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

Stream a Rigging Task

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

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas Rigging yang hendak distrim.

Pulangan

Mengembalikan strim The Rigging Task Objects sebagai Server-Sent Events.

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

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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 stream item, mirroring The Rigging Task Object structure
  "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": {

    "message": ""

  },

  "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?..."
    }
  },
  "preceding_tasks": 0
}

Objek Tugas Rigging

Objek Tugas Rigging mewakili unit kerja untuk melakukan rigging pada sebuah karakter.

Ciri-ciri

Name
id
Type
string
Description
Pengecam unik untuk tugas tersebut.
Name
type
Type
string
Description
Jenis tugas Rigging. Nilainya ialah rig.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas (0-100). 0 jika belum bermula, 100 jika berjaya.
Name
created_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugas dicipta.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut piawaian RFC 3339. Sebagai contoh, Jumaat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini terpakai kepada semua cap masa dalam Meshy API.
Name
started_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugas mula diproses. 0 jika belum bermula.
Name
finished_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugas selesai. 0 jika belum selesai.
Name
expires_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila aset hasil tugas tamat tempoh dan mungkin dipadamkan.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. Hadir apabila status tugas ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan apabila gagal).
Name
result
Type
object
Description
Mengandungi URL aset hasil jika status tugas SUCCEEDED, null sebaliknya.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL muat turun untuk karakter yang telah di-rig dalam format FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL muat turun untuk karakter yang telah di-rig dalam format GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Mengandungi URL untuk animasi lalai. (contohnya jika generate_basic_animations secara tersirat adalah true atau diaktifkan secara lalai).
  Name
  walking_glb_url
  Type
  string
  Description
  URL muat turun untuk animasi berjalan dalam format GLB (dengan kulit).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL muat turun untuk animasi berjalan dalam format FBX (dengan kulit).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL muat turun untuk rangka animasi berjalan dalam format GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL muat turun untuk animasi berlari dalam format GLB (dengan kulit).
  Name
  running_fbx_url
  Type
  string
  Description
  URL muat turun untuk animasi berlari dalam format FBX (dengan kulit).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL muat turun untuk rangka animasi berlari dalam format GLB.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu dalam baris gilir. Hanya bermakna jika status ialah PENDING.

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

    "message": ""

  },

  "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=..."
    }
  },
  "preceding_tasks": 0
}