API Rigging

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

Harap diperhatikan bahwa rigging terprogram saat ini hanya berfungsi dengan baik pada asset humanoid standar (berkaki dua) dengan anggota tubuh dan struktur tubuh yang terdefinisi jelas pada saat ini.

POST/openapi/v1/rigging

Buat Tugas Rigging

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

Saat ini, rigging otomatis tidak cocok untuk model berikut:

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

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

Saat menggunakan model_url, wajah karakter harus menghadap ke sumbu +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 wajib. Jika keduanya disediakan, input_task_id mendapat prioritas.

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
Harap 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).

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-unwrap UV. URL yang dapat diakses publik atau Data URI. Saat ini kami 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 tidak ada: 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 face terlampaui: Model input memiliki lebih dari 300.000 face. Harap gunakan Remesh API untuk mengurangi jumlah face sebelum rigging.
Name
401 - Unauthorized
Description
Autentikasi gagal. Harap periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi 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

Mengambil Tugas Rigging

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

Parameter

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

Hasil yang Dikembalikan

Respons berisi objek Tugas Rigging. Periksa bagian Objek Tugas Rigging 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 terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Path

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

Mengembalikan

Mengembalikan 200 OK jika berhasil.

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

Streaming Tugas Rigging

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

Parameter

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

Mengembalikan

Mengembalikan stream Objek Tugas Rigging sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, stream respons 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
}

Objek Tugas Rigging

Objek Tugas Rigging merepresentasikan unit kerja untuk rigging karakter.

Properti

Name
id
Type
string
Description
Pengidentifikasi unik untuk tugas.
Name
type
Type
string
Description
Jenis tugas Rigging. Nilainya adalah rig.
Name
status
Type
string
Description
Status tugas. Nilai yang memungkinkan: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas (0-100). 0 jika belum dimulai, 100 jika berhasil.
Name
created_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat tugas dibuat.
Stempel waktu merepresentasikan jumlah milidetik yang telah berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Misalnya, Jumat, 1 September 2023 12:00:00 PM GMT direpresentasikan sebagai 1693569600000. Ini berlaku untuk semua stempel waktu di Meshy API.
Name
started_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat tugas mulai diproses. 0 jika belum dimulai.
Name
finished_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat tugas selesai. 0 jika belum selesai.
Name
expires_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat asset hasil tugas kedaluwarsa dan dapat dihapus.
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi objek task_error lengkap.
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 asset keluaran jika tugas SUCCEEDED, jika tidak null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL yang dapat diunduh untuk karakter yang telah di-rigging dalam format FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL yang dapat diunduh untuk karakter yang telah di-rigging 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 tugas sebelumnya dalam antrean. Bermakna hanya 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
}