lowpoly avvecklas den 30 okt. 2026. Byt modell före dessa datum för att undvika fel i förfrågningar. Se alla utfasningar

Rigging API

Lägg till ett skelett (armatur) till en humanoid 3D-modell och bind nätet till det, så att karaktären är redo att animeras. För att applicera animationer på en riggad karaktär, se Animation API.

Rigging fungerar bara bra med standardhumanoida (bipedala) karaktärer som har en tydligt definierad lem- och kroppsstruktur.


POST/openapi/v1/rigging

Skapa en Rigging-uppgift

Skapar en Rigging-uppgift för en 3D-modell. När uppgiften lyckas returneras en riggad karaktär i standardformat och, valfritt, grundläggande gå- och springanimationer.

Uppgiften körs i bakgrunden. För hur lång tid en uppgift vanligtvis tar, se Bearbetningstider.

Rigging passar inte för dessa modeller:

  • Nät utan texturer
  • Icke-humanoida assets
  • Humanoida assets med otydlig lem- och kroppsstruktur

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

Parametrar

  • Name
    input_task_id
    Type
    string
    Obligatorisk
    Description

    Krävs om du inte skickar model_url. ID:t för uppgiften vars modell du vill rigga. Meshy stöder texturerade humanoida modeller.

    Modellen kan ha högst 380 000 trianglar (en quad räknas som 2), och en modell med fler returnerar 400. För att hålla dig under gränsen kör du Remesh API:et på den först med en target_polycount på 300000 eller mindre, eller 150000 eller mindre med topology: quad.

  • Name
    model_url
    Type
    string
    Obligatorisk
    Description

    Krävs om du inte skickar input_task_id. Modellen som ska riggas, som en offentlig URL eller en data-URI. Om du skickar båda använder Meshy input_task_id.

    Modellen måste vara en GLB-fil (.glb) på högst 400 MB från en http- eller https-URL, eller 100 MB som data-URI. Rigging stöder texturerade humanoida modeller.

    Modellen kan ha högst 380 000 trianglar (en quad räknas som 2), och en modell med fler returnerar 400. För att hålla dig under gränsen kör du Remesh API:et på den först med en target_polycount på 300000 eller mindre, eller 150000 eller mindre med topology: quad.

    Karaktärens ansikte måste peka mot +Z-axeln, den vanliga glTF-framåtriktningen. Poseuppskattningen misslyckas för en modell som är vänd mot en annan axel.

    En fil över 100 MB måste också följa dessa regler:

    • Den kan ha högst 10 000 000 ytor. En fil med fler returnerar 400. Meshy räknar ytor som trianglar, och ett nät som ritas flera gånger räknas en gång per kopia.
    • Den får inte använda Draco-komprimering.
  • Name
    height_meters
    Type
    number
    standard 1.7
    Description

    Karaktärens ungefärliga längd, i meter. Meshy använder det för att skala och rigga modellen mer exakt. Ett negativt värde returnerar 400.

  • Name
    texture_image_url
    Type
    string
    ⚠ föråldrad
    Description

    Utelämna den när modellen har sina egna texturer. Utan den använder Meshy texturerna inbäddade i model_url-filen, eller indatauppgiftens texturer. Om du skickar den blir denna bild den riggade modellens enda textur, och modellen förlorar sina PBR-mappar.

    Modellens UV-upplindade bas-färgstextur, som en offentlig URL eller en data-URI. Bilden måste vara en PNG-fil på högst 20 MB. Ett annat bildformat returnerar 400.

  • Name
    skeleton_template
    Type
    string
    standard meshyrig
    Description

    Skelettet för den riggade karaktären, som bestämmer dess bennamn och hierarki. Välj det som din motor eller ditt verktyg förväntar sig.

    Tillgängliga värden:

    • meshyrig: Meshys eget skelett
    • mixamo: Mixamo
    • ue5_mannequin: Unreal Engine 5 Mannequin
    • max_biped: 3ds Max Biped
    • unity_humanoid: Unity Humanoid
    • maya_human_ik: Maya HumanIK
    • blender_rigify_basic_human: Blender Rigify basic human
    • cc5_hd_neutral_base: Character Creator 5 HD neutral base
    • daz_genesis9: DAZ Genesis 9

    Alla andra värden returnerar 400. Fungerar endast med en tvåbent rig.

    Med ett annat värde än meshyrig, eller med include_fingers satt till true, är filerna i meter och använder det skelettets ben, istället för standardfilerna med 24 ben i meshyrig i centimeter. En modell som Meshy inte kan rigga med det skelettet gör att uppgiften misslyckas. Försök igen med meshyrig och include_fingers satt till false, eller med ett annat värde.

    I dessa filer heter animationsklippet retarget_clip och FBX-filen innehåller slutben. Några slutben, som headfront, behåller sina ursprungliga namn.

    Animation-uppgifter som skapas från denna rigg använder samma skelett.

  • Name
    include_fingers
    Type
    boolean
    standard false
    Description

    Om fingerben ska läggas till karaktärens händer. Fungerar endast med en tvåbent rig. Med meshyrig använder fingerbenen Mixamo-namn, som LeftHandThumb1.

    Med true returnerar dessa förfrågningar ett fel, och Meshy debiterar inte för dem:

    • En fyrbent rig, texture_image_url, eller ett input_task_id vars modell har quad-topology returnerar 400.
    • En modell som Meshy endast kan rigga utan fingerben returnerar 422.
    • Om Meshy inte kan rigga karaktärens händer med fingrar misslyckas uppgiften. Försök igen, eller sätt include_fingers till false.

    Meshy hittar fingrarna automatiskt och fungerar bäst på händer med tydligt separerade fingrar. På händer modellerade som en form, till exempel vantar, handskar eller stiliserade händer, kan riggen ha färre fingerben och animera handen som en enda del. Resten av skelettet är detsamma oavsett. Skelettet kan också innehålla extra ben, till exempel för hår eller kläder. Fingerben ändrar inte credits-kostnaden.

