Tools

create_motion_design

Start a job that designs animated motion from plain English: titles, callouts and lower thirds timed across a finished piece, in a look you choose. It runs in the background: this returns a job id at once, then poll get_motion_design until status is completed (usually under a minute). Costs 1 AI credit (3 for duration 1-5min), charged only when it completes. The result is a project the user opens in the Motion designer.

Access token · edit · Changes account data

Parameters

prompt string required

View schema

{
  "type": "string",
  "minLength": 1,
  "maxLength": 12000
}

aspect_ratio string optional

View schema

{
  "type": "string",
  "enum": [
    "16:9",
    "9:16",
    "1:1",
    "4:5"
  ]
}

duration string optional

View schema

{
  "type": "string",
  "enum": [
    "<10s",
    "10-30s",
    "30s-1min",
    "1-5min"
  ]
}

design_system_id string optional

View schema

{
  "type": "string",
  "enum": [
    "heavenly",
    "editorial",
    "mono",
    "neon",
    "sunset",
    "ocean",
    "forest",
    "paper",
    "broadcast",
    "playful"
  ]
}

design_md string optional

Optional: a DESIGN.md as text. Takes precedence over design_system_id.

View schema

{
  "description": "Optional: a DESIGN.md as text. Takes precedence over design_system_id.",
  "type": "string",
  "maxLength": 60000
}

style_reference_url string optional

View schema

{
  "type": "string",
  "maxLength": 4096
}

attachments array optional

View schema

{
  "maxItems": 100,
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "maxLength": 4096
      },
      "name": {
        "type": "string",
        "maxLength": 240
      },
      "type": {
        "type": "string",
        "enum": [
          "image",
          "video",
          "audio",
          "file"
        ]
      },
      "content_type": {
        "type": "string",
        "maxLength": 120
      }
    },
    "required": [
      "url"
    ],
    "additionalProperties": false
  }
}

Request example

{
  "name": "create_motion_design",
  "arguments": {
    "prompt": "YOUR_PROMPT"
  }
}

Replace example values with ids and arguments read from your own Heavenly account. This example does not execute a tool.

Returns

The tool result from Heavenly’s workspace, encoded as MCP text content. The connector returns isError when an argument, permission, plan or account check fails.

Account access and permissions are checked by Heavenly. See errors for failure handling.