Rigging API

Ang Rigging API ay nagbibigay-daan sa iyo na programatikong magdagdag ng skeleton (armature) sa mga 3D humanoid na modelo, na nagbibigkis ng mesh dito upang maging handa para sa animation. Para sa pag-aaplay ng animations sa isang rigged na karakter, tingnan ang Animation API.

Pakitandaan na ang programatikong rigging ay kasalukuyang gumagana lamang nang maayos sa mga karaniwang humanoid (bipedal) na asset na may malinaw na tinukoy na mga biyas at istruktura ng katawan sa kasalukuyan.

POST/openapi/v1/rigging

Gumawa ng Rigging Task

Ang endpoint na ito ay nagpapahintulot sa iyo na lumikha ng bagong rigging task para sa isang ibinigay na 3D model. Kapag matagumpay na natapos, ito ay nagbibigay ng rigged na karakter sa mga karaniwang format at opsyonal na mga pangunahing animasyon ng paglalakad/pagtakbo.

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

Mga mesh na walang texture
Mga asset na hindi humanoid
Mga asset na humanoid na may hindi malinaw na istruktura ng mga braso at katawan

Kapag gumagamit ng input_task_id, ang mga modelo na may higit sa 300,000 faces ay hindi sinusuportahan para sa rigging. Mangyaring gamitin ang Remesh API upang bawasan ang bilang ng mga faces bago mag-rigging.

Kapag gumagamit ng model_url, ang mukha ng karakter ay dapat nakaturo sa +Z axis (ang karaniwang glTF forward direction). Ang mga modelong nakaharap sa ibang axes ay mabibigo sa pose estimation.

Mga Parameter

Isa lamang sa input_task_id o model_url ang kailangan. Kung parehong ibinigay, input_task_id ang may prayoridad.

Name
input_task_id
Type
string
Kinakailangan
Description
Ang input task na kailangang i-rig. Sa kasalukuyan, sinusuportahan namin ang mga textured na humanoid na modelo.

Name
model_url
Type
string
Kinakailangan
Description
Mangyaring magbigay ng 3D model para sa Meshy na i-rig sa pamamagitan ng isang pampublikong accessible na URL o Data URI. Sa kasalukuyan, sinusuportahan namin ang mga textured na humanoid na GLB files (.glb format).

Name
height_meters
Type
number
default 1.7
Description
Ang tinatayang taas ng character model sa metro. Ito ay nakakatulong sa scaling at rigging accuracy. Dapat itong maging positibong numero.
Name
texture_image_url
Type
string
Description
Ang UV-unwrapped base color texture image ng modelo. Pampublikong accessible na URL o Data URI. Sa kasalukuyan, sinusuportahan namin ang .png formats.

Mga Ibinabalik

Ang result property ng tugon ay naglalaman ng task id ng bagong likhang rigging task.

Mga Paraan ng Pagkabigo

Name
400 - Bad Request
Description
Ang kahilingan ay hindi katanggap-tanggap. Karaniwang mga sanhi:
- Nawawalang parameter: Dapat ibigay ang alinman sa model_url o input_task_id.
- Hindi wastong format ng modelo: Ang model_url ay tumutukoy sa isang file na may hindi suportadong extension (tanging .glb ang suportado).
- Hindi maabot na URL: Ang model_url ay hindi ma-download.
- Hindi wastong input task: Ang input_task_id ay hindi tumutukoy sa isang wastong API task.
- Lumampas sa bilang ng mukha: Ang input model ay may higit sa 300,000 faces. Mangyaring gamitin ang Remesh API upang bawasan ang bilang ng mga faces bago mag-rigging.
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. Ang ibinigay na modelo ay maaaring hindi wastong humanoid na karakter.
Name
429 - Too Many Requests
Description
Lumampas ka sa 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 katangian ang kasama.

Mga Parameter

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

Mga Ibinabalik

Ang tugon ay naglalaman ng Rigging Task object. Suriin ang seksyon ng The Rigging Task Object 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

Tanggalin ang Isang Gawain sa Rigging

Ang endpoint na ito ay permanenteng nagtatanggal ng isang gawain sa rigging, kasama ang lahat ng kaugnay na modelo at datos. Ang aksyong ito ay hindi na mababawi.

Mga Parameter ng Path

Name
id
Type
path
Description
Ang ID ng gawain sa rigging na tatanggalin.

Mga Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay.

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

Listahan ng mga Gawain sa Rigging

Nagbabalik ng isang may pagination na listahan ng mga gawain sa rigging ng tumatawag, pinakabago muna. Karaniwang pagination gamit ang page_num at page_size.

Tandaan na ang mga gawain na nilikha 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 mahanap ang isang gawain 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 Isang Rigging Task

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

Mga Parameter

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

Mga Ibinabalik

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

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

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 Objek ng Gawain sa Rigging

Ang Objek ng Gawain sa Rigging ay kumakatawan sa yunit ng trabaho para sa pag-rigging ng isang karakter.

Mga Katangian

Name
id
Type
string
Description
Natatanging pagkakakilanlan para sa gawain.
Name
type
Type
string
Description
Uri ng Gawain sa Rigging. Ang halaga ay rig.
Name
status
Type
string
Description
Katayuan ng gawain. Posibleng mga halaga: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Pag-unlad ng gawain (0-100). 0 kung hindi pa nasimulan, 100 kung nagtagumpay.
Name
created_at
Type
timestamp
Description
Timestamp (mga millisecond mula noong epoch) kung kailan nilikha ang gawain.
Ang isang timestamp ay kumakatawan sa bilang ng mga millisecond na lumipas mula Enero 1, 1970 UTC, alinsunod sa RFC 3339 na pamantayan. Halimbawa, Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Ito ay naaangkop sa lahat ng mga timestamp sa Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp (mga millisecond mula noong epoch) kung kailan nagsimula ang pagproseso ng gawain. 0 kung hindi pa nasimulan.
Name
finished_at
Type
timestamp
Description
Timestamp (mga millisecond mula noong epoch) kung kailan natapos ang gawain. 0 kung hindi pa natapos.
Name
expires_at
Type
timestamp
Description
Timestamp (mga millisecond mula noong epoch) kung kailan mag-e-expire ang mga resulta ng gawain at maaaring matanggal.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong gawain. Tingnan ang Errors para sa buong sanggunian ng task_error na objek.
Name
consumed_credits
Type
integer
Description
Ang bilang ng mga credits na nagamit ng gawain na ito. Kasalukuyan kapag ang katayuan ng gawain ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na gawain (ang mga credits ay ibinabalik kapag nabigo).
Name
result
Type
object
Description
Naglalaman ng mga URL ng output asset kung ang gawain ay SUCCEEDED, null kung hindi.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Downloadable URL para sa rigged na karakter sa format na FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Downloadable URL para sa rigged na karakter 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 implicit na totoo o naka-enable bilang default).
  Name
  walking_glb_url
  Type
  string
  Description
  Downloadable URL para sa walking animation sa format na GLB (may skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  Downloadable URL para sa walking animation sa format na FBX (may skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Downloadable URL para sa walking animation armature sa format na GLB.
  Name
  running_glb_url
  Type
  string
  Description
  Downloadable URL para sa running animation sa format na GLB (may skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Downloadable URL para sa running animation sa format na FBX (may skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Downloadable URL para sa running animation armature sa format na GLB.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang gawain sa pila. Makabuluhan lamang kung ang katayuan 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
}