shot_mutate
Create, update, delete, reorder, or reposition shots, recurring shot elements, scene moodboard selections, and selected shot-audio takes 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.
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.”
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.
shot
Calls: shot.mutateelement
Calls: shot_element.mutatescene_moodboard
Calls: scene_moodboard.mutateshot_audio
Calls: shot_audio.mutateLinked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$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"
]
}
},
"oneOf": [
{
"properties": {
"entity_type": {
"const": "shot"
}
},
"$ref": "./_common/shot_mutate_body.schema.json"
},
{
"properties": {
"entity_type": {
"const": "element"
}
},
"$ref": "./_common/shot_element_mutate_body.schema.json"
},
{
"properties": {
"entity_type": {
"const": "scene_moodboard"
}
},
"$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"
}
},
"type": "object",
"required": [
"operation",
"project_id",
"asset_id"
],
"additionalProperties": false
}
],
"unevaluatedProperties": false
}Output schema
{
"$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"
]
},
"result": {
"type": "object"
}
},
"additionalProperties": true
}