Rigging API

Rigging API låter dig programmatiskt lägga till ett skelett (armatur) till humanoida 3D-modeller, och binda nät till det så att de är redo för animation. För att applicera animationer på en riggad karaktär, se Animation API.

Observera att programmatisk riggning för närvarande endast fungerar bra med standardiserade humanoida (tvåbenta) assetar med tydligt definierade lemmar och kroppsstruktur.

POST/openapi/v1/rigging

Skapa en rigging-uppgift

Denna endpoint låter dig skapa en ny rigging-uppgift för en given 3D-modell. När den har slutförts tillhandahåller den en riggad karaktär i standardformat och valfritt grundläggande gång-/löpanimationer.

För närvarande är automatisk rigging inte lämplig för följande modeller:

Meshar utan textur
Icke-humanoida assets
Humanoida assets med oklar struktur för lemmar och kropp

När du använder input_task_id stöds inte modeller med fler än 300 000 ytor för rigging. Använd Remesh API för att minska antalet ytor före rigging.

När du använder model_url måste karaktärens ansikte vara riktat mot +Z-axeln (standardriktningen framåt i glTF). Modeller som är riktade mot andra axlar misslyckas med positionsuppskattningen.

Parametrar

Endast en av input_task_id eller model_url är obligatorisk. Om båda anges har input_task_id prioritet.

Name
input_task_id
Type
string
Obligatorisk
Description
Indatauppgiften som behöver riggas. Vi stöder för närvarande humanoida modeller med textur.

Name
model_url
Type
string
Obligatorisk
Description
Ange en 3D-modell som Meshy kan rigga via en offentligt tillgänglig URL eller Data URI. Vi stöder för närvarande humanoida GLB-filer med textur (.glb-format).

Name
height_meters
Type
number
standard 1.7
Description
Den ungefärliga höjden på karaktärsmodellen i meter. Detta hjälper till med skalning och rigging-noggrannhet. Det måste vara ett positivt tal.
Name
texture_image_url
Type
string
Description
Modellens UV-uppackade basfärgsbild för textur. Offentligt tillgänglig URL eller Data URI. Vi stöder för närvarande .png-format.

Returnerar

Egenskapen result i svaret innehåller uppgiftens id för den nyligen skapade rigging-uppgiften.

Fellägen

Name
400 - Bad Request
Description
Begäran var oacceptabel. Vanliga orsaker:
- Parameter saknas: Antingen model_url eller input_task_id måste anges.
- Ogiltigt modellformat: model_url pekar på en fil med ett filnamnstillägg som inte stöds (endast .glb stöds).
- Otillgänglig URL: model_url kunde inte laddas ned.
- Ogiltig indatauppgift: input_task_id refererar inte till en giltig API-uppgift.
- Antal ytor överskridet: Indatamodellen har fler än 300 000 ytor. Använd Remesh API för att minska antalet ytor före rigging.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckligt med credits för att utföra denna uppgift.
Name
422 - Unprocessable Entity
Description
Positionsuppskattningen misslyckades. Den angivna modellen kanske inte är en giltig humanoid karaktär.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.

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

Hämta en rigging-uppgift

Denna endpoint låter dig hämta en rigging-uppgift med ett giltigt uppgifts-id. Se Rigging Task-objektet för att se vilka egenskaper som ingår.

Parametrar

Name
id
Type
path
Description
Unik identifierare för rigging-uppgiften som ska hämtas.

Returnerar

Svaret innehåller Rigging Task-objektet. Se avsnittet Rigging Task-objektet för mer information.

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

Ta bort en rigging-uppgift

Denna endpoint tar permanent bort en rigging-uppgift, inklusive alla associerade modeller och data. Denna åtgärd är oåterkallelig.

Sökvägsparametrar

Name
id
Type
path
Description
ID:t för rigging-uppgiften som ska tas bort.

Returnerar

Returnerar 200 OK vid lyckat resultat.

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

Streama en riggningsuppgift

Denna endpoint streamar realtidsuppdateringar för en riggningsuppgift med hjälp av Server-Sent Events (SSE).

Parametrar

Name
id
Type
path
Description
Unik identifierare för riggningsuppgiften som ska streamas.

Returnerar

Returnerar en ström av riggningsuppgiftsobjekten som Server-Sent Events.

För uppgifter med PENDING eller IN_PROGRESS kommer svarsströmmen endast att innehålla nödvändiga fält för progress och 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
}

Riggningsuppgiftsobjektet

Riggningsuppgiftsobjektet representerar arbetsenheten för riggning av en karaktär.

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften.
Name
type
Type
string
Description
Typ av riggningsuppgift. Värdet är rig.
Name
status
Type
string
Description
Uppgiftens status. Möjliga värden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Uppgiftens progress (0-100). 0 om den inte har startats, 100 om den har lyckats.
Name
created_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoken) när uppgiften skapades.
En tidsstämpel representerar antalet millisekunder som har förflutit sedan 1 januari 1970 UTC, enligt standarden RFC 3339. Till exempel representeras fredag 1 september 2023 12:00:00 GMT som 1693569600000. Detta gäller alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoken) när uppgiften började bearbetas. 0 om den inte har startats.
Name
finished_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoken) när uppgiften slutfördes. 0 om den inte är slutförd.
Name
expires_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoken) när uppgiftens resultatassets löper ut och kan raderas.
Name
task_error
Type
object
Description
Feldetaljer för misslyckade uppgifter. Se Fel för den fullständiga objektreferensen för task_error.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av den här uppgiften. Finns när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel).
Name
result
Type
object
Description
Innehåller URL:er till utdataassets om uppgiften SUCCEEDED, annars null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för den riggade karaktären i FBX-format.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Nedladdningsbar URL för den riggade karaktären i GLB-format.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Innehåller URL:er för standardanimationer. (t.ex. om generate_basic_animations implicit var true eller aktiverat som standard).
  Name
  walking_glb_url
  Type
  string
  Description
  Nedladdningsbar URL för gånganimation i GLB-format (med skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för gånganimation i FBX-format (med skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Nedladdningsbar URL för armatur till gånganimation i GLB-format.
  Name
  running_glb_url
  Type
  string
  Description
  Nedladdningsbar URL för löpanimation i GLB-format (med skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för löpanimation i FBX-format (med skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Nedladdningsbar URL för armatur till löpanimation i GLB-format.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter i kön. Meningsfullt endast om status är 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
}