fire_story_video

pro.aicut/aicut · Verify this server

FIRES a parked AI Video Story episode: stage 2 of 3 - the engine resumes the run and generates every kept scene's VIDEO from its reviewed start frame. This is the paid step after frame review; nothing renders yet (the final render is the next stage). WHEN: `get_video` shows `story.stage: "frames_review"`, the user has looked at the frames, wrong ones were regenerated (`regenerate_story_frame`) and their redraws are DONE. Scenes the user wants CUT are removed first with `set_scene_kept` - a removed scene's VIDEO is never generated and never charged, so the fire quote drops by exactly that lane. (Its start frame was already drawn and charged at create; cutting it does not give that back.) Always pass `estimate_only: true` first - it quotes the REMAINING scenes-stage price for exactly the kept lanes that will be charged. THE CARD: this call has ALREADY put the aicut episode card in front of the user, and it follows the scenes stage on its own. So do NOT poll to give them something to look at - the card is that. IT GIVES UP AFTER ABOUT TWENTY MINUTES, which this stage's long tail does exceed: the card then says so and stops updating. That is not your cue to start polling - it is the user's cue to ask, and their question is your cue to make ONE `get_video` read and answer it. AFTER: on success the response says `fired: true` and `story.stage` moves to `generating_scenes`. Give the user the leave-safety line below and STOP - do NOT run a `get_video` poll loop while the scenes generate: it fills the transcript with waiting and tells them nothing they did not already know. Read `get_video` when the user asks how it is going, and again when they come back. When the episode succeeds (or `story.stage` is `ready_to_render`) the scene videos are done - finish it with `render_story_video`, or the user renders in the aicut web editor, where the episode also appears. FIRE ONCE: a fired episode cannot fire twice - a repeat (including a retry after a timeout) answers 409 `already_fired`, which means the first fire WORKED: the episode is generating, treat it as success and poll `get_video`. Other refusals (the common ones, not all of them - always read the `code` you actually get): 409 `not_ready_to_fire` = frames still generating; 409 `frame_regenerating` = a redraw is still running, wait for it; 409 `scenes_missing_frames` = the named scenes have no image, regenerate them first; 409 `scenes_price_unavailable` / `scenes_price_exceeds_quote` = this episode can no longer be priced here, and BOTH mean the same thing to the user: finish it in the aicut web editor, do not retry; 400 `invalid_request` = no scenes are ready to generate (keep at least one scene with a start frame); 402 = not enough tokens for the scenes stage (the response carries `required` and `balance`); 503 `series_unavailable` / `story_unavailable` = transient, try again. COST: the scenes stage - each kept scene's video at the model's published per-scene rate. The frames were already charged at create; this charge is the rest of the episode quote. State the number from `estimate_only` in the message where you ask for the go, and after firing give the user the leave-safety line: the scene videos usually take under ten minutes and sometimes longer, they can close the chat, and the episode will be in their assets either way. SAY WHAT THE NUMBER COVERS, NOT JUST THE NUMBER. The `estimate_only` answer carries `scene_count` (the kept scenes that will actually generate) and `duration_seconds` (their total length) beside `estimated_tokens`, so the ask reads as the webapp's own button does - '6 T for the 4 remaining scenes, 20 seconds' rather than a bare 6 T. This is what makes a re-quote after a cut checkable: when `set_scene_kept` drops a scene, re-quote and say BOTH the new price and the new count, so the user can see their own edit in the numbers. The count is the kept lanes this fire will charge for - it is not a sizing input and it is not the rung's derived `scene_count`. TIMING (measured, not guessed): the scene videos usually finish in under 10 minutes, and OCCASIONALLY take much longer - long enough that the user should not sit and watch. Never promise a finish time; say 'usually under ten minutes, sometimes longer' and tell them they can close the chat. AUTO-RENDER: pass `auto_render: true` to have the final render start AUTOMATICALLY once the scenes finish (for automation flows that should not pause again). This arms a render charged at the render rate when it triggers - the fire's `estimate_only` quote then includes `render_estimated_tokens` - so only pass it when the user approved rendering too. Interactive flows should skip it and call `render_story_video` themselves after reviewing the scenes. THE GO THIS ONE NEEDS (read it before you call): FIRING IS IRREVERSIBLE AND IT IS THE LARGEST SINGLE CHARGE IN THE EPISODE. It cannot be cancelled, undone or refunded once it starts, so it takes an EXPLICIT go that names the thing itself - 'fire it', 'generate the scene videos', 'yes, make the videos'. A STANDING GO NEVER COVERS THE FIRE, not even one that priced it: 'just make it' said before the pictures existed is not permission to spend the biggest charge on pictures the user has not looked at yet. A bare 'yes' / 'go' / 'just do it' is a go ONLY when your priced fire ask was the message immediately before it, nothing else was raised in between, and nothing the user asked for earlier is still outstanding. NONE OF THESE IS A TRIGGER TO FIRE, however clearly the user said them: cutting or keeping a scene (`set_scene_kept`), asking for a redraw (`regenerate_story_frame`), approving ONE picture or saying a picture looks good, a question about price, timing or what happens next, a complaint, or any instruction you are not certain refers to firing. If the user's last message was one of those, ASK - name the price again and wait for an answer that names the fire. When in doubt, do not fire: the wrong guess here is the most expensive mistake available on this surface. 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.