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

Animation API

Applicera animationer på riggade karaktärer, och lista de animationer du kan applicera.

POST/openapi/v1/animations

Skapa en Animation-uppgift

Skapar en Animation-uppgift, som tillämpar en animation på en karaktär du riggade tidigare. Animationen kan vara en av följande:

  • En förinställd rörelse från animationsbiblioteket (action_id)
  • Flera förinställda rörelser sammanfogade till en fil (action_ids)
  • En rörelseklipp du genererat med Text to Motion API (motion_task_id)

Du kan också efterbehandla resultatet. Uppgiften körs i bakgrunden. För hur lång tid en uppgift vanligtvis tar, se Processing times.

Request

POST
/openapi/v1/animations
# Animate a rigged model with required params only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92
  }'

# Apply several preset actions and get one file with one clip per action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_ids": [10, 25, 92]
  }'

# Apply a generated Text to Motion clip instead of a preset action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
  }'

# With post-processing to change FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 24
    }
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

Parametrar

  • Name
    rig_task_id
    Type
    string
    Obligatorisk
    Description

    ID:t för Rigging-uppgiften vars karaktär ska animeras, från POST /openapi/v1/rigging. Uppgiften måste ha statusen SUCCEEDED.

Skicka exakt en av action_id, action_ids och motion_task_id.

  • Name
    action_id
    Type
    integer
    Obligatorisk
    Description

    Krävs om du inte skickar action_ids eller motion_task_id. ID:t för den förinställda animation som ska tillämpas. För den fullständiga listan över animationer, se Animationsbibliotek-referensen eller List animations.

  • Name
    action_ids
    Type
    array of integers
    Obligatorisk
    Description

    Krävs om du inte skickar action_id eller motion_task_id. ID:na för 1 till 10 förinställda animationer som ska tillämpas samtidigt, utan upprepningar. Fler än 10 ID:n, eller ett upprepat ID, ger 400. För ID:na, se Animationsbibliotek-referensen.

    Meshy returnerar en fil med ett animationsklipp per rörelse, vilket passar en tillståndsmaskin i en spelmotor. Meshy debiterar för varje rörelse i listan. Se Priser.

    En lista med ett ID fungerar likadant som att skicka det ID:t som action_id.

  • Name
    motion_task_id
    Type
    string
    Obligatorisk
    Description

    Krävs om du inte skickar action_id eller action_ids. ID:t för en Text to Motion-uppgift vars klipp ska tillämpas istället för en förinställd rörelse. Uppgiften måste ha statusen SUCCEEDED, och riggen måste vara tvåbent.

    Meshy omriktar klippet till den riggade karaktären. Det kopierar klippet när du skapar den här uppgiften, så den här uppgiften påverkas inte om Text to Motion-uppgiften senare upphör att gälla eller du tar bort den. Meshy behåller Text to Motion-uppgiftens filer i 3 dagar, så tillämpa klippet innan dess.

  • Name
    post_process
    Type
    object
    Description

    Efterbehandling för animationsresultatet. Utelämna den för att få de vanliga animationsfilerna.

    Med motion_task_id kan omriktningen producera en animation med enbart GLB. Om du skickar post_process och ingen FBX-fil är tillgänglig misslyckas uppgiften med ett task_error, och Meshy återbetalar dina credits. Utan post_process lyckas uppgiften, och animation_fbx_url är tom.

Gäller endast när post_process is set
  • Name
    operation_type
    Type
    string
    Description

    Åtgärden som ska köras. Utan den skapar Meshy ingen extra fil. Ett värde som inte finns i följande lista ger 400.

    Tillgängliga värden:

    • change_fps: ändrar bildfrekvensen till fps
    • fbx2usdz: konverterar animationen till USDZ
    • extract_armature: extraherar armaturen som en FBX-fil
  • Name
    fps
    Type
    integer
    standard 30
    Description

    Bildfrekvensen att ändra till, en av 24, 25, 30 eller 60. Gäller endast när operation_type är change_fps. Alla andra värden ger 400.