Returnerar

Fältet result i svaret innehåller ID:t för den nya Rigging-uppgiften.

Felscenarier

  • Name
    400 - Bad Request
    Description

    Förfrågan kan inte köras. Felmeddelandet anger vilket problem som hittades. Till exempel:

    • Saknad parameter: Varken model_url eller input_task_id skickades.
    • Ogiltigt modellformat: model_url-filen har ett filtillägg som inte stöds. Endast .glb stöds.
    • Onåbar URL: Meshy kan inte ladda ner model_url-filen.
    • Modellfilen för stor: model_url-filen är över 400 MB från en http- eller https-URL, eller över 100 MB som data-URI.
    • För många ytor: model_url-filen är över 100 MB och har fler än 10 000 000 ytor. Minska antalet ytor och skicka filen igen.
    • Oläsbar modellfil: model_url-filen är över 100 MB, och Meshy kan inte läsa dess header. Till exempel är det en Draco-komprimerad GLB.
    • Modellheadern för komplex: model_url-filen är över 100 MB, och dess header har för många nät, noder eller poster att kontrollera. Minska antalet objekt i filen och skicka den igen.
    • Bild för stor: texture_image_url-bilden är över 20 MB.
    • Ogiltigt texturformat: texture_image_url-bilden är inte en PNG-fil.
    • Ogiltig höjd: height_meters är negativ.
    • Ogiltig skelettmall: skeleton_template är inte ett av de tillgängliga värdena, eller skickades med en fyrbent rig.
    • Fingerben stöds inte: include_fingers är true med en fyrbent rig, texture_image_url, eller ett input_task_id vars modell har quad-topology.
    • Ogiltig indatauppgift: input_task_id refererar inte till en giltig API-uppgift.
    • Indatauppgift inte redo: Uppgiften input_task_id har inte nått SUCCEEDED. Vänta tills den lyckas och försök igen.
    • Ytantal överskridet: Indatamodellen har fler än 380 000 trianglar (en quad räknas som 2). Kör Remesh API:et på den med en target_polycount på 300000 eller mindre, eller 150000 eller mindre med topology: quad, innan du riggar modellen.

    Åtgärda förfrågan och skicka den igen. Se Fel.

  • Name
    401 - Unauthorized
    Description

    API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-headern.

  • Name
    402 - Payment Required
    Description

    Till exempel:

    • Otillräckliga credits: Kontot har inte tillräckligt med credits för denna uppgift, eller kontot har nått en creditgräns. Kontrollera ditt creditsaldo och försök igen.
    • Gratisplan: Att skapa en uppgift kräver en betald plan. Uppgradera din plan i dina prenumerationsinställningar och försök igen.
  • Name
    403 - Forbidden
    Description

    input_task_id är en basrelief-modell, vilket denna endpoint inte kan rigga. Meddelandet är This model type does not support this operation. Skicka en annan modell.

  • Name
    404 - Not Found
    Description

    Meshy kan inte hitta filerna för uppgiften input_task_id. Något av följande gäller:

    • Meshy raderade uppgiftens filer efter dess expires_at. Skapa uppgiften igen och skicka det nya uppgiftens ID.
    • Uppgiften saknar en eller flera av de filer rigging behöver, till exempel en förhandsgranskningsbild, till exempel en Convert-uppgift. Rigga uppgiften den kommer från, eller skicka modellen som model_url.
  • Name
    422 - Unprocessable Entity
    Description

    Till exempel:

    • Poseuppskattning misslyckades: Modellen kanske inte är en giltig humanoid karaktär. Skicka en modell av en humanoid karaktär. För model_url, kontrollera också att karaktären är vänd mot +Z-axeln.
    • Skelettmall otillgänglig: Meshy kan endast rigga denna modell på meshyrig-skelettet. Utelämna skeleton_template, eller sätt det till meshyrig. Meshy debiterar inte för förfrågan.
    • Fingerben otillgängliga: Meshy kan endast rigga denna modell på meshyrig utan fingerben. Utelämna include_fingers och skeleton_template. Meshy debiterar inte för förfrågan.
  • Name
    429 - Too Many Requests
    Description

    Du överskred din hastighetsgräns. Vänta och försök igen. Se Hastighetsgränser.

  • Name
    503 - Service Unavailable
    Description

    Meshy kunde inte slutföra analysen av modellens pose. Försök igen.


