Captions & On-Screen Text — Every Versely Caption Job

add_veed_captions

Add styled, auto-transcribed captions to a video using the VEED Subtitles model (fal.ai veed/subtitles). Burns aesthetic preset styles (Glass, Whisper, Fusion, Glide, etc.) — different from add_dynamic_captions, which is the word-level animated style. Use when the user wants polished social-ready captions with a chosen visual look, or asks for VEED captions specifically. Also offer this proactively as a finishing step after any video / movie / workflow run that produces video content. Two preset tiers: BASIC (1× credit cost, 21 presets — simple/plain/beans/corpo/etc.) and DYNAMIC (2× credit cost, 9 premium presets — glass/whisper/glide2/fusion/glide/terminal/handwritten/backdrop/backdrop2). Default to preset 'glass' for a modern look unless the user specifies a vibe. Supports 165 language codes for transcription (en-US, en-GB, es-ES, es-MX, fr-FR, de-DE, it-IT, pt-BR, ja-JP, ko-KR, zh, ar-SA, ru-RU, etc.).

list_caption_fonts

List all caption/overlay fonts from the app font registry (GET /fonts), grouped by category (sans-serif, serif, display, handwriting, monospace). Each entry has id, name, category, preview. Call this before setting font_id/font_family on caption tools so you never guess font names.

preview_caption_style

Render a SHORT sample (first few seconds) of a caption style on the user's OWN video — a cheap decision aid before full-captioning. Trims the first sample_seconds of video_url, then runs the matching caption path (dynamic / veed / static) on that short clip only. Use when the user is unsure which caption look they want: offer 1–2 styles to preview, then call this (do NOT auto-render every style). After they like a look, call add_dynamic_captions / add_veed_captions / add_video_captions on the FULL video. Fast and cheap vs full-captioning because the clip is short.

add_video_captions

Burn a fixed TEXT OVERLAY onto a standalone video — a hook line, headline, badge, CTA, quote or branded label that you supply. This is NOT a subtitle tool: it does not transcribe speech. For spoken-word subtitles use add_veed_captions. Call list_caption_fonts first when the user wants a specific font.

add_timestamped_captions

Burn TIMESTAMPED TEXT OVERLAYS onto a standalone video — you supply each line with its own `start_sec`/`end_sec`, so the text changes through the clip. NOT a subtitle tool: nothing is transcribed. For spoken-word subtitles use add_veed_captions.

set_brand_kit

Create or update the user's persistent brand kit (partial upsert — only the fields you pass are changed; omitted fields keep their current values). For colors and fonts objects, KEY-MERGE: provided keys override existing ones, absent keys are preserved (not a whole-object replace). Use when the user shares brand details (logo upload, 'our color is #FF5733', fonts, voice/tone, tagline, product shots, caption style, default aspect ratio) and wants them remembered for future content. Also OFFER this proactively when they describe brand details in conversation. After saving, the kit is auto-injected into context so subsequent generations/workflows apply it by default.

get_brand_kit

Fetch the user's full brand kit (colors, fonts, voice_tone, logo, product shots, caption style, default aspect ratio). Prefer the injected User Context brand block for routine reads; call this tool only when you need the complete/current kit after a write, or when the context block is missing fields you need.

clear_brand_kit_field

Clear a single field on the user's brand kit (set it to null). Use when the user says 'remove our logo', 'clear brand colors', etc. Does not delete the whole kit.

add_text_overlay

Add text overlays (captions, titles, quotes) to slideshow images. Use after creating a slideshow when the user wants text on the images. You can send 1 overlay to apply the same text/style to ALL images, or N overlays (matching image count) for different text per slide. The system auto-expands a single overlay to all images.

get_slideshow

MANDATORY TOOL for displaying a slideshow to the user. Calling this is the ONLY way the slideshow-card UI (with thumbnails) appears in the chat — describing the slideshow in text does NOT show the visual card. You MUST call this tool (not just describe in text) whenever the user asks to see, show, open, view, preview, display, pull up, or edit an existing slideshow — including phrases like 'show me my slideshow', 'show it to me', 'let me see it', 'pull up the last one', 'what's in my slideshow', 'the one I just made', 'add text to slide 2', 'edit the overlays'. Do NOT answer these requests from memory or conversation history. ALWAYS fetch fresh state with this tool. If slideshow_id is omitted, returns the user's most recently created slideshow. Also call this before add_text_overlay, convert_slideshow_to_video, remove_slideshow_slide, replace_slideshow_slide, or reorder_slideshow_slides when the user references an existing slideshow without giving you an id.

create_slideshow_caption_in_image

Create a slideshow where the caption is RENDERED INSIDE the image by an AI image model (text is baked into the picture, not stamped on top). Best when the user wants a single cohesive image — typography integrated with the scene — instead of a chat-style overlay. ASYNC: this tool RETURNS BEFORE the images are ready. It dispatches each slide to KIE (Nano Banana Pro by default, or GPT Image 2) and returns immediately with status='slideshow_generating' and a slideshow_id. Each slide completes via webhook over the next ~30–90 seconds. Tell the user 'your slideshow is being generated — ask to see it once it's ready' and use get_slideshow on the next turn to fetch the rendered images. Do NOT chain with create_slideshow, search_pinterest, image-gen tools, or add_text_overlay (that would double-render text).

convert_slideshow_to_video

Convert a slideshow into a video with transitions and optional audio. Use after creating a slideshow when user wants a video/reel version. The video is uploaded to cloud storage and the URL is returned.