agent-media

Paid (3 casting images). Add a recurring character (next id c to h, 8 in the cast at most): face, full body and turnaround, made in the background. relationships: [{to: id or name, kind}], at least one to a lead. On a two-lead series made before cast v2 it also gives the leads a full body and a sheet (4 more images). dry_run prices it.

Paid (1 image). Add a location (next index, 8 at most): an empty plate with walkable depth, made now. Outside places make street and rooftop scenes possible. dry_run prices it.

Costs no credits. Record the user's answer to a checkpoint. While an episode is made the server shows work and waits for the user's yes four times: cast (the cast pictures, faces and outfits, before any filming), cover (the episode cover), storyboard (before the shoot) and first_scene (scene 1 filmed, before the other scenes). make_episode and get_episode return it as show: images or video, say, next and revision. Show it, post say, STOP, and only after the user's yes call this with that kind and revision. A changed thing (a recast, another cover, an edited script, a new take of scene 1) has a new revision and needs a new yes: reason checkpoint_changed returns it to show again. After cast it returns the episode cover to show; after cover call make_episode; after storyboard and first_scene the episode films on by itself (follow it with get_episode). approved false is the user's no: for cover it makes another cover (note: a short direction) and returns it; for first_scene it films scene 1 once more inside the price already approved and shows it again; for cast and storyboard it returns how to change them (recast, save_episode_script). If approve_checkpoint is not in your tool list, call make_episode(series_id, n) again after the user's yes: it counts as the yes. Never call it without the user's answer. A checkpoint left with no answer for 1 hour is approved by itself and the episode goes on to delivery (the user left); one the user said no to waits for them. A season approved all at once stops only once, for the cast pictures.

Free, charges nothing. Record the customer's yes to one exact plan: revision and content_hash as get_season_plan or save_season_plan returned them, after the customer saw say. Refused while any episode needs a rewrite. The paid create_series for a new series and every new make_episode of a planned series need the approved current revision.

Holds credits, generates nothing. Record the customer's one yes to every season script and the season price together: scripts_hash and max_credits exactly as get_season_scripts returned them, after the customer saw say. The price is priced again and held on the account as the season's spending authority: every paid step of the series (casting, voices, storyboards, video, retakes) is drawn from it and never charged above it. approval.state active: film Episode 1 now (create_series with create_series and dry_run false, then make_episode for n 1). pending_funding: the account does not hold that price yet; once it is paid, the same create_series holds it first. Refused while any script is missing, stale, failing or unpriced, or when the price moved since it was shown (show it again).

