Viewmax

Estimate Viewmax credit cost for image or video generation. Only call when the user explicitly asks about cost or pricing.

estimate_generation_cost

Generate a marketing video ad using the selected product, avatar, voice, format, and script. CRITICAL: the script must be SHORT enough to fit the selected duration - about 2-3 sentences for 8 seconds, 3-4 for 10 seconds. Do NOT write a long monologue. The character must finish speaking before the video ends. This tool builds the full marketing prompt with format-specific templates and role-tagged reference media. One call = ONE continuous clip (Seedance max 15s) - for longer ads make one call per scene with the same avatar and voiceId (see the long-ad workflow). firstFrameUrl pins the opening frame (whenever other references are attached - which is any ad with a product or avatar - it is applied as a locked reference image with a first-frame lock in the prompt, since providers reject a hard first frame combined with references). referenceImageUrls/referenceVideos/referenceAudios attach extra references like the in-app studio composer; video and audio references are Seedance-only and require durationSeconds (use the values returned by the upload widget). Returns a video result card that self-polls.

generate_ad

Generate a custom avatar image from a text prompt, or save an uploaded image as an avatar. Called by the ad builder widget.

generate_ad_avatar

Generate a still image with Viewmax. Model routing: Nano Banana 2 (default) for creative/social graphics; GPT Image 2 for text-heavy images, diagrams, or infographics; Gemini Flash for photorealistic (pass useSearch:true for grounded/factual content); Gemini Pro for highest quality photorealistic. ONLY for explicit still image requests - if the user might want motion, use generate_video instead.

generate_image

Generate a voiceover script using AI. Returns a written script optimized for short-form video (TikTok, Reels, Shorts). Provide a topic, product description, or paste a YouTube URL to analyze and write a script based on the video. Optionally pass a format and/or a channelStylePrompt (from analyze_channel_style) to match a specific channel's voice. For multi-scene story videos use the story formats (animal-story, bodycam, custom-story) — they apply the viral story formula where each paragraph maps to one video scene. The script can then be used with generate_voiceover to create audio.

generate_script

Start a Viewmax video generation and return generation ids for polling. Model routing: Seedance 2 for face/identity/lip-sync; Kling 3.0 for premium quality or audio; Kling 3.0 Turbo (default) for fast text-to-video; Veo 3.1 for cinematic/photorealistic; Sora 2 for creative/artistic. For ads/product videos use generate_ad instead. IMPORTANT: pass orientation="portrait" when the user asks for 9:16, and orientation="landscape" when they ask for 16:9. Only Seedance accepts ratio strings or "auto". For story videos, follow the story workflow (get_story_workflow phase "start") — it locks camera medium, continuity, and durations before any generate_video call, and every prompt must pass check_prompt_budget first. LEGACY: scenes planned by plan_story_scenes pass storyPlanId + sceneIndex instead of a prompt (the server injects the exact planned prompt; those scenes default to Sora 2) — only to finish conversations that already hold a planId.

generate_video

Start 2-8 distinct video clips in one reliable server-side batch and return every accepted generation id in scene order. Use this instead of making multiple parallel generate_video calls for explainers, stories, montages, or any composition with multiple scene prompts. One scene object equals one clip; do not claim a scene was submitted unless it appears in sceneGenerations.

generate_video_batch

Generate a WAV voiceover audio file from text using a Viewmax voice and return a stable R2 URL. The result includes a timing field (speechEndSeconds, tailSilenceSeconds, sentenceEnds, beatEnds) — the story workflow reads it as the timeline spine and passes it to lock_story_durations. durationSeconds includes trailing silence; timing.speechEndSeconds is where speech actually ends.

generate_voiceover

Check the status of a caption removal job. Returns status (processing/completed/error) and the result video URL when done.

get_caption_removal_status

Check the status of an add_captions render job. Returns progress percentage and the final video URL when done.

get_caption_render_status

Check the status of a compose_video render. Returns progress and the final assembled video URL when done.

get_compose_status

Return the authenticated Viewmax account's current credit balance. Only call when the user explicitly asks about their credits or balance.

get_credit_balance

Fetch status and final URLs for Viewmax image generation ids. Does not render a card - the generate_image result card updates itself.

get_image_generation_status

The Viewmax STORY WORKFLOW — the required pipeline for found-footage narrated story videos (animal stories, doorbell/CCTV/bodycam stories, "AI story video", story recreations). Call with phase "start" FIRST when the user wants a story video, then fetch the phase each step tells you to. Returns the instructions for that phase: start (entry + core rules + state), story (script + voice), storyboard (whole-film plan), continuity (camera medium + identity locks), model (model + duration lock), plates (reference frames), realism (anti-AI-look gates), prompts (master prompt templates), delivery (final compose + captions), failures (error recovery), contracts (T→V quick index). Free — reading instructions never charges credits. On ChatGPT, its render phases require one generate_video_batch call for all 2–8 masters.

get_story_workflow

Check the status of a video analysis job started by analyze_video. Returns the full analysis when complete, including recreationMethod and recreationGuide — read those before choosing a recreate workflow.

get_video_analysis_status

Fetch status and final URLs for Viewmax video generation ids. Does not render a card - the generate_video result card updates itself.

