Screel

Generate a background music track for the project from a style prompt ('lofi upbeat', 'cinematic strings'). Consumes credits (cost in get_account costs.music). Shows a live progress card while it runs.

generate_music

Make a picture. Give it a prompt (subject, setting, lighting, mood, camera angle) and say where it goes: scene_id or scene_position makes it that scene's still, document_id lands it in that reference document's image bank (from list_documents), and neither leaves it as a picture in this conversation. Never pass both a scene and a document_id. Pass reference_document_ids with the reference documents that govern what the picture shows — the character, object, place or style — and each one conditions the generation with its sheets, or with its pictures on one grid when it has no sheet (per item in a batch, or once at the top level for every item); the result echoes references_used, and a scene item that passes none while the project has reference documents comes back with a warning naming it. Never write a document's title, a picture name or a 'Ref N (...)' label into the prompt instead: that is text to the model and attaches nothing. A scene's still comes from this tool with scene_id, or from set_scene_image. A picture that exists only in the conversation is not part of the project. For several pictures at once — a still per scene, a canonical view per character — make ONE call with images[] (1-20 items, each with its own prompt and destination) instead of one call per picture; items may mix scene stills and document pictures, and the top-level aspect_ratio, negative_prompt and document_id are defaults for items that name none. To make ONE picture FROM pictures Screel already stores — combine them, blend them, 'something based on these' — pass their urls (up to 14) as reference_image_urls with a single prompt: one call, one output conditioned on all of them; a batch item may carry its own reference_image_urls (the previous scene's still, for continuity), replacing the top-level list for that item. A picture that lands in a document takes image_name ('front', 'side') so its bank entry has a label the next prompts can use. get_playbook has the long form of the reference workflows. Consumes credits per picture (cost in get_account costs.image), whatever the destination. Returns job ids immediately and shows a live progress card; generation 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.

generate_image

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. A sheet block also reports its sheet: kind, subject and its views in tile order, each with its picture's id, role, span and url, the canonical one marked. 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 job the short tool descriptions cannot cover: consistent-characters (one subject in every scene, multi-view banks, group shots, variants), props-and-objects (a recurring prop or product), 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), 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 instead — its sheets, or its pictures on one grid when it has no sheet — 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 stills otherwise come from generate_image with scene_id. A picture in the conversation joins the project only when 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, 3:4, 21:9, 4:5, 5:4, 2:3, 3:2) 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, move them, and change their duration or voice settings. Pass scenes[] (1-20 items) and they run IN ORDER, so one call covers a whole set of edits. Each item names its scene by scene_id or scene_position (1-based, exactly one of the two) plus the fields to change; an omitted field stays as it is. position (0-based, unlike scene_position) moves the scene. Positions are read fresh for each item, so a scene_position in a later item means the position AFTER the earlier moves ran — prefer scene_id when the batch also moves scenes. caption is the scene's narration: it is spoken as the voiceover and shown on screen. To remove scenes use delete_scenes; to copy them use duplicate_scenes. 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