Read-only, saves nothing. Same episode JSON as save_episode_script. Runs validation and auto-fit, then the mechanical craft check and the 30 s story grammar: first spoken line within 2 s (the hook), 25 to 45 spoken words per 30 s, lines at most 10 words (warn over 8), exactly one turn on the shot at 10 to 20 s of 30 s (both scale with the runtime), a cliffhanger_type that differs from the previous 2 episodes, no silent shot over 1.2 s except the final 1.5 s reaction, ends on a line or reaction within the last 3 s. Script rules (the server enforces these four, and for a micro_drama rule 5, the beat; episodes that jump between places and people read as unrelated cuts): places only move forward: at most 3 places in an episode, never back to a place already left; a lead (a or b) is on screen in every scene; at most 4 people on screen in an episode; nobody new after 60% of the runtime, except one newcomer in the last scene of an intrusion cliffhanger. Writing guidance, not enforced: the first spoken line is the hook; the episode ends on a lead's line. Write calm, natural acting: no face-acting notes per line; the server directs camera and performance. Cast v2: checks every scene cast (recurring characters and the episode's guests x1 and x2 included), the guests and each scene background (unnamed extras in words, never a reference image: the references are each character's full body and, once made, turnaround sheet), and warns when only the leads appear while the series has recurring characters. Timing is fixed, not handed back: a silent beat where the story is short, a scene up to 0.1 s over timed to its 10 s, a filler word cut from a line that runs long, a long pause tightened; every change is listed in fixed and episode is the fixed script (send it on). The server keeps the camera still (camera "static" by default): one slow push_in on the turn, tracking only on a walk, never a wide first shot; each change is listed in fixed. Optional shot "beat" (touch, grab, embrace, slap, shove, throw, tears, kneel, almost_kiss, kiss): one physical moment, filmed in the server's own words. Script rule 5 (rules_version 2): a micro_drama episode needs one beat on the turn shot or a shot next to it, or the check fails; a script saved before this rule still films as saved. Returns {passed, issues, warnings, episode, fixed, cast_by_scene, episode_cast}. Before the series exists, n 1 is checked against the series your last create_series dry run priced (series_created false); the dry run's own episode_1 field is the same check.

Paid (casting images). The paid call (dry_run false) only after the customer said yes to the season plan: in series_interview the round 4 yes approves it (Episode 1 first and Just go), otherwise approve_season_plan. dry_run true charges nothing and comes first: it shows the casting price, and series_interview's round 4 needs it. A new paid series id is refused without the approved current revision of its season plan, at the plan's quality and its show type's format, and while the season scripts gate is on, without its approved scripts (approve_season_scripts; the round 4 yes's next says which). Casts fictional adults: lead a and lead b (lead_* fields) plus up to 6 recurring characters in cast, each with a face, a full body and a turnaround sheet (the body, and the sheet once it is made, go to the video model in every scene the character is in), and an empty plate per location. One-episode guests and background extras are not cast here: add them per episode in save_episode_script (guests, scene background). cast: [{name, gender, age, look (face and hair), outfit (head to shoes), body_type, palette (a wardrobe colour no one else wears), signature_prop?, voice_note?, function?, relationships: [{to: id or name, kind}]}]; an entry with id a or b adds those extras to a lead. Recurring characters get ids c to h. Photo cast (a real person, with consent): a lead entry (id a or b) or a recurring entry may also carry photos, 1 to 4 image_url values from this account's uploads (upload_image, get_uploads) showing the same one real adult, and photo_consent, required with photos: "i_am_this_person" (the customer is that person) or "i_have_their_permission" (the customer has that person's permission). The photos are copied into the series' own storage and are that character's face (no face is generated or priced); the full body and sheet are made from them and every scene sends them to the video model. Adults only, never a public figure or a celebrity: every call (dry_run too) checks the photos first. Without consent, or for photos that do not pass, the call returns cast_refused true, reason and say (post it as is): nothing is created or charged. locations: 1 to 8 (one place is a whole series), each a description or {name, description, setting interior|exterior, time day|dusk|night}; a place has one time of day in every take, the one its description names. Limits (characters): lead_a_look, lead_b_look and each look 300; outfit 200; body_type 80; palette 30; signature_prop and voice_note 80; function 40 (a few words, like "her best friend"); name 40; relationship kind 120; location description 300, location name 40. Keep every value short; the server cuts anything longer to fit (more than 8 locations keep the first 8) and lists each change in adjusted: show the customer the cast and locations as returned. Short lowercase id; micro_drama|sitcom; language: the dialogue language as an ISO 639-1 code (en, es, fr, de, it, pt, pt-BR, nl, pl, tr, ar, hi, id, zh, ko, ja, ru, and most others; series_interview's supported_languages has the full list); a language shows do not film is refused before anything is priced or made, with a question for the customer offering filmed languages; every line is written, voiced, checked and captioned in this language; quality 480p (12 credits/s) or 720p (24 credits/s) on the standard engine (wan-3.0-prime), or premium (seedance-2.5 at 480p, 60 credits/s: one call per scene with every line, native voices and lip sync; slower, about 10 min a scene; offered in series_interview round 1 as Picture, never for the $1 pilot or the $49 series) for every episode of the series. dry_run=true returns the exact casting credits (0 on a drama plan) and list credits and creates nothing. Casting runs in the background: poll get_series_overview until casting.status is ready and show the images for approval. style: photoreal (default, live-action) or anime (Japanese anime film look: cel shading, painterly backgrounds, one fixed character design per person); it applies to every casting image and every episode and cannot change later. Pass anime only when the customer asked for anime, manga or animation; otherwise photoreal. Calling again with identical values resumes casting and never pays twice. FIRST RUN: pass the Ep1 script (episode JSON) as episode_1 with dry_run true to get its craft_check and first_run price (casting plus Ep1 video, voices and storyboards) free; after the customer's one yes, call with dry_run false and the same episode_1: it is saved as Ep1, ready for make_episode. subtitle_language: leave empty for captions in the dialogue language; set it (he, ar, en, es...) when the customer wants the burned captions in another language than the dialogue (English dialogue with Hebrew subtitles): every spoken line then needs a "subtitle" field, the line translated into that language, and the captions show it timed to the spoken line. Change it later with set_subtitle_language.

Free, generates nothing. Replace episode n of the season plan (same fields as one save_season_plan episode). expected_revision must be the current revision. Every later episode is then marked needs_rewrite (rewrite each with this tool), scripts already saved for episode n onward must be saved again before filming, and the approval is dropped. Refused when episode n or a later one is already queued, filming or delivered.

Generate audio. TTS (default elevenlabs-tts): speak text in a named voice (jessica, sarah, liam, chris, roger, lily, bill, matilda, or a raw ElevenLabs voice id), 16 credits per 1,000 characters, rounded up. Emotion tags are honoured. TTS cloned voices cannot speak Hebrew: a stock voice of the same gender speaks that line. Gemini TTS (model: gemini-tts, Gemini 3.8 Flash TTS): the natural voice for Hebrew and any language; voice sulafat (female, default) or achird (male), optional language (ISO code, e.g. he) and direction (how to read it, e.g. "warm, natural, conversational, like telling a friend"; never read aloud; no emotion tags or tone), 5 credits per 1,000 characters, rounded up; returns an MP3 you can pass as audio_refs to generate_video. Cartesia TTS (model: cartesia-tts, Cartesia Sonic 3.6): native Hebrew voices for narration, 44 languages; voice ayala (female narrator, default), yael, shira, hila (female), gil, noam, yonatan (male), or a Cartesia voice id; Hebrew text speaks Hebrew (optional language, ISO code); optional speed (0.6 to 1.5) and emotion (calm, sad, excited, ...; best in English); no tone or direction, 13 credits per 1,000 characters, rounded up; returns an MP3 you can pass as audio_refs. Voice conversion (model: elevenlabs-sts): pass audio_url (public HTTPS audio, max 15 seconds) and voice to re-voice an existing performance into the locked voice. Optional stability, similarity_boost, style (0..1), seed (uint32), remove_background_noise (boolean). No text or tone for STS. STS costs 1 credits per measured input second, total rounded up; call quote first. Models: elevenlabs-tts, elevenlabs-sts, gemini-tts, cartesia-tts. Returns a job id; poll get_run_status for the audio URL (TTS MP3, STS WAV with source duration).

RETRY SAFETY: set request_id to a fresh UUID for a new generation. Reuse the exact same request_id and inputs only to recover a lost response; that returns the original job without another charge. A deliberately new generation needs a new request_id. Keep the returned job_id and poll get_run_status. Never invent a refund.

Render one image from YOUR prompt. Without refs it paints from the prompt; with refs (https URLs) it edits/composes from them, a portrait to re-light, a product to place in a hand, a character sheet to pose. Use it to build the reference a video needs (portrait first, then generate_video with that URL in refs). Models: gpt-image-2.6, gpt-image-2.6-flare, gpt-image-2.5, gpt-image-2.5-flare, gpt-image-2, nano-banana-pro, nano-banana-2.1 (default gpt-image-2.5). Spends credits per image (see list_models). Returns a job id, poll get_run_status for the image URL.

When the user wants to provide a product photo, portrait, screenshot, or image reference, check tools/list. If open_upload_panel is available, offer it first: call open_upload_panel with {}, show its inline panel or returned browser link, and wait for the user to finish. Then call get_uploads with the returned session_id and use the exact ready image_url in refs, first_frame, last_frame, or the matching skill image field. Do not start a reference-dependent generation until the required images are ready. The panel accepts still PNG, JPEG, and WebP, up to 10 images and 25 MB each. Images expire 24 hours after the panel is created; show the returned expiry, request a new upload if expired, and never make a permanent copy. Uploading uses no generation credits. Do not ask the user for base64, shell commands, or a public hosting service; do not continuously poll while waiting for them. Only call these tool names when discovered. If they are missing from the connected tool catalog, call upload_image with {} to open the same panel; use the returned panel: upload_key with upload_image to retrieve images after the user finishes. If that reports the panel is unavailable, use upload_image only for an already accessible file or URL. Do not build an upload page or request a local folder as a substitute for the existing panel. Never invent access to a chat attachment: if you cannot read it, explain that and offer the panel when available. Browser fallback works without inline UI support; do not promise an inline panel in every client. Inspect the native image previews returned with retrieved uploads before describing them or writing image-specific prompts. Never infer what the image shows from an email domain, account metadata, or filename. Use the original URLs for generation, not preview bytes. If the session ID was lost, call get_uploads with {} to list recent sessions, or upload_image with {"upload_key":"panel:recent"} for cached catalogs; retrieve the matching session before asking for re-upload. Account-wide recent uploads may belong to other conversations, so clarify ambiguous selection. Uploading stores an image; it does not attach it to a generation automatically. If the user already requested a generation with these images, continue that request using the returned URLs; do not stop at "upload complete" or ask again whether to use them. If make_ugc fits the requested outcome, pass a person photo as image or a product photo as product_image, then call quote_ugc before spending. Otherwise compose the direct generators: for generate_image, put the relevant image_url values in refs; for generate_video, use refs for product/person/appearance references, or first_frame for animating a still (last_frame only for an explicitly requested ending frame), and never combine refs with frame fields. Preserve the user's intended image roles and model limits; ask only if the role or selection is unclear. Include the URL in the tool arguments, not only in the prompt. Do not substitute a newly generated image for the uploaded reference. If the request was upload-only, report readiness and wait for a generation request; uploading alone does not authorize spending credits. After submitting, poll get_run_status and return the result.

IMAGES: pass an https URL. If you only have raw bytes or a data: URL, call upload_image FIRST and pass the URL it returns. Never paste base64 into these arguments, the client prints tool arguments in the conversation, so a base64 image becomes a wall of text for the user and is re-sent on every retry.

RETRY SAFETY: set request_id to a fresh UUID for a new generation. Reuse the exact same request_id and inputs only to recover a lost response; that returns the original job without another charge. A deliberately new generation needs a new request_id. Keep the returned job_id and poll get_run_status. Never invent a refund.

Render a video clip from YOUR prompt on the model YOU choose, in one of three MODES that follow from the fields you pass: TEXT (prompt only), IMAGE-TO-VIDEO (first_frame: an https still that becomes frame one, optionally last_frame to end on; the clip animates the still) or REFERENCE (refs: https images such as a portrait, a character sheet from list_characters or a product photo whose identity/look is kept; video_refs: clips whose motion or framing is followed; audio_refs: a voice or sound to carry; address them in the prompt as @image1, @video1, @audio1). Frames and refs cannot be mixed. Write the shot like a director: who is in frame, where, what happens, camera, and the exact spoken words in quotes if anyone talks. HEBREW: the video models cannot speak Hebrew, so Hebrew words in quotes are never left to them: Gemini speaks the line and OmniHuman 1.5 lip-syncs a front-facing still to it (your first_frame, or a keyframe made from the prompt and refs). 9:16 or 1:1, up to 35 s, no video_refs or audio_refs; priced as the voice + the keyframe + 26 credits per lip-sync second instead of the model's rate (call quote); voiceover sets the voice (sulafat, achird) or the gender. Models: seedance-2.0, seedance-2.5, wan-3.0-prime (default seedance-2.5; call list_models for each model's modes, limits, prices and recent results; or pass model:"auto"). Aspect: 9:16 default, also 16:9, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, adaptive where the selected model supports it. Quality: 480p, 720p, 1080p, or 4k where the selected model supports it; omit for the selected model's default. The price per second follows the model and quality (seedance-2.5: 60 credits/s at 480p, 125 credits/s at 720p, 225 credits/s at 1080p; call list_models for the full table). Reference clip seconds are billed like output seconds. Call quote first if the user cares about cost. Returns a job id, then call get_run_status until it is done and hand the user the URL.

