ScreenWeaver

Add stored images to a group as image nodes and connect each one to a node of the group, exactly like dropping the files into the group and connecting them in the app: the image's @# token is appended to the node's text. Default target per group (defaultNodeId in get_group): a shot's panel generator ({ kind: "shot", id }), the starred generator of a shot's production group or the art direction, and for a story element ({ kind: "story_element", id, group }) its Story element node, whose stage body for that group then cites the image. nodeId picks another generator or text node of the group; nodes the app would not connect an image to are refused. mediaIds come from import_media (pages and crops) or from get_group / view_media. An image already in the group is reused, so calling again does not duplicate it. The token alone does not tell a generator what to do with the image: when the image is a board the panel should redraw, or a reference the user gave a purpose for, rewrite the prompt with set_prompt in the same run (see the storyboard guide). A model takes a limited number of reference images: the call fails without writing anything when a generator's prompt would cite more. No images are generated and no credits are spent.

Create a new ScreenWeaver project with an empty script, in an organisation where you are an owner or editor. Ask the user for the title and whether it is a film (scriptMode STANDARD) or a series (EPISODICAL) when they have not said. orgId comes from list_organisations; when there are several, ask the user which one. It can be left out only when you belong to exactly one. aspectRatio (16:9, 9:16, 2.39:1, 4:3, 3:4) is optional; set it only when the user chose one. Pass a requestId you generate (8 to 64 letters, digits, - or _) and reuse it if you retry: a repeat returns the same project (reused: true) instead of creating a second one. Returns projectId, path and url (the project's link; give it to the user). Use projectId with the other tools to write to the new project. Projects cannot be deleted through these tools.

Create storyboard shots in one scene of the project, in order, in a single write. Live collaborators see them immediately. The project needs an aspect ratio first: when get_project_outline shows aspectRatio null, ask the user which one and call set_project_aspect_ratio. Use it to turn director's notes or a shot list into shots: read the scene first (get_scene) and take sceneId from get_project_outline or get_scene; call list_shots to see existing shots and their shotIds. Each shot needs an actionText and may set shotValue (framing), cameraMovement and durationSeconds; unspecified fields keep the app defaults. Set continuesFrom to chain a shot onto an earlier one (index in this call, or an existing shotId of the scene). A continuation inherits the framing and camera of its chain head, so do not rely on its own shotValue/cameraMovement. A shot that is not a continuation and does not already show a place gets the scene heading's place appended to its actionText, so the storyboard image keeps the location. No images are generated and no credits are spent. Returns createdShotIds (same order as the input) and the scene's shots after the write; check them. Max 50 shots per call.

Start an upload of one file for import_media: a PDF, or a PNG, JPEG or WebP image, up to 25 MB.

Returns uploadUrl and uploadId. Send the file's bytes with an HTTP PUT to uploadUrl, with the Content-Type header it returns (for example: curl -X PUT -H "Content-Type: application/pdf" --data-binary @board.pdf ""). Then call import_media with the uploadId. The URL expires after 30 minutes.

Delete storyboard shots: the shots listed in shotIds, every shot of the scenes in sceneIds, or both. It removes them exactly as deleting them in the Storyboard does: uploaded images and audio on those shots are removed, generated images stay in the Generation Center, and a remaining shot that continued a deleted shot becomes a standalone shot.

Call it without confirm first. Nothing is deleted: it returns a preview with the shots (label, scene, whether each has a storyboard image), how many have images, and which remaining shots lose their continuation. Ask the user once to confirm that list. Only after the user agrees, call it again with the same shotIds / sceneIds and confirm: true. Shot deletion cannot be undone from version History.

shotIds come from list_shots and sceneIds from get_project_outline; never invent them. To replace a scene's shots, delete them with sceneIds, then create the new ones with create_shots.

Edit the screenplay with structured operations, applied in order in one write. Live collaborators see the change immediately, and the pre-edit script is saved to version History so the user can undo it.

The script is a flat list of elements. Each element has a type and plain-text content:

• SCENE_HEADING: "INT. KITCHEN - NIGHT" (optional placeId links a place entity)

• ACTION: description of what happens

• CHARACTER: the speaker's name before dialogue, optionally followed by a cue extension: "MARA" or "MARA (O.S.)" (optional characterId links a character entity). characterId links the name only: a linked line shows the entity's name followed by the extension. Pass extension ("O.S.", "V.O.", "CONT'D") instead of typing it into content if you prefer

• DIALOGUE: the spoken line, right after CHARACTER (or PARENTHETICAL)

• PARENTHETICAL: acting direction such as "(whispering)", between CHARACTER and DIALOGUE

• TRANSITION: "CUT TO:"

• SHOT: a camera shot line

• Structure: EPISODE, ACT, SEQUENCE, STORY_BEAT (content is the title); OUTLINE is a note or the description of the structure element before it.

Operations:

• insert: { op: "insert", afterElementId? | beforeElementId?, elements: [{ type, content, extension?, characterId?, placeId? }] }. With no anchor, elements are appended at the end of the script. New ids are created by the server and returned.

• update: { op: "update", elementId, content?, type?, extension?, characterId?, placeId? }. null clears extension / characterId / placeId. extension is applied after content and replaces the extension already on the cue.

• delete: { op: "delete", elementIds }. Any delete requires confirmDeletes: true; ask the user before deleting their writing.

Element ids come from get_scene or search_script; entity ids come from list_entities. Never invent ids: an unknown entity id, a characterId outside CHARACTER / DIALOGUE, or a placeId outside SCENE_HEADING is rejected, and so is an extension outside CHARACTER. Leave them unset when unsure: the app links CHARACTER names and scene headings to existing entities by name, and creates missing ones, when the project is open. A dialogue exchange is CHARACTER then DIALOGUE elements; a new scene starts with a SCENE_HEADING. Limits: 100 operations and 200 inserted elements per call; write a longer script in several calls, each inserting after the last element id the previous call returned. Final Draft (.fdx) and WriterDuet files go through import_script instead.

Turn files into text on the server: a PDF (its text layer, or OCR for scanned pages), or photos or scans of pages (one image per page, in reading order). Also reads plain-text files.

Use it before import_script for a screenplay that arrives as a PDF or as page images: then call import_script with the textId this returns. Never retype a long script with edit_script. For notes and other documents, read the returned text.

Pages with a text layer are free. Each page read by OCR costs about half a credit; when more than 20 pages need OCR, the call returns confirmation_required with the estimate: ask the user, then call again with confirm: true. At most 300 pages per file are read.

Returns the textId, per file the pages read by text layer and by OCR and any failedPages, the OCR spend of this call, and the text in pages of 60000 characters (pass nextOffset as offset for the next page). Calling again with the same files costs nothing for pages already read and retries failed pages.

Read what one group of the canvas holds: a shot's storyboard group (its panel) or production group, a story element's moodboard, storyboard or production group, or the art direction. Returns the group's nodes (generators with their prompt, the @# references it cites and their model; text nodes; the shot node with its action; image nodes; in a story element group, the Story element node first with this stage's body and its references), each image's current output as a mediaId when it has one (look at it with view_media), and the edges into and inside the group. isShotPanel marks the shot's panel generator, isStarred the generator starred as the group's output. defaultNodeId is what add_reference_images and set_prompt write to when no nodeId is given. Read-only, no credits.

