API Rigging

API Rigging memungkinkan Anda untuk secara programatis menambahkan kerangka (armature) ke model humanoid 3D, mengikat mesh ke dalamnya sehingga siap untuk animasi. Untuk menerapkan animasi pada karakter yang telah dirigging, lihat API Animasi.

Harap dicatat bahwa rigging secara programatis saat ini hanya bekerja dengan baik pada asset humanoid standar (berkaki dua) dengan anggota tubuh dan struktur tubuh yang terdefinisi dengan jelas saat ini.

POST/openapi/v1/rigging

Membuat Tugas Rigging

Endpoint ini memungkinkan Anda untuk membuat tugas rigging baru untuk model 3D yang diberikan. Setelah berhasil diselesaikan, ini menyediakan karakter yang telah dirigging dalam format standar dan opsional animasi berjalan/berlari dasar.

Saat ini, auto-rigging tidak cocok untuk model berikut:

Mesh tanpa tekstur
Aset non-humanoid
Aset humanoid dengan struktur anggota tubuh dan tubuh yang tidak jelas

Saat menggunakan input_task_id, model dengan lebih dari 300.000 wajah tidak didukung untuk rigging. Silakan gunakan Remesh API untuk mengurangi jumlah wajah sebelum rigging.

Saat menggunakan model_url, wajah karakter harus menghadap ke arah +Z (arah maju standar glTF). Model yang menghadap sumbu lain akan gagal dalam estimasi pose.

Parameter

Hanya salah satu dari input_task_id atau model_url yang diperlukan. Jika keduanya disediakan, input_task_id memiliki prioritas.

Name
input_task_id
Type
string
Wajib
Description
Tugas input yang perlu dirigging. Kami saat ini mendukung model humanoid bertekstur.

Name
model_url
Type
string
Wajib
Description
Silakan sediakan model 3D untuk Meshy untuk dirigging melalui URL yang dapat diakses publik atau Data URI. Kami saat ini mendukung file GLB humanoid bertekstur (format .glb).

Name
height_meters
Type
number
default 1.7
Description
Tinggi perkiraan model karakter dalam meter. Ini membantu dalam skala dan akurasi rigging. Harus berupa angka positif.
Name
texture_image_url
Type
string
Description
Gambar tekstur warna dasar model yang telah di-UV-unwrapped. URL yang dapat diakses publik atau Data URI. Kami saat ini mendukung format .png.

Mengembalikan

Properti result dari respons berisi id tugas dari tugas rigging yang baru dibuat.

Mode Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Parameter hilang: Salah satu dari model_url atau input_task_id harus disediakan.
- Format model tidak valid: model_url mengarah ke file dengan ekstensi yang tidak didukung (hanya .glb yang didukung).
- URL tidak dapat dijangkau: model_url tidak dapat diunduh.
- Tugas input tidak valid: input_task_id tidak merujuk ke tugas API yang valid.
- Jumlah wajah terlampaui: Model input memiliki lebih dari 300.000 wajah. Silakan gunakan Remesh API untuk mengurangi jumlah wajah sebelum rigging.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melakukan tugas ini.
Name
422 - Unprocessable Entity
Description
Estimasi pose gagal. Model yang disediakan mungkin bukan karakter humanoid yang valid.
Name
429 - Too Many Requests
Description
Anda telah melebihi batas laju 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

Mengambil Tugas Rigging

Endpoint ini memungkinkan Anda untuk mengambil tugas rigging dengan memberikan id tugas yang valid. Lihat Objek Tugas Rigging untuk melihat properti apa saja yang disertakan.

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas rigging yang akan diambil.

Mengembalikan

Respon berisi objek Tugas Rigging. Periksa bagian Objek Tugas Rigging untuk detailnya.

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

Respon

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

Menghapus Tugas Rigging

Endpoint ini secara permanen menghapus tugas rigging, termasuk semua model dan data yang terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Path

Name
id
Type
path
Description
ID dari tugas rigging yang akan dihapus.

Mengembalikan

Mengembalikan 200 OK jika berhasil.

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

Respon

// Returns 200 Ok on success.

GET/openapi/v1/rigging

Daftar Tugas Rigging

Mengembalikan daftar paginasi dari tugas rigging pemanggil, terbaru terlebih dahulu. Paginasi standar melalui page_num dan page_size.

Perhatikan bahwa tugas yang dibuat melalui API dikelola melalui API — mereka tidak muncul di My Assets aplikasi web. Gunakan endpoint ini untuk menemukan tugas 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

Streaming Tugas Rigging

Endpoint ini mengalirkan pembaruan real-time untuk tugas Rigging menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Rigging yang akan di-stream.

Mengembalikan

Mengembalikan aliran Objek Tugas Rigging sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan menyertakan bidang 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}"

Aliran Respons

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

Properti

Name
id
Type
string
Description
Pengenal unik untuk tugas.
Name
type
Type
string
Description
Jenis tugas Rigging. Nilainya adalah rig.
Name
status
Type
string
Description
Status dari tugas. Nilai yang mungkin: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress dari tugas (0-100). 0 jika belum dimulai, 100 jika berhasil.
Name
created_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) ketika tugas dibuat.
Stempel waktu mewakili jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Sebagai contoh, Jumat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini berlaku untuk semua stempel waktu dalam Meshy API.
Name
started_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) ketika tugas mulai diproses. 0 jika belum dimulai.
Name
finished_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) ketika tugas selesai. 0 jika belum selesai.
Name
expires_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) ketika aset hasil tugas kedaluwarsa dan dapat dihapus.
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh tugas ini. Ada ketika status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan jika gagal).
Name
result
Type
object
Description
Berisi URL aset keluaran jika tugas SUCCEEDED, null jika tidak.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL yang dapat diunduh untuk karakter yang telah dirigging dalam format FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL yang dapat diunduh untuk karakter yang telah dirigging dalam format GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Berisi URL untuk animasi default. (misalnya jika generate_basic_animations secara implisit benar atau diaktifkan secara default).
  Name
  walking_glb_url
  Type
  string
  Description
  URL yang dapat diunduh untuk animasi berjalan dalam format GLB (dengan kulit).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL yang dapat diunduh untuk animasi berjalan dalam format FBX (dengan kulit).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL yang dapat diunduh untuk armature animasi berjalan dalam format GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL yang dapat diunduh untuk animasi berlari dalam format GLB (dengan kulit).
  Name
  running_fbx_url
  Type
  string
  Description
  URL yang dapat diunduh untuk animasi berlari dalam format FBX (dengan kulit).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL yang dapat diunduh untuk armature animasi berlari dalam format GLB.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas sebelumnya dalam antrian. Bermakna hanya jika status adalah PENDING.

Contoh Objek Tugas 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
}