get_video_generation_status

List recent Viewmax image and video generations for recovery when a client loses generation ids.

list_generations

List Viewmax image and video models, capabilities, limits, and credit pricing. Use when the user asks about models or when you need to verify a model name, resolution, or capability. Do not call proactively before every generation - use defaults when possible.

list_supported_models

Show an interactive voice picker (built-in Viewmax voices with previews) and let the user choose. Call this when a voiceover/voice-change is requested without a clearly specified voice, then WAIT for the user to tap 'Use' on a voice before generating — do not pick a voice yourself or call generate_voiceover/change_voice until they choose. Do NOT list, enumerate, or describe the voices in your text reply — the picker already shows them all; reply with just one short line telling the user to pick one and tap Use.

list_voices

Story workflow gate (Phase M): partitions the voiceover timeline into N whole-second master durations that sum to the speech length, land cuts on sentence/beat ends, and fit the chosen model's allowed durations. Pass the timing fields from generate_voiceover's result plus beats (master count N) and the model's allowed durations (or just the model name to use the built-in fallback table when list_supported_models is unavailable). Omit both for non-manual-duration models — windows lock as free whole seconds and generation durations round UP into the model's set. If ok is false, follow suggestedBeats. Free and instant.

lock_story_durations

Story workflow gate (Phase S3): rewrites digits and symbols into speakable words (911 → nine one one, 2019 → twenty nineteen, 3:45 → three forty-five, $20 → twenty dollars, # → number). Run on the narration before generating the voiceover and use the returned normalizedText verbatim. Free and instant.

normalize_tts_text

LEGACY story pipeline — for NEW story videos use get_story_workflow (phase "start") instead; do not start new stories with this tool. Plans a multi-scene story video from an approved script with hex-coded consistency passes and one camera-prefixed Sora prompt per scene. Returns a planId and scenes[] — each with index, voiceoverText and prompt. To generate a planned scene's clip, call generate_video with storyPlanId=planId and sceneIndex=scene.index — NOT the prompt text (the server injects the exact planned prompt; retyping it drops the hex codes and breaks character consistency). Only use this to finish conversations that already hold a planId from it.

plan_story_scenes

Create a short-lived upload URL for a local image, video, or audio file that will be used as a Viewmax video-generation input. Local MCP/CLI clients should upload the file with PUT, then call complete_generation_input_upload.

prepare_generation_input_upload

Remove burned-in captions/subtitles from a video. IMPORTANT: Call select_caption_area FIRST so the user can visually pick the caption region. Model: TURBO (fast, good quality) or HD (slower, best quality). Defaults to TURBO. Pass the roi from select_caption_area.

remove_captions

Show the ad format picker widget. Call this FIRST when the user wants to create an ad but hasn't specified a format. The user picks a format (UGC Product, UGC Talking, Hyper Motion, etc.), then you call start_ad with that format. If the user already named a specific format, skip this and call start_ad directly.

select_ad_format

Opens an interactive widget where the user can see their video and drag a box around the captions to define the removal region. Call this BEFORE remove_captions so the user can visually select where the captions are. Pass the video URL (from upload_media_widget or a previous Viewmax result). The user will drag a box and click 'Remove Captions', which sends back the roi coordinates. Then call remove_captions with those coordinates.

select_caption_area

Opens an interactive widget showing animated preview cards of every caption style preset. Call this BEFORE add_captions so the user can visually pick a style instead of guessing a preset name. If the user has not provided a video yet, call upload_media_widget FIRST. The user taps a style and clicks 'Add Captions', which sends the chosen preset back; then call add_captions with that preset and the video URL.

select_caption_style

Open the interactive ad builder widget to create a marketing video ad. The user picks a product, avatar, voice, format, and writes a script, then taps 'Use' to hand the selections back. WAIT for the user to make their selections - do NOT call generate_ad until they tap 'Use'. If the user provides a product URL, pass it as productUrl - the product will be extracted, saved, and pre-selected in the widget.

start_ad

Upload an image or video file to Viewmax storage. Pass the file content as base64 in the `data` parameter. Returns a stable media.viewmax.io URL. Called internally by the upload widget - use upload_media_widget to open the interactive uploader.

upload_media

CALL THIS IMMEDIATELY when the user mentions uploading, sharing, or providing images/videos - even if they say 'I will upload' or 'I have images'. Do NOT plan, ask questions, or write prompts first. Open this widget FIRST, then discuss after they upload. The user drags and drops or browses for files. Uploaded URLs can be used as references in generate_video (referenceImageUrls, firstFrameUrls).

upload_media_widget

Story workflow gate (pre-delivery): validates the assembled story pack — voiceover + ordered masters + duration plan — before compose_video. Checks window math, contiguity, master ordering, narration overlap, visual variety, situation progression, prompt budgets, and the camera sightline laws (doorbell framing its own door, camera devices visible in frame). Fix every error and re-validate before composing. Free and instant.

validate_story_pack

Block until Viewmax image or video generations finish, fail, or time out, then return their final state as text. Does not render a card and does not start new work or spend credits - the generate_image/generate_video result card already updates itself. Only call this when chaining the output URL into another tool call in the same turn.

wait_for_generation