render_story_video

RENDERS an AI Video Story episode into its final delivered file - stage 3 of 3, after the scene videos are done. The render is composed SERVER-side from the stored episode (scenes, captions, music, title card, watermark policy); you pass nothing but the episode id. WHEN: get_video shows the episode succeeded (or story.stage: "ready_to_render"). Rendering an episode the user edited in the aicut web editor picks up those edits. A second render of the same episode is allowed once the first finished - the LATEST render is the file the episode serves. AFTER: the response carries render_id and story.stage: "rendering". Poll get_video and read story: stage: "rendered" means THIS render succeeded - story.render.url is the FINAL delivered file (captions, music, title card); show THAT url to the user. story.render.status: "failed" means the render failed and its charge was refunded - call this tool again. NEVER hand out the episode url before stage: "rendered": at ready_to_render it serves only the raw stitched scene preview, not the finished video. A repeat call while a render is running answers the SAME render_id with coalesced: true - the first render is the render; never treat that as a failure. REFUSALS (the common ones, not all of them - always read the code you actually get): 409 not_ready_to_render names the episode's current stage - finish that stage first. 409 not_renderable = this job is not an AI Video Story episode at all. 409 render_failed = you reused an idempotency_key whose render already failed; a spent key stays spent, so call again with NO key. 402 = not enough tokens (the response carries required and balance). 502 upstream_error and 503 story_unavailable are transient - nothing was charged, call again. COST: the render is charged per rendered minute at the platform render rate, priced from the episode's OWN duration. Pass estimate_only: true first for the exact number without spending, and state it before you ask for the go. THAT ESTIMATE ONLY WORKS ONCE THE EPISODE IS RENDERABLE - the price is read off the COMPOSED episode, which does not exist until the scene videos are done, so before then this tool refuses the quote along with the render and names the stage. TO PUT THE RENDER IN AN EARLIER SIGN-OFF, quote the RATE instead: pricing.render_tokens_per_minute on the series' FULL list_series entry (the series_id call) is what a rendered minute costs, so a 30-second episode is roughly half of it. Say it as the rate or as a rough figure with a tilde, never as the price - the exact number is this tool's own estimate_only, and that is what you state in the message where you ask for the render itself. DELIVERY: hand the user ONE thing - the final video url with a single line (its length, what it is), plus one clause noting that captions, overlays and deeper edits live in the aicut web editor, where the episode already is. Do not narrate the render pipeline. THE GO THIS ONE NEEDS: a render is its OWN charge and its own ask, and it is not implied by anything that came before it. Approving the scene videos, saying the episode looks good, asking to see it, or a standing go whose priced stages have all been spent are NOT a go to render. The user's instruction has to name rendering or the final file ('render it', 'make the final video'), and a bare 'yes' counts only when your priced render ask was the message immediately before it, nothing else was raised in between, and nothing the user asked for earlier is still outstanding. If you are not sure, ask and state the number again. 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.