Rigging API

Rigging API:n låter dig programmera in ett skelett (armatur) till 3D-humanoida 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 programmerbar rigging för närvarande endast fungerar bra med standard humanoida (tvåbenta) assets med tydligt definierade lemmar och kroppsstruktur vid denna tidpunkt.

POST/openapi/v1/rigging

Skapa en Rigging-uppgift

Detta endpoint tillåter dig att skapa en ny rigging-uppgift för en given 3D-modell. Vid framgångsrikt slutförande tillhandahåller den en riggad karaktär i standardformat och valfritt grundläggande gång-/springanimationer.

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

  • Otexturerade mesh
  • Icke-humanoida assets
  • Humanoida assets med oklar lem- och kroppsstruktur

När du använder input_task_id stöds inte modeller med mer än 300,000 ytor för rigging. Vänligen använd Remesh API för att minska antalet ytor innan rigging.

När du använder model_url måste karaktärens ansikte peka mot +Z-axeln (den standard glTF framåtriktningen). Modeller som pekar mot andra axlar kommer att misslyckas med pose-estimering.

Parametrar

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

  • Name
    input_task_id
    Type
    string
    Obligatorisk
    Description

    Den inmatningsuppgift som behöver riggas. Vi stöder för närvarande texturerade humanoida modeller.

  • Name
    model_url
    Type
    string
    Obligatorisk
    Description

    Vänligen tillhandahåll 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).

  • 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 riggingnoggrannhet. Det måste vara ett positivt tal.

  • Name
    texture_image_url
    Type
    string
    Description

    Modellens UV-avvecklade basfärgtexturbild. Offentligt tillgänglig URL eller Data URI. Vi stöder för närvarande .png format.

Returnerar

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

Felmod

  • Name
    400 - Bad Request
    Description

    Begäran var oacceptabel. Vanliga orsaker:

    • Saknad parameter: Antingen model_url eller input_task_id måste tillhandahållas.
    • Ogiltigt modellformat: model_url pekar på en fil med en icke-stödd filändelse (endast .glb stöds).
    • Oåtkomlig URL: model_url kunde inte laddas ner.
    • Ogiltig inmatningsuppgift: input_task_id hänvisar inte till en giltig API-uppgift.
    • Överskridet antal ytor: Inmatningsmodellen har mer än 300,000 ytor. Vänligen använd Remesh API för att minska antalet ytor innan rigging.
  • Name
    401 - Unauthorized
    Description

    Autentisering misslyckades. Vänligen kontrollera din API-nyckel.

  • Name
    402 - Payment Required
    Description

    Otillräckliga credits för att utföra denna uppgift.

  • Name
    422 - Unprocessable Entity
    Description

    Pose-estimering misslyckades. Den tillhandahållna 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

Detta endpoint tillåter dig att hämta en rigging-uppgift givet ett giltigt uppgifts-id. Se The Rigging Task Object 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-uppgiftsobjektet. Kontrollera 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 associerade modeller och data. Denna åtgärd är oåterkallelig.

Sökvägsparametrar

  • Name
    id
    Type
    path
    Description

    ID för den rigging-uppgift som ska tas bort.

Returnerar

Returnerar 200 OK vid framgång.

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

Lista Rigging-uppgifter

Returnerar en paginerad lista över uppringarens rigging-uppgifter, nyaste först. Standardpaginering via page_num och page_size.

Observera att uppgifter skapade genom API hanteras genom API — 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 Rigging-uppgift

Detta endpoint strömmar realtidsuppdateringar för en Rigging-uppgift med hjälp av Server-Sent Events (SSE).

Parametrar

  • Name
    id
    Type
    path
    Description

    Unik identifierare för Rigging-uppgiften att strömma.

Returnerar

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

För PENDING eller IN_PROGRESS uppgifter kommer svarströmmen endast att inkludera nödvändiga progress och status fält.

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
}

Objektet för Rigging-uppgiften

Objektet för Rigging-uppgiften representerar arbetsenheten för rigging av 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

    Status för uppgiften. Möjliga värden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Framsteg för uppgiften (0-100). 0 om inte påbörjad, 100 om lyckad.

  • Name
    created_at
    Type
    timestamp
    Description

    Tidsstämpel (millisekunder sedan epok) när uppgiften skapades.

    En tidsstämpel representerar antalet millisekunder som har gått sedan den 1 januari 1970 UTC, enligt RFC 3339-standarden. Till exempel, fredag den 1 september 2023 kl. 12:00:00 GMT representeras som 1693569600000. Detta gäller för alla tidsstämplar i Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Tidsstämpel (millisekunder sedan epok) när uppgiften började bearbetas. 0 om inte påbörjad.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tidsstämpel (millisekunder sedan epok) när uppgiften avslutades. 0 om inte avslutad.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tidsstämpel (millisekunder sedan epok) när uppgiftens resultat-asset går ut och kan raderas.

  • Name
    task_error
    Type
    object
    Description

    Felformationer för misslyckade uppgifter. Se Fel för fullständig referens till task_error-objektet.

  • Name
    consumed_credits
    Type
    integer
    Description

    Antalet credits som förbrukats av denna uppgift. Förekommer 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 för utdata-asset om uppgiften SUCCEEDED, null annars.

    • 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 sant eller aktiverat som standard).

      • Name
        walking_glb_url
        Type
        string
        Description
        Nedladdningsbar URL för gånganimation i GLB-format (med hud).
      • Name
        walking_fbx_url
        Type
        string
        Description
        Nedladdningsbar URL för gånganimation i FBX-format (med hud).
      • 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 löpanimation i GLB-format (med hud).
      • Name
        running_fbx_url
        Type
        string
        Description
        Nedladdningsbar URL för löpanimation i FBX-format (med hud).
      • Name
        running_armature_glb_url
        Type
        string
        Description
        Nedladdningsbar URL för löpanimationens armatur i GLB-format.
  • Name
    preceding_tasks
    Type
    integer
    Description

    Antalet föregående uppgifter i kön. Meningsfullt endast om status är PENDING.

Exempel på Rigging-uppgiftsobjekt

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