Returns Reverie's filmmaking guide: which tools to call in what order for an idea, a script, a song or dialogue; keeping shots continuous and characters identical; lessons from films made here (what wasted credits and how to avoid it); choosing models; and how spending works. Read it once before planning or rendering a film. Free.

No parameters.

Starts a film from an idea: a short film, music video, commercial, animated story or any other cinematic video. Use it when the user wants to make something but has no finished production plan. Generates three contrasting movie concepts from whatever taste signals are available — genre, mood, favourite films, a target runtime, or nothing at all — and creates a movie-plan draft at the concept stage holding them. Returns concept cards labelled A/B/C for easy reference. If the user has source material (a screenplay, story, or detailed notes), pass it as source_material with fidelity "faithful" — then one concept is derived directly from the source and later stages preserve its scenes, names, and dialogue. Never ask the user for a finished idea: call this early and let them react.

Applies a conversational instruction to a movie-plan draft at its current stage: pick a concept ("go with B"), merge ideas, or edit anything ("make the ending hopeful", "cut it to 60 seconds"). Returns the updated plan and a summary of what changed. This edits in place — it never advances the stage; use advance_plan_stage for that.

Develops a movie-plan draft to its next stage: a chosen concept becomes a story bible (synopsis, characters, visual style); a bible becomes a storyboard (scenes with per-clip video prompts). At the concept stage pass choose_concept ("A"/"B"/"C") unless one was already chosen via refine_plan. One successful call reaches the bible stage, which is enough for create_project_from_plan; a second call reaches storyboard, at which point calling create_project_from_plan again adds scenes and clips to the same project.

Returns a movie-plan draft in full (stage plus all filled sections). Use it to answer questions about the plan's current content.

Lists the user's movie-plan drafts newest-first with id, title, stage, and whether they've been built into a project — use it to resume an earlier idea instead of starting over.

Converts a movie-plan draft into a real Reverie project: characters (available from the bible stage onward), plus scenes and clips with their generation prompts once the storyboard exists. Free — no video is rendered yet. Returns the project id and created structure so render_clip and generate_character_image/generate_clip_image can reference characters/clips directly. Calling this again on an already-built draft extends the same project (adds scenes/clips once the storyboard develops) rather than creating a new one; each draft revision only extends once — refine_plan first to build a variant.

Lists the user's movie projects, newest first, with id, title, scene/clip counts, render progress (how many clips have finished videos), and last activity. Call this first when the user refers to existing work ("my space movie") to find the right project id.

Returns one movie project in full: scenes in narrative order, each scene's clips in order (id, title, prompt, duration, whether an image and a rendered video exist), characters (with slugs and whether reference images exist), and in-flight render/export jobs. This is the tool to understand current state before modifying, rendering, or exporting anything.

Start a new, empty film — for when the user already has their material (a song for a music video, a screenplay, a storyboard or a shot list) and wants to go straight to production without the ideation flow. Free. Then build it with create_scene, create_clip and create_character, and bring in their files with start_upload + add_file.

Change the film's title, logline, or overall look: theme (cinematic, documentary, commercial, artistic, minimalist, vintage), style (photorealistic, animated, illustrated, mixed-media), mood (energetic, calm, dramatic, uplifting, mysterious, professional), aspect_ratio (16:9 or 9:16), resolution (720p or 1080p). Free. A shot whose shape was set in the editor keeps it; render quotes say each shot's shape. The look applies to what's generated from now on — it doesn't change images or videos that already exist; say so if that matters.

Add a scene to the storyboard. It lands at the end; use reorder_scenes to place it elsewhere. Free, and creates no shots — follow with create_clip for each shot in it.

Change a scene's title, description, narrative purpose, plot or action. Free and reversible — apply it and say what changed.

Permanently remove a scene. Destructive and not undoable — confirm with the user in words first, and tell them what happens to the shots inside it.

Set the narrative order of scenes. Pass every scene id, first to last.

Add a shot to the project. Pass scene_id to place it at the end of that scene; omit it for a loose clip. Free — it creates the shot and its prompt, it does not render anything. A continuation is linked to the shot before it and starts on its last frame; the result says which shot and whether that frame is ready yet (it is once that shot has a video).

Change one shot: its title, its prompt (what happens), its image_prompt (how the still looks), its duration, which scene it belongs to, where it sits on the timeline (trims and pin), or whether its own sound plays (audio_muted). Free and immediately reversible — apply it and tell the user what changed rather than asking permission first. Pass scene_id: null to pull a clip out of its scene. Editing the prompt does NOT re-render an existing video; offer render_clip separately if they want to see it. To shorten a rendered shot, trim it; don't change duration_seconds, which is the length to render. Trimming or pinning moves the shots after it, so any lip-sync on them will be out (get_project's lip_sync_out_by_seconds): trim before lip-syncing.

