Servers Playground How we check Submit a server

Squall Studio

Working · 1.8 s

com.squallstudio/squall-studiov1.0.0 Domain verified

Read, edit and generate AI microdrama scripts, shots, characters and video in Squall Studio

Design & Creative

Website Registry entry

Try it

Call this server's tools from your browser. Nothing to install.

https://squallstudio.com/api/mcp

Authorization (required)

API key from https://squallstudio.com/api-keys

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

attach_shot_continuity_reference

Attach an image that already exists in this project to a shot as a continuity reference. A continuity reference is fed into this shot's next clip generation as a layout, prop, wardrobe and screen-direction guide — it is NOT used as the shot's opening frame or exact composition. Attaching one changes nothing until the clip is generated again. Find asset ids with get_asset_library. A shot's own thumbnail is its clip's last frame, so attaching the previous scene's thumbnail is the cheapest way to carry continuity forward. To use an image that is not yet an asset here, use upload_shot_continuity_reference instead.

shot_idstring, required

Shot id (episode_shots row) to attach the reference to.

asset_idstring, required

Id of an existing image asset in this project.

guidancestring

How the video model should use this reference, e.g. which positions or props to match and what to ignore. Saved on the reference and sent with every later generation of the shot.

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Squall Studio MCP server | mcptry

Squall Studio

Working · 1.8 s

com.squallstudio/squall-studiov1.0.0 Domain verified

Read, edit and generate AI microdrama scripts, shots, characters and video in Squall Studio

Design & Creative

Website Registry entry

Try it

Call this server's tools from your browser. Nothing to install.

https://squallstudio.com/api/mcp

Authorization (required)

API key from https://squallstudio.com/api-keys

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

attach_shot_continuity_reference

shot_idstring, required

Shot id (episode_shots row) to attach the reference to.

asset_idstring, required

Id of an existing image asset in this project.

guidancestring

How the video model should use this reference, e.g. which positions or props to match and what to ignore. Saved on the reference and sent with every later generation of the shot.

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Tools (30)

attach_shot_continuity_reference

Argument	Type	Description
shot_id*	string	Shot id (episode_shots row) to attach the reference to.
asset_id*	string	Id of an existing image asset in this project.
guidance	string	How the video model should use this reference, e.g. which positions or props to match and what to ignore. Saved on the reference and sent with every later generation of the shot.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "shot_id",
    "asset_id"
  ],
  "properties": {
    "shot_id": {
      "type": "string",
      "description": "Shot id (episode_shots row) to attach the reference to."
    },
    "asset_id": {
      "type": "string",
      "description": "Id of an existing image asset in this project."
    },
    "guidance": {
      "type": "string",
      "maxLength": 1000,
      "description": "How the video model should use this reference, e.g. which positions or props to match and what to ignore. Saved on the reference and sent with every later generation of the shot."
    }
  },
  "additionalProperties": false
}

generate_character_image

Generate a reference image for a character. Spends credits. Returns a job id — poll it with get_job.

Argument	Type	Description
user_notes	string	Extra direction for the image.
character_id*	string	Character id.
idempotency_key*	string	Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation.
character_look_id	string	Specific look; defaults to the base look.
reference_image_asset_ids	array	Existing asset ids to use as references.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "character_id",
    "idempotency_key"
  ],
  "properties": {
    "user_notes": {
      "type": "string",
      "description": "Extra direction for the image."
    },
    "character_id": {
      "type": "string",
      "description": "Character id."
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]+$",
      "maxLength": 200,
      "minLength": 8,
      "description": "Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation."
    },
    "character_look_id": {
      "type": "string",
      "description": "Specific look; defaults to the base look."
    },
    "reference_image_asset_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Existing asset ids to use as references."
    }
  },
  "additionalProperties": false
}

generate_episode_music

Generate a background music track for an episode. Requires the episode to already have an assembled video. Spends credits. Returns a job id — poll it with get_job.

Argument	Type	Description
episode_id*	string	Episode id.
idempotency_key*	string	Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "episode_id",
    "idempotency_key"
  ],
  "properties": {
    "episode_id": {
      "type": "string",
      "description": "Episode id."
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]+$",
      "maxLength": 200,
      "minLength": 8,
      "description": "Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation."
    }
  },
  "additionalProperties": false
}

generate_location_image

Generate a reference image for a location. Spends credits. Returns a job id — poll it with get_job.