When the user wants to provide a product photo, portrait, screenshot, or image reference, check tools/list. If open_upload_panel is available, offer it first: call open_upload_panel with {}, show its inline panel or returned browser link, and wait for the user to finish. Then call get_uploads with the returned session_id and use the exact ready image_url in refs, first_frame, last_frame, or the matching skill image field. Do not start a reference-dependent generation until the required images are ready. The panel accepts still PNG, JPEG, and WebP, up to 10 images and 25 MB each. Images expire 24 hours after the panel is created; show the returned expiry, request a new upload if expired, and never make a permanent copy. Uploading uses no generation credits. Do not ask the user for base64, shell commands, or a public hosting service; do not continuously poll while waiting for them. Only call these tool names when discovered. If they are missing from the connected tool catalog, call upload_image with {} to open the same panel; use the returned panel: upload_key with upload_image to retrieve images after the user finishes. If that reports the panel is unavailable, use upload_image only for an already accessible file or URL. Do not build an upload page or request a local folder as a substitute for the existing panel. Never invent access to a chat attachment: if you cannot read it, explain that and offer the panel when available. Browser fallback works without inline UI support; do not promise an inline panel in every client. Inspect the native image previews returned with retrieved uploads before describing them or writing image-specific prompts. Never infer what the image shows from an email domain, account metadata, or filename. Use the original URLs for generation, not preview bytes. If the session ID was lost, call get_uploads with {} to list recent sessions, or upload_image with {"upload_key":"panel:recent"} for cached catalogs; retrieve the matching session before asking for re-upload. Account-wide recent uploads may belong to other conversations, so clarify ambiguous selection. Uploading stores an image; it does not attach it to a generation automatically. If the user already requested a generation with these images, continue that request using the returned URLs; do not stop at "upload complete" or ask again whether to use them. If make_ugc fits the requested outcome, pass a person photo as image or a product photo as product_image, then call quote_ugc before spending. Otherwise compose the direct generators: for generate_image, put the relevant image_url values in refs; for generate_video, use refs for product/person/appearance references, or first_frame for animating a still (last_frame only for an explicitly requested ending frame), and never combine refs with frame fields. Preserve the user's intended image roles and model limits; ask only if the role or selection is unclear. Include the URL in the tool arguments, not only in the prompt. Do not substitute a newly generated image for the uploaded reference. If the request was upload-only, report readiness and wait for a generation request; uploading alone does not authorize spending credits. After submitting, poll get_run_status and return the result.