Read a page of the ScreenWeaver guide: how the app's script, story elements, storyboard, production canvas, art direction, references and credits work, and which tools to use for what. Read the page for an area before your first write there. Call with no topic to list the topics.

Overview of one project: title, aspectRatio, stats (element, scene, episode, shot and entity counts), and the script's episodes with their scenes in order. Scripts without EPISODE elements return a single episode 1 with title null. Scenes that come before the script's first EPISODE are listed under episode 0 (title null); labels restart in each episode, and stats.episodeCount is the number of entries in episodes. Each scene has sceneId (the SCENE_HEADING element id), label (Scene N within its episode), heading, placeId (linked place entity or null), elementCount (elements in the scene, heading included) and shotCount (storyboard shots). unscheduledShotCount counts shots whose scene is no longer in the script. Start here, then use get_scene, list_shots or search_script with the ids it returns.

Read one scene of the screenplay. Returns the scene label, episodeIndex (0 when the scene comes before the script's first EPISODE), heading, placeId (linked place entity, if any) and its elements in order: the SCENE_HEADING itself, then every element up to (not including) the next SCENE_HEADING or structure element (EPISODE, ACT, SEQUENCE, STORY_BEAT). Each element has elementId, type, content, and characterId / placeId when linked to an entity (see list_entities). A CHARACTER element's content is the name plus any cue extension ("MARA (O.S.)"); the extension is also returned on its own as extension. With includeShots (default true) it also returns the scene's storyboard shots in the same shape as list_shots. Get sceneId from get_project_outline or search_script.

Bring a PDF or an image into the project as media: comic pages, hand-drawn storyboards, style or reference pictures. A PDF becomes one image per page (at most 50 pages per call; pass pages for the others). An image file is page 1.

findPanels: true finds the panels of each page (comic panels, storyboard frames) and cuts each one as its own image, labelled "Page N, panel K" with a one-line caption of what it shows. Use it for comic pages and storyboard boards: it is more precise than boxes you place yourself, and you need not see the pages first. It costs about 1 credit per page; when more than 20 pages need it, the call returns confirmation_required with the estimate: ask the user, then call again with confirm: true. Pages already searched cost nothing again. With mediaId, it finds the panels of that stored image.

crops cuts boxes out of pages: each box becomes its own image, stored next to the page and linked to it. Boxes are fractions of the page (x, y from the top-left corner, width, height, all from 0 to 1), so a box over the top half of a page is { x: 0, y: 0, width: 1, height: 0.5 }. You decide the boxes (comic panels, storyboard frames, webtoon strips); the tool only cuts the pixels. At most 300 crops per call. To cut boxes from a page imported earlier, pass its mediaId and crops. When you cannot see the pages (a PDF is often not shown to you as images), import without crops first, look at the pages with view_media and their media ids, then cut them with mediaId and crops.

Pass one source: uploadId (from create_upload: the way to send a file you hold), url (a public https URL), base64 with mimeType (files up to 1024 KB only) or mediaId (crops of stored media). Up to 25 MB per file.

Returns the media id, size and page of every page and crop (with panelsFound per page, and panelsFailed for a page the model could not read: cut that one with crops), and the panel spend. Importing the same file again returns the same media ids and stores nothing twice. Without findPanels the import is free.

Import a Final Draft (.fdx) file, a WriterDuet (.json) file, or Fountain / screenplay-formatted plain text (a pasted script) into the project's script. Pass the full text as content, or the textId extract_file_text returned for a PDF or page images. The format is detected from the content; pass format only to force it ("fountain" forces the plain-text importer). Plain text counts as a screenplay when it has INT./EXT. scene headings or uppercase character cues with dialogue below them.

Call it with dryRun: true first. Nothing is written. The preview lists the scenes, element counts, where the content goes (and whether a Final Draft title page is kept), and for each character and place name in the file the entity it links to or "create", with near-miss candidates (a similar existing name, for example TOBY and TOBIAS). When the preview has names to create or near misses, show the user those links and ask. Then import for real with entityMap, mapping each confirmed name to its entityId (from the preview or list_entities). Names left out of entityMap are linked by name or created.

entityMap keys are names as the file writes them; a cue extension is ignored ("MARA (O.S.)" is the key "MARA"). Only characters and places can be mapped. A mapped cue line takes the entity's name and keeps its extension, and a mapped scene heading takes the place's name.

The file is parsed by the app's own importers: scene headings, action, characters, dialogue, parentheticals, transitions and structure keep their types. CHARACTER lines and scene headings are linked to the project's characters and places by name ("MARA (O.S.)" and "MARA (CONT'D)" link to MARA and keep "(O.S.)" / "(CONT'D)" on the cue line), and missing ones are created as story elements (returned in createdEntities). The pre-import script is saved to version History so the user can undo it.

insertPosition: "end" (default) appends after the current script; "start" puts the file first, after the script's title block (its first EPISODE and the OUTLINE lines under it); "replace" replaces the whole script and requires confirmReplace: true on the real call (a dryRun does not), so ask the user before replacing their writing. A Final Draft or Fountain title page becomes the script's title block only on a replace or an empty script; otherwise it is left out.

A PDF, a scan or photos of pages: call extract_file_text first, then import its text here with textId. Never retype a long script with edit_script. For text that is not screenplay-formatted (notes, prose), do not use this tool: write it with edit_script, one element per scene heading, action paragraph, character cue, parenthetical and dialogue line.

List the project's story entities (characters, places, objects) in the order the user arranged them. Each has entityId, kind, name, slug, color and referenceHandle (write it in a shot's actionText to show the entity in that shot). entityId is what script elements carry as characterId / placeId (see get_scene) and what scene headings link as placeId in get_project_outline. Filter with kind; set includeDescriptions to also return each entity's description text (empty string when none).

