Rigging API

Přidejte kostru (armaturu) k humanoidnímu 3D modelu a svažte s ní síť, aby byla postava připravena k animaci. Chcete-li aplikovat animace na postavu s kostrou, podívejte se na Animation API.

Rigging funguje dobře pouze u standardních humanoidních (dvounohých) postav, které mají jasně definovanou strukturu končetin a těla.

POST/openapi/v1/rigging

Vytvoření úlohy Rigging

Vytvoří úlohu Rigging pro 3D model. Po úspěšném dokončení vrátí vyriggovanou postavu ve standardních formátech a volitelně základní animace chůze a běhu.

Úloha běží na pozadí. Informace o obvyklé délce zpracování najdete v části Doby zpracování.

Rigging není vhodný pro tyto modely:

Sítě bez textur
Assety, které nejsou humanoidní
Humanoidní assety s nejasnou strukturou končetin a těla

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"
}

Parametry

Name
input_task_id
Type
string
Povinné
Description
Vyžadováno, pokud neodešlete model_url. ID úlohy, jejíž model chcete vyriggovat. Meshy podporuje texturované humanoidní modely.
Model může mít nejvýše 380 000 trojúhelníků (čtyřúhelník se počítá jako 2), a model s vyšším počtem vrátí 400. Abyste zůstali pod limitem, nejprve na něm spusťte Remesh API s hodnotou target_polycount 300000 nebo nižší, případně 150000 nebo nižší při topology: quad.

Name
model_url
Type
string
Povinné
Description
Vyžadováno, pokud neodešlete input_task_id. Model k vyriggování jako veřejná URL adresa nebo data URI. Pokud odešlete obojí, Meshy použije input_task_id.
Model musí být soubor GLB (.glb) o velikosti nejvýše 400 MB z URL adresy http nebo https, nebo 100 MB jako data URI. Rigging podporuje texturované humanoidní modely.
Model může mít nejvýše 380 000 trojúhelníků (čtyřúhelník se počítá jako 2), a model s vyšším počtem vrátí 400. Abyste zůstali pod limitem, nejprve na něm spusťte Remesh API s hodnotou target_polycount 300000 nebo nižší, případně 150000 nebo nižší při topology: quad.
Obličej postavy musí směřovat ve směru osy +Z, standardního směru „vpřed“ ve formátu glTF. U modelu, který směřuje jinou osou, selže odhad pozy.
Soubor nad 100 MB musí navíc splňovat tato pravidla:
- Může mít nejvýše 10 000 000 ploch. Soubor s vyšším počtem vrátí 400. Meshy počítá plochy jako trojúhelníky a síť vykreslená vícekrát se počítá jednou za každou kopii.
- Nesmí používat kompresi Draco.

Name
height_meters
Type
number
výchozí 1.7
Description
Přibližná výška postavy v metrech. Meshy ji používá k přesnějšímu škálování a riggování modelu. Záporná hodnota vrátí 400.
Name
texture_image_url
Type
string
⚠ zastaralé
Description
Vynechte, pokud má model vlastní textury. Bez tohoto parametru Meshy použije textury vložené v souboru model_url, nebo textury ze vstupní úlohy. Pokud jej odešlete, tento obrázek se stane jedinou texturou vyriggovaného modelu a model ztratí své PBR mapy.
UV-rozbalená základní barevná textura modelu jako veřejná URL adresa nebo data URI. Obrázek musí být soubor PNG o velikosti nejvýše 20 MB. Jiný formát obrázku vrátí 400.

Návratová hodnota

Pole result v odpovědi obsahuje ID nové úlohy Rigging.