Med action_ids returnerar uppgiften en sammanslagen fil istället för en fil per rörelse. animation_glb_url och animation_fbx_url pekar vardera på en fil som innehåller varje begärd rörelse som ett separat klipp. I den filen:

  • Klippordning: ordningen i arrayen action_ids, inte den numeriska ordningen av ID:na.
  • Klippnamn: animationens namn i biblioteket. Dessa matchar namnen du får när du exporterar alla en karaktärs animationer som en fil från Meshys webbapp. Om två begärda ID:n har samma klippnamn lägger Meshy till action_id i det senare för att hålla namnen unika.
  • Efterbehandling: Meshy tillämpar den på den sammanslagna filen, inte på varje klipp.

Returnerar

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

Felmoder

  • Name
    400 - Bad Request
    Description

    Begäran kan inte köras. Felmeddelandet anger vilket problem det hittade. Till exempel:

    • Saknad parameter: rig_task_id saknas, eller ingen av action_id, action_ids och motion_task_id skickades.
    • Motstridiga parametrar: Begäran har mer än en av action_id, action_ids och motion_task_id. Skicka endast en.
    • Ogiltig riggningsuppgift: rig_task_id är inte ett giltigt uppgifts-ID, är inte en Rigging-uppgift, eller pekar på en uppgift som inte har lyckats.
    • Ogiltigt rörelse-ID: Ett action_id, eller en post i action_ids, är inte en giltig animation.
    • För många rörelser: action_ids har fler än 10 ID:n.
    • Dubbletter av rörelser: action_ids har samma ID mer än en gång.
    • Motion-uppgift inte klar: motion_task_id-uppgiften har inte nått SUCCEEDED ännu.
    • Rigg stöds inte: motion_task_id kräver en tvåbent rigg, och Meshy avvisar en fyrbent rigg.

    Åtgärda begäran och skicka den sedan 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 den här uppgiften, eller kontot har nått en creditgräns. Kontrollera ditt creditsaldo och försök sedan igen.
    • Gratisplan: Att skapa en uppgift kräver en betald plan. Uppgradera din plan i dina prenumerationsinställningar och försök sedan igen.
  • Name
    403 - Forbidden
    Description

    Uppgiften rig_task_id är en basreliefmodell, som denna endpoint inte kan animera. Meddelandet är This model type does not support this operation. Rigga en annan modell.

  • Name
    404 - Not Found
    Description

    Meshy kan inte hitta en uppgift eller fil som begäran behöver. Något av följande gäller:

    • Meshy kan inte hitta uppgiften rig_task_id bland dina uppgifter. Kontrollera ID:t.
    • Meshy tog bort filerna för uppgiften rig_task_id efter dess expires_at. Rigga karaktären igen.
    • Meshy kan inte hitta uppgiften motion_task_id. Kontrollera ID:t.
    • Rörelseklippet har upphört att gälla, eftersom Meshy behåller en Text to Motion-uppgifts filer i 3 dagar. Skapa en ny Text to Motion-uppgift.
  • Name
    429 - Too Many Requests
    Description

    Du överskred din hastighetsgräns. Vänta och försök sedan igen. Se Rate limits.

GET/openapi/v1/animations/:id

Hämta en Animation-uppgift

Returnerar en Animation-uppgift baserat på dess ID.

Request

GET
/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791
curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": null,
  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  }
}

Parametrar

  • Name
    id
    Type
    path
    Description

    Uppgifts-ID:t från skapandesvaret.

Returnerar

Animation-uppgiftsobjektet.

DELETE/openapi/v1/animations/:id

Radera en Animation-uppgift

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

Request

DELETE
/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/animations/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 raderas.

Uppgiftsstatus

Om du raderar en PENDING-uppgift återbetalas de credits som användes när du skapade den.

En IN_PROGRESS-uppgift kan inte raderas. Förfrågan returnerar 409 Conflict, och uppgiften fortsätter att köras. Meshy återbetalar inte en uppgift som har startat, så att radera den skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och radera den sedan.

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