List the organisations where you can create projects (you are an owner or editor there), sorted by name. Each has orgId, name and your role. Call it before create_project: when there are several, ask the user which organisation the project belongs to; do not pick one for them. An empty list means you cannot create projects.

List the ScreenWeaver projects you can open (owned or shared with you), most recently updated first, at most 200. Each has projectId, title, your role (owner, editor or viewer; only owners and editors can change a project), aspectRatio (null when unset) and updatedAt (ISO 8601). Pass projectId to every other tool.

List the storyboard shots of the project in timeline order (script scene order, then shot order within each scene). Each shot has its shotId, display label (S1, S1A for a continuation of S1, or a custom label), sceneId and sceneLabel, order (1-based timeline position), shotValue, cameraMovement, durationSeconds, actionText, continuesFromShotId (set when the shot continues an earlier shot of the same scene), hasStoryboardImage, and isUnscheduled (true when its scene was removed from the script; unscheduled shots come last). Pass sceneId (from get_project_outline) to list one scene's shots.

Find screenplay elements whose text contains the query (case-insensitive substring), in script order. Each match has elementId, type, the containing sceneId and sceneLabel (null outside any scene, e.g. title page or episode/act headings) and a ~160-character snippet around the match. Filter with types (e.g. ["DIALOGUE", "CHARACTER"]). truncated is true when more matches exist than limit. Use get_scene with the sceneId to read the full scene.

