Generate character animations
generate_character_animationPAID, 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
| Name | Required | Description | Default |
|---|---|---|---|
| dryRun | No | 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. | |
| animations | Yes | Animation slugs to generate, e.g. ["walk_right","idle"]. REQUIRED — each one is a separate paid video call. | |
| videoModel | No | Override the video model. | |
| animPrompts | No | Per-animation extra guidance, keyed by animation slug. Folded into that animation's composed prompt. | |
| characterId | Yes | Character id. | |
| customAnims | No | Define animations that are NOT part of the game type's standard set, keyed by the new slug. | |
| mirrorAnims | No | 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. | |
| animDurations | No | 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. | |
| targetFacings | No | 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. | |
| idempotencyKey | No | Optional 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. | |
| poseLastFrameIds | No | 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. | |
| poseFirstFrameIds | No | 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. | |
| animationDirectionMode | No | 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. | |
| animationPipelineAssignmentToken | No | 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. |