regenerate_story_frame

pro.aicut/aicut · Verify this server

Redraws ONE scene's start frame of an AI Video Story episode that is parked at frames review (`story.stage: "frames_review"` on `get_video`). The engine redraws it with the scene's own composed prompt, cast and continuity references - you author nothing (hard rule: you never write image prompts; there is no prompt argument). WHEN: the user looked at the frames and dislikes THE PICTURE ITSELF - bad hands, odd framing, a face that came out wrong, or a lane that failed. `scene_index` is that frame's `scene_index` from `get_video`'s `story.frames`, zero-based. IT IS NOT THE TOOL FOR 'CHANGE WHAT HAPPENS'. This redraws the same scene from the SAME text, so a user who wants the kid to look sad, the scene moved outside, or a different thing to be going on gets another picture of the beat they already rejected - and pays for it. That ask is `change_story_scene`, which rewrites the scene's own text first and costs the same one image. Read the frame's `summary` before you choose: if what it says is wrong, redrawing cannot fix it. SAY WHAT IT DID, WHICH IS THE PICTURE AND NOTHING ELSE. The response carries a `report` sentence - RELAY IT, do not replace it with your own account of what happened. It says the scene was redrawn from its EXISTING text and that what happens, who is in frame and the SPOKEN LINES are all unchanged, because this tool changes none of them. Never tell the user a redraw made a scene different. AFTER: returns `image_id` with status `generating`. 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 grid 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's progress, and once it succeeds the frame's `url` IS the new image. The new frame is applied to the episode when you fire. Repeats are allowed: the LATEST successful redraw per scene wins. A failed redraw keeps the old frame. CHECK `attached`: if it comes back `false` the image still generates and is still CHARGED, but it will NOT replace the frame at fire - say so and regenerate that scene again before firing. CAST PICK (optional): pass `cast_member_ids` to redraw the scene with a DIFFERENT subset of the episode's cast - the same library ids you passed to `generate_story_video` (from `generate_cast_portraits` or `list_characters`, kind `cast_member` - the FREE `generate_cast` draft has no library ids at all). Only when the user explicitly asks to change who is in the frame; omit it otherwise (the scene's own cast is used). `[]` draws the scene with no characters at all. A member the episode never cast is refused; a scene built from a reference image refuses any pick. Keep picks SMALL (the people actually in the shot) - a pick beyond what the frame model can seat draws only the first few portraits. REFUSALS you act on (this list is the common ones, not all of them - always read the `code` you actually get): 409 `frame_regenerating` = this scene's redraw is already running, wait and poll `get_video`. 409 `already_fired` / `not_ready_to_fire` = the episode is not at frames review (too late, or the frames are still generating). 409 `not_in_review` = the review window is closed for this episode. 400 `invalid_request` = an invalid scene index, a scene that has been REMOVED (`set_scene_kept`), or a cast pick the episode never cast / a reference-built scene that takes none. 402 = not enough tokens. 503 `story_unavailable` = transient, try again. COST: one standard image generation. A redraw ALWAYS runs on the series' RESOLVED start-frame model - not on the `start_frame_model` the episode was created with - at that model's ordinary image rate, which is NOT the discounted per-frame rate the create charged for the same lane. So do not quote it from `pricing.start_frame_models`: the series' `pricing.frame_regen_tokens`, which rides the series' FULL `list_series` entry - the `series_id` call, since the compact catalog carries no prices is that number when the catalog publishes one, and `estimate_only: true` is both the confirmation and the ONLY answer when it is null. State the figure before you ask for the go, every time - a redraw is not covered by a standing go on the episode. THE GO THIS ONE NEEDS: one redraw, one named scene, one priced ask - and the user has to say which scene. A complaint about a picture ('scene 3 looks off') is a reason to OFFER the redraw with its price, never a go to buy it, and a bare 'yes' counts only when your priced ask for THAT scene's redraw was the message immediately before it, nothing else was raised in between, and nothing the user asked for earlier is still outstanding. Never redraw more scenes than the user named, and never treat a go for one scene as a go for the rest. Redrawing is also NOT firing: this tool draws a picture and nothing else. 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.