Argument	Type	Description
user_notes	string
location_id*	string	Location id.
idempotency_key*	string	Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation.
reference_image_asset_ids	array

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "location_id",
    "idempotency_key"
  ],
  "properties": {
    "user_notes": {
      "type": "string"
    },
    "location_id": {
      "type": "string",
      "description": "Location id."
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]+$",
      "maxLength": 200,
      "minLength": 8,
      "description": "Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation."
    },
    "reference_image_asset_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false
}

generate_script

Write a full multi-episode script from a story premise. This CREATES A NEW PROJECT — it does not edit an existing one, and it takes no project_id. While the job runs, job.output carries live progress (phase, completedEpisodes, totalEpisodes). On success the new project also has its characters, locations, episodes, shots and segments seeded, ready for the other tools. Spends credits. Returns a job id — poll it with get_job.

Argument	Type	Description
genre	string	Genre label. Omit to let the story set it.
language	string	Language for dialogue, voiceover and on-screen text. Omit to use the language the story asks for.
story_idea*	string	The story premise to write from.
screen_ratio	string	Aspect ratio.
visual_style	string	Visual style. Defaults to Realistic TV Drama.
episode_count	any	How many episodes to write. null to let the model choose.
idempotency_key*	string	Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation.

generate_shot_background_image

Generate an empty background plate for one short shot. Both reference inputs steer what the plate itself looks like — layout, prop identity, materials and lighting — and are unrelated to upload_shot_continuity_reference, which guides clip generation instead. Use reference_image_asset_ids for images already in this project (find them with get_asset_library) and reference_images_base64 to send bytes you produced locally, for example a frame lifted from an earlier scene so a prop matches what is already on screen. Uploaded bytes are used for this one generation and are not kept as project assets. The location's own reference images are always included on top of both. Spends credits. Returns a job id — poll it with get_job.

Argument	Type	Description
shot_id*	string	Shot id.
idempotency_key*	string	Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation.
short_shot_number*	integer	Short shot number within the shot.
reference_images_base64	array	Images to send as bytes. PNG, JPEG and WebP only; the bytes are sniffed, so the filename extension alone will not get a non-image through. Keep them small — a 720x1280 JPEG is roughly 40-130KB of base64.
reference_image_asset_ids	array

generate_shot_clip

Generate a video clip for a single shot (episode_shots row). Spends credits. Returns a job id — poll it with get_job.

Argument	Type	Description
model	string	Video model override.
shot_id*	string	Shot id.
idempotency_key*	string	Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation.
short_shot_number	integer	Target a specific short shot.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "shot_id",
    "idempotency_key"
  ],
  "properties": {
    "model": {
      "type": "string",
      "description": "Video model override."
    },
    "shot_id": {
      "type": "string",
      "description": "Shot id."
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]+$",
      "maxLength": 200,
      "minLength": 8,
      "description": "Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation."
    },
    "short_shot_number": {
      "type": "integer",
      "description": "Target a specific short shot."
    }
  },
  "additionalProperties": false
}

get_asset_library

List generated assets available to a project.

read-only

Argument	Type	Description
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project id."
    }
  },
  "additionalProperties": false
}

get_character

Get one character record.

read-only

Argument	Type	Description
character_id*	string	Character id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "character_id"
  ],
  "properties": {
    "character_id": {
      "type": "string",
      "description": "Character id."
    }
  },
  "additionalProperties": false
}

get_character_looks

List a character's looks.

read-only

Argument	Type	Description
character_id*	string	Character id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "character_id"
  ],
  "properties": {
    "character_id": {
      "type": "string",
      "description": "Character id."
    }
  },
  "additionalProperties": false
}

get_episode

Get one episode record.

read-only

Argument	Type	Description
episode_id*	string	Episode id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "episode_id"
  ],
  "properties": {
    "episode_id": {
      "type": "string",
      "description": "Episode id."
    }
  },
  "additionalProperties": false
}

get_episode_editor

Get the full episode tree in one call: project, episode, outline, script, segments, shots, characters, looks, locations and jobs. Prefer this over several narrower calls.

read-only

Argument	Type	Description
episode_id*	string	Episode id.
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "project_id",
    "episode_id"
  ],
  "properties": {
    "episode_id": {
      "type": "string",
      "description": "Episode id."
    },
    "project_id": {
      "type": "string",
      "description": "Project id."
    }
  },
  "additionalProperties": false
}

get_episode_shots

List the shots in an episode.

read-only

