Screel

Generate text-to-speech narration for scenes. For multiple scenes make ONE call with scenes[] (1-20 items of {scene_id, text, voice?, style_key?, speed?}) instead of one call per scene; top-level voice/style_key/speed act as defaults for every item. Jobs may come back with status 'waiting' plus a queue_position — they start automatically in order; never re-submit a waiting job. You write the narration text — HARD LIMIT: 200 characters of spoken text (inline [tags] don't count); anything over the cap is rejected or truncated, so keep narration timed to the scene's duration at ~2.5 words/sec (a 5s scene ≈ 12 words). Consumes credits (cost in get_account costs.voiceover). Voices (pass as voice; one-word character): Zephyr bright, Puck upbeat (default), Charon informative, Kore firm, Fenrir excitable, Leda youthful, Orus firm, Aoede breezy, Callirrhoe easy-going, Autonoe bright, Enceladus breathy, Iapetus clear, Umbriel easy-going, Algieba smooth, Despina smooth, Erinome clear, Algenib gravelly, Rasalgethi informative, Laomedeia upbeat, Achernar soft, Alnilam firm, Schedar even, Gacrux mature, Pulcherrima forward, Achird friendly, Zubenelgenubi casual, Vindemiatrix gentle, Sadachbia lively, Sadaltager knowledgeable, Sulafat warm; aliases male→Charon, female→Aoede. This is the whole catalogue — pick from it, call list_voices to show the user the voices with descriptions when they want to choose, and let the user hear a voice in the web app when they want to compare. Optional style_key sets the overall delivery: natural (default), dramatic, cheerful, warm, documentary, whispered, excited, conversational. speed is a speaking-rate multiplier (1.0 normal, <1 slower, >1 faster). For emphasis on single moments, embed inline audio tags in the text — [whispers], [laughs], [sighs], [excited], [sarcastic], [warm], [serious], [curious], [tired], [gasp], [amazed], [disappointed] — use AT MOST 2 per narration. Shows a live progress card while it runs.

generate_voiceover

Read one document: its title, kind, version, blocks (each with an id, type and markdown), image bank (each picture's id, name and url) and the suggestions already waiting for the user. Pass the literal "script" as document_id for the project's script; every other document takes the id list_documents reported. Script blocks also report the scene they are linked to — scene_id (the literal "music" links the block to the project's background music), the scene's number and title as they stand now, scene_missing when that scene is gone, scene_link_kind (general, voiceover or animate) and estimated_seconds, the narration time for that block's text. READ THE OUTLINE FIRST on any document past a few dozen blocks: view "outline" returns one short row per block — its index, id, first line, size, scene link and which template fields it carries — so a whole script fits one call. Then read only what you need: block_ids returns the named blocks, scene_ids (script only) the blocks linked to those scenes, and fields (references, story_beat, action, visual, dialogue, voice, audio, changes) trims every template-formatted scene block down to those items plus its heading — dialogue and voice for a narration pass, references, action and visual for an image pass. Read a block before rewriting it: edit_document with blocks replaces the whole body, and ops needs each block's id. Keep the version — edit_document takes it as base_version. A document whose text is the project's standing instructions is the user's policy for this project rather than ordinary notes. A full read of a long document comes back a window at a time: pass start_block to read on from where the previous call stopped, and max_blocks to ask for a different window size.

get_document

Get a project's full state: all scenes in order with their image/video/voiceover status and asset URLs, plus background-music state. Use to check progress, review generated content, or decide next steps. detail summary returns the scene list with its statuses only — take it for a routine progress check and keep the default full read for the whole storyboard. The result also lists the project's reference documents and its render settings, with effective_resolution as the resolution a render would use on this account. This renders a storyboard the user can see. For the project's finished videos use get_render, and for its reference documents use list_documents.

get_project

Get one render's status and, when complete, the final video URL (playable/downloadable). Pass render_id, or pass project_id to get the project's latest render ('show me the render / the video for X'). Pass all with project_id to get every render of that project instead, newest first, for 'show me all the versions' or when the user wants an older one back. Renders a video player the user can watch inline EVERY time it is called, so call it exactly once per finished render: wait for the render's job (get_job_status, or the progress card) to report completed, then one get_render. Calling it while the render is still processing, or again after the player is on screen, posts the player twice.

get_render

List the project's reference documents: the character sheets, place and product descriptions, style and tone notes the user keeps beside the storyboard. Each row carries the document's id, title, kind, version, position and block_count. Read this before creating a document — the one you need usually already exists — and before an image batch, so the scenes are generated against the references the project already carries. get_document reads a whole one.

list_documents

List the user's Screel video projects (newest first, paginated) with name, thumbnail, scene count and whether a finished render exists. Use when the user refers to an existing video/project.

list_projects

List the text-to-speech options for generate_voiceover: the 30 prebuilt voices, each with a one-word characterization and a one-sentence description of its tone and best use (plus male/female aliases), the delivery style presets (style_key values) with their descriptions, and the default voice/model. Free, no credits. Use it when the user wants to choose a voice or asks what voices/styles exist; for common cases you can pass a voice name to generate_voiceover directly.

list_voices

Hand the user a link that opens this project in the Screel web app, for work this app cannot do. Call it for those cases only, or when the user asks for the link: fine-tuning scene timing, trimming clips or reordering on the timeline (view canvas, with scene_id or scene_position to land on one scene); editing a document in place, or working on whiteboards, storyboards and breakdowns (view documents, with document_id for one document); browsing or downloading originals, managing media and restoring older versions (view gallery); inviting collaborators, sharing and comments, and previewing voices before choosing one (view editor, the default); exporting a document as a file. Never offer it as a nudge and never as a replacement for a tool that already does the job here. Returns the project's name and the url — give the user the url and say what it opens. Costs no credits and changes nothing.

open_project

Read one of Screel's playbooks before a workflow the short tool descriptions cannot cover: consistent-characters (one subject in every scene, multi-view banks, group shots, variants), references-from-uploads (a user's photo, product, logo or place into a reference document), scene-continuity (later scenes generated from earlier stills, waves, shot/reverse shot) and style-and-world (a style document, place documents, combining style + place + character without conflict). Read the one that matches before the first image batch of that kind, then follow it. Costs nothing and changes nothing.

get_playbook

Edit an existing picture with an instruction ('warmer light', 'seen from behind', 'remove the text'). Name exactly one source: scene_id or scene_position edits that scene's current still and replaces it in place (the old version stays in the scene's history), while image_url edits a picture Screel already stores — one a Screel tool returned, or a document's bank image; any other url is refused. With a scene you may pass resource_id to edit an older version from its history instead of the current one. With image_url you may pass document_id to land the result in that document's image bank, plus image_id to REPLACE that bank entry in place (its id and name survive, so the [image:<image_id>] tokens in the text keep resolving); a scene edit writes to the scene, so it takes neither. Up to 14 style or character references ride along as reference_images — attach the actual image files from this chat. reference_document_ids conditions the edit on a reference document's bank pictures instead, which is how an edit keeps a character on model; the result echoes references_used. A batch item may carry its own reference_image_urls (pictures Screel already stores), replacing the top-level references for that item. A result added to a document as a new entry takes image_name ('side', 'back'); an entry replaced through image_id keeps its name. Consumes credits per picture (cost in get_account costs.refine). For several edits at once make ONE call with images[] (1-20 items) instead of one call per picture; items may mix scene stills and document pictures. Returns job ids immediately; editing takes ~10-60s. A job may come back with status 'waiting' plus a queue_position: it is already accepted and starts automatically in order — NEVER re-submit it.

refine_image

Stitch selected scenes (with audio) into the final video file. The user may call this 'making a screel' — 'make a/the screel' means render this project. Scenes with an animated clip render the clip; scenes without one render their still image for the scene's duration — animation is NOT required. Consumes credits (cost in get_account costs.render). Returns job_id + render_id and shows a live progress card; takes a few minutes. Idempotent while a render runs: if this project already has a render in progress, the call returns the ACTIVE render's job_id/render_id and current status instead of dispatching a duplicate — resume polling get_job_status with that job_id (or cancel_job to abort); do not retry render_project. When the render completes, call get_render to show the playable video player.

render_project

Put a picture in a reference document's image bank. Pass exactly one source: `image` is the actual image file attached to this tool call — one the user uploaded, or one you made in chat as a reference picture — and `image_url` names a picture Screel already stores, such as a generate_image result. Omit image_id and the picture is ADDED as a new entry, which touches nothing else in the document. Pass image_id (from get_document) and that entry is pointed at the new picture instead: its id survives, so every [image:<image_id>] token in the body keeps resolving, and the picture it replaced is kept as a previous version the user can restore in the web app. name is what the document calls the picture ('front', 'logo'); leave it out and one is filled in. A document holds at most 24 images. Adding a picture does NOT put it in the text — the result carries the entry's id, and writing an [image:<image_id>] token into a block is edit_document's job. Costs no credits; an attached picture counts toward storage. Returns the updated document, bank included.

set_document_image

Put a picture on a scene, or restore one the scene already had. Pass exactly one source. `image` is the actual image file attached to this tool call — one the user uploaded, or one you made in chat for a reference document; attach the file itself, never a path or URL. `resource_id` instead restores a version from the scene's own history (ids come from get_project), bringing that version's prompt back with it. Use it whenever the user wants a picture from this conversation in a scene ('use this image for scene 2', 'upload it to the first scene'), or wants a scene's earlier visual back ('put the old image back'). Scene visuals otherwise come from generate_image with scene_id — never make a scene's still with your built-in image generator, because a chat image is invisible to the project until this tool attaches it. Costs no credits; an attached picture counts toward storage. The picture becomes the scene's still, ready for animate_scene, and the visual it replaced stays in the scene's history. Target the scene by scene_id (from get_project or add_scenes results) or simply by scene_position (1-based: 'the first scene' = 1).

set_scene_image

Update a project's settings: rename it, rewrite its description, change the aspect_ratio (16:9, 9:16, 1:1, 4:3) or set background_music_volume (0.0-1.0, default 0.5). Provide only the fields to change. Does not consume credits. Changing aspect_ratio does NOT regenerate scene media — existing images may be letterboxed or cropped at the new ratio, so offer to regenerate the scenes that matter. Returns the updated scene list.

update_project

Change the project's scenes: rename them, rewrite their descriptions or narration, reorder them, change their duration or voice settings, delete them and duplicate them. Pass scenes[] (1-20 items) and they run IN ORDER, so one call covers a whole reshuffle. Each item names its scene by scene_id or scene_position (1-based, exactly one of the two) and carries op: 'update' (the default) with the fields to change, 'delete' to remove the scene, or 'duplicate' to copy it in place. A delete or duplicate item takes no update fields. Positions are read fresh for each item, so a scene_position in a later item means the position AFTER the earlier items ran — prefer scene_id when the batch also deletes or duplicates. caption is the scene's narration: it is spoken as the voiceover and shown on screen. A delete is irreversible and a scene with a running job is refused, so cancel_job first. If an item fails the batch stops there: the changes before it stay applied and the result says which ran. Does not consume credits. Returns the updated scene list.

update_scenes

Upscale a finished render to 1080p/1440p/2160p. Not available on every account — check get_account first and only call this when upscale_available is true. EXPENSIVE: credits per second by resolution (get_account costs.upscale) — state the cost and confirm with the user before calling, unless they explicitly asked for the upscale. Shows a live progress card; when it completes, call get_render to show the upscaled video.

upscale_render