Permanently remove a shot and any video rendered for it. Destructive and not undoable — always confirm with the user in words before calling, every time, even if they asked for it a moment ago.

Reorder shots. The clips you pass are rearranged among the positions they already occupy, in the order given; every clip you don't pass stays exactly where it is. So swapping two shots is a two-id call, and passing every clip sets the whole running order.

Add a character to the cast. Free; generate_character_image gives them a face afterwards, or a real photo of them can be their portrait (best for a real person, costume or mascot that must never change). To keep them identical across shots: pass their slug in render_clip's characters on a model that takes references (kling-4.0, veo-3.1-generate-001), give continuations an end frame showing them, keep them large in frame, and look at each finished shot before building on it.

Change a character's name, role, description, appearance or personality. Free and reversible. Changing appearance does not regenerate an existing portrait — offer generate_character_image if they want to see the change.

Give a character their speaking voice for Kling 4.0 renders: from then on, when they're named in a kling-4.0 shot they speak its dialogue in this voice, the same in every shot. audio_track_id is a project audio track (from get_project, add_file or generate_voice_over) of 5 to 30 seconds with just that one person speaking clearly — several of their lines joined works well. Free; takes a few seconds. Setting it again replaces the voice; the old one comes back only by setting it again from its original track, so check before replacing a voice the user already has.

Make reference views of a character from their portrait: three_quarter (head and shoulders, turned), profile (side on) and full_body (head to toe). They join the character's gallery; the portrait stays. Renders that take several images of a character (Kling 4.0) can then see them from more than the front, so faces hold when people turn or leave and come back. Needs a portrait first. views picks some (default all three); a view made again replaces the old one. Costs credits per view: call it once and you'll get a quote to show the user; only after a clear yes call again with confirm=true. Look at the views when they're ready and redo any that don't match the portrait. A confirm must carry the quote's quote_id (the server refuses one without it).

Permanently remove a character from the cast. Destructive and not undoable — confirm with the user in words first, and mention which scenes and shots they appear in.

Set who appears in a scene — the continuity record shots and renders draw on. Replaces the scene's cast with exactly the characters given (by slug or name); [] clears it. Free.

Generates a portrait for one character — a still image so the user can see the character before the storyboard is even written. Characters exist as soon as create_project_from_plan is called at the bible stage. Reverie makes the image and, when it finishes, sets it as the character's portrait and reference for renders. If a suitable image is already in the conversation (one you made, or the user's), offer attach_image instead — it's free. Same cost as generate_clip_image, and quoted and confirmed the same way. Returns a job; poll get_render_job_status for the finished image.