GET/openapi/v1/rigging/:id

Hämta en rigging-uppgift

Returnerar en rigging-uppgift baserat på dess 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=..."
    }
  }
}

Parametrar

  • Name
    id
    Type
    path
    Description

    Uppgifts-ID:t från skapandesvaret.

Returnerar

Rigging-uppgiftsobjektet.


DELETE/openapi/v1/rigging/:id

Ta bort en Rigging-uppgift

Tar bort en Rigging-uppgift permanent, inklusive dess modeller och data. Du kan inte ångra en borttagning.

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

Sökvägsparametrar

  • Name
    id
    Type
    path
    Description

    ID:t för uppgiften som ska tas bort.

Uppgiftsstatus

Att ta bort en PENDING-uppgift återbetalar de credits som användes när du skapade den.

En IN_PROGRESS-uppgift kan inte tas bort. Begäran returnerar 409 Conflict, och uppgiften fortsätter att köras. Meshy återbetalar inte en uppgift som har påbörjats, så att ta bort den skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

Att ta bort en uppgift i en slutgiltig status (SUCCEEDED, FAILED eller CANCELED) återbetalar inte dess credits.

Returnerar

200 OK när uppgiften har tagits bort, eller 409 Conflict när uppgiften är IN_PROGRESS.


GET/openapi/v1/rigging

Lista Rigging-uppgifter

Returnerar en paginerad lista över dina Rigging-uppgifter, nyaste först. För att bläddra igenom listan, använd page_num och page_size.

