checkpoint_restore
ChatGPTUse this when the user asks to go back to a saved checkpoint. It replaces the current content with the checkpoint's. Do not use for undoing one small change (edit it with episode_save or library_save) or anything the user did not ask for: work done since the checkpoint is lost. Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","checkpointId":"8e0a2c4e-6a8c-4e0a-a2c4-4e6a8c0e2abb"}
checkpoint_save
ChatGPTUse this when you are about to make a large change (a rewrite, a replace) and want a point to return to. Give it a label the user would recognise. Do not use for small edits, or going back to an earlier state (use checkpoint_restore). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","label":"Before act two rewrite"}
episode_export
ChatGPTUse this when the user asks for the finished video file of an episode. It uses each render group's cut where one exists and the animatic (stills and takes) for every other shot. Returns a job; call jobs_wait for the result. Export only when the user asks for the file. Do not use for previewing (the panel plays the episode without an export), rendering shots (use video_generate), or exporting on your own after a render: refused (conflict) while a render landed since your last handoff: studio_handoff with review "render" lets the user preview the cut and ask for trims or changes first. Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22"}
episode_read
ChatGPTUse this when you need an episode's shots, lines, takes, render groups and timing with their ids. For an edit read only what it needs: shotIds for the shots it touches (the panel's selection names them), or detail "outline" to find them; every shot in "full" only when you need it all. Do not use for the show's brief, cast, sets or props (use show_read). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","shotIds":["a1f3c5e7-2b4d-4c6e-8f0a-1b3d5f7a9c44"]}
episode_save
ChatGPTUse this when setup is done (refused until the user presses Continue on the sets): first script at once, no approval. The episode is one list of shots; you choose them. "replace": the whole episode, each shot complete. "merge": only changes: an item with id keeps omitted fields, an omitted lines list stays, a list naming every shot (or line) sets the order, no id = new, removeIds deletes. To change one shot or line, merge only its id and the changed fields; the rest stays as saved. Answers with ids, not the episode. Rewording a line clears its selected take. Do not use for frames, takes or video (images_attach, takes_generate, video_generate). "replace" deletes what you leave out. Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","mode":"merge","shots":[{"id":"a1f3c5e7-2b4d-4c6e-8f0a-1b3d5f7a9c44","camera":"Slow zoom in"}]}
images_attach
ChatGPTUse this when the images_upload curl uploads are done and you want the images in the show: on a character, set or prop (by handle), as a shot's frame (by shotId, once setup is done), as the cover, or as the style image (target "style", from the user's artwork, at the brief). Attach a whole step in one call; failures are per image. A redo the user asked for REPLACES the bad image (send replaces). removeImageIds takes images off. Do not use for files that are not uploaded yet (call images_upload and run its curl lines first), or leaving a rejected image beside its fix. Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","images":[{"imageId":"d2c4e6a8-1b3f-4e5d-a7c9-5b7d9f1a3c77","target":"character","handle":"alex","role":"main","label":"Character sheet","source":"agent","prompt":"Character sheet of a wiry line cook, red bandana: full-body turnaround and three expressions."}]}
images_get
ChatGPTUse this when you need the file of an image you did not make this turn (for example one the user added in the panel, or one from an earlier chat) before using it as a reference. Returns a signed URL per image and where it is attached; download it with curl. Do not use for images you still have on disk, or adding images (use images_upload then images_attach). The URLs expire: download now, do not keep them. Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","imageIds":["d2c4e6a8-1b3f-4e5d-a7c9-5b7d9f1a3c77"]}
images_upload
ChatGPTUse this when you have image files to add (ones you generated or ones the user gave you). List every file in one call with its localPath; for each you get an imageId and a curl line that is ready to run. Run the curl lines (in parallel is fine), then call images_attach. Do not use for generating images (you make every image yourself with your own image tool) or attaching them (use images_attach). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","files":[{"name":"alex-main.png","mime":"image/png","localPath":"/Users/me/night-kitchen/alex-main.png"},{"name":"diner-kitchen.png","mime":"image/png","localPath":"/Users/me/night-kitchen/diner-kitchen.png"}]}
jobs_wait
ChatGPTUse this when takes, renders or an export are still running. The server waits up to waitSeconds and returns each job's state and, when done, a signed url of its output that expires. Call it again while pendingJobIds is not empty. Do not use for starting work (use takes_generate, video_generate or episode_export). It waits on the server, so no sleep or polling of another tool is needed. Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","waitSeconds":45}
library_save
ChatGPTUse this when you create or update characters, sets or props, all in one call. You choose each handle; an existing handle is updated, a new one is created. Create a prop only when a shot needs it. A set whose window or door shows another set names it in sees. Past the plan's limit it is refused (plan_limit): relay its note. Do not use for images (use images_upload then images_attach), voices (use voices_offer), or the script (use episode_save). removeHandles deletes entries: only on the user's request; a character that still speaks lines is refused. Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","characters":[{"handle":"alex","name":"Alex","description":"Wiry line cook in his 30s, burn-scarred forearms, red bandana.","role":"lead"}],"sets":[{"handle":"diner-kitchen","name":"Diner kitchen","description":"Cramped steel galley kitchen, green neon through the pass window."}]}
panel_add
ChatGPTUse this when the user adds an empty shot or line by hand; the answer carries the new id. Do not use for moving an existing one (use panel_reorder). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","kind":"shot","position":2}
panel_billing_summary
ChatGPTUse this when the panel loads or refetches a workspace's balance in credits, its plan with its limits and usage, and whether automatic refills are on. It changes nothing. Do not use for what the workspace spent (use panel_billing_usage). Example: {"workspaceId":"0d3c1f52-8a47-4e0b-b1c6-5a9e7d2f4c10"}
panel_billing_usage
ChatGPTUse this when the billing panel shows what the workspace spent: by family, by day, by endpoint, the grants and the recent debits, in whole credits; for a period (UTC calendar days, to exclusive) or the whole history. Do not use for the balance alone (panel_billing_summary has it). Example: {"workspaceId":"0d3c1f52-8a47-4e0b-b1c6-5a9e7d2f4c10","from":"2026-10-01","to":"2026-11-01"}
panel_cut_edit
ChatGPTUse this when the user trims, blades, reorders or deletes clips on a render group's Cut face; the panel sends the whole edited cut. Do not use for storyboard edits (shots, lines and takes have their own tools). Example: {"groupId":"e4d7b2a1-9c35-4b68-a2f1-0c8e5d3b6a33","cut":{"v":1,"clips":[{"id":"c1","renderId":"5c9f2f0e-6f4b-4d57-9a3e-0d5b8c1a7e42","inPoint":0,"dur":6.25}],"cues":[],"renderedAt":null}}
panel_delete
ChatGPTUse this when the user deletes a shot or a line by hand. Do not use for removing a clip from a cut (use panel_cut_edit) or a character, set or prop. Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","kind":"line","id":"f6b8d0a2-4c1e-4a3b-9d5f-7e9a1c3b5d55"}
panel_delete_show
ChatGPTUse this when the user deletes a show from the Library: the show is soft-deleted with its episodes, cast and sets, and a slot it held under the plan is freed. Do not use for an agent request (the agent cannot delete shows) or removing one item inside a show (use panel_delete). Example: {"workspaceId":"0d3c1f52-8a47-4e0b-b1c6-5a9e7d2f4c10","showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11"}
panel_edit_entity
ChatGPTUse this when the user edits the name or description of a character, set or prop by hand. Do not use for its images (use panel_set_main_image) or voice (use panel_pick_voice). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","kind":"character","id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c99","description":"Wiry line cook, red bandana."}
panel_edit_episode
ChatGPTUse this when the user renames an episode by hand (the show header's episode menu). Do not use for the script (the agent writes it with episode_save). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","name":"The Pitch"}
panel_edit_line
ChatGPTUse this when the user edits a line's text, delivery or speaker by hand. Changing the text clears the selected take. Do not use for its position in time or trim (use panel_timing) or take (use panel_select_take). Example: {"lineId":"f6b8d0a2-4c1e-4a3b-9d5f-7e9a1c3b5d55","text":"We are closed."}
panel_edit_shot
ChatGPTUse this when the user edits a shot's direction, framing, camera, set or set angle by hand. Do not use for its length (use panel_timing) or order (use panel_reorder). Example: {"shotId":"a1f3c5e7-2b4d-4c6e-8f0a-1b3d5f7a9c44","shotType":"Close-up","camera":null}
panel_edit_show
ChatGPTUse this when the user edits the show's name, logline or brief by hand. Do not use for the style (use panel_pick_style). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","name":"Night Kitchen"}
panel_episode
ChatGPTUse this when the panel loads or refetches an episode document. Do not use for the show's cast, sets or props (use panel_show). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22"}
panel_export
ChatGPTUse this when the user presses Export on an episode. Do not use for previewing (the player needs no export). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22"}
panel_generate_takes
ChatGPTUse this when the user mints a take for one or more lines from the panel (the ghost line's play button, Regenerate). Do not use for choosing between existing takes (use panel_select_take). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","lineIds":["f6b8d0a2-4c1e-4a3b-9d5f-7e9a1c3b5d55"]}
panel_handoff
ChatGPTUse this when the panel is about to open a page of the Montra app outside the host (the account page, in the system browser, which has none of the app's cookies): it answers a one-time URL that signs that browser in as this user and lands on next. Do not use for pages that are not the app's own (open them as they are), or anything the model asks for. Example: {"next":"/app"}
panel_home
ChatGPTUse this when the user opens Scripter from the Codex sidebar or a thread tab (the host calls it with {}): it opens the Scripter panel on the Library, the list of the user's workspaces and shows, and names the show this user's agent is working on. The panel calls it again while it is on the Library. It changes nothing. Do not use for the library itself (use panel_library) or a show's content (use panel_show). Example: {}
panel_library
ChatGPTUse this when the panel lists the account, its workspaces with their balance, and the shows of one workspace. Do not use for a show's content (use panel_show). Example: {"workspaceId":"0d3c1f52-8a47-4e0b-b1c6-5a9e7d2f4c10"}
panel_media
ChatGPTUse this when the panel needs signed URLs (the original, or an image's thumbnail) for media ids it is about to display or play. Do not use for uploading (the agent uploads with images_upload). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","mediaIds":["d2c4e6a8-1b3f-4e5d-a7c9-5b7d9f1a3c77"]}
panel_pick_style
ChatGPTUse this when the user picks a style in the style grid: a catalog style, or the custom style from their artwork (styleMediaId). Do not use for style notes (the agent writes those with show_save). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","styleId":"ink-wash"}
panel_pick_voice
ChatGPTUse this when the user picks one of a character's voice options, or a voice from the voice picker. Do not use for searching voices (use panel_voice_search). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","characterId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c99","voiceId":"JBFqnCBsd6RMkjVDRZzb"}
panel_plan_keep_show
ChatGPTUse this when the user picks a show the plan left read-only to keep active in its place: the newest choice stays active, the oldest choice is dropped when the plan's slots are full, and the oldest unchosen shows fill the rest. Owners and admins. Do not use for lifting the limit (that is a plan change) or deleting a show. Example: {"workspaceId":"0d3c1f52-8a47-4e0b-b1c6-5a9e7d2f4c10","showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11"}
panel_profile_avatar
ChatGPTUse this when the user picks a photo (the Account screen, the web welcome's first step): it answers a signed URL the page PUTs the file to, and the path panel_profile_save then stores. Do not use for saving the profile (use panel_profile_save with the path). Example: {"contentType":"image/png","size":48213}
panel_profile_save
ChatGPTUse this when the Account screen or the web welcome (name and photo, heard about us, describes you) saves what the user answered; on the welcome also the step they move to, done marking it finished, Skip saving only the step. Do not use for the plan (managed on the account page) or the photo's bytes (use panel_profile_avatar first, then pass its path). Example: {"displayName":"Sam Lee","welcomeStep":"heard"}
panel_realtime_token
ChatGPTUse this when the panel subscribes to the workspace's balance: it answers the caller's own short-lived access token for Realtime, the Realtime URL, the publishable key and the private channel's topic. Members only. Do not use for reading the balance itself (use panel_billing_summary) or any write. Example: {"workspaceId":"0d3c1f52-8a47-4e0b-b1c6-5a9e7d2f4c10"}
panel_remove_image
ChatGPTUse this when the user removes an image from a character, set or prop. Removing the main image makes the next one main; shots that used a removed set angle lose it. Do not use for the only image of an entity, or undoing a removal (use panel_restore_image). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","kind":"set","entityId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c99","mediaId":"d2c4e6a8-1b3f-4e5d-a7c9-5b7d9f1a3c77"}
panel_render_approve
ChatGPTUse this when the user confirms Generate in the panel: stores the resolution on the episode and approves the credits it showed for the agent's next renders of it. Do not use for starting renders (the agent starts them with video_generate). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","resolution":"1080P","credits":240}
panel_render_quote
ChatGPTUse this when the user opens Generate All in the panel: the credits to render every shot still owed, at each resolution, and the balance. Do not use for rendering (the agent renders with video_generate). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22"}
panel_reorder
ChatGPTUse this when the user moves a shot to a new place in the episode, or a line within its shot or into another shot. Do not use for reordering clips of a cut (use panel_cut_edit). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","kind":"shot","id":"a1f3c5e7-2b4d-4c6e-8f0a-1b3d5f7a9c44","toPosition":2}
panel_restore
ChatGPTUse this when the user undoes a delete: the shot or line comes back at its old place with everything that was deleted with it (lines, frame, takes, its render group). Do not use for adding a new empty one (use panel_add) or going back to a checkpoint. Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","kind":"shot","id":"a1f3c5e7-2b4d-4c6e-8f0a-1b3d5f7a9c44"}
panel_restore_image
ChatGPTUse this when the user undoes an image removal: the image comes back with its role, label and place, and the shots that lost it as their set angle get it back. Do not use for adding a new image (the agent attaches them). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","kind":"set","entityId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c99","mediaId":"d2c4e6a8-1b3f-4e5d-a7c9-5b7d9f1a3c77"}
panel_select_take
ChatGPTUse this when the user chooses which take a line plays. Do not use for generating takes (the agent does that). Example: {"lineId":"f6b8d0a2-4c1e-4a3b-9d5f-7e9a1c3b5d55","takeId":"b9d1f3a5-6e8c-4d2a-8b4f-3a5c7e9b1d66"}
panel_set_main_image
ChatGPTUse this when the user makes a variant or angle the main image of its character, set or prop. Do not use for adding images (the agent attaches them). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","kind":"set","entityId":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c99","mediaId":"d2c4e6a8-1b3f-4e5d-a7c9-5b7d9f1a3c77"}
panel_setup_continue
ChatGPTUse this when the user presses Continue on a setup screen; the show moves to the stage after fromStage, and from the brief or the cast it is held for the agent until it starts on the next screen. Do not use for jumping to an arbitrary stage. Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","fromStage":"cast"}
panel_show
ChatGPTUse this when the panel loads or refetches the show document. Do not use for an episode's shots (use panel_episode). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11"}
panel_split_shot
ChatGPTUse this when the user splits a shot in two at a line (Split at the playhead, or Split in the shot's menu): a new shot right after it with the same set, cast, props, camera and frame takes that line and every line after it, with their takes and seats. Nothing is generated. Do not use for cutting a rendered clip (use panel_cut_edit) or moving one line (use panel_reorder). Example: {"shotId":"a1f3c5e7-2b4d-4c6e-8f0a-1b3d5f7a9c44","atLineId":"f6b8d0a2-4c1e-4a3b-9d5f-7e9a1c3b5d55"}
panel_sync
ChatGPTUse this when the panel polls the busy signal, the show version and running jobs. Do not use for content: refetch with panel_show or panel_episode only when showVersion changes. Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11"}
panel_timing
ChatGPTUse this when a storyboard gesture changes timing: a ripple (add or remove air), a free move, a take trim, a shot trim or the cut bar (air out). One atomic write of the seats (each on its line's shot clock), trims and beat lengths that changed; label names the undo step. Do not use for trimming a rendered clip (use panel_cut_edit) or moving a line to another shot (use panel_reorder). Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","lines":[{"lineId":"f6b8d0a2-4c1e-4a3b-9d5f-7e9a1c3b5d55","seat":1.25}],"shots":[{"shotId":"a1f3c5e7-2b4d-4c6e-8f0a-1b3d5f7a9c44","holdSeconds":3.8}],"label":"Add air"}
panel_unlock
ChatGPTUse this when the agent has gone quiet and the user presses Unlock: the show becomes idle and everything the agent made is kept. It works in every state; the agent's running jobs keep the show held and are not cancelled. Do not use for stopping the agent's jobs, or undoing its work (use a checkpoint). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11"}
panel_voice_search
ChatGPTUse this when the user searches the voice catalog in the voice picker. Do not use for assigning the voice (use panel_pick_voice). Example: {"query":"gravelly, tired, warm","gender":"male"}
shot_split
ChatGPTUse this when an "action" shot runs past the 15 s render cap (video_generate names the cut, the Generate all message says "split it before rendering") and must become two shots at a line boundary. Split before rendering, without asking: cut at a natural beat (a punchline and its reaction stay together), else at the line video_generate names. The new shot goes right after it with the same frame, set, cast, props and camera; the lines from atLineId on move to it with their takes and seats. Nothing is generated; no credits are spent. Then tell the user in one line where you cut. Do not use for reordering, rewording or moving single lines (use episode_save), or one line over 15 s: render it with "lipSync" or rewrite it as two lines. Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","shotId":"a1f3c5e7-2b4d-4c6e-8f0a-1b3d5f7a9c44","atLineId":"f6b8d0a2-4c1e-4a3b-9d5f-7e9a1c3b5d55"}
show_read
ChatGPTUse this when you need the show: setup stage, your notes, style notes, characters, sets and props with their handles and image ids, the episode list, and what the user changed by hand (userEdits). During setup call it at the start of each turn (detail "full" is the default then). After setup the default is "summary"; ask for "full" only for the brief, descriptions or image prompts, and skip it for an edit to a shot or line (use episode_read). Do not use for the script, shots, lines or takes of an episode (use episode_read). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11"}
show_save
ChatGPTUse this when you create a show (omit showId; also a second show in the same chat, or a new one from the current show, when the user asks) or update its name, logline, brief, aspect or style notes after the user agreed to them in chat, or its notes (your memory across chats; send them whole just before each handoff). Send only the fields that change. setupStage only takes the brief to "cast", once a style is picked or derived from the user's artwork; the user moves the cast and the sets on with Continue in the panel. A plan_limit refusal: relay its note. Do not use for characters, sets or props (use library_save), the script (use episode_save), or picking the style for the user: the user picks it in the panel, not in chat. Example: {"name":"Night Kitchen","logline":"Two line cooks run a diner that only opens after midnight.","aspect":"16:9"}
studio_handoff
ChatGPTUse this when you have finished a piece of work and it is the user's turn. It unlocks the panel, shows your message and opens what there is to review (review only brings a part into view; it does not change the setup stage). It closes every turn that changed the show (the show's notes are updated with show_save first), and its next says what the user does now. After frames landed, review "episode" carries continuity: what your frame-by-frame scan found and fixed. Do not use for progress updates in the middle of work, or while jobs you started are still running (call jobs_wait first). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","message":"The animatic is ready. Press play, then tell me what to change.","review":"episode","continuity":"Scanned shots 1-6 against their neighbours; redrew shot 3, where Dev's chair was empty."}
studio_open
ChatGPTUse this when the user wants to see, start or switch to a show (switching in the same chat is fine; say which show you are on). With no ids it lists workspaces, with workspaceId that workspace's shows, with showId that show, with episodeId too that episode. With showId it also opens the Scripter panel: the show's editor, where the user sees its cast, sets and storyboard, picks the style and voices, and plays the episode. Call it once right after show_save creates a show, and when the user asks to see a show or switch episodes. It changes nothing. Do not use for reading a show's content for your own work (use show_read) or creating a show (use show_save). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11"}
styles_list
ChatGPTUse this when you need the style catalog (id, name, description), for example to describe the style the user picked or to write image prompts that match it. Do not use for setting the show's style: the user picks it in the panel. Example: {}
takes_generate
ChatGPTUse this when setup is done and lines need spoken takes. By default it makes a take for every line that has none, waits, and returns per line the take, its duration, whether the transcript matched and its direction. A new take becomes the line's selected take; older takes are kept. A line whose speaker has no voice comes back with an error; the others proceed. A take falls back from the performance to the delivery's tags to the plain words until the transcript matches: tell the user when a direction was dropped. If transcriptOk is still false, fix the performance before regenerating. Do not use for changing what a line says (use episode_save first) or rendering video (use video_generate). While pendingJobIds is not empty, jobs_wait waits for them on the server. Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","scope":"missing","waitSeconds":45}
video_generate
ChatGPTUse this when the user asked for video. You group the shots: a render is one clip of consecutive shots (shotIds) sharing one moment, by "lipSync" (a character speaking: ONE still, referenceImageIds[0] or the first frame, speaks their audio; no prompt) or "action" (movement, no dialogue: the frames then referenceImageIds, nine at most, your prompt and their audio; 5 to 15 s). An up-to-date group is skipped (no cost) unless rerender: true (the user asked for a new version). Write a prompt per "action" render and call once: the renders start. Say what started and its cost in one line (no models, no question), then jobs_wait. Do not use for the animatic (stills and takes play without any render) or anything the user has not asked to render. Example: {"episodeId":"c2a9f6d4-3b71-4f25-8e0a-9d4c6b1f7a22","renders":[{"shotIds":["a1f3c5e7-2b4d-4c6e-8f0a-1b3d5f7a9c44"],"model":"lipSync"}]}
voices_clone
ChatGPTUse this when the voices_upload uploads are done and you want that voice for a character or the narrator (character "narrator"). Only a voice the user has the right to clone: their own, or one they have permission for. The samples go to the voice provider; the voice takes one of the workspace's custom-voice slots. Give a short name and a descriptor of the sound. pick true when the user chose this voice (it replaces the current one); otherwise it is offered in the panel. Returns the voiceId and a preview. A refusal (cloning off, slots full) says what to tell the user. Do not use for catalog voices (use voices_search and voices_offer) or designing a voice from a description. Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","character":"june","name":"June's own voice","description":"warm, fast-talking, slight rasp","audioIds":["3e5a7c9b-1d2f-4a6c-8e0b-2c4e6a8c0d88"],"pick":true}
voices_offer
ChatGPTUse this when you have three good, different voices per character and want the user to pick in the panel. Fewer than three is refused: search again with other words; only if fewer really fit, say why in fewer. Send every character in one call (character "narrator" for the narrator, when lines have no character), then hand off; do not ask in chat which voice they want. Offers are added beside a character's earlier ones (nine kept), not instead of them: for More options send that character only, with three voices it was not offered before. Do not use for setting a voice the user already chose in chat (use voices_set) or finding voices (use voices_search). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","offers":[{"character":"alex","voiceIds":["JBFqnCBsd6RMkjVDRZzb","pNInz6obpgDQGcFmaJgB","onwK4e9ZLuTAKqWW03F9"],"recommendedVoiceId":"JBFqnCBsd6RMkjVDRZzb"}]}
voices_search
ChatGPTUse this when you need candidate voices for a character or the narrator. Searches the curated catalog (about 730 English voices, each checked by ear). Describe the sound in query and narrow with gender, age or accent. Returns voiceIds with preview URLs and the line each preview speaks. Search for every character at once, while their sheets are drawn. Do not use for assigning a voice (use voices_offer so the user picks in the panel, or voices_set when the user named the voice in chat). Example: {"query":"gravelly, tired, warm","gender":"male","age":"middle_aged","limit":5}
voices_set
ChatGPTUse this when the user told you in chat exactly which voice a character or the narrator should have, or asked you to choose for them. Use character "narrator" for the narrator's voice. Do not use for the normal setup flow, where the user picks from your offers in the panel (use voices_offer). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","character":"alex","voiceId":"JBFqnCBsd6RMkjVDRZzb"}
voices_upload
ChatGPTUse this when the user gave you audio of a voice to clone. Only a voice the user has the right to clone: their own, or one they have permission for. Each sample: 30 s to 3 min of one clean speaker, no music, mp3 or wav, 10 MB at most. List one to three files with their localPath; for each you get an audioId and a curl line that is ready to run. It only stores the files for voices_clone; nothing is cloned yet. Run the curl lines, then call voices_clone. Do not use for images (use images_upload), voices from the catalog (use voices_search), or a voice the user has no right to clone (a public figure's, or anyone's without their permission). Example: {"showId":"7b1e4c1a-5d0f-4a8e-9c3b-2f6a1d0e8b11","files":[{"name":"june-sample.mp3","mime":"audio/mpeg","localPath":"/Users/me/night-kitchen/june-sample.mp3"}]}
