Rigging API

Ang Rigging API ay nagbibigay-daan sa iyo upang idagdag nang programmatically ang isang skeleton (armature) sa 3D humanoid models, na iki-bind ang mesh dito upang maging handa ang mga ito para sa animation. Para sa paglalapat ng mga animation sa isang naka-rig na karakter, tingnan ang Animation API.

Pakitandaan na sa kasalukuyan, ang programmatic rigging ay maayos lamang gumagana sa mga karaniwang humanoid (bipedal) na asset na may malinaw na tinukoy na mga paa at kamay at istruktura ng katawan.

POST/openapi/v1/rigging

Gumawa ng Rigging Task

Ang endpoint na ito ay nagbibigay-daan sa iyo na gumawa ng bagong rigging task para sa isang ibinigay na 3D model. Kapag matagumpay na natapos, nagbibigay ito ng rigged character sa karaniwang mga format at opsyonal na mga basic na walking/running animation.

Ang task ay tumatakbo sa background. Para sa karaniwang tagal, tingnan ang Processing Times.

Sa kasalukuyan, hindi angkop ang auto-rigging para sa mga sumusunod na model:

Mga mesh na walang texture
Mga asset na hindi humanoid
Mga humanoid asset na may hindi malinaw na istraktura ng limbs at katawan

Kapag gumagamit ng input_task_id, hindi suportado ang mga model na may mahigit sa 300,000 faces para sa rigging. Mangyaring gamitin ang Remesh API upang bawasan ang bilang ng face bago mag-rig.

Kapag gumagamit ng model_url, dapat nakaharap ang mukha ng character sa +Z axis (ang standard na glTF forward direction). Mabibigo ang pose estimation para sa mga model na nakaharap sa ibang axis.

Mga Parameter

Isa lamang sa input_task_id o model_url ang kinakailangan. Kung parehong ibinigay, ang input_task_id ang mauuna.

Name
input_task_id
Type
string
Kinakailangan
Description
Ang input task na kailangang i-rig. Kasalukuyan naming sinusuportahan ang mga textured na humanoid model.

Name
model_url
Type
string
Kinakailangan
Description
Mangyaring magbigay ng 3D model para ma-rig ng Meshy sa pamamagitan ng publicly accessible na URL o Data URI. Kasalukuyan naming sinusuportahan ang mga textured na humanoid GLB file (.glb format).
Pinakamataas na laki ng file: 400 MB para sa http o https na URL, 100 MB para sa data: na URI.
Ang isang file na mahigit 100 MB na may mahigit 10,000,000 faces ay magbabalik ng 400. Ang mga face ay binibilang bilang mga triangle, at ang isang mesh na iginuhit nang higit sa isang beses ay binibilang nang isang beses bawat kopya. Ang isang GLB na mahigit 100 MB ay hindi dapat gumamit ng Draco compression.

Name
height_meters
Type
number
default 1.7
Description
Ang tinatayang taas ng character model sa metro. Nakakatulong ito sa katumpakan ng pagsukat at rigging. Dapat itong isang positibong numero.
Name
texture_image_url
Type
string
Description
Ang UV-unwrapped na base color texture image ng model. Publicly accessible na URL o Data URI. Kasalukuyan naming sinusuportahan ang mga .png na format.
Pinakamataas na laki ng file: 20 MB.

Mga Ibinabalik

Ang result property ng response ay naglalaman ng task id ng bagong nagawang rigging task.

Mga Mode ng Kabiguan

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang sanhi:
- Nawawalang parameter: Dapat ibigay ang model_url o input_task_id.
- Di-wastong format ng model: Ang model_url ay tumuturo sa isang file na may hindi suportadong extension (.glb lamang ang suportado).
- Hindi ma-access na URL: Hindi ma-download ang model_url.
- Masyadong malaki ang model file: Ang model_url na file ay lumagpas sa 400 MB (http o https na URL) o 100 MB (data: na URI).
- Masyadong maraming faces: Ang model_url na file ay mahigit 100 MB at may mahigit 10,000,000 faces. Bawasan ang bilang ng face, pagkatapos ay ipadala muli ang file.
- Hindi mabasang model file: Ang model_url na file ay mahigit 100 MB at hindi mabasa ang header nito, halimbawa isang Draco-compressed na GLB.
- Masyadong komplikado ang header ng model: Ang model_url na file ay mahigit 100 MB at ang header nito ay may masyadong maraming mesh, node, o record na dapat suriin. Bawasan ang bilang ng mga object sa file, pagkatapos ay ipadala muli ito.
- Masyadong malaki ang imahe: Ang texture_image_url na imahe ay lumagpas sa 20 MB.
- Di-wastong input task: Ang input_task_id ay hindi tumutukoy sa isang wastong API task.
- Nalagpasan ang bilang ng face: Ang input model ay may mahigit 300,000 faces. Mangyaring gamitin ang Remesh API upang bawasan ang bilang ng face bago mag-rig.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Mangyaring suriin ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat ang credits upang isagawa ang task na ito.
Name
422 - Unprocessable Entity
Description
Nabigo ang pose estimation. Maaaring hindi wastong humanoid character ang ibinigay na model.
Name
429 - Too Many Requests
Description
Nalagpasan mo na ang iyong rate limit.

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