Generates a look for one clip — a still image, typically the opening shot of a scene — so the user can see the visual direction before committing to a video render. Cheap and fast (a few seconds, a handful of credits) compared to render_clip. When it finishes it becomes the clip's image (its opening frame for render_clip) — or, with use_as end_frame, the image the clip's video ends on (any clip, continuations included). If a suitable image is already in the conversation (one you made, or the user's), offer attach_image instead — it's free. Returns a job; poll get_render_job_status for the finished image. If the clip is the opening shot of its scene, applying the image also sets that scene's setting image and seeds future clips added to the scene. Costs credits: call without confirm for a quote, show it to the user, and only after they approve call again with confirm=true and the quote_id.

Free. Puts an image the user already has on a character (as their portrait, used as reference in renders) or a shot (as its image, which render_clip starts from) — one you made earlier in this conversation, one the user attached, or a public https link. Before quoting generate_character_image or generate_clip_image, check whether a suitable image is already in the conversation; if so, offer this instead, since it costs nothing. Pass exactly one of character_id or clip_id. Doesn't apply to a continuation shot, which starts on the previous shot's last frame.

Every image a shot (clip_id) or a character portrait (character_id) has had, oldest first, with the current one marked. Use it when the user wants an earlier look back — 'the previous one was better', 'go back to the first portrait'. Pass exactly one of clip_id or character_id.

Switch a shot or a character portrait back to one of its earlier takes from list_image_takes. Free and instant — always prefer this over generating again when the user wants a look they've already had. Pass exactly one of clip_id or character_id, plus the take_id.

Choose the image a shot's video should finish on — the clip editor's "last frame". From another shot's frame (from_clip_id, frame first|last: e.g. end on the first frame of a later shot so they meet), from one of this shot's image takes (take_id, from list_image_takes), or clear: true. To make a new image for it, use generate_clip_image with use_as end_frame. Free; takes effect on the next render.

Generates the AI video for one shot of a project: text-to-video, or image-to-video from the shot's still or the previous shot's last frame, with characters kept consistent from their portraits. State intent, not mechanics: a quality tier ("preview" fast/cheap, "standard" default, "premium" best fidelity), optional with_audio, optional continue_from to seamlessly continue motion from another clip's last rendered frame (works across scenes), and optional character slugs whose reference images should guide the shot. Reverie picks the model and satisfies all technical constraints. Costs credits — call without confirm first to get a quote, show it to the user, and only after they approve call again with confirm=true and the quote's quote_id (the server refuses a confirm without one).

Renders a run of continuation shots in order, for a continuous move across several shots: each shot starts from the last frame of the one before when its turn comes. Pass clip_ids in order; each after the first must be the continuation of the one before it, and the first must be ready to render now. Quotes the whole run as one total. After the user approves, Reverie renders the first shot, waits for it to finish, starts the next, and so on, stopping at the first failure (later shots stay unrendered; only finished shots are charged). Check each shot with view_shot_frames as it lands. Costs credits: call without confirm for the quote, show it to the user, and only after they approve call again with confirm=true and the quote_id.

Make a rendered shot 7 seconds longer, as the timeline's Extend does: Veo continues the shot's own video with what you describe, and the longer video replaces it (the current one stays a video take). Costs credits — call without confirm for a quote, show it, and only call with confirm: true after a clear yes. A confirm must carry the quote's quote_id (the server refuses one without it).

Every video a shot has had — its renders and enhancements, oldest first, with which is playing. Use before use_video_take, e.g. when the user wants to undo an enhancement or go back to an earlier render.

Make one of a shot's earlier videos (from list_video_takes) the one that plays — always prefer this over rendering again. Free and instant, unless a cross-dissolve or motion bridge touches the shot: those are remade from the new video at 1 credit each, so then it returns a quote first — show it and call again with confirm: true after a yes. A confirm must carry the quote's quote_id (the server refuses one without it).

Remove a shot's video, as the clip card's delete-video does: the shot goes back to unrendered (its transitions go too). The video itself is kept as a take, so use_video_take can bring it back. Confirm in words first.

Give a rendered shot a new look over the whole shot, keeping its motion and framing. prompt describes the look; character (optional, a slug or name) uses their portrait as the visual reference. Costs credits: call without confirm for the quote, tell the user, and only after a clear yes call again with confirm=true and the quote's quote_id. Takes a few minutes; the result replaces the shot's video automatically (its transitions reset) and you'll be told — the previous version stays available via list_video_takes.

Change one specific thing in a rendered shot and keep the rest. prompt is the instruction, e.g. "make the jacket red", "remove the lamp", "make it night". Shots of up to 10 seconds; cheaper than restyle_clip. Costs credits: call without confirm for the quote, tell the user, and only after a clear yes call again with confirm=true and the quote's quote_id. Takes a few minutes; the result replaces the shot's video automatically (its transitions reset) and you'll be told — the previous version stays available via list_video_takes.

Set how a shot is entered from the shot before it: 'hard_cut' (a straight cut), 'cross_dissolve' (a blend between the two) or 'motion_bridge' (generated in-between frames that carry the motion across). A hard cut, or switching to a transition this shot already has (transitions_ready in get_project), is free and instant. Making a new cross-dissolve or motion bridge costs 1 credit, needs both shots rendered, takes a minute or so, and is applied automatically when it's ready — you'll be told. Like everything that spends, it's quoted first: call without confirm, and only after the user says yes call again with confirm: true. duration_ms (cross-dissolve only, 200–2000, default 500) and regenerate:true make a fresh one. A confirm must carry the quote's quote_id (the server refuses one without it).

Get a link to upload one of the user's files — a song, a vocal stem, dialogue, a photo, a video — into a project. Free. Returns an upload_url to PUT the file's bytes to (with the headers given, within the hour) and an upload_id; then call add_file to say where it goes. Images up to 10 MB; audio and video up to 300 MB.

Put a file uploaded with start_upload where the user means it to go — the same places the editor's uploads go. use_as: audio_track (a song or sound, added as a track at the start of the film — then update_audio_track to place, trim or fade it, and lip_sync_clip to sync a shot to it), character_portrait (an image as a character's portrait, which renders use as reference; character_id), shot_image (an image as a shot's start image; clip_id; not for continuations), end_frame (an image the shot's video finishes on; clip_id), scene_setting (an image as a scene's setting; scene_id), shot_video (a video as the shot's video; clip_id — the earlier one stays a take) or likeness_reference (a photo of a real person the character is; character_id). Generated people are otherwise always stylised and unidentifiable; a likeness_reference makes that character's portraits and shots photorealistic, as themselves — so pass consent=true only when the user has said the photo is of them, or of someone who has agreed to appear, and never on your own judgement. Free.

