Skip to main content
Glama

Generate character animations

generate_character_animation

PAID, and the cost MULTIPLIES BY THE NUMBER OF ANIMATIONS (each is its own image-to-video call; Wan 3.0 costs 150 credits/second, so its default 2-second clip is 300 credits). All frames are text-free by default: no subtitles, captions or invented writing. This is real motion — a walk cycle, an attack, an idle bob — not the 1-frame still that create_animation_from_pose produces. Read the character's gameType and use the standard animation names for it (get_character shows what already exists); the project gameType is irrelevant after character creation. A topdown character inside a platformer project still uses top-down prompts and directional behavior. A name that already exists is NEVER replaced: the server allocates the next numeric slug (walk → walk_2 → walk_3), and the returned animations list contains the resolved names. Ask the user which animations they want before spending: 4 animations cost 4x. For a topdown character, resolve the animation direction mode BEFORE choosing those animation names. Read animationDirection from get_character and preselect its Luna-classified mode; let the user override it. Pass animationDirectionMode on both the dry run and confirmed request: overhead uses one engine-rotated sprite with base action names and no 360; four_direction uses S/N/E/W rows with FREE four-pose image setup; eight_direction also uses diagonals and keeps the regular 360 video setup (+200 credits when newly needed). Overhead setup is free; animation videos are priced separately. Setup and Luna run only after animation generation is confirmed; the server creates the poses and automatically assigns matching facings without pose approval for four_direction, then continues animation generation. Poll all operation jobs while queued or running; an approved directionalPoseReview is a completion record, not a user checkpoint. The chosen mode is saved on the character. A missing classification is not permission to guess silently. Every animation defaults to 2 seconds, including walks, runs, attacks, and loops. Omit animDurations and customAnims[*].duration unless the user explicitly asks for a different clip length; never infer a longer duration from the motion or from the fact that it loops. If the character came from a successful 2x2 create, there may be two, three, four, or more siblings and animating is per-character: show the user the characterPreviews from get_job and have them pick one before you spend. For multi-direction sets, mirrorAnims gives you FREE flipped copies of a direction generated in the same call (walk_left from walk_right) — prefer a real generation when the character is asymmetric, because a held item switches sides under a mirror. The server uses the standard pose-aware animation pipeline for new requests; there is no flag argument to set. When the user wants stored poses as the actual video endpoints, call list_character_poses and pass their ids through poseFirstFrameIds / poseLastFrameIds. Omit those maps to let the server plan anchors automatically; never pass a pose URL. Before each new clip the server classifies the effective anchor as empty-handed, held, or unclear and adds the matching inventory-preservation lock automatically; there is no inventory argument to send. For platformer walk/run, the server-created cached mid-walk anchor pose is FREE; explicit pose generation remains paid. For eight-direction and legacy video-based topdown/isometric clips with targetFacings, automatic planning uses one cached standing internal 360 rotation for every action, including custom actions; its one-time surcharge is included in the dry-run quote. Do NOT call generate_character_turn merely to prepare an animation — that explicit visible turn is a separate action. When that internal 360 is needed, the job pauses at waiting_approval before any animation video starts. Present directionalPoseReview from get_job and call approve_directional_poses only after the user accepts the full set, including explicit confirmation to use any candidates they did not review individually. The dry-run response includes animationPipelineAssignmentToken; copy it verbatim into the confirmed call so the quoted pipeline decision cannot change while the user is deciding. If it expires, run the same dry-run again. The same response includes preflight with per-animation resolved names, durations and credits; setup and total credits; model resolution; runtime frame size; and explicit unknown-until-generated frame count/FPS/ETA. Show that structured preview instead of inventing precision. API-key calls can use the account's full wallet balance; the dashboard-only 600-credit limit and its first-animation exception do not apply. The independent key spend cap, paid-attempt ceiling, and ordinary wallet balance still apply. Returns { jobId, animations, operations, rejectedOperations? }; jobId is the first operation only for backward compatibility. Poll, retry, or cancel every operations[].jobId independently. When an operation reaches done, it returns an animationQualityGate requiring get_character; finish that review/repair loop before exporting or saying the animation is ready. A prompt that composes too long for the model is rejected with PROMPT_TOO_LONG before anything is charged, and the response names the animation. Check isTemplate on that entry: false means YOUR text is what is long, so shorten it; true means the shipped template is over the ceiling and no prompt you send can fix it — report it rather than retrying. DEFAULTS TO A COST PREVIEW — see the dryRun argument.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dryRunNoDEFAULTS TO TRUE. While true this returns only a cost quote ({ estimatedCredits, balance, spendCapDaily, spentLast24h, capRemaining }) and executes nothing. Show the user estimatedCredits, then ask a normal confirmation question. Prefer the client's native question UI with Approve / Decline / Discuss choices when available; otherwise accept any unambiguous conversational approval. Never require a fixed phrase or ask the user to type a magic word. Only after approval, re-call with dryRun:false to actually spend.
animationsYesAnimation slugs to generate, e.g. ["walk_right","idle"]. REQUIRED — each one is a separate paid video call.
videoModelNoOverride the video model.
animPromptsNoPer-animation extra guidance, keyed by animation slug. Folded into that animation's composed prompt.
characterIdYesCharacter id.
customAnimsNoDefine animations that are NOT part of the game type's standard set, keyed by the new slug.
mirrorAnimsNoFREE mirrored copies, keyed newName → sourceName (e.g. { "walk_left": "walk_right" }). The source must be in this call's animations list; its fresh frames are flipped in the same job at no extra cost.
animDurationsNoUSER-REQUESTED OVERRIDES ONLY (2-10s). Omit this field by default: every animation, including walks and loops, defaults to 2s. Never choose a longer clip unless the user explicitly requested that duration. Longer clips cost more.
targetFacingsNoCamera-relative facing per animation slug (n, ne, e, se, s, sw, w, nw). Omit for overhead; four_direction accepts only n/e/s/w. Use this for custom actions and any standard action whose slug does not itself encode the intended direction.
idempotencyKeyNoOptional Idempotency-Key for the real (dryRun:false) call. Omit and one is minted per call. Reuse the SAME value when retrying a call that failed with ENTITY_BUSY / 402 / 429 so the retry cannot double-dispatch.
poseLastFrameIdsNoOptional per-animation END anchor pose ids, keyed by animation slug. Resolve ids with list_character_poses and use only status:"done" poses. The same pose id may be used for both endpoints of a loop.
poseFirstFrameIdsNoOptional per-animation START anchor pose ids, keyed by animation slug. Resolve ids with list_character_poses and use only status:"done" poses. Omit an entry to let the server choose/generate its anchor.
animationDirectionModeNoChoose this BEFORE selecting animations for a topdown character and pass it on dry-run plus confirmation. Preselect get_character.animationDirection.mode when present (Luna suggestion; user may override). overhead uses one rotatable true-overhead sprite, base action names, and no 360; four_direction uses S/N/E/W animations; eight_direction also uses NE/SE/SW/NW. The confirmed choice is saved on the character.
animationPipelineAssignmentTokenNoOpaque server proof returned by this tool's dry-run. Copy it verbatim into the confirmed dryRun:false call; never create or edit it. If the server reports ANIMATION_PIPELINE_ASSIGNMENT_EXPIRED, preview again.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / dryRun / description
      Previous value: -"DEFAULTS TO TRUE. While true this returns only a cost quote ({ estimatedCredits, balance, spendCapDaily, spentLast24h, capRemaining }) and executes nothing. Show the user estimatedCredits and get an explicit yes for that amount, THEN re-call with dryRun:false to actually spend."New value: +"DEFAULTS TO TRUE. While true this returns only a cost quote ({ estimatedCredits, balance, spendCapDaily, spentLast24h, capRemaining }) and executes nothing. Show the user estimatedCredits, then ask a normal confirmation question. Prefer the client's native question UI with Approve / Decline / Discuss choices when available; otherwise accept any unambiguous conversational approval. Never require a fixed phrase or ask the user to type a magic word. Only after approval, re-call with dryRun:false to actually spend."
  2. Changed1 schema field changed
    • changedInput schema / properties / targetFacings / description
      Previous value: -"Camera-relative facing per animation slug (n, ne, e, se, s, sw, w, nw). Use this for custom actions and any standard action whose slug does not itself encode the intended direction."New value: +"Camera-relative facing per animation slug (n, ne, e, se, s, sw, w, nw). Omit for overhead; four_direction accepts only n/e/s/w. Use this for custom actions and any standard action whose slug does not itself encode the intended direction."
  3. Changed1 schema field changed
    • addedInput schema / properties / animationDirectionMode
      Added value: +{
      +  "description": "Choose this BEFORE selecting animations for a topdown character and pass it on dry-run plus confirmation. Preselect get_character.animationDirection.mode when present (Luna suggestion; user may override). overhead uses one rotatable true-overhead sprite, base action names, and no 360; four_direction uses S/N/E/W animations; eight_direction also uses NE/SE/SW/NW. The confirmed choice is saved on the character.",
      +  "enum": [
      +    "overhead",
      +    "four_direction",
      +    "eight_direction"
      +  ],
      +  "type": "string"
      +}
  4. Changed1 schema field changed
    • addedInput schema / properties / targetFacings
      Added value: +{
      +  "additionalProperties": {
      +    "enum": [
      +      "s",
      +      "se",
      +      "e",
      +      "ne",
      +      "n",
      +      "nw",
      +      "w",
      +      "sw"
      +    ],
      +    "type": "string"
      +  },
      +  "description": "Camera-relative facing per animation slug (n, ne, e, se, s, sw, w, nw). Use this for custom actions and any standard action whose slug does not itself encode the intended direction.",
      +  "type": "object"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / customAnims / additionalProperties / properties / anchorToGround
      Added value: +{
      +  "description": "Pin each output frame to its visible feet so game physics owns vertical movement.",
      +  "type": "boolean"
      +}
  6. Changed1 schema field changed
    • addedInput schema / properties / animations / maxItems
      Added value: +16
  7. Changed2 schema fields changed
    • changedInput schema / properties / animDurations / description
      Previous value: -"Per-animation clip length in seconds (2-10). Longer clips cost more."New value: +"USER-REQUESTED OVERRIDES ONLY (2-10s). Omit this field by default: every animation, including walks and loops, defaults to 2s. Never choose a longer clip unless the user explicitly requested that duration. Longer clips cost more."
    • changedInput schema / properties / customAnims / additionalProperties / properties / duration / description
      Previous value: -"Clip length in seconds."New value: +"USER-REQUESTED OVERRIDE ONLY. Omit for the 2s default, even for a looping animation."
  8. Changed3 schema fields changed
    • addedInput schema / properties / animationPipelineAssignmentToken
      Added value: +{
      +  "description": "Opaque server proof returned by this tool's dry-run. Copy it verbatim into the confirmed dryRun:false call; never create or edit it. If the server reports ANIMATION_PIPELINE_ASSIGNMENT_EXPIRED, preview again.",
      +  "type": "string"
      +}
    • addedInput schema / properties / poseFirstFrameIds
      Added value: +{
      +  "additionalProperties": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "description": "Optional per-animation START anchor pose ids, keyed by animation slug. Resolve ids with list_character_poses and use only status:\"done\" poses. Omit an entry to let the server choose/generate its anchor.",
      +  "type": "object"
      +}
    • addedInput schema / properties / poseLastFrameIds
      Added value: +{
      +  "additionalProperties": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "description": "Optional per-animation END anchor pose ids, keyed by animation slug. Resolve ids with list_character_poses and use only status:\"done\" poses. The same pose id may be used for both endpoints of a loop.",
      +  "type": "object"
      +}
  9. Changed1 schema field changed
    • addedInput schema / properties / mirrorAnims
      Added value: +{
      +  "additionalProperties": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "description": "FREE mirrored copies, keyed newName → sourceName (e.g. { \"walk_left\": \"walk_right\" }). The source must be in this call's animations list; its fresh frames are flipped in the same job at no extra cost.",
      +  "type": "object"
      +}
  10. First observed

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes far beyond the annotations, revealing that this is a paid, credit-multiplying operation, that existing animation slugs are never replaced but the server allocates numeric suffixes, that dry-run defaults to a cost preview, that setup and Luna classification run only after confirmation, that directional approval may be required, that animations default to 2 seconds, and that PROMPT_TOO_LONG can occur before charging. No annotation is contradicted, and the description provides the full behavioral context an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but every major section earns its place given the 14 parameters, the expensive and asynchronous nature of the operation, and the need to coordinate with sibling tools and user approvals. It front-loads the most critical information—cost multiplication, text-free output, and the difference from create_animation_from_pose—before diving into workflow details. It is not a model of brevity, and a tighter structure with headings would help, but for this complexity it is appropriately dense rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the full lifecycle: cost preview, user confirmation, direction mode resolution, naming behavior, per-operation jobs, polling, directional approval, pipeline token handling, wallet limits, error handling, quality gates, and the exact output shape. With no output schema present, the description carries that burden and does so thoroughly. An agent has enough context to invoke, verify, and recover from failures correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds substantial behavioral meaning to parameters: dryRun should be re-called only after explicit user approval, animDurations must be omitted unless the user requests otherwise, animationDirectionMode must be passed on both dry-run and confirmation and preselected from get_character, animationPipelineAssignmentToken must be copied verbatim, and poseFirstFrameIds/poseLastFrameIds must be resolved through list_character_poses. This goes beyond the schema's field-level descriptions and materially improves correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the exact operation—generating character animations—and pins it against siblings: it is real motion rather than the 1-frame still from create_animation_from_pose, and it is not the separate visible-turn action generate_character_turn. This gives an agent a precise, differentiable purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool, when not to use it, and which alternatives to call instead: use it for any real motion including walk cycles and attacks, do NOT use create_animation_from_pose for 1-frame stills, do NOT use generate_character_turn merely to prepare an animation, and use list_character_poses when the user wants stored poses as video endpoints. It also warns to ask the user before spending and to poll jobs, giving an agent a clear invocation policy.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources