generate_cast

Writes the CAST for an AI Video Story series - named characters with a role and a one-line description each - and returns it as a DRAFT for the user to read. FREE: this call spends no tokens. It generates no portraits and saves nothing to the user's character library. WHAT IT ACTUALLY RUNS: a showrunner model reads the series and the idea you passed and answers with the cast that idea needs - who those people are, how they relate, what species the series casts them as. IT DOES NOT WRITE THE STORY. When you pass an idea, the response's idea field is the one you sent, unchanged (translated into the output language if it was in another one); the plot is written later, by generate_story_video. If you pass NO idea, the call authors a logline itself and the idea field is that logline - the only case where it comes back with something you did not send. Same call the webapp's cast step makes. Nothing is charged for any of it. WHEN: as soon as the episode idea is settled, on a series whose cast.required is true (or whose user wants custom characters). Do NOT ask permission first - it costs nothing, and the webapp writes this roster automatically at the same point. A series with cast.writer_owned: true casts itself at episode-write time; never call this for it. AFTER: show the user the names and roles, one short line each - the cast is the whole review. Do NOT present the idea field back to them as news when you passed one in: it is their own idea and saying otherwise invents a change that did not happen. The one exception is the no-idea call, where the idea you get back IS the logline the writer chose and the user has not seen it yet - show them that one and ask whether to keep it. If they dislike the roster, call this tool AGAIN with a sharper idea - a re-draft is free and replaces it, exactly like the webapp's 'Rewrite cast'. Never buy portraits for a cast the user has not accepted. THE PRICE OF THE NEXT STEP RIDES THIS RESPONSE: portraits_needed is how many faces are missing - it counts exactly the members whose needs_portrait is true, because a preset-bound member arrives photographed and costs nothing - and portrait_models lists every image model that can draw them, each with per_portrait_tokens and the roster's total_tokens on it (the default: true entry is what the series is tuned for). Use those numbers verbatim in the message where you ask for the go - do not multiply anything out yourself. THEN: generate_cast_portraits with this response's draft_id mints the portraits. That call is the money. The draft stays redeemable for about two hours; after that write a fresh one (free). NOT ON THIS SURFACE (the aicut webapp owns them today): renaming a cast member, adding your own character, and adding one from a photo. Say so if the user asks - do NOT re-draft the whole cast to work around a single member, and do not try to steer one member by rewording the idea. CHANGING what a member IS is available once the portraits are bought: describe_cast_member rewrites one member's look for one portrait's price. REFUSALS you act on, all 400 invalid_request except the last two - the message says which: the series is unknown or unavailable; the series SHIPS ITS OWN FIXED CAST, so there is no roster to write and none to buy; the series casts itself at episode-write time (cast.writer_owned on list_series predicts this one); or the series does not support a cast-first flow at all. In every one of those, go straight to generate_story_video without a cast rather than retrying with different wording. 429 utility_rate_limited / utility_globally_limited = this call is FREE but not unlimited - it spends a rate-limited AI-writing allowance shared with the webapp, and the answer is to wait the retry-after (about a minute for a burst, a rolling day for the account's daily cap), never to top up tokens. 503 casts_unavailable = transient, try again. BREVITY: lead with the ONE decision you need from the user, and keep at most one short paragraph before the question. Never re-explain the staged flow (cast -> frames -> fire -> render) once it has been explained in this conversation - after that, name only the next step. When suggesting episode ideas, offer at most 3, one line each. 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.