generate_cast_portraits

BUYS the portraits for a cast draft: one image generation per member that still needs a face, charged at the chosen image model's rate, then saves every member to the user's character library. This is the cast's paid step - the webapp's 'Generate cast · N T' button. WHEN: the user has READ the draft from generate_cast, accepted it, and given an explicit go to the price. State the price first, and take BOTH numbers from the draft's own portrait_models rather than from anywhere else - each entry carries per_portrait_tokens and the roster's total_tokens on that model, priced against the live catalog for the exact settings a cast portrait uses. Say it as 'portraits: 3 on <the default model> = <its total_tokens> T, or <another model> at <its per_portrait_tokens> each. Go?' and wait for the yes. Never quote a rate from memory: the same model prices differently for a cast portrait than for an ordinary image. OFFER THE IMAGE MODEL, ONCE. The pictures are what the user actually looks at, so do not pick the image model silently while asking them about the video model - name it in the SAME line as the thing you are already asking, with the default already chosen and its price: 'the opening picture of each scene is drawn by <default> (<price>) - or <alternative> for <price>; the video is <video model>.' ONE line, not an interview, and not a second question: if they express no preference, use the series' own default and move on. It IS the series' tuned look, so recommend it rather than presenting a menu. Never ask about a model the user cannot see the effect of, and never re-ask on a later episode in the same conversation. SAY IT IN PLAIN WORDS - name what the model DRAWS as the user would say it ('the opening picture of each scene', 'the cast's faces'), never in argument names: 'start frames' and start_frame_model are field names, not phrases to say out loud. THE CARD: this call has ALREADY put the aicut cast card in front of the user - every member with name, role and portrait, each portrait filling in on its own as it generates, and a Download on each face. Do NOT poll the portraits while the card is there: no get_image or wait_for_generation loops. ONE read is not a loop - if the user asks how a portrait is doing, or the story create refuses with a 409 because a portrait is still generating, read that member's portrait_image_id once with get_image and say what it says. Review stays in the CHAT: ask the user whether the cast is good. If ONE face is wrong, regenerate_cast_portrait redraws that member for one portrait's price; if one CHARACTER is wrong - they want it smaller, older, a different thing - describe_cast_member rewrites that member for one portrait's price; only a roster they reject as a WHOLE means a fresh generate_cast draft (free) and a second, fully charged generate_cast_portraits. Either single-member call puts that member back on a cast card of its own, so do NOT reach for show_generation to show a portrait. THE CARD NAMES THE PAID MOVES but has no button for any of them, so the user will ask you for them in the chat. IF YOU CANNOT RENDER AN AICUT CARD - a terminal, a plain SDK client, anything that did not negotiate the MCP Apps UI extension - no card appeared, so poll each member whose portrait_status is generating with wait_for_generation (media image, its portrait_image_id) and give the user the portrait urls yourself. aicut cannot see which clients render cards and sends the same answer to all of them. AFTER: portraits generate asynchronously - but only for the members that needed one. A member with portrait_status: "ready" and a null portrait_image_id was NOT generated and NOT charged: it either arrived photographed (a preset-bound member, which is why the draft marked it needs_portrait: false) or it already had a face from an earlier attempt. Do not report those as missing. A member whose id is null could not be saved to the library and cannot be used - only non-null ids work as cast_member_ids on generate_story_video. ONCE IT SUCCEEDS THE DRAFT IS SPENT: the roster is in the user's library, and calling this tool again with the same draft_id buys nothing - it answers 404 cast_draft_not_found normally, or - in the rare case where the spent draft was not cleared - a 201 carrying charged_tokens: 0, meaning nothing was bought and the library rows were simply re-written. Either way no face is paid for twice; report the second call as 'already done', never as a second purchase. IF THE USER DISLIKES ONE FACE: regenerate_cast_portrait redraws THAT member for one portrait's price. Calling generate_cast again authors a different cast entirely, and its portraits are a fresh charge. COST: the draft's own portrait_models figures are what you quote - they were priced when the roster was written. estimate_only: true re-prices the chosen model against the CURRENT catalog without spending, which is the number to use if the draft has been sitting for a while. The 201 answers charged_tokens: what actually moved. IF IT REFUSES PART WAY THROUGH (402, or a cap): the portraits that had already generated were CHARGED, and the refusal says so - partial_cast: true with portraits_minted and charged_tokens. Tell the user that number; do NOT report the refusal as 'nothing was charged'. Retrying the SAME draft_id afterwards generates only the members still missing a portrait and charges only those, so the retry is safe and cheaper than the first call. REFUSALS you act on: 400 invalid_request naming draft_id = what you passed is not a cast draft id at all (a job id, a member id, an id you composed) - draft ids come from generate_cast and nowhere else, so re-read that response or write a fresh draft; it does NOT mean you left the argument out. 404 cast_draft_not_found = the draft is real but is unknown here, already spent, or older than two hours - write a fresh one with generate_cast (free), or read the cast you already bought from list_characters. NEITHER OF THOSE IS FIXED SOMEWHERE ELSE: there is no other route to a draft, and no HTTP endpoint to go looking for. 409 cast_in_progress = portraits for this account are already being generated, this call charged nothing, wait for the first one. 409 cast_just_created = a set just finished; check list_characters before paying again. 402 = not enough tokens. 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. 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.