Způsoby selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Chybová zpráva uvádí, jaký problém byl zjištěn. Například:
- Chybějící parametr: Nebyl odeslán ani model_url, ani input_task_id.
- Neplatný formát modelu: Soubor model_url má nepodporovanou příponu. Podporován je pouze .glb.
- Nedostupná URL: Meshy nemůže stáhnout soubor model_url.
- Příliš velký soubor modelu: Soubor model_url je větší než 400 MB z URL adresy http nebo https, nebo větší než 100 MB jako data URI.
- Příliš mnoho ploch: Soubor model_url je větší než 100 MB a má více než 10 000 000 ploch. Snižte počet ploch a soubor odešlete znovu.
- Nečitelný soubor modelu: Soubor model_url je větší než 100 MB a Meshy nemůže přečíst jeho hlavičku. Jde například o GLB komprimovaný pomocí Draco.
- Příliš složitá hlavička modelu: Soubor model_url je větší než 100 MB a jeho hlavička obsahuje příliš mnoho sítí, uzlů nebo záznamů ke kontrole. Snižte počet objektů v souboru a odešlete ho znovu.
- Příliš velký obrázek: Obrázek texture_image_url je větší než 20 MB.
- Neplatný formát textury: Obrázek texture_image_url není soubor PNG.
- Neplatná výška: height_meters je záporné.
- Neplatná vstupní úloha: input_task_id neodkazuje na platnou API úlohu.
- Vstupní úloha není připravena: Úloha input_task_id nedosáhla stavu SUCCEEDED. Počkejte, až bude úspěšná, a zkuste to znovu.
- Překročen počet ploch: Vstupní model má více než 380 000 trojúhelníků (čtyřúhelník se počítá jako 2). Před riggováním modelu na něm spusťte Remesh API s hodnotou target_polycount 300000 nebo nižší, případně 150000 nebo nižší při topology: quad.
Opravte požadavek a odešlete jej znovu. Viz Chyby.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
402 - Payment Required
Description
Například:
- Nedostatek kreditů: Účet nemá na tuto úlohu dostatek kreditů, nebo účet dosáhl limitu kreditů. Zkontrolujte svůj zůstatek kreditů a zkuste to znovu.
- Plán zdarma: Vytvoření úlohy vyžaduje placený plán. Upgradujte svůj plán v nastavení předplatného a zkuste to znovu.
Name
403 - Forbidden
Description
input_task_id je model reliéfu (bas-relief), který tento koncový bod nedokáže vyriggovat. Zpráva zní This model type does not support this operation. Odešlete jiný model.
Name
404 - Not Found
Description
Meshy nemůže najít soubory úlohy input_task_id. Platí jedna z těchto možností:
- Meshy odstranilo soubory úlohy po uplynutí jejího expires_at. Vytvořte úlohu znovu a odešlete ID této nové úlohy.
- Úloha neobsahuje žádný ze souborů potřebných pro rigging, například náhledový obrázek, jako je tomu například u úlohy Convert. Vyriggujte úlohu, ze které tato úloha vznikla, nebo odešlete model jako model_url.
Name
422 - Unprocessable Entity
Description
Odhad pozy se nezdařil. Model pravděpodobně není platnou humanoidní postavou. Odešlete model humanoidní postavy. U model_url také zkontrolujte, zda postava směřuje ve směru osy +Z.
Name
429 - Too Many Requests
Description
Překročili jste limit rychlosti. Počkejte a zkuste to znovu. Viz Limity rychlosti.

GET/openapi/v1/rigging/:id

Získání úkolu Rigging

Vrátí úkol Rigging podle jeho ID.

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": null,
  "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=..."
    }
  }
}

Parametry

Name
id
Type
path
Description
ID úkolu z odpovědi na vytvoření.

Návratová hodnota

Objekt úkolu Rigging.

DELETE/openapi/v1/rigging/:id

Smazání úlohy rigování

Trvale smaže úlohu rigování, včetně jejích modelů a dat. Smazání nelze vrátit zpět.

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 keeps 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."
}

Parametry cesty

Name
id
Type
path
Description
ID úlohy, která má být smazána.

Stav úlohy

Smazání úlohy ve stavu PENDING vrátí kredity, které byly použity při jejím vytvoření.