Argument	Type	Description
episode_id*	string	Episode id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "episode_id"
  ],
  "properties": {
    "episode_id": {
      "type": "string",
      "description": "Episode id."
    }
  },
  "additionalProperties": false
}

get_job

Get one generation job's status and output. Use this to poll a job returned by a generate_* tool.

read-only

Argument	Type	Description
job_id*	string	Job id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "job_id"
  ],
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Job id."
    }
  },
  "additionalProperties": false
}

get_location

Get one location record.

read-only

Argument	Type	Description
location_id*	string	Location id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "location_id"
  ],
  "properties": {
    "location_id": {
      "type": "string",
      "description": "Location id."
    }
  },
  "additionalProperties": false
}

get_project

Get one project's summary and current workflow step.

read-only

Argument	Type	Description
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project id."
    }
  },
  "additionalProperties": false
}

get_project_characters

List a project's characters.

read-only

Argument	Type	Description
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project id."
    }
  },
  "additionalProperties": false
}

get_project_episodes

List the episodes in a project.

read-only

Argument	Type	Description
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project id."
    }
  },
  "additionalProperties": false
}

get_project_locations

List a project's locations.

read-only

Argument	Type	Description
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project id."
    }
  },
  "additionalProperties": false
}

get_project_script

Get a project's full script package.

read-only

Argument	Type	Description
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project id."
    }
  },
  "additionalProperties": false
}

get_scene_assets

Get one scene with its shots, characters, locations and continuity references.

read-only

Argument	Type	Description
episode_id*	string	Episode id.
project_id*	string	Project id.
scene_number*	integer	Scene number.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "project_id",
    "episode_id",
    "scene_number"
  ],
  "properties": {
    "episode_id": {
      "type": "string",
      "description": "Episode id."
    },
    "project_id": {
      "type": "string",
      "description": "Project id."
    },
    "scene_number": {
      "type": "integer",
      "description": "Scene number."
    }
  },
  "additionalProperties": false
}

list_episode_segments

List the video segments in an episode.

read-only

Argument	Type	Description
episode_id*	string	Episode id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "episode_id"
  ],
  "properties": {
    "episode_id": {
      "type": "string",
      "description": "Episode id."
    }
  },
  "additionalProperties": false
}

list_project_jobs

List generation jobs for a project, newest first.

read-only

Argument	Type	Description
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project id."
    }
  },
  "additionalProperties": false
}

list_projects

List all projects owned by the authenticated user.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

list_shot_continuity_references

List the continuity reference images attached to one shot. get_scene_assets also returns these, but only for a whole scene — use this when you need the asset ids, for example to remove one or update its guidance. Each reference's saved guidance is in metadata.continuityGuidance.

read-only

Argument	Type	Description
shot_id*	string	Shot id (episode_shots row).

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "shot_id"
  ],
  "properties": {
    "shot_id": {
      "type": "string",
      "description": "Shot id (episode_shots row)."
    }
  },
  "additionalProperties": false
}

remove_shot_continuity_reference

Detach one continuity reference from a shot. List them first with list_shot_continuity_references to get the asset id. This deletes the reference asset permanently and cannot be undone.

destructive

Argument	Type	Description
shot_id*	string	Shot id (episode_shots row) the reference is attached to.
asset_id*	string	Id of the continuity reference to remove, from list_shot_continuity_references.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "shot_id",
    "asset_id"
  ],
  "properties": {
    "shot_id": {
      "type": "string",
      "description": "Shot id (episode_shots row) the reference is attached to."
    },
    "asset_id": {
      "type": "string",
      "description": "Id of the continuity reference to remove, from list_shot_continuity_references."
    }
  },
  "additionalProperties": false
}

update_location

Overwrite fields on one location. Read it first (get_project_locations or get_location), then send ONLY the fields you changed — omitted fields are left untouched. IMPORTANT: a location is usually shared by several scenes across episodes, so this edit changes every scene that uses it. Check where it is used first; if the change is meant for one scene only, it needs a NEW location rather than an edit to this one. Editing name, short_description, visual_prompt, user_prompt, visual_style, aspect_ratio or spatial_layout marks the location stale, because its existing generated image no longer matches the description — regenerate the image if you want them back in sync. Editing mood, location_type, recurring or appears_in_episodes does not affect the image and leaves the stale flag alone. spatial_layout is the set bible: the named zones of the set and the fixed zone and height of each prop. Scenes must draw their spatial_geometry zones from it instead of inventing labels, so correcting it here fixes prop placement for every scene at once. Keep descriptions consistent with the owning character's status and the project's tone. This writes immediately and cannot be undone.

