Rigging API

Rigging API:n låter dig programmatiskt lägga till ett skelett (armatur) till humanoida 3D-modeller och binda nätet 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 rigging för närvarande endast fungerar bra med vanliga humanoida (bipedala) assets med tydligt definierade lemmar och kroppsstruktur.

POST/openapi/v1/rigging

Skapa en Rigging-uppgift

Denna endpoint låter dig skapa en ny riggningsuppgift för en given 3D-modell. Vid lyckad slutförande tillhandahåller den en riggad karaktär i standardformat och eventuellt enkla animationer för att gå/springa.

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

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

Nät utan textur
Icke-humanoida assets
Humanoida assets med otydlig lemm- och kroppsstruktur

Vid användning av input_task_id stöds inte modeller med mer än 300 000 polygoner för riggning. Använd Remesh API för att minska polygonantalet innan riggning.

Vid användning av model_url måste karaktärens ansikte peka mot +Z-axeln (den standardmässiga framåtriktningen för glTF). Modeller som är vända mot andra axlar kommer att misslyckas med poseuppskattning.

Parametrar

Endast en av input_task_id eller model_url krävs. Om båda anges har input_task_id prioritet.

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

Name
model_url
Type
string
Obligatorisk
Description
Vänligen ange en 3D-modell för Meshy att rigga via en offentligt tillgänglig URL eller Data URI. Vi stöder för närvarande texturerade humanoida GLB-filer (.glb-format).
Maximal filstorlek: 400 MB för en http- eller https-URL, 100 MB för en data:-URI.
En fil över 100 MB med mer än 10 000 000 polygoner returnerar 400. Polygoner räknas som trianglar, och ett nät som ritas mer än en gång räknas en gång per kopia. En GLB över 100 MB får inte använda Draco-komprimering.

Name
height_meters
Type
number
standard 1.7
Description
Den ungefärliga höjden på karaktärsmodellen i meter. Detta underlättar skalning och riggningsnoggrannhet. Det måste vara ett positivt tal.
Name
texture_image_url
Type
string
Description
Modellens UV-upprullade baskulör-texturbild. Offentligt tillgänglig URL eller Data URI. Vi stöder för närvarande .png-format.
Maximal filstorlek: 20 MB.

Returnerar

Svarets result-egenskap innehåller den nyss skapade riggningsuppgiftens id.

Felscenarier

Name
400 - Bad Request
Description
Begäran var oacceptabel. Vanliga orsaker:
- Saknad parameter: Antingen model_url eller input_task_id måste anges.
- Ogiltigt modellformat: model_url pekar på en fil med en filändelse som inte stöds (endast .glb stöds).
- Onåbar URL: model_url kunde inte laddas ner.
- Modellfilen för stor: model_url-filen överskrider 400 MB (http- eller https-URL) eller 100 MB (data:-URI).
- För många polygoner: model_url-filen är över 100 MB och har mer än 10 000 000 polygoner. Minska polygonantalet och skicka sedan filen igen.
- Oläsbar modellfil: model_url-filen är över 100 MB och dess header kan inte läsas, exempelvis en Draco-komprimerad GLB.
- Modellhuvud för komplext: 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 sedan igen.
- Bild för stor: texture_image_url-bilden överskrider 20 MB.
- Ogiltig inmatningsuppgift: input_task_id refererar inte till en giltig API-uppgift.
- Polygonantal överskridet: Inmatningsmodellen har fler än 300 000 polygoner. Använd Remesh API för att minska polygonantalet innan riggning.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckliga credits för att utföra denna uppgift.
Name
422 - Unprocessable Entity
Description
Poseuppskattning misslyckades. Den angivna modellen är kanske inte 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 Task

Denna endpoint låter dig hämta en rigging task med ett giltigt task-id. Se The Rigging Task Object för vilka egenskaper som ingår.

Parametrar

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

Returnerar

Svaret innehåller Rigging Task-objektet. Se avsnittet The Rigging Task Object för detaljer.

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 tillhörande modeller och data. Denna åtgärd är oåterkallelig.

Sökvägsparametrar

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

Uppgiftsstatus

En uppgift som fortfarande är PENDING tas bort och de credits som förbrukades vid skapandet återbetalas.

En uppgift som redan är IN_PROGRESS kan inte tas bort: begäran avvisas med 409 Conflict och uppgiften fortsätter att köra. Credits för en uppgift som arbetaren redan har påbörjat kan inte återbetalas, så att ta bort den mitt i körningen skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

En uppgift i ett slutgiltigt tillstånd (SUCCEEDED, FAILED eller CANCELED) tas bort utan återbetalning.

Returvärden

Returnerar 200 OK vid lyckad borttagning, eller 409 Conflict när uppgiften är IN_PROGRESS.

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

GET/openapi/v1/rigging

Lista riggningsuppgifter

Returnerar en paginerad lista över anroparens riggningsuppgifter, nyaste först. Standardpaginering via page_num och page_size.

Observera att uppgifter som skapats via API:et hanteras via API:et — de visas inte i webbappens Mina tillgångar. Använd denna endpoint för att hitta en uppgift vars ID du inte längre har.

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 riggningsuppgift

Denna endpoint strömmar 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 strömmas.

Returnerar

Returnerar en ström av The Rigging Task Objects som Server-Sent Events.

För uppgifter med status 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
}

The Rigging Task Object

Rigging Task-objektet representerar arbetsenheten för att rigga en karaktär.

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften.
Name
type
Type
string
Description
Typ av Rigging-uppgift. 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 inte påbörjad, 100 om lyckad.
Name
created_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) 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 fredagen den 1 september 2023 12:00:00 PM GMT som 1693569600000. Detta gäller för alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiften började bearbetas. 0 om inte påbörjad.
Name
finished_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiften avslutades. 0 om inte avslutad.
Name
expires_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiftens resultat-assets upphör att gälla och kan komma att raderas.
Name
task_error
Type
object
Description
Felinformation för misslyckade uppgifter. Se Fel för den fullständiga referensen för task_error-objektet.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Finns när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid misslyckande).
Name
result
Type
object
Description
Innehåller URL:er till resultat-assets om uppgiften är 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 aktiverad 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 gånganimationens armatur i GLB-format.
  Name
  running_glb_url
  Type
  string
  Description
  Nedladdningsbar URL för springanimation i GLB-format (med skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för springanimation i FBX-format (med skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Nedladdningsbar URL för springanimationens armatur i GLB-format.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter i kön. Endast relevant 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
}