Rigging API

Rigging API vám umožňuje programově přidat kostru (armaturu) k 3D humanoidním modelům a připojit k ní síť, aby byly připraveny k animaci. Pro aplikaci animací na postavu s kostrou viz Animace API.

Vezměte prosím na vědomí, že programové rigging v současné době funguje dobře pouze se standardními humanoidními (bipedálními) assety s jasně definovanými končetinami a strukturou těla.

POST/openapi/v1/rigging

Vytvoření úkolu pro rigging

Tento endpoint vám umožňuje vytvořit nový úkol pro rigging pro daný 3D model. Po úspěšném dokončení poskytne rigged postavu ve standardních formátech a volitelně základní animace chůze/běhu.

V současné době není automatický rigging vhodný pro následující modely:

  • Meshy bez textury
  • 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 podporovány pro rigging. Použijte prosím Remesh API ke snížení počtu ploch před riggingem.

Při použití model_url musí být obličej postavy orientován směrem k ose +Z (standardní směr vpřed pro glTF). Modely orientované k jiným osám selžou při odhadu pózy.

Parametry

Pouze jeden z input_task_id nebo model_url je požadován. Pokud jsou poskytnuty oba, input_task_id má prioritu.

  • Name
    input_task_id
    Type
    string
    Povinné
    Description

    Vstupní úkol, který je potřeba riggovat. V současné době podporujeme texturované humanoidní modely.

  • Name
    model_url
    Type
    string
    Povinné
    Description

    Poskytněte prosím 3D model pro Meshy k riggování prostřednictvím veřejně přístupného URL nebo Data URI. V současné době podporujeme texturované humanoidní GLB soubory (.glb formát).

  • Name
    height_meters
    Type
    number
    výchozí 1.7
    Description

    Přibližná výška modelu postavy v metrech. To pomáhá při škálování a přesnosti riggingu. Musí to být kladné číslo.

  • Name
    texture_image_url
    Type
    string
    Description

    UV-rozbalený základní barevný texturový obrázek modelu. Veřejně přístupné URL nebo Data URI. V současné době podporujeme .png formáty.

Návraty

Vlastnost result odpovědi obsahuje id nově vytvořeného úkolu pro rigging.

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 poskytnut buď model_url nebo input_task_id.
    • Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou (pouze .glb je podporováno).
    • Nedosažitelné URL: model_url nemohl být stažen.
    • Neplatný vstupní úkol: input_task_id neodkazuje na platný API úkol.
    • Překročený počet ploch: Vstupní model má více než 300 000 ploch. Použijte prosím Remesh API ke snížení počtu ploch před riggingem.
  • Name
    401 - Unauthorized
    Description

    Autentizace selhala. Zkontrolujte prosím váš API klíč.

  • Name
    402 - Payment Required
    Description

    Nedostatečné kredity pro provedení tohoto úkolu.

  • Name
    422 - Unprocessable Entity
    Description

    Odhad pózy selhal. Poskytnutý model nemusí být platná humanoidní postava.

  • 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číst úkol riggingu

Tento koncový bod vám umožňuje načíst úkol riggingu na základě platného id úkolu. Podívejte se na Objekt úkolu riggingu, abyste viděli, které vlastnosti jsou zahrnuty.

Parametry

  • Name
    id
    Type
    path
    Description

    Unikátní identifikátor pro úkol riggingu, který chcete načíst.

Vrací

Odpověď obsahuje objekt úkolu riggingu. Podrobnosti naleznete v sekci Objekt úkolu riggingu.

Požadavek

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

Odpověď

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

Smazání úkolu riggingu

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

Parametry cesty

  • Name
    id
    Type
    path
    Description

    ID úkolu riggingu, který chcete smazat.

Vrátí

Vrátí 200 OK při úspěchu.

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

Seznam úkolů pro rigging

Vrací stránkovaný seznam úkolů pro rigging volajícího, nejnovější jako první. Standardní stránkování pomocí page_num a page_size.

Všimněte si, že úkoly vytvořené prostřednictvím API jsou spravovány prostřednictvím API — neobjevují se v sekci Moje assety webové aplikace. Použijte tento koncový bod k nalezení úkolu, jehož ID již nemáte.

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 Rigging

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

Parametry

  • Name
    id
    Type
    path
    Description

    Unikátní identifikátor pro úlohu Rigging ke streamování.

Vrací

Vrací stream Objektů úlohy Rigging jako Server-Sent Events.

Pro úlohy ve stavu 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 úkolu riggingu

Objekt úkolu riggingu představuje pracovní jednotku pro rigging postavy.

Vlastnosti

  • Name
    id
    Type
    string
    Description

    Unikátní identifikátor pro úkol.

  • Name
    type
    Type
    string
    Description

    Typ úkolu riggingu. Hodnota je rig.

  • Name
    status
    Type
    string
    Description

    Stav úkolu. Možné hodnoty: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress úkolu (0-100). 0 pokud nebyl zahájen, 100 pokud byl úspěšný.

  • Name
    created_at
    Type
    timestamp
    Description

    Časové razítko (milisekundy od epochy), kdy byl úkol vytvořen.

    Č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 GMT je reprezentován jako 1693569600000. Toto platí pro všechna časová razítka v Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Časové razítko (milisekundy od epochy), kdy úkol začal být zpracováván. 0 pokud nebyl zahájen.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko (milisekundy od epochy), kdy byl úkol dokončen. 0 pokud nebyl dokončen.

  • Name
    expires_at
    Type
    timestamp
    Description

    Časové razítko (milisekundy od epochy), kdy vyprší platnost výsledných assetů úkolu a mohou být smazány.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě pro neúspěšné úkoly. Viz Chyby pro úplný odkaz na objekt task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů spotřebovaných tímto úkolem. Přítomno, když je stav úkolu PENDING, IN_PROGRESS nebo SUCCEEDED. Vrací 0 pro úkoly FAILED (kredity jsou při selhání vráceny).

  • Name
    result
    Type
    object
    Description

    Obsahuje URL výstupních assetů, pokud úkol SUCCEEDED, jinak null.

    • Name
      rigged_character_fbx_url
      Type
      string
      Description

      Stáhnutelná URL pro rigged postavu ve formátu FBX.

    • Name
      rigged_character_glb_url
      Type
      string
      Description

      Stáhnutelná URL pro rigged postavu ve formátu GLB.

    • Name
      basic_animations
      Type
      object (optional)
      Description

      Obsahuje URL pro výchozí animace. (např. pokud bylo generate_basic_animations implicitně pravdivé nebo povoleno ve výchozím nastavení).

      • Name
        walking_glb_url
        Type
        string
        Description
        Stáhnutelná URL pro animaci chůze ve formátu GLB (s kůží).
      • Name
        walking_fbx_url
        Type
        string
        Description
        Stáhnutelná URL pro animaci chůze ve formátu FBX (s kůží).
      • Name
        walking_armature_glb_url
        Type
        string
        Description
        Stáhnutelná URL pro armaturu animace chůze ve formátu GLB.
      • Name
        running_glb_url
        Type
        string
        Description
        Stáhnutelná URL pro animaci běhu ve formátu GLB (s kůží).
      • Name
        running_fbx_url
        Type
        string
        Description
        Stáhnutelná URL pro animaci běhu ve formátu FBX (s kůží).
      • Name
        running_armature_glb_url
        Type
        string
        Description
        Stáhnutelná URL pro armaturu animace běhu ve formátu GLB.
  • Name
    preceding_tasks
    Type
    integer
    Description

    Počet předcházejících úkolů ve frontě. Má smysl pouze, pokud je stav 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
}