Returnerar

200 OK när uppgiften raderas, eller 409 Conflict när uppgiften är IN_PROGRESS.

GET/openapi/v1/animations

Lista Animation-uppgifter

Returnerar en paginerad lista över dina Animation-uppgifter, nyaste först. För att bläddra genom listan använder du page_num och page_size.

Uppgifter som du skapar via API:et visas inte under My Assets i webbappen, så du hanterar dem via API:et. Använd denna endpoint för att hitta en uppgift vars ID du inte längre har.

Request

GET
/openapi/v1/animations
curl "https://api.meshy.ai/openapi/v1/animations?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/animations/:id/stream

Streama en Animation-uppgift

Streamar uppdateringar för en Animation-uppgift som Server-Sent Events (SSE).

Request

GET
/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream
curl -N https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/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": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, with the same structure as the Animation task object
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": null,
  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  }
}

Parametrar

  • Name
    id
    Type
    path
    Description

    Uppgifts-ID:t från skaparsvaret.

Returnerar

En ström av Animation task-objekt som Server-Sent Events.

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

Animation-uppgiftsobjektet

Ett Animation-uppgiftsobjekt beskriver en animation som tillämpas på en riggad karaktär. Det innehåller status, progress och animationsfilerna när uppgiften lyckas.

Egenskaper

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": null,
  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  }
}
  • Name
    id
    Type
    string
    Description

    Uppgifts-ID. Behandla det som en ogenomskinlig sträng och förlita dig inte på dess format.

  • Name
    type
    Type
    string
    Description

    Uppgiftstypen, alltid animate.

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    created_at
    Type
    timestamp
    Description

    Tidpunkten då uppgiften skapades, i Unix-millisekunder.

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

    Tidpunkten då uppgiften avslutades, i Unix-millisekunder. Den är 0 tills uppgiften är klar.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tidpunkten då uppgiftens resultatfiler går ut, i Unix-millisekunder.

  • Name
    task_error
    Type
    object
    Description

    Felinformationen när uppgiften misslyckas. Den är null om inte statusen är FAILED. Se Fel.

  • Name
    consumed_credits
    Type
    integer
    Description

    Antalet credits som uppgiften förbrukade. Finns med när statusen är PENDING, IN_PROGRESS eller SUCCEEDED. Den är 0 för en FAILED-uppgift, eftersom Meshy återbetalar credits när en uppgift misslyckas.

  • Name
    result
    Type
    object
    Description

    Nedladdningslänkar för animationsfilerna, när uppgiften har statusen SUCCEEDED.

    • Name
      animation_glb_url
      Type
      string
      Description
      Animationen som en GLB-fil. För en uppgift som skapats med action_ids innehåller denna enda fil varje begärd åtgärd som ett separat klipp.
    • Name
      animation_fbx_url
      Type
      string
      Description
      Animationen som en FBX-fil. För en uppgift som skapats med action_ids innehåller denna enda fil varje begärd åtgärd som ett separat klipp.
    • Name
      processed_usdz_url
      Type
      string
      Description
      Den bearbetade animationen som en USDZ-fil.
    • Name
      processed_armature_fbx_url
      Type
      string
      Description
      Den bearbetade armaturen som en FBX-fil.
    • Name
      processed_animation_fps_fbx_url
      Type
      string
      Description
      Animationen med den ändrade bildfrekvensen, som en FBX-fil, till exempel när du använde operationen change_fps.
  • Name
    preceding_tasks
    Type
    integer
    Description

    Antalet uppgifter före denna i kön. Värdet är meningsfullt endast medan uppgiften är PENDING. Fältet utelämnas när värdet är 0.

GET/openapi/v1/animations/library

Lista animationer

Returnerar varje animation i biblioteket, ordnade efter action_id. Svaret är den fullständiga listan, utan sidindelning, så ett enda anrop kan fylla en åtgärdsväljare. Filter begränsar resultatet. För att få alla animationer, utelämna dem alla.

