# Cartwheel Text to Motion — API Reference Model ID: `model_cartwheel-text-to-motion` --- ## Authentication - **API_KEY** and **API_SECRET** are found in your [Scenario Project Settings](https://app.scenario.com/team&tab=api_keys) under API Keys. - Set them as environment variables `SCENARIO_SDK_API_KEY` and `SCENARIO_SDK_API_SECRET` — both SDKs pick them up by default. - For raw HTTP (cURL), use Basic Auth: `Authorization: Basic base64(":")`. ### Install the SDK - JavaScript / TypeScript: `npm install @scenario-labs/sdk` - Python: `pip install scenario-sdk` --- ## Generate **Endpoint:** `POST https://api.cloud.scenario.com/v1/generate/custom/model_cartwheel-text-to-motion` ### Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `prompt` | string | yes | - | Describe the movement you want the character to perform — for example, "walks forward, then jumps and waves." | | `characterFile` | assetId | - | - | Optionally upload your own character. It's automatically prepared so the generated motion can be applied to it. | | `duration` | number | - | `5` | How long the animation lasts, in seconds. | | `cfgScale` | number | - | `7.5` | How closely the result follows your prompt. Higher values stick to your description more strictly; lower values give the model more creative freedom. | | `outputFormat` | string | - | `glb` | The file type you get back. Choose the one that matches your software — for example, GLB for general 3D use, or an FBX option for Blender, Maya, Unreal, or Roblox. | | `frameRate` | number | - | `24` | How many frames play per second. Higher values look smoother; 24 is standard for film, 30 or 60 for games. | | `forward` | string | - | `Z` | Which direction the character is set to face. Match this to your 3D software's setup if the motion comes in turned the wrong way. | | `up` | string | - | `Y` | Which direction counts as "up" for the character. Match this to your 3D software if the motion comes in oriented incorrectly. | | `frameStepSize` | number | - | `1` | Controls how often a frame is recorded. Higher values produce fewer frames and a lighter file, with slightly less smooth motion. | | `moveInPlace` | boolean | - | `false` | Keeps the character animating on the spot instead of traveling across the scene — useful for game engines where movement is handled separately. | | `faceExpression` | string | - | `Default` | An optional facial expression to apply throughout the animation, such as Happy, Angry, or Surprised. | | `handPose` | string | - | `default` | The hand pose to apply on the character. | | `keyframeCleaning` | string | - | `none` | Tidies up the animation data. Reduce and Simplify trim extra detail to make the file lighter and easier to edit by hand. | | `loop` | boolean | - | `false` | Makes the animation repeat seamlessly, so the end flows back into the start without a visible jump. | | `skinHex` | string | - | - | An optional color for the character's skin, given as a hex code (for example, #BF916D). | ### Example Requests **cURL** ```bash curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_cartwheel-text-to-motion" \ -H "Authorization: Basic $(echo -n ':' | base64)" \ -H "Content-Type: application/json" \ --data-binary @- <<'EOF' { "prompt": "A fantasy landscape", "duration": 5, "cfgScale": 7.5, "outputFormat": "glb", "frameRate": 24, "forward": "Z", "up": "Y", "frameStepSize": 1, "moveInPlace": false, "faceExpression": "Default", "handPose": "default", "keyframeCleaning": "none", "loop": false } EOF ``` **Python** ```python import os from scenario_sdk import Scenario client = Scenario( api_key=os.environ.get("SCENARIO_SDK_API_KEY"), api_secret=os.environ.get("SCENARIO_SDK_API_SECRET"), ) body = { "prompt": "A fantasy landscape", "duration": 5, "cfgScale": 7.5, "outputFormat": "glb", "frameRate": 24, "forward": "Z", "up": "Y", "frameStepSize": 1, "moveInPlace": False, "faceExpression": "Default", "handPose": "default", "keyframeCleaning": "none", "loop": False } response = client.generate.run_model( model_id="model_cartwheel-text-to-motion", body=body, ) print(response) ``` **JavaScript** ```javascript import Scenario from "@scenario-labs/sdk"; const client = new Scenario({ apiKey: process.env["SCENARIO_SDK_API_KEY"], apiSecret: process.env["SCENARIO_SDK_API_SECRET"], }); const body = { "prompt": "A fantasy landscape", "duration": 5, "cfgScale": 7.5, "outputFormat": "glb", "frameRate": 24, "forward": "Z", "up": "Y", "frameStepSize": 1, "moveInPlace": false, "faceExpression": "Default", "handPose": "default", "keyframeCleaning": "none", "loop": false }; const response = await client.generate.runModel("model_cartwheel-text-to-motion", { body }); console.info(response); ``` --- ## Retrieve Results After submitting a generation request, you receive a `jobId`. Poll the job until `job.status` is `"success"`. The generated asset IDs are in `job.metadata.assetIds`. **Endpoint:** `GET https://api.cloud.scenario.com/v1/jobs/{jobId}` ### Example Requests **cURL** ```bash curl -X GET "https://api.cloud.scenario.com/v1/jobs/" \ -H "Authorization: Basic $(echo -n ':' | base64)" ``` **Python** ```python job = client.jobs.retrieve(job_id="") print(job.status) print(job.metadata.asset_ids) ``` **JavaScript** ```javascript // Option 1 — wait on the response from runModel using the SDK helper const completed = await response.job.wait(); console.info(completed.status); console.info(completed.metadata?.assetIds); // Option 2 — retrieve a job by its ID const job = await client.jobs.retrieve(""); console.info(job.status); console.info(job.metadata?.assetIds); ``` **Example response:** ```json { "job": { "jobId": "job_abc123", "status": "success", "metadata": { "assetIds": [ "asset_abc123" ] } } } ``` > **Important:** Generated asset URLs are **temporary** and expire after a short period. Download and store any images you wish to keep before the URL expires. More info: [Content Delivery Network (CDN)](https://docs.scenario.com/get-started/documentation/content-delivery-network-cdn). --- *Generated by [Scenario](https://app.scenario.com)*