API Rigging

API Rigging membolehkan anda menambahkan rangka (rangka) secara programatik pada model humanoid 3D, mengikat jejaring kepadanya supaya ia sedia untuk animasi. Untuk menggunakan animasi pada watak yang telah melalui rigging, lihat API Animasi.

Sila ambil perhatian bahawa rigging secara programatik pada masa ini hanya berfungsi dengan baik untuk aset humanoid standard (berkaki dua) dengan anggota badan dan struktur tubuh yang ditakrifkan dengan jelas pada masa ini.

POST/openapi/v1/rigging

Cipta Tugas Rigging

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

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

Mesh 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 face tidak disokong untuk rigging. Sila gunakan Remesh API untuk mengurangkan bilangan face sebelum rigging.

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

Parameter

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

Name
input_task_id
Type
string
Diperlukan
Description
Tugas input yang perlu di-rig. Pada masa ini kami menyokong model humanoid bertekstur.

Name
model_url
Type
string
Diperlukan
Description
Sila berikan model 3D untuk Meshy rig melalui URL yang boleh diakses secara awam atau Data URI. Pada masa ini kami menyokong fail GLB humanoid bertekstur (format .glb).

Name
height_meters
Type
number
lalai 1.7
Description
Anggaran ketinggian model watak dalam meter. Ini membantu dalam penskalaan dan ketepatan rigging. Ia mestilah nombor positif.
Name
texture_image_url
Type
string
Description
Imej tekstur warna asas model yang telah dibuka balut UV. URL yang boleh diakses secara awam atau Data URI. Pada masa ini kami menyokong format .png.

Pulangan

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

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca lazim:
- Parameter hilang: Sama ada model_url atau input_task_id mesti diberikan.
- Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong (hanya .glb disokong).
- URL tidak boleh dicapai: model_url tidak dapat dimuat turun.
- Tugas input tidak sah: input_task_id tidak merujuk kepada tugas API yang sah.
- Bilangan face melebihi had: Model input mempunyai lebih daripada 300,000 face. Sila gunakan Remesh API untuk mengurangkan bilangan face 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 diberikan 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 Tugasan Rigging

endpoint ini membolehkan anda mendapatkan tugasan rigging berdasarkan id tugasan yang sah. Rujuk Objek Tugasan Rigging untuk melihat sifat yang disertakan.

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugasan rigging yang hendak didapatkan.

Pulangan

Respons mengandungi objek Tugasan Rigging. Semak bahagian Objek Tugasan Rigging untuk butiran.

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 Tugasan Rigging

endpoint ini memadamkan tugasan rigging secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh dibatalkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugasan rigging untuk dipadam.

Pulangan

Mengembalikan 200 OK apabila berjaya.

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

// Returns 200 Ok on success.

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

Strim Tugas Rigging

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

Parameter

Name
id
Type
path
Description
Pengenal pasti unik untuk tugas Rigging yang akan distrim.

Pulangan

Mengembalikan strim Objek Tugas Rigging sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, strim respons hanya akan merangkumi 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 watak.

Sifat

Name
id
Type
string
Description
Pengecam unik untuk tugas.
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 telah berlalu sejak 1 Januari 1970 UTC, mengikut standard 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 objek task_error penuh.
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 dibayar balik apabila gagal).
Name
result
Type
object
Description
Mengandungi URL aset output jika tugas SUCCEEDED, jika tidak null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL boleh dimuat turun untuk watak yang telah di-rig dalam format FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL boleh dimuat turun untuk watak yang telah di-rig dalam format GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Mengandungi URL untuk animasi lalai. (cth. jika generate_basic_animations secara tersirat benar atau didayakan secara lalai).
  Name
  walking_glb_url
  Type
  string
  Description
  URL boleh dimuat turun untuk animasi berjalan dalam format GLB (dengan kulit).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL boleh dimuat turun untuk animasi berjalan dalam format FBX (dengan kulit).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL boleh dimuat turun untuk rangka animasi berjalan dalam format GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL boleh dimuat turun untuk animasi berlari dalam format GLB (dengan kulit).
  Name
  running_fbx_url
  Type
  string
  Description
  URL boleh dimuat turun untuk animasi berlari dalam format FBX (dengan kulit).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL boleh dimuat turun untuk rangka animasi berlari dalam format GLB.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu dalam baris gilir. Bermakna hanya 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
}