---
title: "Enqueue one to four motions generated from a text prompt (ML /generate/motion). Each is saved to the account's motions (GET /games/motions) and can be used wherever an animation preset goes. One GENERATE_MOTION charge per motion (Roles: user)"
method: POST
path: "/jobs/generate-motion"
tags: ["Jobs"]
---

# Enqueue one to four motions generated from a text prompt (ML /generate/motion). Each is saved to the account's motions (GET /games/motions) and can be used wherever an animation preset goes. One GENERATE_MOTION charge per motion (Roles: user)

`POST /jobs/generate-motion`

## Request

- Base URL: `https://api.ludo.ai/api`
- URL: `https://api.ludo.ai/api/jobs/generate-motion`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/ludo/apis/ludo-ai-api/docs/jobs/generate-motion/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- GenerateMotionPayload
  - `request_id` string
  - `prompt` string, required: The move, in any language (sword slash, zombie walk). With augment_prompt false it goes to the motion model as written and has to follow the format given there.
  - `num_variants` integer: How many motions to generate, each with its own seed and each charged.
  - `seed` integer: Seed of the first variant.
  - `duration` number, float: Length in seconds. Omit to let the ML choose. Required when augment_prompt is false.
  - `loop` boolean: A seamless cycle (walk, idle), 2 to 8 s. Omit to let the ML choose.
  - `start_idle` boolean: Start on the relaxed standing pose (not with a loop). Omit to let the ML choose.
  - `end_idle` boolean: End on the relaxed standing pose (not with a loop). Omit to let the ML choose.
  - `left_hand` 'relaxed' | 'fist' | 'grip' | 'open' | 'flat' | 'point' | 'thumbs_up' | 'pinch' | 'v_sign' | 'claw': The left hand's pose. Only these are supported (no free text). Omit to let the ML choose.
  - `right_hand` 'relaxed' | 'fist' | 'grip' | 'open' | 'flat' | 'point' | 'thumbs_up' | 'pinch' | 'v_sign' | 'claw': The right hand's pose, as left_hand.
  - `keep_facing` boolean: No turning, for fixed-direction sprites. Omit to let the ML choose (on unless turning is the point of the move).
  - `augment_prompt` boolean: On by default: the prompt is rewritten for the motion model and every option left out is inferred from it. False sends the prompt to the motion model as written, so write it in the model's own format: one plain English sentence of under 50 words that starts with "A person". Describe only how the body moves, including which limbs and which side, e.g. "A person swings a sword overhead with the right arm and steps forward on the left foot". Leave out props, scenery, camera, clothing and story; a held object is only implied through the arms ("as if holding a sword in the right hand"). Do not describe hand shapes in the prompt: use left_hand and right_hand. For a loop, describe one steady repeating movement with no start or stop ("A person walks forward at a steady pace"). duration has to be set explicitly; it is not inferred from the text.

## Response `202`

Accepted

- JobAcceptedResponse
  - `jobId` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `queue_position` integer

## Other responses

- `400`: Error

## Changes

- **2026-11-10** `970a84f6c315`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ludo/apis/ludo-ai-api/changes/jobs/generate-motion/post.md)

---

[API](https://skmtc.dev/ludo/apis/ludo-ai-api.md) - [All operations](https://skmtc.dev/ludo/apis/ludo-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ludo/apis/ludo-ai-api/revisions/b88dd65efd1a?raw)