destructive

Argument	Type	Description
patch*	object	Fields to change. Send only what you are changing.
location_id*	string	Location id to update.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "location_id",
    "patch"
  ],
  "properties": {
    "patch": {
      "type": "object",
      "properties": {
        "mood": {
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "type": "string",
          "minLength": 1
        },
        "recurring": {
          "type": "boolean"
        },
        "user_prompt": {
          "type": [
            "string",
            "null"
          ]
        },
        "aspect_ratio": {
          "type": [
            "string",
            "null"
          ]
        },
        "visual_style": {
          "type": [
            "string",
            "null"
          ]
        },
        "location_type": {
          "type": [
            "string",
            "null"
          ]
        },
        "visual_prompt": {
          "type": "string",
          "minLength": 1
        },
        "spatial_layout": {
          "anyOf": [
            {
              "type": "object",
              "required": [
                "layout_summary"
              ],
              "properties": {
                "props": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "name",
                      "zone",
                      "height",
                      "description"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "zone": {
                        "type": "string"
                      },
                      "height": {
                        "type": "string"
                      },
                      "movable": {
                        "type": "boolean",
                        "default": false
                      },
                      "key_prop": {
                        "type": "boolean"
                      },
                      "description": {
                        "type": "string"
                      },
                      "co_located_with": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "default": []
                      }
                    },
                    "additionalProperties": false
                  },
                  "default": []
                },
                "zones": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "description"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "adjacent_to": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "default": []
                      },
                      "description": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  "default": []
                },
                "layout_summary": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "short_description": {
          "type": [
            "string",
            "null"
          ]
        },
        "appears_in_episodes": {
          "type": "array",
          "items": {
            "type": "integer",
            "exclusiveMinimum": 0
          }
        }
      },
      "description": "Fields to change. Send only what you are changing.",
      "additionalProperties": false
    },
    "location_id": {
      "type": "string",
      "description": "Location id to update."
    }
  },
  "additionalProperties": false
}

update_shot

Overwrite fields on one shot. Read the shot first (get_episode_shots or get_episode_editor), decide the change yourself, then send ONLY the fields you changed — omitted fields are left untouched. To change dialogue, edit camera_setup.short_shots[].dialogue_covered; never send the deprecated `dialogue` field, which can duplicate or resurrect lines. This writes immediately and cannot be undone.

destructive

