Create an AI Video Story episode (frames stage)
generate_story_videoStarts an AI Video Story EPISODE (stage 1 of 3): the engine writes the multi-scene episode from your idea, draws the OPENING PICTURE OF EVERY SCENE, and PARKS for the user to look at them before any video generates. Returns immediately. Say 'the opening picture of each scene' to the user, never 'start frames' or 'frames review' (field names). WHEN: the series is picked and its FULL entry fetched (list_series WITH series_id and video_model: the ladder and prices are only there), the idea is settled, and for a cast.required series the cast is drafted, its portraits bought and the user has said go to them. The whole flow: get_recipe story-episode. INPUT: ONE idea (a short paragraph) plus options; never scenes, dialogue or image prompts (a scenes field is refused). A member whose portrait is still generating is refused 409. Use the series' defaults unless the user names a model. THE CARD: this call already put the aicut frames card in front of the user; it follows the episode through writing and pictures itself. Say one short line (what was ordered, and that the opening picture of each scene will appear for them to look at, in plain words) and STOP: no wait_for_generation, no get_video loop while it walks. The card stops updating at the review, so after a redraw read get_video until that lane's regenerate is terminal, then show_generation with the episode id puts a fresh grid up. No card (a terminal)? Poll get_video until story.stage is frames_review and give the user the frame urls. AFTER: story.stage moves starting, generating_frames, frames_review and STAYS there until fired: the next move is the user's. writing_failed is terminal, nothing charged, cast saved: call again with the same idea and cast_member_ids. IF EVERY FRAME FAILED it parks with no usable picture: regenerate_story_frame is the way out; do not offer delete_video, which throws away pictures ALREADY PAID FOR (story-episode recipe, step 6). COST: this charges the FRAMES stage now and refuses an account that could not afford the whole episode. Quote the chosen rung from the FULL entry: frames_tokens now, videos_tokens at fire (charged only then), total_tokens. TILDE a figure whose videos_estimated or frames_estimated is true (a SEPARATE question from exact: even when exact is true), and tilde the TOTAL whenever EITHER is. If a rung is not exact, or you pass a start_frame_model other than the default, quote estimate_only: it and the paid 201 carry the same markers (frames_estimated, videos_estimated, scene_count_estimated), reported with the same tildes. cast_member_ids_missing: true on an estimate means the request would be REFUSED: do not ask for a go on it. SIZING: ask only LENGTH in seconds (30 is the default), never a scene count; offer lengths from pricing.video_models[].durations.options (only on the series_id call of list_series) and pass the chosen seconds as duration_seconds; never compute a rung. Never state a scene count as fact: it is only what a rung derives and the writer decides; do not volunteer it. OFFER THE IMAGE MODEL ONCE, in a line you are already writing (not an interview): name the model that draws the pictures in plain words with its default and price; no preference means the series' default. SPENDS TOKENS: price with estimate_only: true, ask in the SAME message as the price, and wait for a go that names THIS purchase (SPENDING RULES, this server's instructions). IDEMPOTENCY: a reused idempotency_key REPLAYS the first job whatever the settings: never reuse one for a new generation (this server's instructions).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| idea | Yes | The episode idea: one short paragraph of plain prose, no scene lists, shot directions or image prompts. | |
| language | No | Omit unless the user asked for another language: the series' `defaults.language` is used. | |
| series_id | Yes | The series id, exactly as `list_series` returns it. | |
| video_model | Yes | One of the series' `pricing.video_models` ids: its `defaults.video_model` unless the user names one. It decides which duration ladder applies, so pick it before the length. | |
| aspect_ratio | No | `9:16` (default) or `16:9`. | |
| estimate_only | No | Price only; creates nothing. | |
| cast_member_ids | No | Approved cast member ids from `generate_cast_portraits` (or `list_characters`, kind `cast_member`), in roster order. Required when `cast.required`, forbidden when `cast.writer_owned`. | |
| idempotency_key | No | Retry-safety key (IDEMPOTENCY). | |
| duration_seconds | Yes | Episode length in SECONDS: one of the chosen model's published `durations.options[].seconds` on the series' FULL `list_series` entry (`durations.default_seconds` if the user has no preference). Never a scene count; an unpublished value is refused. | |
| start_frame_model | No | Image model for the opening pictures (`pricing.start_frame_models`). Omit for the series' `defaults.start_frame_model`, which `frames_tokens` is priced at; any other needs a fresh `estimate_only`. |