Rigging API

Rigging API memungkinkan Anda untuk secara terprogram menambahkan kerangka (armature) ke model 3D humanoid, mengikat mesh ke kerangka tersebut sehingga siap untuk dianimasikan. Untuk menerapkan Animasi pada karakter yang sudah di-rigging, lihat Animation API.

Perlu diketahui bahwa rigging terprogram saat ini hanya berfungsi dengan baik pada asset humanoid (bipedal) standar dengan anggota tubuh dan struktur tubuh yang jelas terdefinisi.

POST/openapi/v1/rigging

Create a Rigging Task

Endpoint ini memungkinkan Anda membuat tugas rigging baru untuk model 3D tertentu. Setelah berhasil diselesaikan, endpoint ini menghasilkan karakter yang telah di-rig dalam format standar dan secara opsional animasi berjalan/berlari dasar.

Tugas berjalan di latar belakang. Untuk informasi berapa lama biasanya proses ini berlangsung, lihat Processing Times.

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

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

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

Saat menggunakan model_url, bagian wajah karakter harus menghadap ke sumbu +Z (arah depan 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 diberikan, input_task_id akan diprioritaskan.

Name
input_task_id
Type
string
Wajib
Description
Tugas input yang perlu di-rig. Saat ini kami mendukung model humanoid bertekstur.

Name
model_url
Type
string
Wajib
Description
Silakan berikan model 3D untuk di-rig oleh Meshy melalui URL yang dapat diakses publik atau Data URI. Saat ini kami mendukung file GLB humanoid bertekstur (format .glb).
Ukuran file maksimum: 400 MB untuk URL http atau https, 100 MB untuk data: URI.
File di atas 100 MB dengan lebih dari 10.000.000 face akan mengembalikan 400. Face dihitung sebagai segitiga, dan mesh yang digambar lebih dari sekali dihitung sekali per salinan. GLB di atas 100 MB tidak boleh menggunakan kompresi Draco.

Name
height_meters
Type
number
default 1.7
Description
Perkiraan tinggi model karakter dalam meter. Ini membantu akurasi penskalaan dan rigging. Nilainya harus berupa angka positif.
Name
texture_image_url
Type
string
Description
Gambar tekstur warna dasar model yang telah di-UV-unwrap. URL yang dapat diakses publik atau Data URI. Saat ini kami mendukung format .png.
Ukuran file maksimum: 20 MB.

Returns

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

Failure Modes

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Parameter hilang: Salah satu dari model_url atau input_task_id harus diberikan.
- Format model tidak valid: model_url mengarah ke file dengan ekstensi yang tidak didukung (hanya .glb yang didukung).
- URL tidak dapat diakses: File model_url tidak dapat diunduh.
- File model terlalu besar: File model_url melebihi 400 MB (URL http atau https) atau 100 MB (data: URI).
- Terlalu banyak face: File model_url berukuran di atas 100 MB dan memiliki lebih dari 10.000.000 face. Kurangi jumlah face, lalu kirim ulang file tersebut.
- File model tidak dapat dibaca: File model_url berukuran di atas 100 MB dan headernya tidak dapat dibaca, misalnya GLB yang dikompresi dengan Draco.
- Header model terlalu kompleks: File model_url berukuran di atas 100 MB dan headernya memiliki terlalu banyak mesh, node, atau record untuk diperiksa. Kurangi jumlah objek dalam file tersebut, lalu kirim ulang.
- Gambar terlalu besar: Gambar texture_image_url melebihi 20 MB.
- Tugas input tidak valid: input_task_id tidak merujuk ke tugas API yang valid.
- Jumlah face terlampaui: Model input memiliki lebih dari 300.000 face. Silakan gunakan Remesh API untuk mengurangi jumlah face sebelum melakukan rigging.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak cukup untuk menjalankan tugas ini.
Name
422 - Unprocessable Entity
Description
Estimasi pose gagal. Model yang diberikan mungkin bukan karakter humanoid yang valid.
Name
429 - Too Many Requests
Description
Anda telah melampaui 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

Retrieve a Rigging Task

Endpoint ini memungkinkan Anda mengambil tugas rigging berdasarkan id tugas yang valid. Lihat The Rigging Task Object untuk melihat properti apa saja yang disertakan.

Parameter

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

Returns

Respons berisi objek Rigging Task. Periksa bagian The Rigging Task Object untuk detailnya.

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

Hapus Tugas Rigging

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

Path Parameters

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

Status Tugas

Tugas yang masih berstatus PENDING akan dihapus dan kredit yang terpakai saat dibuat akan dikembalikan.

Tugas yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan tugas tetap berjalan. Kredit untuk tugas yang sudah mulai diproses oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga tugas mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus tugas tersebut.

Tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) akan dihapus tanpa pengembalian kredit.

Returns

Mengembalikan 200 OK jika berhasil, atau 409 Conflict jika 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

List Rigging Tasks

Mengembalikan daftar tugas rigging milik pemanggil dengan paginasi, dari yang terbaru. Paginasi standar melalui page_num dan page_size.

Perlu diperhatikan bahwa tugas yang dibuat melalui API dikelola melalui API — tugas tersebut tidak muncul di My Assets pada aplikasi web. Gunakan endpoint ini untuk menemukan tugas yang ID-nya sudah tidak Anda miliki lagi.

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

Streaming Tugas Rigging

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

Parameter

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

Returns

Mengembalikan stream dari The Rigging Task Objects sebagai Server-Sent Events.

Untuk tugas dengan status PENDING atau IN_PROGRESS, response stream hanya akan menyertakan field 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
}

The Rigging Task Object

Rigging Task object merepresentasikan unit kerja untuk melakukan rigging pada karakter.

Properties

Name
id
Type
string
Description
Pengenal unik untuk task.
Name
type
Type
string
Description
Jenis task Rigging. Nilainya adalah rig.
Name
status
Type
string
Description
Status task. Kemungkinan nilainya: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress task (0-100). 0 jika belum dimulai, 100 jika berhasil.
Name
created_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat task dibuat.
Stempel waktu merepresentasikan jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Sebagai contoh, Jumat, 1 September 2023 pukul 12:00:00 WIB GMT direpresentasikan sebagai 1693569600000. Hal ini berlaku untuk semua stempel waktu di Meshy API.
Name
started_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat task mulai diproses. 0 jika belum dimulai.
Name
finished_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat task selesai. 0 jika belum selesai.
Name
expires_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat aset hasil task kedaluwarsa dan mungkin akan dihapus.
Name
task_error
Type
object
Description
Detail kesalahan untuk task yang gagal. Lihat Errors untuk referensi lengkap objek task_error.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang dikonsumsi oleh task ini. Muncul ketika status task adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk task FAILED (kredit dikembalikan jika gagal).
Name
result
Type
object
Description
Berisi URL aset keluaran jika task SUCCEEDED, null jika sebaliknya.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL yang dapat diunduh untuk karakter yang telah di-rig dalam format FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL yang dapat diunduh untuk karakter yang telah di-rig dalam format GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Berisi URL untuk animasi default. (misalnya jika generate_basic_animations secara implisit bernilai true atau diaktifkan secara default).
  Name
  walking_glb_url
  Type
  string
  Description
  URL yang dapat diunduh untuk animasi berjalan dalam format GLB (dengan skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL yang dapat diunduh untuk animasi berjalan dalam format FBX (dengan skin).
  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 skin).
  Name
  running_fbx_url
  Type
  string
  Description
  URL yang dapat diunduh untuk animasi berlari dalam format FBX (dengan skin).
  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 task yang mendahului dalam antrean. Hanya berarti jika status adalah 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
}