Argument	Type	Description
patch*	object	Fields to change. Send only what you are changing. Edit dialogue via camera_setup.short_shots[].dialogue_covered, not the deprecated `dialogue`.
shot_id*	string	Shot id (episode_shots row) to update.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "shot_id",
    "patch"
  ],
  "properties": {
    "patch": {
      "type": "object",
      "properties": {
        "title": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "type": "null"
            }
          ]
        },
        "dialogue": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "character",
              "line",
              "emotion",
              "delivery_note"
            ],
            "properties": {
              "line": {
                "type": "string"
              },
              "emotion": {
                "type": "string"
              },
              "line_id": {
                "type": "string"
              },
              "character": {
                "type": "string"
              },
              "delivery_note": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "location": {
          "type": [
            "string",
            "null"
          ]
        },
        "shot_size": {
          "type": [
            "string",
            "null"
          ]
        },
        "characters": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "composition": {
          "type": [
            "string",
            "null"
          ]
        },
        "script_text": {
          "type": "string",
          "minLength": 1
        },
        "time_of_day": {
          "type": [
            "string",
            "null"
          ]
        },
        "camera_angle": {
          "type": [
            "string",
            "null"
          ]
        },
        "camera_setup": {
          "anyOf": [
            {
              "type": "object",
              "required": [
                "shot_size",
                "subject_movement",
                "visual_purpose",
                "short_shots"
              ],
              "properties": {
                "shot_size": {
                  "type": "string"
                },
                "short_shots": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "shot_number",
                      "duration_seconds",
                      "shot_size",
                      "action",
                      "subject_movement",
                      "dialogue_covered",
                      "visual_purpose"
                    ],
                    "properties": {
                      "action": {
                        "type": "string"
                      },
                      "location": {
                        "type": "string"
                      },
                      "beat_type": {
                        "enum": [
                          "establishing",
                          "entrance",
                          "exit",
                          "movement",
                          "prop_interaction",
                          "insert",
                          "reveal",
                          "blocking",
                          "reaction",
                          "decision",
                          "dialogue",
                          "transition",
                          "cliffhanger"
                        ],
                        "type": "string"
                      },
                      "end_state": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "shot_size": {
                        "type": "string"
                      },
                      "shot_number": {
                        "type": "number"
                      },
                      "start_state": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "visual_purpose": {
                        "type": "string"
                      },
                      "background_view": {
                        "anyOf": [
                          {
                            "type": "object",
                            "required": [
                              "location_name",
                              "view_name",
                              "background_description",
                              "camera_facing",
                              "continuity_note"
                            ],
                            "properties": {
                              "image_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "view_name": {
                                "type": "string"
                              },
                              "depth_layout": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "camera_facing": {
                                "type": "string"
                              },
                              "location_name": {
                                "type": "string"
                              },
                              "continuity_note": {
                                "type": "string"
                              },
                              "reference_usage": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "visible_anchors": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "generated_asset_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "lighting_description": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "reference_description": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "background_description": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "dialogue_covered": {
                        "type": "array",
                        "items": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "$ref": "#/properties/patch/properties/dialogue/items"
                            }
                          ]
                        }
                      },
                      "duration_seconds": {
                        "type": "number"
                      },
                      "spatial_geometry": {
                        "anyOf": [
                          {
                            "type": "object",
                            "required": [
                              "location_axis",
                              "subject_start_zone",
                              "subject_end_zone",
                              "subject_travel_direction",
                              "camera_zone",
                              "camera_facing_direction",
                              "camera_subject_relationship",
                              "background_visible_direction",
                              "consistency_note"
                            ],
                            "properties": {
                              "camera_zone": {
                                "type": "string"
                              },
                              "location_axis": {
                                "type": "string"
                              },
                              "consistency_note": {
                                "type": "string"
                              },
                              "interaction_axis": {
                                "type": "string"
                              },
                              "subject_end_zone": {
                                "type": "string"
                              },
                              "subject_start_zone": {
                                "type": "string"
                              },
                              "camera_facing_direction": {
                                "type": "string"
                              },
                              "subject_travel_direction": {
                                "type": "string"
                              },
                              "camera_subject_relationship": {
                                "type": "string"
                              },
                              "background_visible_direction": {
                                "type": "string"
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "subject_movement": {
                        "type": "string"
                      },
                      "camera_setup_detail": {
                        "type": "object",
                        "required": [
                          "camera_position",
                          "camera_angle",
                          "camera_movement"
                        ],
                        "properties": {
                          "camera_angle": {
                            "type": "string"
                          },
                          "camera_movement": {
                            "type": "string"
                          },
                          "camera_position": {
                            "type": "string"
                          },
                          "subject_orientation": {
                            "type": "string"
                          },
                          "subject_orientations": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "subject"
                              ],
                              "properties": {
                                "subject": {
                                  "type": "string"
                                },
                                "looking_at": {
                                  "type": "string"
                                },
                                "orientation_to_camera": {
                                  "type": "string"
                                }
                              },
                              "additionalProperties": false
                            }
                          }
                        },
                        "additionalProperties": false
                      },
                      "background_people_description": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "post_dialogue_visual_progression": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "visual_purpose": {
                  "type": "string"
                },
                "subject_movement": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "scene_purpose": {
          "type": [
            "string",
            "null"
          ]
        },
        "scene_setting": {
          "type": [
            "string",
            "null"
          ]
        },
        "subtitle_text": {
          "type": [
            "string",
            "null"
          ]
        },
        "omit_subtitles": {
          "type": "boolean"
        },
        "audio_direction": {
          "type": [
            "string",
            "null"
          ]
        },
        "camera_movement": {
          "type": [
            "string",
            "null"
          ]
        },
        "camera_direction": {
          "type": [
            "string",
            "null"
          ]
        },
        "duration_seconds": {
          "type": "integer",
          "maximum": 60,
          "minimum": 1
        },
        "source_scene_number": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "null"
            }
          ]
        },
        "referenced_location_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "referenced_character_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "referenced_character_look_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "description": "Fields to change. Send only what you are changing. Edit dialogue via camera_setup.short_shots[].dialogue_covered, not the deprecated `dialogue`.",
      "additionalProperties": false
    },
    "shot_id": {
      "type": "string",
      "description": "Shot id (episode_shots row) to update."
    }
  },
  "additionalProperties": false
}

