API Rigging

API Rigging membolehkan anda menambah rangka (rangka) secara programatik kepada model humanoid 3D, mengikat jejaring kepadanya supaya ia sedia untuk animasi. Untuk menerapkan animasi kepada watak yang telah dirangka, lihat API Animasi.

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

POST/openapi/v1/rigging

Buat Tugas Rigging

Endpoint ini membolehkan anda untuk membuat tugas rigging baru untuk model 3D yang diberikan. Setelah selesai dengan jayanya, ia menyediakan watak yang telah dirig dalam format standard dan 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 badan 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 mesti menghadap ke arah +Z (arah hadapan glTF standard). Model yang menghadap paksi lain akan gagal dalam anggaran pose.

Parameter

Hanya satu daripada input_task_id atau model_url adalah 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 umum atau Data URI. Kami kini menyokong fail GLB humanoid bertekstur (format .glb).

Name
height_meters
Type
number
lalai 1.7
Description
Ketinggian anggaran model watak dalam meter. Ini membantu dalam penskalaan dan ketepatan rigging. Ia mesti nombor positif.
Name
texture_image_url
Type
string
Description
Imej tekstur warna asas model yang telah di-UV-unwrapped. URL yang boleh diakses secara umum atau Data URI. Kami kini menyokong format .png.

Pulangan

Properti result dalam respons mengandungi id tugas rigging yang baru dibuat.

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.
- Tugas input tidak sah: input_task_id tidak merujuk kepada tugas API yang sah.
- Bilangan muka melebihi: 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 memberikan id tugas yang sah. Rujuk kepada Objek Tugas Rigging untuk melihat sifat-sifat yang disertakan.

Parameter

Name
id
Type
path
Description
Pengenal pasti unik untuk tugas rigging yang ingin diperoleh.

Pulangan

Respons mengandungi objek Tugas Rigging. Semak bahagian Objek Tugas Rigging untuk butiran lanjut.

Permintaan

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

Respons

{
  "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 dipulihkan.

Parameter Laluan

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

Pulangan

Mengembalikan 200 OK jika berjaya.

Permintaan

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

Respons

// Returns 200 Ok on success.

GET/openapi/v1/rigging

Senarai Tugasan Rigging

Mengembalikan senarai penomboran halaman tugasan rigging pemanggil, yang terbaru dahulu. Penomboran halaman standard melalui page_num dan page_size.

Perhatikan bahawa tugasan yang dibuat melalui API diuruskan melalui API — ia tidak muncul dalam Aplikasi Web My Assets. Gunakan endpoint ini untuk mencari tugasan yang ID-nya tidak lagi anda miliki.

Permintaan

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

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 unik untuk tugas Rigging yang hendak distrim.

Pulangan

Mengembalikan strim Objek Tugas Rigging sebagai Server-Sent Events.

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

Permintaan

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

Objek Tugasan Rigging mewakili unit kerja untuk rigging watak.

Sifat

Name
id
Type
string
Description
Pengenal pasti unik untuk tugasan.
Name
type
Type
string
Description
Jenis tugasan Rigging. Nilainya adalah rig.
Name
status
Type
string
Description
Status tugasan. Nilai yang mungkin: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugasan (0-100). 0 jika belum bermula, 100 jika berjaya.
Name
created_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugasan 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 tugasan mula diproses. 0 jika belum bermula.
Name
finished_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugasan selesai. 0 jika belum selesai.
Name
expires_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila aset hasil tugasan tamat tempoh dan mungkin dipadamkan.
Name
task_error
Type
object
Description
Butiran ralat untuk tugasan yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugasan ini. Hadir apabila status tugasan adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugasan FAILED (kredit dikembalikan jika gagal).
Name
result
Type
object
Description
Mengandungi URL aset output jika tugasan SUCCEEDED, null jika tidak.
- 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. (contohnya jika generate_basic_animations secara implisit benar atau diaktifkan 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 tugasan terdahulu dalam barisan. Bermakna hanya jika status adalah PENDING.

Contoh Objek Tugasan Rigging

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