generate_story_video

Starts an AI Video Story EPISODE: the engine writes the whole multi-scene episode from the idea, draws the OPENING PICTURE OF EVERY SCENE (the start_frame in this API's fields), and PARKS the run so the user can look at those pictures before anything moves. This is stage 1 of 3 - no scene videos generate yet, and this tool returns immediately. TALK TO THE USER IN THOSE PLAIN WORDS: 'the opening picture of each scene', 'the pictures', 'the still for scene 2'. 'Start frames' and 'frames review' are field names in the responses you read - do not say them to the user. WHEN: the series is picked and its FULL entry fetched (list_series with series_id - that is where the duration ladder and the prices are), the idea is iterated with the user in chat, and - for a series whose cast.required is true - the cast is drafted (generate_cast), its portraits are bought (generate_cast_portraits) and DONE, and the user approved them. INPUT DISCIPLINE (hard rule): you pass ONE IDEA - a short paragraph - plus options. You NEVER author scenes, episode JSON, dialogue, or image prompts; the engine owns all generation. A scenes field is rejected. CAST: pass the approved members' ids from generate_cast_portraits (or existing cast members from list_characters, kind cast_member) as cast_member_ids. Members whose portraits are still generating are refused with a 409 - wait for the portraits first. A cast.writer_owned series refuses cast ids (it casts itself). THE CARD: this call has ALREADY put the aicut frames card in front of the user. It follows the episode through writing and frame generation on its own and shows the scene-by-scene review rows the moment the run parks - each one the opening picture, what happens in that scene, and a Show more for what is said in it. You do not poll anything to make that happen. Do NOT call wait_for_generation or loop get_video WHILE THE CARD IS WALKING TO THE REVIEW: say one short line (what was ordered, and that the opening picture of each scene will appear on the card for them to look at - plain words, not 'start frames' or 'frames review'), then STOP and wait for the user. When they answer, act on WHICH KIND of complaint it is: change_story_scene when what HAPPENS in a scene is wrong (it rewrites that scene and redraws it), regenerate_story_frame when only the PICTURE is wrong, set_scene_kept to cut a scene, and fire_story_video ONLY once they have given a go that names firing the scene videos at the price you quoted - liking the pictures is not that go. THE CARD STOPS UPDATING ONCE IT REACHES THE REVIEW, so a redraw you order afterwards does NOT appear on it: read get_video until that lane's regenerate is terminal, and then call show_generation with the episode id to put a fresh grid in front of the user. That is the one place a second card is wanted rather than a duplicate. THE CARD SHOWS BAD OUTCOMES TOO, and neither is something you sit and wait through: a writer failure ends the card on its failed note, and an episode whose frames all failed parks with an EMPTY grid. If the user asks about either, make ONE get_video read and tell them what it says (see IF WRITING FAILS and IF EVERY FRAME FAILS) - one read, not a loop. Call wait_for_generation ONLY when no card rendered - a terminal, a plain SDK client, anything that did not negotiate the MCP Apps UI extension; there, poll get_video until story.stage is frames_review and give the user the frame urls yourself. aicut cannot see which clients render cards and sends the same answer to all of them. AFTER: the response is the parked job (story.stage), which moves starting -> generating_frames -> frames_review with each frame's url. A parked episode STAYS at frames_review until it is fired, so nothing is waiting on you there - the next move is the USER's. Redraw frames they dislike with regenerate_story_frame, cut ones they want gone with set_scene_kept, then fire_story_video generates the scene videos. RENDER is the last stage: once the episode succeeds (or story.stage is ready_to_render), render_story_video produces the final file - or the user renders in the aicut web editor, where the episode also appears. IF EVERY FRAME FAILS: the episode reaches frames_review with no usable image - none of the frames has a url. Tell the user plainly: no pictures came back, every one failed, and NO VIDEO HAS BEEN CHARGED - the scene videos are only bought at fire. Their two moves are the same as the webapp's, and BOTH KEEP THE EPISODE: redraw the ones they want with regenerate_story_frame, and cut the ones they do not want with set_scene_kept (free, and it drops the fire price by those lanes). THE REDRAW IS THE ONE THAT UNBLOCKS IT - cutting alone never gets there, because every KEPT scene needs an image before fire (409 scenes_missing_frames) and the last kept scene cannot be cut. So do not offer cutting as an alternative to redrawing: it is how the user drops the scenes they are not going to redraw. Do not reach for delete_video here: it throws away an episode whose start frames are ALREADY PAID FOR and gives none of that back, so it is a genuine last resort for a user who wants the whole episode gone, not the second exit. Do not fire an episode while it has no usable frame. IF WRITING FAILS: get_video answers status: "failed" with story.stage: "writing_failed" - TERMINAL, stop polling. Nothing was charged for the episode and the cast is saved: offer the user a retry, which is simply a fresh generate_story_video call with the same idea and the same cast_member_ids (it quotes and charges like any new episode - no double charge, the failed one took nothing). The dead job charges nothing and can simply be left, or removed with delete_video. DEFAULTS: the series' defaults block from list_series with series_id is what it is tuned for - use it unless the USER names a model, and never interview the user about options they did not ask about. defaults.language is the language the SERIES is written in (some are German formats): omit language and it is used automatically - only pass one when the user asked for a different language. NOT ON THIS SURFACE (deliberate - the aicut webapp owns them today): dance scenes, multi-part / continuation episodes, recreate-from-a-video, per-scene location or setting images, custom per-scene scripts, open-idea (series-less) episodes, and part of the cast edit surface (renaming a member, adding your own, adding one from a photo - a single portrait CAN be redrawn with regenerate_cast_portrait, and a member CAN be changed into a different character with describe_cast_member). AT FRAME REVIEW the webapp additionally offers, and this surface does not: changing ONE scene's length (which re-prices the fire), editing a scene's DIALOGUE line by line, and pinning a per-scene reference still. Say so if the user asks for one - do NOT try to emulate them through the idea text, through a redraw, or by starting the episode over. WHAT IS NO LONGER ON THAT LIST: changing what HAPPENS in a scene. change_story_scene takes a plain sentence ('the kid should look super sad'), rewrites that scene's own setting / people / action text from it and redraws its picture for one image's price - and the change reaches the scene VIDEO too, not only the still. COST: this charges the FRAMES stage now and refuses accounts that could not afford the whole episode. Quote the chosen length's own rung from the series' FULL list_series entry (the series_id call - the compact catalog has no rungs) - frames_tokens now, videos_tokens at fire, total_tokens for the episode - in the message where you ask for the go, together with the promise that the videos are only charged when the user fires them. EVERY RUNG THAT SHIPS IS exact, so its price is ONE number rather than a range - and if one ever ships with exact: false, do not read the price off the rung at all: call estimate_only and quote that. TILDE WHAT THE RUNG SAYS IS NOT FIRM, which is a SEPARATE question from exact: videos_estimated true means the episode writer is not held to videos_tokens (it picks its own scene count and lengths whatever the rung orders), and frames_estimated true means the same for frames_tokens (the rung ordered only a total length, so that figure is what the expected scene count costs). Mark each true one with a tilde even when exact is true - a rung is routinely both - and tilde the TOTAL whenever EITHER is true, since the total is the two halves added. Those are the sign-off's own verdicts, so quoting them this way reads exactly as the webapp's button does. ONE CAVEAT: frames_tokens is priced at the series' DEFAULT start-frame model, so if you also pass start_frame_model the frames charge will differ - quote from estimate_only in that case, never from the published rung. estimate_only echoes the SAME markers (frames_estimated, videos_estimated, scene_count_estimated), so tilde its figures on exactly the same rule - it is a quote, not a firmer number than the rung it came from. SO DOES THE PAID 201, and that is the response you report off: if it comes back with frames_estimated or scene_count_estimated true, then frames_stage_tokens, estimated_tokens and scene_count on it are all still estimates, and you say so in the line where you tell the user what was ordered. estimate_only: true re-quotes the same split against the live balance without spending. The frames figure follows the REAL written scene count: on series whose writer sizes the episode itself the written episode can carry a few scenes more or fewer than the rung derives, and fire_story_video's own estimate_only is the exact remaining price at fire time, for exactly the lanes that will generate. WHEN YOU CAN STATE THE ALL-IN TOTAL, which is not before the cast. Four things are bought across an episode: the cast portraits, the start frames, the scene videos and the final render. THREE of them are quotable up front - the two stage figures ride the rung above, and pricing.render_tokens_per_minute on the same list_series entry is what a rendered minute costs. THE PORTRAITS ARE NOT: their number is portraits_needed on the FREE generate_cast response, which does not exist until the cast has been drafted. So the itemized total is stated AFTER the free cast call and BEFORE the portraits are bought - that is the first moment every line of it is real. Do not guess a portrait count from the idea to get a total sooner, and do not present the two stage figures as the whole episode: say what they cover. IF THIS SERIES NEEDS A CAST, THE QUOTE SAYS SO. An estimate_only answer carries cast_required and cast_member_ids_missing when the series takes one: cast_member_ids_missing: true means this exact request PRICES but would be REFUSED - the price is real, the call is not yet executable. Do not ask for a go on it. Draft the cast (generate_cast, free), buy its portraits, and quote again with the member ids. SIZING: the only sizing question you ever ask is LENGTH in seconds - 'how long should it be? 30 seconds is the default.' NEVER ask the user for a scene count. Do NOT derive a length or a count yourself either - the series' published pricing.video_models[].durations.options IS the picker: each entry is a real episode length in seconds with the scene count the rung derives and the tokens it costs. THAT BLOCK COMES FROM list_series WITH series_id (the compact catalog carries no ladder and no prices - only a rough episode_tokens range for pitching), so make that call before you offer lengths or state any price. Offer the lengths near what the user asked for, then pass the chosen entry's seconds as duration_seconds. durations.default_seconds is the rung to assume when they express no preference. Every rung that ships is exact, so its price is ONE number rather than a range; if one ever ships with exact: false, do not read the price off the rung at all - call estimate_only and quote that. videos_estimated and frames_estimated are a different question, and they say whether each figure is one the episode writer is HELD to: tilde every figure whose flag is true even on an exact rung, and tilde the total whenever either is. And scene_count_estimated says the same about the rung's scene_count. NEVER STATE A SCENE COUNT AS FACT. A rung's scene_count is what THAT RUNG DERIVES, not what the episode will contain: the writer sizes the episode itself and routinely lands a scene or two either side - on a rung whose frames_estimated is true it is not held to the count at all. So do not say 'at 20s that's 3 scenes'. If the user asks how many scenes they get, answer with the hedge attached - 'the writer decides; this length usually comes out around 3' - and never let a count you stated become a number the user thinks they bought. The count is not a sizing input, not a quote, and not a promise. AND DO NOT VOLUNTEER IT AT ALL: scene_count is internal bookkeeping that rides these responses so the machinery can be reasoned about, not a fact the product tells anyone - the webapp never shows a user a scene count and never asks for one, so neither do you. Answer it only if the user asks, with the hedge above, and never open a sizing question with it. OFFER THE IMAGE MODEL, ONCE. The pictures are what the user actually looks at, so do not pick the image model silently while asking them about the video model - name it in the SAME line as the thing you are already asking, with the default already chosen and its price: 'the opening picture of each scene is drawn by <default> (<price>) - or <alternative> for <price>; the video is <video model>.' ONE line, not an interview, and not a second question: if they express no preference, use the series' own default and move on. It IS the series' tuned look, so recommend it rather than presenting a menu. Never ask about a model the user cannot see the effect of, and never re-ask on a later episode in the same conversation. SAY IT IN PLAIN WORDS - name what the model DRAWS as the user would say it ('the opening picture of each scene', 'the cast's faces'), never in argument names: 'start frames' and start_frame_model are field names, not phrases to say out loud. SPEND ETIQUETTE (the money grammar): in the webapp the priced button is the user's own finger; in chat YOUR tool call is not - so state the price IN THE SAME MESSAGE as the ask, and the user's explicit go is the button press. Never charge on inference: quoting is not asking, and after a price you wait for the yes. THIS APPLIES TO EVERY TOOL CARRYING THIS NOTE, including this one. A GO IS SCOPED TO ONE PURCHASE, AND IT MUST BE UNAMBIGUOUS. The user's instruction has to NAME the thing you are about to buy, or refer to it so plainly that it cannot mean anything else. A BARE AFFIRMATION - 'go', 'yes', 'ok', 'do it', 'just do it', 'sure' - counts ONLY when ALL THREE of these hold: the message immediately before it was YOUR priced ask for THAT EXACT action, nothing else was raised in between, and NOTHING THE USER ASKED FOR EARLIER IS STILL OUTSTANDING. That last one is the trap the others miss: if the user's OWN previous turn asked for something else - a refusal, a different scene, an edit, a redraw, a question - their 'just do it' may be answering THAT, and it is AMBIGUOUS even when your priced ask happens to be the last thing said in the thread. An ambiguous affirmation is not a go: ask WHICH one they mean and state that price again. WHEN IN DOUBT ABOUT WHAT A 'GO' REFERS TO, ASK. A wrong guess spends the user's money on something they never asked for, and nothing on this surface can undo it or give it back - asking costs one sentence. An episode's STAGES - cast portraits, episode create, fire, render - are each their own priced ask. A STANDING GO IS NOT UNLIMITED: 'just make it' or 'go ahead with the whole episode' authorizes the stages you PRICED IN THAT SAME MESSAGE, in the order you named them, and nothing beyond them - so do not re-ask per stage while it holds, and do not stretch it over a stage whose price the user never saw. IT EXPIRES THE MOMENT THE USER RAISES ANYTHING ELSE - a change, a question, a refusal, a redraw, a new idea - and after that the next stage needs its own priced ask. ONE STAGE IS NEVER COVERED BY A STANDING GO AT ALL: the FIRE (fire_story_video) is irreversible and the biggest single charge in the episode, so it always takes a go that NAMES firing, whatever was said earlier - see that tool's own note. A REDRAW IS NOT A STAGE: regenerate_story_frame and regenerate_cast_portrait are extra spends the user asks for one at a time, so state that price every time, even under a standing go. A standing go never carries to a different episode, and never to generate_video, generate_image or generate_audio - each of those is its own ask. ACCOUNT FOR YOUR OWN CALLS: if the user says something happened that you did not intend - a charge they did not expect, a step they did not ask for - RE-READ YOUR OWN TOOL CALLS IN THIS CONVERSATION before you answer, and tell them plainly which tools you called and when. NEVER SPECULATE ABOUT A CAUSE YOU CANNOT OBSERVE: not a button on an aicut card, not the user's own click, not their client. The aicut cards CANNOT SPEND - the only tools they ever call are the reads (get_video / get_image / get_audio), and their buttons either save a file or send a VISIBLE user turn into the chat - none of them calls a spending tool - so saying a card might have generated or charged something is false, not a hedge. (If a spend followed one of those visible turns, it was still YOUR call, and the honest answer names it.) If your call history disagrees with what you told the user, say what you actually called and let them correct you; do not invent an explanation that makes the two agree. BREVITY: lead with the ONE decision you need from the user, and keep at most one short paragraph before the question. Never re-explain the staged flow (cast -> frames -> fire -> render) once it has been explained in this conversation - after that, name only the next step. When suggesting episode ideas, offer at most 3, one line each. IDEMPOTENCY: idempotency_key is optional and makes a retry safe. Set it on the FIRST call, not only on a retry - the job is addressed by the key, so a key added afterwards cannot find a job that was created without one. Reusing a key REPLAYS the job that key already created and returns it unchanged - even if you send a different prompt or different settings, and even after that job has finished. A key is therefore spent permanently. Do NOT reuse one to make another generation: two deliberate generations are two jobs and need two different keys (or none). ONE EXCEPTION, on render_story_video: replaying a key whose render FAILED answers 409 render_failed rather than replaying the failure, because a spent key stays spent - retry that one with a NEW key or with none. A KEY IS NOT SCOPED TO A TOOL: it addresses a job on the whole account, so reusing the key you gave generate_video on generate_story_video replays that first video instead of starting an episode. One key, one thing you made. (render_story_video is the one door that namespaces its own, which is why an episode's key can be reused on its render without colliding - but there is no reason to reuse it there either.) Never derive the key from the request body. You do NOT need to pass one to be safe against a duplicated delivery: aicut already derives a per-call key server-side, so a retry the transport makes on its own replays rather than charging twice. Pass your own only when YOU want to retry a call whose answer you never saw. OUTPUT: this returns JSON for you to read. When you report back to the user, give them the media URL plus a one-line summary. Do not paste the raw JSON, job ids, or internal field names into the conversation.