Úlohu ve stavu IN_PROGRESS nelze smazat. Požadavek vrátí 409 Conflict a úloha dál běží. Meshy nevrací kredity za úlohu, která už byla spuštěna, takže jejím smazáním byste přišli jak o kredity, tak o výsledek. Počkejte, až dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

Smazání úlohy v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) kredity nevrací.

Návratové hodnoty

200 OK, pokud je úloha smazána, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

GET/openapi/v1/rigging

Výpis úloh Rigging

Vrátí stránkovaný seznam vašich úloh Rigging, seřazený od nejnovějších. Pro procházení seznamu použijte page_num a page_size.

Úlohy vytvořené pomocí API zůstávají v API a nezobrazují se v sekci My Assets ve webové aplikaci. Pokud chcete najít úlohu, jejíž ID již nemáte, použijte tento koncový bod.

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

Streamování úlohy riggingu

Streamuje aktualizace úlohy riggingu jako Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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 event, with the same fields as the 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": null,
  "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?..."
    }
  }
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Proud objektů úlohy riggingu jako Server-Sent Events.

Každá událost obsahuje celý objekt úlohy ve stejné podobě, jakou vrací koncový bod Get. Dokud je úloha ve stavu PENDING nebo IN_PROGRESS, její výsledková pole zatím nemají hodnoty.

Objekt úlohy riggingu

Objekt úlohy riggingu popisuje rigging jedné postavy. Obsahuje stav, progress a výstupní soubory, pokud úloha uspěje.

Vlastnosti

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": null,
  "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=..."
    }
  }
}

Name
id
Type
string
Description
ID úlohy. Považujte jej za neprůhledný řetězec a nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úlohy, vždy rig.
Name
status
Type
string
Description
Stav úlohy, jedna z hodnot PENDING, IN_PROGRESS, SUCCEEDED, FAILED nebo CANCELED.
Name
progress
Type
integer
Description
Kolik z úlohy je hotovo, v procentech. Je 0, dokud úloha nezačne, a 100, když uspěje.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách Unix.
Name
started_at
Type
timestamp
Description
Čas zahájení úlohy, v milisekundách Unix. Je 0, dokud úloha nezačne.
Name
finished_at
Type
timestamp
Description
Čas dokončení úlohy, v milisekundách Unix. Je 0, dokud úloha neskončí.
Name
expires_at
Type
timestamp
Description
Čas, kdy vyprší platnost výsledných souborů úlohy, v milisekundách Unix. Po tomto čase může Meshy soubory smazat.
Name
task_error
Type
object
Description
Podrobnosti o chybě, pokud úloha selže. Je null, pokud stav není FAILED. Viz Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů, které úloha spotřebovala. Přítomno, když je stav PENDING, IN_PROGRESS nebo SUCCEEDED. U úlohy se stavem FAILED je 0, protože Meshy při selhání úlohy kredity vrací.
Name
result
Type
object
Description
URL adresy výstupních souborů. Dokud úloha neuspěje, každá URL adresa je prázdný řetězec a basic_animations je null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL ke stažení vyriggované postavy jako soubor FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL ke stažení vyriggované postavy jako soubor GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  URL ke stažení výchozích animací chůze a běhu.
  Name
  walking_glb_url
  Type
  string
  Description
  Animace chůze s kůží, jako soubor GLB.
  Name
  walking_fbx_url
  Type
  string
  Description
  Animace chůze s kůží, jako soubor FBX.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Armatura animace chůze, jako soubor GLB.
  Name
  running_glb_url
  Type
  string
  Description
  Animace běhu s kůží, jako soubor GLB.
  Name
  running_fbx_url
  Type
  string
  Description
  Animace běhu s kůží, jako soubor FBX.
  Name
  running_armature_glb_url
  Type
  string
  Description
  Armatura animace běhu, jako soubor GLB.
Name
preceding_tasks
Type
integer
Description
Počet úloh před touto úlohou ve frontě. Hodnota má smysl pouze tehdy, je-li úloha ve stavu PENDING. Toto pole je vynecháno, pokud je hodnota 0.