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.
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
# 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 entarget_polycountpå300000eller mindre, eller150000eller mindre medtopology: 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 Meshyinput_task_id.Modellen måste vara en GLB-fil (
.glb) på högst 400 MB från enhttp- ellerhttps-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 entarget_polycountpå300000eller mindre, eller150000eller mindre medtopology: 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.
- Den kan ha högst 10 000 000 ytor. En fil med fler returnerar
- 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 skelettmixamo: Mixamoue5_mannequin: Unreal Engine 5 Mannequinmax_biped: 3ds Max Bipedunity_humanoid: Unity Humanoidmaya_human_ik: Maya HumanIKblender_rigify_basic_human: Blender Rigify basic humancc5_hd_neutral_base: Character Creator 5 HD neutral basedaz_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 medinclude_fingerssatt tilltrue, är filerna i meter och använder det skelettets ben, istället för standardfilerna med 24 ben imeshyrigi centimeter. En modell som Meshy inte kan rigga med det skelettet gör att uppgiften misslyckas. Försök igen medmeshyrigochinclude_fingerssatt tillfalse, eller med ett annat värde.I dessa filer heter animationsklippet
retarget_clipoch FBX-filen innehåller slutben. Några slutben, somheadfront, 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
meshyriganvänder fingerbenen Mixamo-namn, somLeftHandThumb1.Med
truereturnerar dessa förfrågningar ett fel, och Meshy debiterar inte för dem:- En fyrbent rig,
texture_image_url, eller ettinput_task_idvars modell har quad-topology returnerar400. - 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_fingerstillfalse.
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.
- En fyrbent rig,
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_urlellerinput_task_idskickades. - Ogiltigt modellformat:
model_url-filen har ett filtillägg som inte stöds. Endast.glbstö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 enhttp- ellerhttps-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ärtruemed en fyrbent rig,texture_image_url, eller ettinput_task_idvars modell har quad-topology. - Ogiltig indatauppgift:
input_task_idrefererar inte till en giltig API-uppgift. - Indatauppgift inte redo: Uppgiften
input_task_idhar inte nåttSUCCEEDED. 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_polycountpå300000eller mindre, eller150000eller mindre medtopology: quad, innan du riggar modellen.
Åtgärda förfrågan och skicka den igen. Se Fel.
- Saknad parameter: Varken
- 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 ärThis 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.
- Meshy raderade uppgiftens filer efter dess
- 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ämnaskeleton_template, eller sätt det tillmeshyrig. Meshy debiterar inte för förfrågan. - Fingerben otillgängliga: Meshy kan endast rigga denna modell på
meshyrigutan fingerben. Utelämnainclude_fingersochskeleton_template. Meshy debiterar inte för förfrågan.
- Poseuppskattning misslyckades: Modellen kanske inte är en giltig humanoid karaktär. Skicka en modell av en humanoid karaktär. För
- 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.
Hämta en rigging-uppgift
Returnerar en rigging-uppgift baserat på dess ID.
Request
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
Ta bort en Rigging-uppgift
Tar bort en Rigging-uppgift permanent, inklusive dess modeller och data. Du kan inte ångra en borttagning.
Request
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.
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
curl "https://api.meshy.ai/openapi/v1/rigging?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Strömma en Rigging-uppgift
Strömmar uppdateringar för en Rigging-uppgift som Server-Sent Events (SSE).
Request
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,FAILEDellerCANCELED.
- Name
- progress
- Type
- integer
- Description
Hur stor del av aktiviteten som är klar, i procent. Den är
0tills aktiviteten startar och100nä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
0tills aktiviteten startar.
- Name
- finished_at
- Type
- timestamp
- Description
Tidpunkten då aktiviteten avslutades, i Unix-millisekunder. Den är
0tills 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
nullom inte statusen ärFAILED. Se Fel.
- Name
- consumed_credits
- Type
- integer
- Description
Antalet credits som aktiviteten använde. Finns med när statusen är
PENDING,IN_PROGRESSellerSUCCEEDED. Den är0för enFAILED-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ärnull.- 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 är0.