IMAGES: pass an https URL. If you only have raw bytes or a data: URL, call upload_image FIRST and pass the URL it returns. Never paste base64 into these arguments, the client prints tool arguments in the conversation, so a base64 image becomes a wall of text for the user and is re-sent on every retry.

RETRY SAFETY: set request_id to a fresh UUID for a new generation. Reuse the exact same request_id and inputs only to recover a lost response; that returns the original job without another charge. A deliberately new generation needs a new request_id. Keep the returned job_id and poll get_run_status. Never invent a refund.

Check this authenticated connection, available generation credits, and whether generation/upload services are configured. Free and read-only: does not create an upload session, generate media, refill credits or change billing. Call before the first generation; then use quote_ugc for make_ugc or quote for a direct generator and compare the cost with the balance. A positive balance is not a guarantee of sufficient funds for a specific request or provider availability.

Job progress, phase completion, per-scene line checks, quote, plan balance and public MP4 URL when delivered. progress.say is one line to post as is: episode X of Y, step k of 6 (voices, storyboard, shot list, filming, edit, publishing) and time left. wait_seconds (0 to 40) waits for the next step before answering; use 40 while filming. When delivered, finish has the video, series page, Library link and the one-line ask for the next episode: post finish.say; cover_url is the episode's cover (the series cover when it has none), the thumbnail to post the episode with (YouTube, TikTok). status awaiting_checkpoint: the episode waits for the user's yes; show has what to show (images or video), say, next and revision: show it, post say, STOP, and after the yes call approve_checkpoint.

Full saved script: scenes, locations, shots, lines and speakers.

Episode outfits, every scene's stored storyboard image, location, full shots and animatic. Returns durable R2 media URLs when available.