Change how an audio track plays: start_time_seconds (where it starts on the film's timeline; negative starts it before the film, so it plays from partway in), volume (0–1), muted, fade_in_seconds, fade_out_seconds, trim_start_seconds / trim_end_seconds (cut from the start or end of the file). Free. Pass only what changes. Track ids are in get_project's audio_tracks. Add a track with start_upload and add_file (use_as audio_track).

Remove an audio track from the film. Confirm in words first.

Set the order of the audio tracks (their stacking in the audio panel). Pass every track id, in the new order.

Speak a line in a chosen voice (ElevenLabs) and add it to the project as an audio track — for narration or a character's dialogue, and ready for lip sync (lip_sync_clip with the new track's id). text is the words to speak, up to 2000 characters; it can carry expressive tags like [whispers], [laughs], [sighs] or [pause]. voice is one of the preset voices. speed runs 0.7 to 1.2 (1 is normal). start_time_seconds places it on the timeline (default 0) — to start it with a shot, use that shot's start time from get_project. Costs 1 credit per 200 characters: call it once and you'll get a quote to show the user; only after a clear yes call again with confirm=true. A confirm must carry the quote's quote_id (the server refuses one without it).

Compose original music (Google Lyria) from a brief and add it to the project as an audio track — a score for the film, or a song. prompt is the brief: genre, instruments, mood, tempo and how it builds; time its sections to the film's moments, e.g. "[0:00-0:15] solo felt piano, curious. [0:15-0:35] pizzicato strings join…" — get_project gives each shot's start time. Describe the sound; never name an artist or quote lyrics you didn't write (it refuses those). duration_seconds is its length, 5 to 180 — usually the film's runtime; a longer piece is cut to length with a fade. instrumental defaults to true; false lets it sing (lyrics can go in the brief). start_time_seconds places it on the timeline (default 0). Costs 5 credits for up to 30 seconds, 10 for longer: call it once and you'll get a quote to show the user; only after a clear yes call again with confirm=true. Takes about half a minute. A confirm must carry the quote's quote_id (the server refuses one without it).

Re-sync the mouths in a rendered shot to an audio track (audio_track_id, from get_project or add_file). By default only the part of the track that plays during this shot; whole_track: true uses all of it. A vocals-only track works best. quality: standard (default) or best — sync.so's sync-3, closer on faces at about 3x the price; use it for dialogue close-ups. Lip sync is most convincing on a close-up whose shot was rendered with the mouth closed. Costs credits: call without confirm for the quote, tell the user, and only after a clear yes call again with confirm=true and the quote's quote_id. Takes a few minutes; the result replaces the shot's video automatically (its transitions reset) and you'll be told — the previous version stays available via list_video_takes.

Generate sound for a rendered shot from prompt and bake it into the shot's video. Costs credits: call without confirm for the quote, tell the user, and only after a clear yes call again with confirm=true and the quote's quote_id. Takes a few minutes; the result replaces the shot's video automatically (its transitions reset) and you'll be told — the previous version stays available via list_video_takes.

Checks one or more render/export jobs. Returns status (queued/running/done/failed), progress percent, the video URL when completed, and a structured error when failed. Batch your polling: pass all outstanding job ids in one call and wait poll_after_seconds between calls.

Shows you a rendered shot: one image of 2 to 8 frames taken evenly through its video, first to last, with the time of each. Use it to check a shot before building on it: that the characters and objects look right, nothing unexpected has appeared, and a continuation picks up where the shot before ended. Free.

Cancels a queued or running render job. Use it when the user changes their mind after confirming.

Returns the user's current credit balance and current pricing (credits per 8 seconds of video by quality tier). Use it before quoting large renders so you don't propose something the user can't afford.

No parameters.

Assembles a project's rendered clips (in narrative order, with transitions and audio) into the final downloadable movie file — this is the step that produces the movie; rendering alone leaves individual clips. Costs 1 credit, charged when the film is ready: quote first like any spend. Fails if clips are still un-rendered — check get_project first. Returns a job; poll get_render_job_status for the finished movie's URL.