Tools

heavenly_save_edit

SAVE an explicitly user-requested batch to the real Heavenly timeline. Requires heavenly:edit consent, edit permissions, known clip ids, current baseRevision and stable requestId. Retrying the same requestId is safe. Saved edits appear in the editor and its existing undo history. Never claims an MP4 export or publication.

OAuth · heavenly:read + heavenly:edit · Changes account data

Parameters

projectId string required

View schema

{
  "type": "string"
}

requestId string required

View schema

{
  "type": "string",
  "pattern": "^[A-Za-z0-9_-]{1,36}$"
}

baseRevision string required

View schema

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[a-zA-Z0-9_:.-]+$"
}

commands array required

View schema

{
  "type": "array",
  "minItems": 1,
  "maxItems": 32,
  "items": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "razor",
          "lift",
          "extract",
          "extract_ranges",
          "delete",
          "magnetic_delete",
          "insert",
          "overwrite",
          "trim",
          "slip",
          "slide",
          "move",
          "magnetic_move",
          "link",
          "unlink",
          "extract_audio",
          "set_enabled",
          "set_item_props",
          "set_track",
          "add_track",
          "remove_track",
          "add_marker",
          "remove_marker",
          "set_marker",
          "set_in_out",
          "set_speed",
          "set_speed_curve",
          "set_reverse",
          "rate_stretch",
          "set_frame",
          "set_canvas",
          "add_text",
          "add_motion",
          "set_motion",
          "set_keyframe",
          "remove_keyframe",
          "set_text",
          "set_caption_style",
          "set_title",
          "set_effect",
          "remove_effect",
          "copy_effect",
          "set_transition",
          "remove_transition",
          "add_music",
          "add_overlay",
          "duplicate",
          "freeze_frame"
        ]
      },
      "sequenceId": {
        "type": "string"
      }
    },
    "required": [
      "type",
      "sequenceId"
    ],
    "additionalProperties": true,
    "description": "Read heavenly_edit_schema for the exact arguments. Heavenly validates every command against its real edit engine."
  }
}

Request example

{
  "name": "heavenly_save_edit",
  "arguments": {
    "projectId": "YOUR_PROJECT_ID",
    "requestId": "YOUR_REQUEST_ID",
    "baseRevision": "YOUR_BASE_REVISION",
    "commands": [
      {
        "type": "razor",
        "sequenceId": "YOUR_SEQUENCE_ID"
      }
    ]
  }
}

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

Returns

The saved timeline edit and revision. It is available in the editor and existing undo history.

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