Read-only, starts and charges nothing. Where is my episode: the latest started episodes in your account, across every series, newest first (limit 1 to 20). Each row: series_id, series_title, n, title, status, say (one line to post as is: the progress line while it films, the finish line once delivered), eta and eta_seconds while it films, library (the series in the customer's agent-media Library) and, once delivered, watch (the video), page (the episode on the public series page, null for a private series), cover_url (the series cover, the thumbnail to post the episode with) and next_prompt. Drafts not started are not listed. series lists every series by id and title with its own latest_episode (n and status, null before any started), past the limit too. plan: the account's balance and its $1 Episode 1 (pilot) or micro drama (series_pass) block, which says which offer the account is on; the price of an episode is on its saved script. To follow one episode while it films, use get_episode.

Read-only. Your real credit balance from agent-media as seconds left at 480p, 720p and premium; with series_id also 30 s episodes left at that series' quality. plan is null with a reason if the balance check fails; never guess.

Check a generation you already submitted, and get its output URL (video, image or audio) when it is done. Pass the id ANY agent-media tool returned (run id, skill run id, or job id), this resolves all of them. Set wait:true to block until the job reaches a terminal state (up to ~45 seconds per call; if it is still running, just call again: a video often takes several minutes, and list_models recent has each model's median render time, so keep calling until it is done). ALWAYS call this after submitting: without it you cannot tell whether the video succeeded, and cannot give the user a link.

Free, read-only, generates nothing. The show types and season sizes, for when the season size is asked: after Episode 1 is delivered, or when the customer chose the whole season now. A new series starts with series_interview, not here. Returns the four show types (drama_romance, comedy_sitcom, thriller_horror, fantasy_scifi) with their format, writing guidance (tone, hook, twist, cliffhanger, avoid) and starters, and every season size (episodes 1, 3, 5 or 10 x 30 or 60 s x 480p, 720p or premium, the seedance-2.5 engine) with its price and, for this account, available or locked with unlock {plan, name, url} (the monthly Pro, Max and Studio plans, Pro first). When the size is asked it has no default: post say and let the customer pick one. series_id: the planned series id (a micro drama already bound to a show).

Free, read-only. The stored season plan: revision, content_hash, approved_current, the plan with its grid, needs_rewrite and script_stale episode lists, size_status, warnings, say and next.

Free, generates nothing. Every season script with its craft_check, price and stale flag, casting_credits, total_credits (casting plus every episode's video, voices and storyboards: the one season price), scripts_hash, approval (state active, pending_funding or pending, and the held authority), create_series (the exact arguments the paid create_series must use) and say: show say (every script and the price) and ask once; on the customer's yes call approve_season_scripts with scripts_hash and max_credits total_credits.

Premise, beat map, leads/voices/portraits (and on cast v2 every character with full body and sheet), locations, all episodes and cover_url (the series cover; cover_custom true when set_series_cover set it).

Full series canon: the cast (faces, full bodies, turnaround sheets, voices, outfits, who is whose friend), the locations, casting progress, and every episode's outfits, storyboard images, shots and filmed line checks. Retained in R2; read before writing the next episode.

Actual billed credits from the ledger, by phase and episode, including voices, boards and replacements.

Read-only. Everything about your series in one call, for the SERIES BOARD: logline, premise, cover_url (the series cover), format, language, quality, visibility, cast (every character: role, look, outfit, relations, face, full body and turnaround sheet), the locations (inside or outside) with plates, casting progress (casting.status, images_done of images_total), the plan (beat map) if one exists, and every episode in order with status (draft, awaiting_approval, queued, running, delivered, failed, needs_revision), the full saved script (scenes, locations, shots, lines, speakers), seconds, quote, video URL when delivered, storyboard URL, whether the script is still editable, and next_episode_n. Without series_id, all your series.

Read first: writing/staging rules, episode JSON, pricing and approval flow.

Retrieve uploaded images as native image previews plus original generation URLs and expiry times. Inspect the previews before describing the image or writing a prompt. Omit session_id to find recent unexpired sessions on this account if the session ID was lost; choose the session matching the user request, never silently mix unrelated uploads. Call after the user finishes uploading, not in a tight polling loop. Sessions and images expire 24 hours after the session opens; request a fresh upload if expired. Reuse these URLs for generation without downloading, re-encoding, or making a permanent copy.

List the authenticated user's saved, reusable characters. Each has a character_id (char_…) and a character_sheet_url. Pass either one as make_ugc's character, or pass the sheet/portrait URL in refs of the advanced generate_video / generate_image tools. Plus a portrait/thumbnail URL for display.

Episode numbers, titles, production status and delivered public watch links.

List the generation models agent-media can use: for each, its MODES (video: text, image-to-video via first_frame, reference via refs / video_refs / audio_refs) with the exact inputs, limits, aspects, qualities and credits per second of every mode, a "pick when" line, prompting tips, expected latency, how to select it, plus recent: the last 30 days of real runs per model (fail rate, auto-judge score, user ratings, median render time). Read this BEFORE choosing a model or a mode for generate_video / generate_image / generate_audio: the default seedance-2.5 is right for most jobs. Pass the id as model, or model:"auto" and the printed policy picks from the stats. Costs NO credits. Includes the same authenticated balance check as get_account; compare it with quote before generation. Set include_candidates:true to also see planned models that cannot be selected yet.

Every series in your account, leads, locations, delivered episode count and cover_url (the series cover).

Free, read-only, generates nothing. Fourteen proven one-line starters in four show types: drama_romance (revenge, billionaire romance, werewolf/paranormal, mafia, secret identity, second chance, thriller, family betrayal), comedy_sitcom (workplace comedy, roommates sitcom), thriller_horror (haunted house horror, snowed-in survival), fantasy_scifi (palace dragon fantasy, starship sci-fi); show_type keeps only that type's starters. Each full starter also carries season_plan (show_type, season_plot, episodes; episodes 1, 3, 5 or 10 sizes it) ready for save_season_plan and its type's writing guidance. Pass the customer's words as genre (e.g. "make me a werewolf drama") to get the full starter: premise, tone, two leads, three sets, hook pattern, cliffhanger style, Ep1 first line, ready create_series and save_series_bible arguments and a checked 10-episode grid; follow its how_to_use (the starters are the story options in series_interview round 1; one yes before any spend). Without genre, or with no match, returns every starter's one-liner to offer as options.

After script/quote approval, enqueue voices, storyboard for this episode, book, filming, ASR check, one paid retake for each scene that fails it (within the quoted replacement budget), edit and delivery. Returns immediately with progress.say (post it); then call get_episode with wait_seconds 40 until delivered. A repeated call resumes the same job, but while a checkpoint waits a repeated call can be the user's yes: after a reconnect or a lost answer, call get_episode first (it shows any waiting stop again). Refuses (started false, craft_check) while the saved script has craft_check issues; fix the script with save_episode_script instead of passing override_craft_check. Script rules (the server enforces these four, and for a micro_drama rule 5, the beat; episodes that jump between places and people read as unrelated cuts): places only move forward: at most 3 places in an episode, never back to a place already left; a lead (a or b) is on screen in every scene; at most 4 people on screen in an episode; nobody new after 60% of the runtime, except one newcomer in the last scene of an intrusion cliffhanger. Writing guidance, not enforced: the first spoken line is the hook; the episode ends on a lead's line. Write calm, natural acting: no face-acting notes per line; the server directs camera and performance. make_episode's override_craft_check never lifts the four rules or rule 5. Script rule 5 (rules_version 2): a micro_drama episode needs one beat (shot "beat") on the turn shot or a shot next to it; a script saved before this rule still films as saved. Warns when save_story_state was not saved through the previous episode. A series cast from a season plan films a new episode only from the approved current plan: otherwise started false with reason season_plan_* and say (post it as is). After an Episode 1 first start, make_episode after the customer's yes to a saved episode's script and price is that yes: it holds that one episode's price (never beside a held season price, never for an episode the season yes covers) and films it; no season approval is needed. It refuses with say (post it as is) while the episode before it is still being made (episode_hold_busy), out of order (episode_order), when the price rose above the one shown at save (episode_price_changed: show it again) or the account lacks the credits (insufficient_credits). A series in a language shows do not film never starts: started false, reason language_not_supported and say (post it as is). Checkpoints: before filming it returns started false, reason checkpoint_pending and show (the cast pictures, then the episode cover): show them, post say, and after the user's yes call approve_checkpoint, then make_episode again. If approve_checkpoint is not in your tool list, call make_episode(series_id, n) again after the user's yes: it counts as the yes. Never call it without the user's answer. The job then waits twice more (get_episode status awaiting_checkpoint: the storyboard, then scene 1 filmed). A season approved all at once stops only for the cast pictures; a checkpoint with no answer for 1 hour passes by itself. cover_url is the episode's cover.

Paid (1 image). Make a vertical 2:3 cover for your series from its cast: lead a and lead b close together in a romantic or tense pose that stays non-explicit, in the series' main location, with the title and logline as text. dry_run true (the default) returns its price in credits and makes nothing: show say and the price. After the customer's yes, call with dry_run false (same note): it makes one image and returns image_url, credits and say; calling again with the same values never pays twice, and a note (a short direction, 200 characters at most) makes a new take. The image is not the cover yet: show it, and after the customer's yes call with approve true (charges nothing) to set it as the cover, or use set_series_cover with image_url. Not made returns cover_made false with reason (cast_not_ready, price_unavailable, still_making: call again with the same values, image_refused, not_enough_credits, make_failed) and say (post it as is).

Optional convenience workflow for one finished vertical UGC video from a script. Use it when the user wants the server to choose takes and timing, join a long monologue, and optionally burn captions. Use the direct generate_image, generate_video and generate_audio tools instead when the agent needs custom models, modes, shot structure, intermediate assets, or a different composition. Use image for a person photo, product_image for a product photo, or character for a saved character. Use scene for where it happens (a beach, a gym, in bed, a car); without a place the video is set in an ordinary room. Call quote_ugc with the exact same input first; it costs no credits. Ask before setting captions:true. After submission, keep calling get_run_status until it returns the finished video URL. Files it lists under So far are intermediate, not the result.

When the user wants to provide a product photo, portrait, screenshot, or image reference, check tools/list. If open_upload_panel is available, offer it first: call open_upload_panel with {}, show its inline panel or returned browser link, and wait for the user to finish. Then call get_uploads with the returned session_id and use the exact ready image_url in refs, first_frame, last_frame, or the matching skill image field. Do not start a reference-dependent generation until the required images are ready. The panel accepts still PNG, JPEG, and WebP, up to 10 images and 25 MB each. Images expire 24 hours after the panel is created; show the returned expiry, request a new upload if expired, and never make a permanent copy. Uploading uses no generation credits. Do not ask the user for base64, shell commands, or a public hosting service; do not continuously poll while waiting for them. Only call these tool names when discovered. If they are missing from the connected tool catalog, call upload_image with {} to open the same panel; use the returned panel: upload_key with upload_image to retrieve images after the user finishes. If that reports the panel is unavailable, use upload_image only for an already accessible file or URL. Do not build an upload page or request a local folder as a substitute for the existing panel. Never invent access to a chat attachment: if you cannot read it, explain that and offer the panel when available. Browser fallback works without inline UI support; do not promise an inline panel in every client. Inspect the native image previews returned with retrieved uploads before describing them or writing image-specific prompts. Never infer what the image shows from an email domain, account metadata, or filename. Use the original URLs for generation, not preview bytes. If the session ID was lost, call get_uploads with {} to list recent sessions, or upload_image with {"upload_key":"panel:recent"} for cached catalogs; retrieve the matching session before asking for re-upload. Account-wide recent uploads may belong to other conversations, so clarify ambiguous selection. Uploading stores an image; it does not attach it to a generation automatically. If the user already requested a generation with these images, continue that request using the returned URLs; do not stop at "upload complete" or ask again whether to use them. If make_ugc fits the requested outcome, pass a person photo as image or a product photo as product_image, then call quote_ugc before spending. Otherwise compose the direct generators: for generate_image, put the relevant image_url values in refs; for generate_video, use refs for product/person/appearance references, or first_frame for animating a still (last_frame only for an explicitly requested ending frame), and never combine refs with frame fields. Preserve the user's intended image roles and model limits; ask only if the role or selection is unclear. Include the URL in the tool arguments, not only in the prompt. Do not substitute a newly generated image for the uploaded reference. If the request was upload-only, report readiness and wait for a generation request; uploading alone does not authorize spending credits. After submitting, poll get_run_status and return the result.

IMAGES: pass an https URL. If you only have raw bytes or a data: URL, call upload_image FIRST and pass the URL it returns. Never paste base64 into these arguments, the client prints tool arguments in the conversation, so a base64 image becomes a wall of text for the user and is re-sent on every retry.

Open a drag-and-drop image upload panel for the user. Use when the user wants to supply photos, portraits, products, or image references, especially in Claude or ChatGPT. PNG/JPEG/WebP, up to 25 MB each and 10 images, available for up to 24 hours. No generation credits. Returns a browser link for clients without inline panels. Never ask the user to paste base64. After the user uploads, call get_uploads with the returned session_id; use the exact image_url in refs, first_frame, or a skill image field. Do not generate before images are ready.

Price a generate_image / generate_video / generate_audio call WITHOUT running it. Pass the same input you would pass to the tool. Returns credits (1 credit = $0.01), the model that would run, and the breakdown. Costs nothing. Use it before spending when the user asked about cost, when choosing between models, or before a clip longer than a few seconds.

Price an optional make_ugc workflow and check the spendable balance without rendering or using credits. Pass the exact input intended for make_ugc. Show the returned price to the user and only call make_ugc after the user has authorized that spend.

Rate a finished generate_video / generate_image / generate_audio run 1 to 5, with an optional note (what was wrong or right). Costs nothing. Do this when the user reacts to an output, "perfect", "her face changed", "too slow", or when you can see a defect yourself. Ratings feed the per-model stats in list_models and the model:"auto" choice, so an honest 2 helps more than a polite 4.

Paid (casting images). Recast character id (a to h) before their first episode: a new look remakes face, full body and sheet (3 images); a new outfit or body_type remakes body and sheet (2). At most 2 per character; redoing a refused image does not count. Runs in the background; dry_run prices it.

Paid portrait replacement for lead a|b, allowed only before filming begins. Show new portrait for approval. On a cast v2 series this is recast with a new look.

Free, generates nothing. Before casting only: the customer leaves this season (another show type, size or idea), so the price held by approve_season_scripts is given back and the yes is dropped. A cast series keeps its held price for its approved episodes.

Validate and save an episode before production. Returns the video quote plus replacement budget, price (video, voices and storyboards, and guests when the episode has any: show price.total_credits), craft_check {passed, issues, warnings}, ready_to_film and (cast v2) cast_by_scene and episode_cast. Episode fields: cliffhanger_type (partial_reveal|reversal_setup|intrusion|ticking_clock|betrayal_reveal) and one turn (text) on the shot where the reversal lands, 10 to 20 s of a 30 s episode. Script rules (the server enforces these four, and for a micro_drama rule 5, the beat; episodes that jump between places and people read as unrelated cuts): places only move forward: at most 3 places in an episode, never back to a place already left; a lead (a or b) is on screen in every scene; at most 4 people on screen in an episode; nobody new after 60% of the runtime, except one newcomer in the last scene of an intrusion cliffhanger. Writing guidance, not enforced: the first spoken line is the hook; the episode ends on a lead's line. Write calm, natural acting: no face-acting notes per line; the server directs camera and performance. make_episode's override_craft_check never lifts the four rules or rule 5. Cast v2: every scene "cast" lists everyone featured in it (4 at most), the recurring characters too, not only the two leads: use the recurring cast across the season so it feels like a real series. Each character's full body and (once made) turnaround sheet go to the video model as references. Optional "guests": up to 2 one-episode characters [{id x1|x2 (or left out), name, gender, age, look, outfit, body_type, palette (a colour no one else wears), signature_prop?, voice_note?, function?}], adults only, names and palettes not used by the cast; each is cast for this episode only (face, full body and turnaround sheet, made when the episode is made) and priced in this quote (price.guests_credits, guest_images, guests_included); scenes list them by id in cast. Guest images are made only when the plan includes them (0 credits, as a drama plan includes casting), never charged: on a plan that does not, price.guests_note says so and the guests are described in words. A guest that cannot be made is described in words and the episode still films. Optional scene "background": a short line of unnamed extras in words (120 characters at most, e.g. "two nurses walking past, a crowd at the bar"), never named, never speaking, never in focus and never a reference image. The server fixes timing itself (a silent beat where the story is short, a scene up to 0.1 s over timed to its 10 s, a filler word cut from a line that runs long, a long pause tightened) and lists every change in fixed: show fixed with the script; the price is the fixed script's. The server keeps the camera still (camera "static" by default): one slow push_in on the turn, tracking only on a walk, never a wide first shot; each change is listed in fixed. Optional shot "beat" (touch, grab, embrace, slap, shove, throw, tears, kneel, almost_kiss, kiss): one physical moment, filmed in the server's own words. Script rule 5 (rules_version 2): a micro_drama episode needs one beat on the turn shot or a shot next to it, or the save is refused; a script saved before this rule still films as saved. Fix the craft_check issues left before showing the script; show script, check and price for approval before make_episode. Maximum 60 seconds.

Free, generates nothing. Save the season plan BEFORE the paid create_series: series_id (the id you will pass to create_series), show_type, size {episodes, seconds, quality}: in series_interview the size from brief.size (Episode 1 first plans at its provisional size, asked again after Episode 1), otherwise exactly as the customer chose it from get_season_options (no default; a locked size can be planned and is filmed once its plan is bought), season_plot (the whole season, start to finale, at least 15 words) and episodes: one per episode in order, [{ep, title, summary, twist, cliffhanger, cliffhanger_type partial_reveal|reversal_setup|intrusion|ticking_clock|betrayal_reveal, final_line, tension 1-10, payoff none|small|major, cast? (character ids: give the recurring characters a part in most episodes, not only the leads), locations?, gag?, drama_beat? (touch|grab|embrace|slap|shove|throw|tears|kneel|almost_kiss|kiss: the physical moment on this episode's turn; a drama_romance plan warns for an episode without one), guests? (up to 2 short descriptions of this episode's one-episode guests, like "the night nurse", cast with its script)}]; the last is the finale and needs resolution and payoff major. You write the plot from the type guidance (or a starter's season_plan); this tool checks it is complete. Returns revision, content_hash, say (the plan as the customer reads it), size_status, warnings and next. Replacing a saved plan needs expected_revision (the current revision); queued, filming and delivered episodes keep their rows; later rows not rewritten in the same call are marked needs_rewrite. Saving drops any approval.

Free, generates nothing. After the season plan is approved and before the paid create_series. Episode 1 first (the interview's default, and Just go): save only Episode 1's script before casting. After Episode 1 is delivered the customer chooses: the next episode alone (save_episode_script, its price, and on the yes make_episode, which holds that episode's own price), or the rest of the season here on one yes. The whole season now: write every episode's script from its plan row, in order, one call each. The same episode JSON as save_episode_script. Script rules (the server enforces these four, and for a micro_drama rule 5, the beat; episodes that jump between places and people read as unrelated cuts): places only move forward: at most 3 places in an episode, never back to a place already left; a lead (a or b) is on screen in every scene; at most 4 people on screen in an episode; nobody new after 60% of the runtime, except one newcomer in the last scene of an intrusion cliffhanger. Writing guidance, not enforced: the first spoken line is the hook; the episode ends on a lead's line. Write calm, natural acting: no face-acting notes per line; the server directs camera and performance. make_episode's override_craft_check never lifts the four rules or rule 5. Script rule 5 (rules_version 2): a micro_drama episode needs one beat (shot "beat") on the turn shot or a shot next to it, or the save is refused. The first call needs series: the create_series arguments the season is cast with (title, language, premise, lead_a_* and lead_b_* fields, locations, cast; format and quality are the plan's); passing it again changes them and checks every script again. Each script is validated, auto-fitted and craft-checked like check_episode_script (the cliffhanger type against the two episodes before it, the season's episode length) and priced: video, voices and storyboards for this account. A plan change makes that episode's script and every later one stale until saved again. A change after the customer's yes keeps that yes and its held price while the season price stays within the approved max_credits (nothing is asked again); only a price above it gives the held price back (before casting) or waits for one new yes. Returns every script with craft_check, price and stale, casting_credits, total_credits (the season price), scripts_hash, say and next.

Save the season logline and beat map, one line per episode (usually Ep1–Ep10), plus the optional story bible and season grid. Omitted optional fields keep their saved value. leads: {a,b}: {want, wound, secret_id (a secrets id or null), hidden_asset, optional role, voice, arc, relationship_tension, visual_lock}. secrets: [{id, holder a|b, truth, planted_ep, half_reveal_ep, full_reveal_ep}]. grid: [{ep, goal, turn, cliffhanger_type partial_reveal|reversal_setup|intrusion|ticking_clock|betrayal_reveal, final_line, tension 1-10, payoff none|small|major}]. free_episodes: free episodes before login (default 3); the last free episode is the free-to-paid point. characters: {recurring id: {function, want, relation, arc?, voice?, comic_trait?}}; secrets holder and grid rows may use any character id, and grid rows take optional cast (ids), locations (indexes) and gag (sitcom). Returns season_check.warnings; fix the grid until it is clean.

Story memory after each delivered episode (free, append-only; the latest is returned by get_series_canon and get_series_overview). facts: [{text, ep}]; knowledge: {a: [], b: [], viewer: []} (who knows what; any character id); open_loops: [{text, opened_ep, must_close_by}]; used_beats: [text]; power_holder: who holds power now; last_cliffhanger_types: types used so far, newest last.

Free, generates nothing. Every new series starts here. Returns one round of up to 4 multiple-choice questions (header; 2 to 4 options with label, description and live prices; the recommended option first; an Other) and say, the same round as text: post say as is, then wait for the reply. Start without series_draft_id (pass the customer's one line as idea; a matching starter becomes the recommended story). Then pass the reply as answers ("1b 2a 3 Other: ..." or {"1": "b"}) with series_draft_id; skipped questions take the stated default. After round 3, write the bible and Ep1, price them with create_series dry_run true and episode_1, then call with series_id for round 4: the bible summary, the exact price and one yes. create_series refuses the paid call for an interviewed series without that yes. Shows are filmed in most languages (supported_languages in rounds 1 to 3 and the write step's next list their codes; the dialogue language is the one the idea is written in or asks for): when the idea is in or asks for a language shows do not film, round 1 opens with a question offering filmed languages; post it as is and let the customer pick one for the dialogue, never naming another language. subtitle_language: when the customer wants the burned captions in another language than the dialogue (English dialogue with Hebrew subtitles), its code (he, ar, en, es...; any filmed language, Hebrew and Yiddish too); kept for the write step, which passes it to create_series and gives every line a "subtitle".

Change wardrobe for episode n and all later saved episodes. Faces stay locked. Call before make_episode; the whole update is rejected if any affected episode is already queued. Empty inputs leave that character unchanged. outfits maps any character id (a to h) to wardrobe text.

Paid replacement of a location plate (index 0 to 2 on older series, 0 to 7 on cast v2 with optional name, setting interior|exterior, time day|dusk|night; at most 2 replacements per location). Existing jobs retain their locked location references.

Costs no credits, generates nothing. Set the cover (poster) of your series: the picture the public series page, the Library and Studio show (cover_url in get_series, list_series and get_series_overview). image: the https URL of a picture in this account, a generate_image output, an upload_image URL or an upload panel image (open_upload_panel, get_uploads) (PNG, JPEG or WebP, at least 200 pixels a side, up to 15 MB; vertical 2:3 fits best). The picture is copied into the series' own storage. Leave image out (or pass null) to go back to the default cover, the lead's portrait: that returns cleared true, cover_set false and the default cover_url. Returns cover_set, cover_url, warnings and say (post it as is); a refused picture returns cover_set false with reason (image_not_allowed, not_an_image, image_too_small, image_too_large, image_missing, download_failed, storage_failed) and say.

Set discovery visibility for your series. Public is the default; private removes it from discovery. Existing media URLs are not revoked.

Costs no credits, generates nothing. The language of a series' burned captions: language is a code (he, ar, en, es...; any filmed language, Hebrew and Yiddish too) for subtitles under the dialogue (English dialogue with Hebrew subtitles), or empty for captions in the dialogue language. Episodes already filmed keep their captions; every line of a script filmed from now on needs a "subtitle" field in that language (save_episode_script names the lines without one). Returns language (the dialogue's), subtitle_language and say (post it as is).

When the user wants to provide a product photo, portrait, screenshot, or image reference, check tools/list. If open_upload_panel is available, offer it first: call open_upload_panel with {}, show its inline panel or returned browser link, and wait for the user to finish. Then call get_uploads with the returned session_id and use the exact ready image_url in refs, first_frame, last_frame, or the matching skill image field. Do not start a reference-dependent generation until the required images are ready. The panel accepts still PNG, JPEG, and WebP, up to 10 images and 25 MB each. Images expire 24 hours after the panel is created; show the returned expiry, request a new upload if expired, and never make a permanent copy. Uploading uses no generation credits. Do not ask the user for base64, shell commands, or a public hosting service; do not continuously poll while waiting for them. Only call these tool names when discovered. If they are missing from the connected tool catalog, call upload_image with {} to open the same panel; use the returned panel: upload_key with upload_image to retrieve images after the user finishes. If that reports the panel is unavailable, use upload_image only for an already accessible file or URL. Do not build an upload page or request a local folder as a substitute for the existing panel. Never invent access to a chat attachment: if you cannot read it, explain that and offer the panel when available. Browser fallback works without inline UI support; do not promise an inline panel in every client. Inspect the native image previews returned with retrieved uploads before describing them or writing image-specific prompts. Never infer what the image shows from an email domain, account metadata, or filename. Use the original URLs for generation, not preview bytes. If the session ID was lost, call get_uploads with {} to list recent sessions, or upload_image with {"upload_key":"panel:recent"} for cached catalogs; retrieve the matching session before asking for re-upload. Account-wide recent uploads may belong to other conversations, so clarify ambiguous selection. Uploading stores an image; it does not attach it to a generation automatically. If the user already requested a generation with these images, continue that request using the returned URLs; do not stop at "upload complete" or ask again whether to use them. If make_ugc fits the requested outcome, pass a person photo as image or a product photo as product_image, then call quote_ugc before spending. Otherwise compose the direct generators: for generate_image, put the relevant image_url values in refs; for generate_video, use refs for product/person/appearance references, or first_frame for animating a still (last_frame only for an explicitly requested ending frame), and never combine refs with frame fields. Preserve the user's intended image roles and model limits; ask only if the role or selection is unclear. Include the URL in the tool arguments, not only in the prompt. Do not substitute a newly generated image for the uploaded reference. If the request was upload-only, report readiness and wait for a generation request; uploading alone does not authorize spending credits. After submitting, poll get_run_status and return the result.

For an image already accessible to you: Store an image and get back a stable https URL you can pass to any agent-media tool. Costs NO credits. THREE ways in, in this order:

1. FILE ON DISK (when the file is already accessible to your shell): call upload_image with file_bytes set to the exact byte size of the file (wc -c < photo.png) and file_name. You get back a put_url; run the printed curl to stream the file straight to storage, then call upload_image again with the upload_key you were given to get the URL. The bytes never pass through this conversation, so there is NO reason to resize, crop or re-encode the user’s photo first. Do not: a downscaled product photo is what the video model will show. Up to 25 MB.

2. A URL you already have: pass image_url to re-host it.

3. Raw bytes with no shell available: pass image_base64 (PNG or JPEG, 10 MB max after decoding). Only when 1 and 2 are impossible, and even then upload the original, never a shrunken copy. Then pass the returned URL everywhere. Do NOT paste base64 into other tool arguments or into the conversation: the client displays tool arguments to the user, so a base64 image becomes a wall of unreadable text, and every retry re-sends it.