Set the project's frame shape: one of 16:9, 9:16, 2.39:1, 4:3, 3:4. A project needs one before storyboard work: create_shots refuses while get_project_outline shows aspectRatio null. Ask the user which ratio they want; do not pick one for them. Shots created afterwards use it for their storyboard and production frames; existing shots keep the ratio they were created with. Returns aspectRatio and previousAspectRatio (null when it was unset).

Replace the text of a node of a group, as typing it in the app would: a generator's prompt, a text node's body, or a story element's stage body (the Story element node of a story element group, for that group's stage). @# tokens are checked (every token must cite something in the project); on a generator the reference edges follow the tokens, so a token you drop disconnects that input and a token you add connects it. Defaults to the group's default target (defaultNodeId in get_group: a shot's panel, the starred generator of a production group or the art direction, a story element's Story element node); nodeId picks another. Read the current text and its references with get_group first. The shot panel's prompt is managed by the app: a prompt you set there is kept as written (it no longer follows the shot's action, framing and camera) until you call again with restoreDefault: true. Story element referenceHandles (@ref_…) are turned into live references. No images are generated and no credits are spent.

Change one storyboard shot: its action text, framing (shotValue), camera movement, duration, or continuation link. Only the fields you pass change. Get shotIds from list_shots. Live collaborators see the change immediately. No images are regenerated and no credits are spent. A shot that continues another (continuesFromShotId set) takes its framing and camera movement from its chain head: shotValue / cameraMovement passed for it are not applied and come back in ignored; change the chain head instead. Pass continuesFromShotId to link to an earlier shot of the same scene, or null to unlink. At least one field besides shotId is required. Returns the shot as list_shots shows it after the write.

Look at images stored in the project: imported or generated media by mediaIds, a shot's selected panel by shotIds, or a canvas node's current image output by nodeIds. Returns each image downscaled (JPEG, longest side maxSize, default 1024px) with its size and media id, after a JSON list of what was returned. Up to 8 images per call within a size budget; an image that could not be returned is listed in skipped with the reason. Use it to read boards or pages you imported, or to check a generated panel before telling the user it is right. Costs no credits.