För att bläddra i samma lista med en animerad förhandsvisning av varje åtgärd, se Animation Library-referensen.

Denna förfrågan kostar inga credits.

Request

GET
/openapi/v1/animations/library
curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

Parametrar

  • Name
    search
    Type
    string
    Description

    Text att söka efter. Meshy returnerar de animationer vars name eller key innehåller denna text, utan hänsyn till skiftläge. Meshy matchar texten bokstavligt, så % och _ är inte jokertecken.

  • Name
    category
    Type
    string
    Description

    Kategorin att lista, som en exakt matchning. En okänd kategori returnerar en tom lista.

    Tillgängliga värden:

    • WalkAndRun
    • BodyMovements
    • DailyActions
    • Fighting
    • Dancing
  • Name
    sub_category
    Type
    string
    Description

    Underkategorin att lista, som en exakt matchning. Du kan skicka den utan category. Underkategorinamn är inte unika mellan kategorier. Till exempel finns Transitioning under både Fighting och DailyActions. Så utan category matchar filtret underkategorin i varje kategori.

  • Name
    action_ids
    Type
    string
    Description

    De animationer som ska returneras, som upp till 200 kommaseparerade action_id-värden. Använd den för att slå upp specifika ID:n istället för att bläddra. Fler än 200 ID:n returnerar 400.

    Svaret utelämnar ett ID som ingen animation har. Så du kan också använda detta filter för att kontrollera om ID:n du har sparat fortfarande är tillgängliga.

Kombinera filter

Meshy tillämpar filtren tillsammans. Varje filter begränsar resultatet, så Meshy returnerar en animation endast om den matchar alla filter. Inom ett filter kan vilket som helst av dess värden matcha. Till exempel matchar search name eller key, och action_ids matchar vilket som helst ID i listan.

Så en kombination utan överlapp returnerar en tom array, inte ett fel. Åtgärd 92 är "Double Combo Attack", en Fighting-animation. Till exempel:

  • ?action_ids=92&category=Fighting returnerar åtgärd 92.
  • ?action_ids=92&category=Dancing returnerar [], eftersom den inte är en Dancing-animation.
  • ?action_ids=92&search=walk returnerar [], eftersom dess namn inte matchar walk.

För att få specifika animationer i vilken kategori som helst, skicka action_ids ensamt.

Returnerar

En lista med animationsobjekt.

Skapa en Animation-uppgift accepterar varje action_id denna endpoint returnerar, och denna endpoint returnerar varje ID som skapandet accepterar. Ingen av dem inkluderar pensionerade animationer. Om du cachelagrar biblioteket, uppdatera det då och då, så att ett pensionerat ID inte blir kvar i din väljare.

Animationsobjektet

Ett animationsobjekt beskriver en animation i biblioteket.

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}
  • Name
    action_id
    Type
    integer
    Description

    Värdet som skickas som action_id när du skapar en Animation-uppgift. Det är unikt och stabilt, men inte sammanhängande. Pensionerade animationer lämnar luckor i numreringen, så anta inte att varje ID inom ett intervall är giltigt.

  • Name
    name
    Type
    string
    Description

    Animationens visningsnamn. Det är inte unikt, eftersom vissa animationer delar namn med en annan variant. För att identifiera en animation, använd action_id eller key.

  • Name
    key
    Type
    string
    Description

    En unik, stabil slug för animationen. Använd den när du behöver ett icke-numeriskt ID att basera din egen lagring på.

  • Name
    category
    Type
    string
    Description

    Den övergripande gruppen, till exempel Fighting.

  • Name
    sub_category
    Type
    string
    Description

    Gruppen inom kategorin, till exempel AttackingwithWeapon.

  • Name
    preview_url
    Type
    string
    Description

    URL till en animerad GIF-förhandsgranskning av åtgärden. Du kan visa den direkt i din egen väljare.