Rigging API

Pinapayagan ka ng Rigging API na magdagdag ng skeleton (armature) sa mga 3D humanoid model sa pamamagitan ng program, na ibina-bind ang mesh dito upang maging handa ang mga ito para sa Animation. Para sa paglalapat ng mga Animation sa isang character na na-rig, tingnan ang Animation API.

Pakitandaan na ang programmatic rigging ay kasalukuyang gumagana lamang nang maayos sa mga standard na humanoid (bipedal) asset na may malinaw na tinukoy na mga limb at body structure sa ngayon.

POST/openapi/v1/rigging

Gumawa ng Rigging Task

Pinapayagan ka ng endpoint na ito na gumawa ng bagong rigging task para sa isang ibinigay na 3D model. Kapag matagumpay na nakumpleto, nagbibigay ito ng rigged na character sa mga standard na format at opsyonal na mga basic walking/running animation.

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

Mga mesh na walang texture
Mga non-humanoid asset
Mga humanoid asset na hindi malinaw ang istruktura ng mga limb at katawan

Kapag ginagamit ang input_task_id, ang mga model na may higit sa 300,000 faces ay hindi sinusuportahan para sa rigging. Pakigamit ang Remesh API upang bawasan ang bilang ng face bago ang rigging.

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

Mga Parameter

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

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

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

Name
height_meters
Type
number
default 1.7
Description
Ang tinatayang taas ng character model sa metro. Nakakatulong ito sa scaling at katumpakan ng rigging. Dapat itong maging positibong numero.
Name
texture_image_url
Type
string
Description
Ang UV-unwrapped base color texture image ng model. Publicly accessible URL o Data URI. Sa kasalukuyan, sinusuportahan namin ang mga .png format.

Mga Return

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

Mga Failure Mode

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang sanhi:
- Nawawalang parameter: Dapat ibigay ang alinman sa model_url o input_task_id.
- Invalid na model format: Ang model_url ay tumuturo sa file na may hindi sinusuportahang extension (.glb lamang ang sinusuportahan).
- Hindi maabot na URL: Hindi ma-download ang model_url.
- Invalid na input task: Ang input_task_id ay hindi tumutukoy sa isang valid na API task.
- Lumampas sa bilang ng face: Ang input model ay may higit sa 300,000 faces. Pakigamit ang Remesh API upang bawasan ang bilang ng face bago ang rigging.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakitingnan ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat ang credits upang maisagawa ang task na ito.
Name
422 - Unprocessable Entity
Description
Nabigo ang pose estimation. Maaaring hindi valid na humanoid character ang ibinigay na model.
Name
429 - Too Many Requests
Description
Lumampas ka na 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 Gawain sa Rigging

Pinapayagan ka ng endpoint na ito na kunin ang isang gawain sa rigging gamit ang valid na task id. Sumangguni sa Ang Rigging Task Object para makita kung aling mga property ang kasama.

Mga Parameter

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

Mga Ibinabalik

Naglalaman ang response ng Rigging Task object. Tingnan ang seksyong Ang 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

Mag-delete ng Gawain sa Rigging

Permanenteng dine-delete ng endpoint na ito ang isang gawain sa rigging, kasama ang lahat ng kaugnay na modelo at data. Hindi na maibabalik ang aksyong ito.

Mga Path Parameter

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

Ibinabalik

Ibinabalik ang 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/:id/stream

Mag-stream ng Rigging Task

Ang endpoint na ito ay nag-i-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.

Mga Ibinabalik

Nagbabalik ng stream ng Mga Rigging Task Object bilang Server-Sent Events.

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

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 gawain para sa rigging ng isang karakter.

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 nagtagumpay.
Name
created_at
Type
timestamp
Description
timestamp (milliseconds mula noong epoch) kung kailan ginawa ang task.
Ang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula 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 timestamps sa Meshy API.
Name
started_at
Type
timestamp
Description
timestamp (milliseconds mula noong epoch) kung kailan nagsimulang iproseso ang task. 0 kung hindi pa nagsisimula.
Name
finished_at
Type
timestamp
Description
timestamp (milliseconds mula noong epoch) kung kailan natapos ang task. 0 kung hindi pa natatapos.
Name
expires_at
Type
timestamp
Description
timestamp (milliseconds mula noong epoch) kung kailan mag-e-expire ang mga result asset ng task at maaaring tanggalin.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong task_error object reference.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nakonsumo ng task na ito. Naroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED task (ire-refund ang credits kapag nabigo).
Name
result
Type
object
Description
Naglalaman ng mga output asset URL kung ang task ay SUCCEEDED, kung hindi ay null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Nada-download na URL para sa character na na-rig sa FBX format.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Nada-download na URL para sa character na na-rig sa GLB format.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Naglalaman ng mga URL para sa default na animations. (hal. kung ang generate_basic_animations ay implicit na true o enabled by default).
  Name
  walking_glb_url
  Type
  string
  Description
  Nada-download na URL para sa walking animation sa GLB format (may skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  Nada-download na URL para sa walking animation sa FBX format (may skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Nada-download na URL para sa walking animation armature sa GLB format.
  Name
  running_glb_url
  Type
  string
  Description
  Nada-download na URL para sa running animation sa GLB format (may skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Nada-download na URL para sa running animation sa FBX format (may skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Nada-download na URL para sa running animation armature sa GLB format.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga nauunang task sa queue. Makabuluhan 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
}