MCP / Tools / Shot / Media / Export / shot_mutate

shot_mutate

writebetaauth: project:writeapproval: requiredstatus: v1

Create, update, delete, reorder, or reposition shots, recurring shot elements, scene moodboard selections, selected shot-audio takes, and reviewed video-continuity checkpoints inside an existing shot-list scope using an entity_type discriminator.

When to use

Use `entity_type=shot` for direct shot mutations after a shot-list scope already exists.
Use `entity_type=element` for recurring shot-element CRUD, shot linking, and shot-element asset metadata updates, including creating a missing recurring character/location/object before image generation.
To create or update a recurring element, use the exact top-level shape `entity_type=element`, `operation=upsert_element`, numeric `project_id`, stable lowercase `token`, and `element_type` (`character`, `environment`, `object`, `style`, or `other`); include `display_name`, `description`, or `prompt` when useful.
Use `entity_type=scene_moodboard` to select, unselect, or delete existing Scene Moodboard assets.
Use `entity_type=shot_audio` and `operation=select` after `media_generate(workflow=scene_audio)` finalizes the generated audio take that should feed video generation.
Use `entity_type=video_continuity` with `accept`, `unaccept`, or `reanchor` after inspecting a succeeded generated video. Primary video selection is not continuity acceptance.
For optimistic concurrency, pass the video asset `updated_at` when accepting, or `continuity_updated_at` when unaccepting/re-anchoring, from `project_assets_query(asset_kind=video)` as `if_match_updated_at`.

When not to use

Do not use for re-running shot-list generation; use `shot_list_generate`.
Do not use for story card/scene/graph edits; use `story_mutate`.
Do not use for generating the image asset itself after an element exists; use `image_generate(workflow=generate_element)` with that element id.
Do not use to create or attach reusable voice samples; use `asset_upload(target_type=reference_audio_asset)` and `voice_profile`.

Examples

“Reorder the shots in this scope.”
“Create Anna as a recurring character element with `entity_type=element`, `operation=upsert_element`, `project_id=1121`, `token=anna`, `element_type=character`, and `display_name=Anna`.”
“Update a recurring wardrobe element prompt with `entity_type=element`, `operation=upsert_element`, and the existing element `token` or `element_id`.”
“Select the approved Scene Moodboard for this scope.”
“Select generated scene-audio media asset 9101 as the active shot audio take.”
“Accept generated video asset 9001 as the reviewed continuity checkpoint for its shot.”

Anti-examples

Generate a new shot list for the scene.
Generate a full-body photoreal reference for Anna when her recurring element already exists; use `image_generate(workflow=generate_element)`.
Change a story beat or scene summary; use `story_mutate`.
Generate Seed Audio for a shot; use `media_generate(workflow=scene_audio)`.

Workflows

Switch behavior by setting the entity_type input field.

Workflow	Phases	Calls
`shot`		`shot.mutate`
`element`		`shot_element.mutate`
`scene_moodboard`		`scene_moodboard.mutate`
`shot_audio`		`shot_audio.mutate`
`video_continuity`		`video_continuity.mutate`

Linked resources

Tool calls may return resource_links pointing at these resource families.

shot_list_scope

Input schema

shot_mutate input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "entity_type"
  ],
  "properties": {
    "entity_type": {
      "type": "string",
      "enum": [
        "shot",
        "element",
        "scene_moodboard",
        "shot_audio",
        "video_continuity"
      ]
    }
  },
  "oneOf": [
    {
      "$ref": "./_common/shot_mutate_body.schema.json"
    },
    {
      "$ref": "./_common/shot_element_mutate_body.schema.json"
    },
    {
      "$ref": "./_common/scene_moodboard_mutate_body.schema.json"
    },
    {
      "properties": {
        "operation": {
          "type": "string",
          "enum": [
            "select"
          ]
        },
        "project_id": {
          "type": "integer"
        },
        "asset_id": {
          "type": "integer",
          "description": "Generated scene_audio media asset id to select for its shot."
        },
        "if_match_updated_at": {
          "type": "string"
        },
        "entity_type": {
          "const": "shot_audio"
        }
      },
      "type": "object",
      "required": [
        "operation",
        "project_id",
        "asset_id"
      ],
      "additionalProperties": false
    },
    {
      "properties": {
        "operation": {
          "type": "string",
          "enum": [
            "accept",
            "unaccept",
            "reanchor"
          ]
        },
        "project_id": {
          "type": "integer"
        },
        "asset_id": {
          "type": "integer",
          "description": "Succeeded generated video asset id whose continuity checkpoint should be mutated."
        },
        "if_match_updated_at": {
          "type": "string",
          "description": "Optional video asset updated_at for accept, or continuity_updated_at for unaccept/reanchor, from project_assets_query."
        },
        "entity_type": {
          "const": "video_continuity"
        }
      },
      "type": "object",
      "required": [
        "operation",
        "project_id",
        "asset_id"
      ],
      "additionalProperties": false
    }
  ],
  "unevaluatedProperties": false
}

Output schema

shot_mutate output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "entity_type",
    "result"
  ],
  "properties": {
    "entity_type": {
      "type": "string",
      "enum": [
        "shot",
        "element",
        "scene_moodboard",
        "shot_audio",
        "video_continuity"
      ]
    },
    "result": {
      "type": "object"
    }
  },
  "additionalProperties": true
}