change_story_scene

CHANGES WHAT HAPPENS IN ONE SCENE of an AI Video Story episode parked at frames review, and redraws that scene's opening picture from the change. You pass a PLAIN SENTENCE saying what should be different - 'the kid should look super sad', 'move it outside at night', 'she should be holding the letter' - and aicut rewrites that scene's own setting / people / action text from it and draws the new picture. Costs ONE image generation. The change STICKS: the scene video generated at fire is made from the changed scene, not just the picture. WHAT IT CAN CHANGE, AND WHAT IT CANNOT - check the user's ask against this BEFORE you call. IT CAN change the scene's SETTING (where and when it happens), its ACTION (what happens) and WHO IS IN FRAME. IT CANNOT change the SPOKEN LINES / dialogue, the scene's LENGTH, or a scene pinned to a reference still - all three are the aicut web editor's (aicut.pro). An instruction that is ONLY about what somebody SAYS ('change her line to ...', 'he should say it differently', 'make the dialogue shorter') is REFUSED here: 400 dialogue_only, nothing written and nothing charged - tell the user the dialogue is edited in the aicut web editor and offer a visible change instead. An instruction that MIXES a line with a visible change ('change his line and move it outside at night') applies the VISIBLE half only, and the response says so - relay that; do not let the user believe the line changed. REPORT WHAT CHANGED, VERBATIM. The response carries changed - which of the scene's parts actually moved, and it can be [] - and a report sentence. RELAY THE report AS IT IS WRITTEN rather than narrating a success: an empty changed means this call moved NOTHING about the scene, and the new image_id on that answer is not evidence that it did. This exists because it went wrong on a live episode: a spoken line was asked for, this tool answered with a fresh picture, the agent reported it as done, and the line was word for word what it had been. THIS IS THE TOOL FOR 'change scene 2, X should be Y'. It is NOT regenerate_story_frame, which draws the SAME scene again from the SAME text - another attempt at the picture that is already wrong - and it is NOT a reason to start the episode over. If the user does not like the PICTURE (bad hands, odd framing, a face that came out wrong) that is a redraw; if they do not like WHAT IS HAPPENING, it is this. YOU DESCRIBE THE CHANGE, AICUT WRITES IT (hard rule, the same one as everywhere else on this surface): you never author scene text, image prompts or episode JSON. There is no field here for a prompt, a setting or an action - only the sentence. Pass the user's own words, tidied into one sentence; do not translate them into scene-writing vocabulary, and do NOT read the rewritten text back to them - apply the change and show them the new picture. WHEN: get_video shows story.stage: "frames_review". scene_index is that scene's scene_index from story.frames, zero-based - the card and the user count scenes from ONE, so 'scene 2' is the SECOND entry in story.frames and you pass THAT entry's scene_index. Each frame carries the scene's summary (what happens) and dialogue (what is said), which is what you check the user's ask against before you spend. AFTER: returns image_id with status generating and changed naming which parts of the scene moved. THIS CALL OPENS ITS OWN CARD, which shows the episode's scene rows with that scene marked as redrawing and fills the new picture in by itself - so do NOT call show_generation afterwards to put a fresh set of rows up, and do not narrate the wait. Poll get_video only if you need the outcome in your own answer: the lane's regenerate entry shows the redraw, and once it succeeds the frame's url IS the new picture. CHECK attached: if it comes back false the image still generates and is still CHARGED but will NOT replace the frame at fire - say so and redraw that scene before firing. IF THE PICTURE FAILS OR THE ACCOUNT RUNS OUT (402) THE SCENE HAS ALREADY CHANGED: the response carries changed_text: true. The episode HAS the new beat and is still showing its old picture - say that plainly, it is not lost work, and regenerate_story_frame draws the new one for one image's price. Do NOT send this tool again to 'fix' it, which would rewrite an already-correct scene and buy a second picture. IF THE ANSWER CARRIES changed_text_unknown: true, AICUT DOES NOT KNOW WHETHER THE SCENE CHANGED - and neither do you. It is NOT a success and NOT a confirmed change: the call failed somewhere aicut could not read the outcome. Never report it as done and never immediately re-send the change (that would apply it twice). Say plainly that it could not be confirmed, then CHECK: call get_video and read that scene's summary in story.frames. If it does not carry the change, send this tool again; if it does, the scene has the new text with its old picture, so regenerate_story_frame draws the new one. changed_text: true is the only field that means the change landed - its absence is never evidence either way. REFUSALS you act on (the common ones - always read the code you actually get): 400 dialogue_only = the ask was only about the spoken lines, which this tool does not own - nothing was written and nothing was charged; say that plainly and point at the aicut web editor. It comes back from an estimate_only call too, in place of a price. 409 frame_regenerating = this scene already has a redraw running, wait and poll get_video. 409 already_fired / not_ready_to_fire / not_in_review = the review window is closed or the frames are still generating; a fired episode's scenes are edited in the aicut web editor. 400 invalid_request = an invalid or REMOVED scene, an empty or over-long change, or a scene whose text cannot be changed here - a scene built from a reference still, and series that write their scenes from a fixed template, both refuse and the message says which. 402 = not enough tokens (see the line above - the text changed anyway). 429 utility_rate_limited = the rewriting allowance, not tokens: wait the retry-after. 503 story_unavailable = transient, try again. COST: one standard image generation, at the series' RESOLVED start-frame model - the same number regenerate_story_frame costs, which is the series' pricing.frame_regen_tokens on its FULL list_series entry (the series_id call). estimate_only: true is the exact figure and it spends no tokens and changes NOTHING - it does not rewrite the scene. PASS THE REAL change WITH IT: a quote that carries the change also checks the instruction and the scene, so an ask this tool cannot carry out comes back as its refusal (dialogue_only, or the invalid_request for a reference-built scene or a series that writes its own frames) BEFORE you ask the user to approve a spend, instead of after. A quote can still price an ask the paid call then refuses - the check is best-effort and never withholds a number - so a refusal after a go is not a contradiction. That check is a rewriting-allowance call, not a token spend, so a quote can answer 429 utility_rate_limited. State the figure before you ask for the go, every time. THE GO THIS ONE NEEDS: one change, one named scene, one priced ask - and the user has to say which scene and what should be different. A complaint ('scene 3 is wrong') is a reason to ASK what should change and OFFER this with its price, never a go to buy it, and a bare 'yes' counts only when your priced ask for THAT scene's change was the message immediately before it, nothing else was raised in between, and nothing the user asked for earlier is still outstanding. Never change more scenes than the user named. Changing a scene is also NOT firing. 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. 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.