Rigging API

Rigging API umožňuje programově přidat kostru (armaturu) k 3D humanoidním modelům a navázat na ni síť, aby byly připravené pro animaci. Informace o použití animací na postavu s rigem najdete v Animation API.

Upozorňujeme, že programový rigging v současnosti dobře funguje pouze se standardními humanoidními (bipedálními) assety s jasně definovanými končetinami a tělesnou strukturou.

POST/openapi/v1/rigging

Vytvořit úlohu riggingu

Tento koncový bod vám umožňuje vytvořit novou úlohu riggingu pro daný 3D model. Po úspěšném dokončení poskytne postavu s riggingem ve standardních formátech a volitelně základní animace chůze/běhu.

Automatický rigging v současnosti není vhodný pro následující modely:

Meshe bez textur
Nehumanoidní assety
Humanoidní assety s nejasnou strukturou končetin a těla

Při použití input_task_id nejsou modely s více než 300 000 plochami pro rigging podporovány. Před riggingem prosím použijte Remesh API ke snížení počtu ploch.

Při použití model_url musí obličej postavy směřovat k ose +Z (standardní směr dopředu v glTF). U modelů směřujících k jiným osám selže odhad pozice.

Parametry

Vyžadováno je pouze jedno z input_task_id nebo model_url. Pokud jsou uvedeny obě hodnoty, input_task_id má prioritu.

Name
input_task_id
Type
string
Povinné
Description
Vstupní úloha, pro kterou je potřeba provést rigging. V současnosti podporujeme humanoidní modely s texturami.

Name
model_url
Type
string
Povinné
Description
Poskytněte prosím 3D model, pro který má Meshy provést rigging, prostřednictvím veřejně dostupné URL nebo Data URI. V současnosti podporujeme humanoidní GLB soubory s texturami (formát .glb).

Name
height_meters
Type
number
výchozí 1.7
Description
Přibližná výška modelu postavy v metrech. Pomáhá se škálováním a přesností riggingu. Musí jít o kladné číslo.
Name
texture_image_url
Type
string
Description
Obrázek základní barevné textury modelu s rozbaleným UV. Veřejně dostupná URL nebo Data URI. V současnosti podporujeme formáty .png.

Vrací

Vlastnost result v odpovědi obsahuje id úlohy nově vytvořené úlohy riggingu.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Běžné příčiny:
- Chybějící parametr: Musí být uvedeno buď model_url, nebo input_task_id.
- Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou (podporováno pouze .glb).
- Nedostupná URL: model_url se nepodařilo stáhnout.
- Neplatná vstupní úloha: input_task_id neodkazuje na platnou úlohu API.
- Překročen počet ploch: Vstupní model má více než 300 000 ploch. Před riggingem prosím použijte Remesh API ke snížení počtu ploch.
Name
401 - Unauthorized
Description
Autentizace selhala. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatek kreditů k provedení této úlohy.
Name
422 - Unprocessable Entity
Description
Odhad pozice selhal. Poskytnutý model nemusí být platnou humanoidní postavou.
Name
429 - Too Many Requests
Description
Překročili jste svůj limit rychlosti.

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

Načtení úlohy riggingu

Tento koncový bod umožňuje načíst úlohu riggingu pomocí platného id. Podívejte se na Objekt úlohy riggingu, kde zjistíte, které vlastnosti jsou zahrnuty.

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy riggingu, kterou chcete načíst.

Vrací

Odpověď obsahuje objekt úlohy riggingu. Podrobnosti najdete v části Objekt úlohy riggingu.

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

Odstranit úlohu riggingu

Tento koncový bod trvale odstraní úlohu riggingu včetně všech přidružených modelů a dat. Tato akce je nevratná.

Parametry cesty

Name
id
Type
path
Description
ID úlohy riggingu, kterou chcete odstranit.

Návratová hodnota

Při úspěchu vrací 200 OK.

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

Streamování úlohy riggingu

Tento koncový bod streamuje aktualizace úlohy riggingu v reálném čase pomocí Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy riggingu, kterou chcete streamovat.

Vrací

Vrací stream objektů úlohy riggingu jako Server-Sent Events.

U úloh PENDING nebo IN_PROGRESS bude stream odpovědi obsahovat pouze nezbytná pole progress a 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
}

Objekt úlohy riggingu

Objekt Rigging Task představuje pracovní jednotku pro rigging postavy.

Vlastnosti

Name
id
Type
string
Description
Jedinečný identifikátor úlohy.
Name
type
Type
string
Description
Typ úlohy riggingu. Hodnota je rig.
Name
status
Type
string
Description
Stav úlohy. Možné hodnoty: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress úlohy (0-100). 0, pokud nebyla spuštěna, 100, pokud uspěla.
Name
created_at
Type
timestamp
Description
Časové razítko (milisekundy od epochy), kdy byla úloha vytvořena.
Časové razítko představuje počet milisekund uplynulých od 1. ledna 1970 UTC podle standardu RFC 3339. Například pátek 1. září 2023 12:00:00 PM GMT je reprezentován jako 1693569600000. To platí pro všechna časová razítka v Meshy API.
Name
started_at
Type
timestamp
Description
Časové razítko (milisekundy od epochy), kdy úloha začala zpracování. 0, pokud nebyla spuštěna.
Name
finished_at
Type
timestamp
Description
Časové razítko (milisekundy od epochy), kdy byla úloha dokončena. 0, pokud nebyla dokončena.
Name
expires_at
Type
timestamp
Description
Časové razítko (milisekundy od epochy), kdy vyprší platnost výsledných assetů úlohy a mohou být odstraněny.
Name
task_error
Type
object
Description
Podrobnosti o chybě u neúspěšných úloh. Úplnou referenci objektu task_error najdete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Přítomno, když je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. Pro úlohy FAILED vrací 0 (kredity se při selhání vracejí).
Name
result
Type
object
Description
Obsahuje URL výstupních assetů, pokud úloha SUCCEEDED, jinak null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL ke stažení narigované postavy ve formátu FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL ke stažení narigované postavy ve formátu GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Obsahuje URL pro výchozí animace. (např. pokud bylo generate_basic_animations implicitně true nebo ve výchozím nastavení povoleno).
  Name
  walking_glb_url
  Type
  string
  Description
  URL ke stažení animace chůze ve formátu GLB (se skinem).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL ke stažení animace chůze ve formátu FBX (se skinem).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL ke stažení armatury animace chůze ve formátu GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL ke stažení animace běhu ve formátu GLB (se skinem).
  Name
  running_fbx_url
  Type
  string
  Description
  URL ke stažení animace běhu ve formátu FBX (se skinem).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL ke stažení armatury animace běhu ve formátu GLB.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úloh ve frontě. Smysluplné pouze v případě, že stav je 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
}