Kunin ang Isang Rigging Task

Ang endpoint na ito ay nagbibigay-daan sa iyo na kunin ang isang rigging task gamit ang isang wastong id ng task. Sumangguni sa The Rigging Task Object upang makita kung aling mga property ang kasama.

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa rigging task na kukunin.

Ibinabalik

Ang tugon ay naglalaman ng Rigging Task object. Tingnan ang The Rigging Task Object na seksyon para sa mga detalye.

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

Mag-delete ng Rigging Task

Ang endpoint na ito ay permanenteng nagde-delete ng isang rigging task, kasama ang lahat ng kaugnay na mga modelo at data. Hindi na maaaring bawiin ang aksyong ito.

Mga Path Parameter

Name
id
Type
path
Description
Ang ID ng rigging task na ide-delete.

Katayuan ng Task

Ang isang task na nasa PENDING pa ay dine-delete at ire-refund ang mga credits na nagamit noong oras ng paggawa nito.

Ang isang task na IN_PROGRESS na ay hindi maaaring i-delete: ang request ay tatanggihan na may 409 Conflict at magpapatuloy ang task. Ang mga credits para sa isang task na nasimulan na ng worker ay hindi na maaaring i-refund, kaya ang pag-delete nito habang tumatakbo ay magiging kapalit ng credits at ng resulta. Hintayin itong umabot sa SUCCEEDED, FAILED, o CANCELED, bago ito i-delete.

Ang isang task na nasa terminal state (SUCCEEDED, FAILED, o CANCELED) ay dine-delete nang walang refund.

Mga Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay 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

Nagbabalik ng paginated na listahan ng mga rigging task ng tumawag, pinakabago muna. Standard na pagination gamit ang page_num at page_size.

Pansinin na ang mga task na ginawa sa pamamagitan ng API ay pinamamahalaan sa pamamagitan ng API — hindi sila lumalabas sa My Assets ng web app. Gamitin ang endpoint na ito upang hanapin ang isang task na wala ka nang ID.

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

I-stream ang Rigging Task

Ang endpoint na ito ay nagsa-stream ng real-time na mga update para sa isang Rigging task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Rigging task na i-stream.

Ibinabalik

Nagbabalik ng stream ng The Rigging Task Objects bilang Server-Sent Events.

Para sa mga task na PENDING o IN_PROGRESS, ang response stream ay magsasama lamang ng kinakailangang progress at status fields.

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
}

Ang Rigging Task Object

Kinakatawan ng Rigging Task object ang yunit ng trabaho para sa pag-rig ng isang character.

Mga Property

Name
id
Type
string
Description
Natatanging identifier para sa task.
Name
type
Type
string
Description
Uri ng Rigging task. Ang value ay rig.
Name
status
Type
string
Description
Status ng task. Mga posibleng value: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress ng task (0-100). 0 kung hindi pa nagsisimula, 100 kung matagumpay (SUCCEEDED).
Name
created_at
Type
timestamp
Description
Timestamp (milliseconds mula sa epoch) kung kailan nagawa ang task.
Ang isang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas simula Enero 1, 1970 UTC, alinsunod sa RFC 3339 standard. Halimbawa, ang Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Nalalapat ito sa lahat ng timestamp sa Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp (milliseconds mula sa epoch) kung kailan nagsimulang iproseso ang task. 0 kung hindi pa nagsisimula.
Name
finished_at
Type
timestamp
Description
Timestamp (milliseconds mula sa epoch) kung kailan natapos ang task. 0 kung hindi pa tapos.
Name
expires_at
Type
timestamp
Description
Timestamp (milliseconds mula sa epoch) kung kailan mag-e-expire ang mga asset na resulta ng task at posibleng matanggal.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reference ng task_error object.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nagamit ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga task na FAILED (ang credits ay ire-refund kapag nabigo).
Name
result
Type
object
Description
Naglalaman ng mga URL ng output asset kung ang task ay SUCCEEDED, null kung hindi.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Na-download na URL para sa naka-rig na character sa format na FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Na-download na URL para sa naka-rig na character sa format na GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Naglalaman ng mga URL para sa mga default na animation. (hal. kung ang generate_basic_animations ay implicitly true o pinagana bilang default).
  Name
  walking_glb_url
  Type
  string
  Description
  Na-download na URL para sa animation ng paglalakad sa format na GLB (na may skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  Na-download na URL para sa animation ng paglalakad sa format na FBX (na may skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Na-download na URL para sa armature ng animation ng paglalakad sa format na GLB.
  Name
  running_glb_url
  Type
  string
  Description
  Na-download na URL para sa animation ng pagtakbo sa format na GLB (na may skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Na-download na URL para sa animation ng pagtakbo sa format na FBX (na may skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Na-download na URL para sa armature ng animation ng pagtakbo sa format na GLB.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga nauunang task sa queue. May kahulugan lamang kung ang status ay 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
}