update_shot_continuity_reference

Set or clear the guidance on one continuity reference already attached to a shot — the note telling the video model how to use that image. List references first with list_shot_continuity_references to get the asset id. Like attaching, this changes nothing until the clip is generated again.

Argument	Type	Description
shot_id*	string	Shot id (episode_shots row) the reference is attached to.
asset_id*	string	Id of the continuity reference to update, from list_shot_continuity_references.
guidance*	any	How the video model should use this reference, e.g. which positions or props to match and what to ignore. Send null or an empty string to clear it.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "shot_id",
    "asset_id",
    "guidance"
  ],
  "properties": {
    "shot_id": {
      "type": "string",
      "description": "Shot id (episode_shots row) the reference is attached to."
    },
    "asset_id": {
      "type": "string",
      "description": "Id of the continuity reference to update, from list_shot_continuity_references."
    },
    "guidance": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000
        },
        {
          "type": "null"
        }
      ],
      "description": "How the video model should use this reference, e.g. which positions or props to match and what to ignore. Send null or an empty string to clear it."
    }
  },
  "additionalProperties": false
}

upload_shot_continuity_reference

Attach an image you produced locally to a shot as a continuity reference. A continuity reference is fed into this shot's next clip generation as a layout, prop, wardrobe and screen-direction guide — it is NOT used as the shot's opening frame or exact composition. Attaching one changes nothing until the clip is generated again. Send the image as base64 — keep it small (a 720x1280 JPEG is roughly 40-130KB of base64). PNG, JPEG and WebP only; the bytes are sniffed, so the filename extension alone will not get a non-image through. If the image is already an asset in this project, use attach_shot_continuity_reference instead and send no bytes.

Argument	Type	Description
shot_id*	string	Shot id (episode_shots row) to attach the reference to.
filename*	string	File name to store it under, e.g. scene-1-last-frame.jpg.
guidance	string	How the video model should use this reference, e.g. which positions or props to match and what to ignore. Saved on the reference and sent with every later generation of the shot.
image_base64*	string	The image bytes, base64-encoded. No data: URI prefix.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "shot_id",
    "image_base64",
    "filename"
  ],
  "properties": {
    "shot_id": {
      "type": "string",
      "description": "Shot id (episode_shots row) to attach the reference to."
    },
    "filename": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "File name to store it under, e.g. scene-1-last-frame.jpg."
    },
    "guidance": {
      "type": "string",
      "maxLength": 1000,
      "description": "How the video model should use this reference, e.g. which positions or props to match and what to ignore. Saved on the reference and sent with every later generation of the shot."
    },
    "image_base64": {
      "type": "string",
      "maxLength": 34000000,
      "minLength": 1,
      "description": "The image bytes, base64-encoded. No data: URI prefix."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "story_idea",
    "episode_length_seconds",
    "idempotency_key"
  ],
  "properties": {
    "genre": {
      "type": "string",
      "minLength": 1,
      "description": "Genre label. Omit to let the story set it."
    },
    "language": {
      "type": "string",
      "minLength": 1,
      "description": "Language for dialogue, voiceover and on-screen text. Omit to use the language the story asks for."
    },
    "story_idea": {
      "type": "string",
      "minLength": 10,
      "description": "The story premise to write from."
    },
    "screen_ratio": {
      "enum": [
        "9:16",
        "16:9",
        "1:1"
      ],
      "type": "string",
      "default": "9:16",
      "description": "Aspect ratio."
    },
    "visual_style": {
      "enum": [
        "Realistic TV Drama",
        "Cinematic Romance",
        "2D Anime",
        "3D Animated",
        "Dark Thriller"
      ],
      "type": "string",
      "description": "Visual style. Defaults to Realistic TV Drama."
    },
    "episode_count": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 3,
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ],
      "default": 3,
      "description": "How many episodes to write. null to let the model choose."
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]+$",
      "maxLength": 200,
      "minLength": 8,
      "description": "Stable key identifying this generation request. Reuse the SAME key when retrying the same request — the original job is returned and no second charge is made. Use a NEW key when you deliberately want another generation."
    },
    "target_platform": {
      "enum": [
        "TikTok",
        "Reels",
        "YouTube Shorts"
      ],
      "type": "string",
      "default": "TikTok",
      "description": "Platform the episodes are cut for."
    },
    "episode_length_seconds": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 300,
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Target length of each episode, in seconds. null to let the model choose."
    }
  },
  "additionalProperties": false
}