Uppgifter du skapar med API:et finns kvar i API:et och visas inte i Mina tillgångar i webbappen. För att hitta en uppgift vars ID du inte längre har, använd denna endpoint.

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

Strömma en Rigging-uppgift

Strömmar uppdateringar för en Rigging-uppgift som 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?..."
    }
  }
}

Parametrar

  • Name
    id
    Type
    path
    Description

    Uppgifts-ID:t från skapandesvaret.

Returnerar

En ström av Rigging-uppgiftsobjekt som Server-Sent Events.

Varje event innehåller hela uppgiftsobjektet, i samma format som Get-endpointen returnerar. Medan uppgiften är PENDING eller IN_PROGRESS har dess resultatfält ännu inga värden.


Riggingaktivitetsobjektet

Ett riggingaktivitetsobjekt beskriver riggingen av en karaktär. Det innehåller status, progress och utdatafilerna när aktiviteten lyckas.

Egenskaper

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

    Aktivitetens ID. Behandla det som en opak sträng och förlita dig inte på dess format.

  • Name
    type
    Type
    string
    Description

    Aktivitetstypen, alltid rig.

  • Name
    status
    Type
    string
    Description

    Aktivitetens status, en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED eller CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Hur stor del av aktiviteten som är klar, i procent. Den är 0 tills aktiviteten startar och 100 när den lyckas.

  • Name
    created_at
    Type
    timestamp
    Description

    Tidpunkten då aktiviteten skapades, i Unix-millisekunder.

  • Name
    started_at
    Type
    timestamp
    Description

    Tidpunkten då aktiviteten startade, i Unix-millisekunder. Den är 0 tills aktiviteten startar.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tidpunkten då aktiviteten avslutades, i Unix-millisekunder. Den är 0 tills aktiviteten avslutas.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tidpunkten då aktivitetens resultatfiler upphör att gälla, i Unix-millisekunder. Efter denna tidpunkt kan Meshy radera filerna.

  • Name
    task_error
    Type
    object
    Description

    Feldetaljerna när aktiviteten misslyckas. Den är null om inte statusen är FAILED. Se Fel.

  • Name
    consumed_credits
    Type
    integer
    Description

    Antalet credits som aktiviteten använde. Finns med när statusen är PENDING, IN_PROGRESS eller SUCCEEDED. Den är 0 för en FAILED-aktivitet, eftersom Meshy återbetalar credits när en aktivitet misslyckas.

  • Name
    result
    Type
    object
    Description

    URL:erna till utdatafilerna. Tills aktiviteten lyckas är varje URL en tom sträng, och basic_animations är null.

    • Name
      rigged_character_fbx_url
      Type
      string
      Description

      Nedladdnings-URL för den riggade karaktären som en FBX-fil.

    • Name
      rigged_character_glb_url
      Type
      string
      Description

      Nedladdnings-URL för den riggade karaktären som en GLB-fil.

    • Name
      basic_animations
      Type
      object (optional)
      Description

      Nedladdnings-URL:er för standardanimationerna för att gå och springa.

      • Name
        walking_glb_url
        Type
        string
        Description
        Gånganimationen med skinn, som en GLB-fil.
      • Name
        walking_fbx_url
        Type
        string
        Description
        Gånganimationen med skinn, som en FBX-fil.
      • Name
        walking_armature_glb_url
        Type
        string
        Description
        Gånganimationens armatur, som en GLB-fil.
      • Name
        running_glb_url
        Type
        string
        Description
        Springanimationen med skinn, som en GLB-fil.
      • Name
        running_fbx_url
        Type
        string
        Description
        Springanimationen med skinn, som en FBX-fil.
      • Name
        running_armature_glb_url
        Type
        string
        Description
        Springanimationens armatur, som en GLB-fil.
  • Name
    preceding_tasks
    Type
    integer
    Description

    Antalet aktiviteter som ligger före denna i kön. Värdet är endast meningsfullt medan aktiviteten är PENDING. Fältet utelämnas när värdet är 0.