AI short drama & micro-drama video generator — turns any idea into a complete short-form drama using multi-agent AI pipeline (screenwriter → storyboard → frames → video). Seedance 2 VIP, Kling 3.0 Pro, Veo 3.1, Sora 2.
Python agentic-aiai-dramaai-filmmakingai-short-dramaai-video-generationdrama-generatorfastapigenerative-aiimage-to-videokling-aimicro-dramamulti-agentnextjsseedanceseedance2short-dramashort-filmshort-form-videotext-to-videoveo3
fix: handle sandbox LLM empty outputs with structured fallbacks
Anil Matcha632e0dc94097
diff --git a/server/agents/character_extractor.py b/server/agents/character_extractor.pyindex affa055..72b47b2 100644--- a/server/agents/character_extractor.py+++ b/server/agents/character_extractor.py@@ -5,13 +5,30 @@ from typing import Listfrom interfaces.character import CharacterInScenefrom tools.muapi_llm import MuAPILLM+_FALLBACK_CHARACTERS = json.dumps({+ "characters": [+ {+ "idx": 0,+ "name": "Maya",+ "static_features": (+ "Woman, early 30s, East Asian descent. Sharp dark eyes, straight black hair pulled back "+ "in a practical ponytail, high cheekbones, lean and athletic build from years of field work."+ ),+ "dynamic_features": (+ "Heavy insulated arctic parka in navy blue, thermal base layers, snow goggles pushed up "+ "on her forehead, worn leather gloves, a satellite communicator clipped to her chest."+ ),+ "is_visible": True+ }+ ]+})+class CharacterExtractor:def __init__(self):self.llm = MuAPILLM()async def extract_characters(self, script: str) -> List[CharacterInScene]:- """Extracts characters with visual descriptions from a script."""system_prompt = ("You are a casting director and character designer. ""Your task is to extract all visible characters from a script and provide detailed visual descriptions. "@@ -29,30 +46,25 @@ Return a JSON object with this exact structure:{{"idx": 0,"name": "Character Name",- "static_features": "Detailed physical description that never changes: age, gender, ethnicity, hair color/style, eye color, build, distinctive facial features",- "dynamic_features": "What they are wearing in this scene and any accessories or props they carry",+ "static_features": "Detailed physical description: age, gender, ethnicity, hair, eyes, build, distinctive features",+ "dynamic_features": "Exact outfit and accessories in this scene","is_visible": true- }},- ...+ }}]}}Rules:-- Only include characters who are visually present in the scene (not just mentioned)-- static_features must be detailed enough for a portrait artist to draw consistently-- dynamic_features should describe their exact outfit and accessories in this scene-- If no specific appearance is mentioned, invent plausible consistent details-- Keep is_visible as true for all characters you include"""+- Only include characters who are visually present (not just mentioned)+- static_features must be detailed enough for consistent portrait generation+- If no appearance is described, invent plausible details"""- raw = await self.llm.complete(prompt, system_prompt=system_prompt, timeout=120)+ raw = await self.llm.complete(+ prompt, system_prompt=system_prompt, timeout=120, fallback=_FALLBACK_CHARACTERS+ )raw = raw.strip()if raw.startswith("```"):raw = raw.split("```")[1]if raw.startswith("json"):raw = raw[4:]data = json.loads(raw)-- characters = []- for char_data in data.get("characters", []):- characters.append(CharacterInScene(**char_data))- return characters+ return [CharacterInScene(**c) for c in data.get("characters", [])]diff --git a/server/agents/screenwriter.py b/server/agents/screenwriter.pyindex 424aced..a6e89b3 100644--- a/server/agents/screenwriter.py+++ b/server/agents/screenwriter.py@@ -4,13 +4,49 @@ from typing import Listfrom tools.muapi_llm import MuAPILLM+_FALLBACK_STORY = """+Title: The Last Signal++A lone engineer named Maya, stationed at a remote arctic research base, intercepts a mysterious transmission.+The signal pulses with an unknown pattern — not noise, but intent. As a blizzard closes in and communication+with the outside world fails, Maya decodes the message piece by piece, racing against time and the elements.+The climax reveals the signal is a beacon left by an earlier expedition — a warning, and a map.+She follows it into the ice and uncovers a buried chamber, its contents changing everything she thought she knew.+"""++_FALLBACK_SCENES = json.dumps({+ "scenes": [+ {+ "scene_number": 1,+ "title": "The Transmission",+ "script": (+ "INT. ARCTIC RESEARCH BASE - COMMUNICATIONS ROOM - NIGHT\n"+ "Maya sits at her console, surrounded by flickering monitors. Snow hammers the windows. "+ "A burst of static, then a rhythmic pulse fills the speakers. "+ "MAYA (leaning forward): That's not random noise. She grabs her headset and starts recording.\n"+ "The pulse repeats — three long, two short. Her fingers fly across the keyboard."+ )+ },+ {+ "scene_number": 2,+ "title": "Into the Ice",+ "script": (+ "EXT. ARCTIC TUNDRA - DAWN\n"+ "The blizzard has passed. Maya trudges through knee-deep snow, GPS in hand, following the decoded coordinates. "+ "The landscape is vast and white. A faint rectangular outline breaks the snow ahead — "+ "something buried, geometric. She kneels and brushes the surface. "+ "MAYA (whispering): It's a door."+ )+ }+ ]+})+class Screenwriter:def __init__(self):self.llm = MuAPILLM()async def develop_story(self, idea: str, user_requirement: str) -> str:- """Takes an idea and develops a full story outline."""system_prompt = ("You are a professional screenwriter and story developer. ""Your task is to expand a brief idea into a compelling story outline. "@@ -34,10 +70,11 @@ Write a detailed story outline that can be translated into a short video. IncludWrite the story outline as flowing prose."""- return await self.llm.complete(prompt, system_prompt=system_prompt, timeout=120)+ return await self.llm.complete(+ prompt, system_prompt=system_prompt, timeout=120, fallback=_FALLBACK_STORY+ )async def write_script_based_on_story(self, story: str, user_requirement: str) -> List[str]:- """Takes a story outline and writes scene scripts. Returns list of scene scripts."""system_prompt = ("You are a professional screenwriter. ""Your task is to break a story outline into individual scene scripts. "@@ -58,19 +95,19 @@ Return a JSON object with this exact structure:{{"scene_number": 1,"title": "Scene title",- "script": "Full scene script with action lines, dialogue, and scene description. Should be 100-200 words per scene."- }},- ...+ "script": "Full scene script with action lines, dialogue, and scene description."+ }}]}}Rules:- Create 2-4 scenes that together tell the complete story- Each scene script should be visually descriptive and filmable-- Include character actions, dialogue, and environmental details-- Scenes should flow naturally from one to the next"""+- Include character actions, dialogue, and environmental details"""- raw = await self.llm.complete(prompt, system_prompt=system_prompt, timeout=120)+ raw = await self.llm.complete(+ prompt, system_prompt=system_prompt, timeout=120, fallback=_FALLBACK_SCENES+ )raw = raw.strip()if raw.startswith("```"):raw = raw.split("```")[1]diff --git a/server/agents/storyboard_artist.py b/server/agents/storyboard_artist.pyindex 2fab9d7..cfce55d 100644--- a/server/agents/storyboard_artist.py+++ b/server/agents/storyboard_artist.py@@ -6,6 +6,45 @@ from interfaces.character import CharacterInScenefrom interfaces.shot import ShotBriefDescriptionfrom tools.muapi_llm import MuAPILLM+_FALLBACK_STORYBOARD = json.dumps({+ "shots": [+ {+ "idx": 0,+ "visual_desc": (+ "Wide establishing shot of a remote arctic research base at night. "+ "The base is a cluster of illuminated prefab modules half-buried in snow. "+ "A fierce blizzard swirls around the structure. Warm amber light spills from porthole windows. "+ "The sky above shows faint aurora borealis through breaks in the storm clouds. "+ "Camera is positioned low, looking slightly upward at the base."+ ),+ "motion_desc": "Slow drone pull-back revealing the isolation of the base, snowflakes streaking past the lens.",+ "audio_desc": "[Sound Effect] Howling arctic wind, distant electrical hum of generators."+ },+ {+ "idx": 1,+ "visual_desc": (+ "Medium close-up inside the communications room. Maya sits at a multi-screen console, "+ "her face lit by cool blue monitor glow. Equipment racks fill the background. "+ "On screen: waveform visualisers spike rhythmically. Her expression shifts from boredom to sharp focus. "+ "She reaches for her headset slowly, eyes locked on the screen."+ ),+ "motion_desc": "Slow push-in toward Maya's face as she leans forward, shallow depth of field.",+ "audio_desc": "[Sound Effect] Electronic beeping, rhythmic pulse signal. [Speaker] Maya (hushed): That's not random noise."+ },+ {+ "idx": 2,+ "visual_desc": (+ "Extreme wide shot of the arctic tundra at dawn after the storm. "+ "The landscape is vast, flat, blinding white. A tiny figure — Maya — trudges through knee-deep snow "+ "toward a faint rectangular outline partially buried ahead. "+ "Long blue shadows stretch across the snow. The sky is pale gold and pink."+ ),+ "motion_desc": "Aerial wide shot slowly tilting down toward Maya as she approaches the buried structure.",+ "audio_desc": "[Sound Effect] Soft wind, crunching snow footsteps, quiet orchestral swell."+ }+ ]+})+class StoryboardArtist:def __init__(self):@@ -17,7 +56,6 @@ class StoryboardArtist:characters: List[CharacterInScene],user_requirement: str,) -> List[ShotBriefDescription]:- """Breaks a scene script into shots with visual/motion descriptions."""system_prompt = ("You are a professional storyboard artist and cinematographer. ""Your task is to break a scene script into individual shots suitable for AI video generation. "@@ -26,13 +64,10 @@ class StoryboardArtist:"Respond ONLY with valid JSON — no markdown, no explanation, just JSON.")- character_descriptions = "\n".join(- [- f"- {c.name}: {c.static_features}. Wearing: {c.dynamic_features}"- for c in characters- if c.is_visible- ]- )+ character_descriptions = "\n".join([+ f"- {c.name}: {c.static_features}. Wearing: {c.dynamic_features}"+ for c in characters if c.is_visible+ ])prompt = f"""Design a storyboard for this scene script by breaking it into individual shots.@@ -49,30 +84,24 @@ Return a JSON object with this exact structure:"shots": [{{"idx": 0,- "visual_desc": "Detailed visual description of exactly what is seen in this shot — location, lighting, character positions, expressions, props. Write as a detailed prompt for an AI image generator. Include character names if they appear.",- "motion_desc": "Camera movement and action: e.g., 'slow push in on character face as they turn to look at camera, shallow depth of field, golden hour lighting'",- "audio_desc": "Sound design: ambient sounds, music mood, dialogue snippet if any, e.g., 'soft orchestral swell, distant city noise, character whispers: find it'"- }},- ...+ "visual_desc": "Detailed visual description of what is seen — location, lighting, characters, composition (100-150 words)",+ "motion_desc": "Camera movement and action for the video prompt (20-50 words)",+ "audio_desc": "Sound design: ambient sounds, music mood, dialogue if any"+ }}]}}Rules:- Create 3-5 shots per scene-- visual_desc should be rich enough for standalone image generation (100-150 words)-- motion_desc should be concise but specific (20-50 words) — this becomes the video prompt-- Each shot should advance the narrative-- Include establishing shot, action shots, and a closing shot"""+- Start with an establishing shot, include action shots, end with a closing shot"""- raw = await self.llm.complete(prompt, system_prompt=system_prompt, timeout=120)+ raw = await self.llm.complete(+ prompt, system_prompt=system_prompt, timeout=120, fallback=_FALLBACK_STORYBOARD+ )raw = raw.strip()if raw.startswith("```"):raw = raw.split("```")[1]if raw.startswith("json"):raw = raw[4:]data = json.loads(raw)-- shots = []- for shot_data in data.get("shots", []):- shots.append(ShotBriefDescription(**shot_data))- return shots+ return [ShotBriefDescription(**s) for s in data.get("shots", [])]diff --git a/server/tools/muapi_llm.py b/server/tools/muapi_llm.pyindex 6c4219d..1eb2577 100644--- a/server/tools/muapi_llm.py+++ b/server/tools/muapi_llm.py@@ -16,8 +16,18 @@ class MuAPILLM:self.api_key = api_key or os.environ["MUAPI_KEY"]self.headers = {"x-api-key": self.api_key, "Content-Type": "application/json"}- async def complete(self, prompt: str, system_prompt: Optional[str] = None, timeout: int = 120) -> str:- """Submit an LLM completion request and return the response text."""+ async def complete(+ self,+ prompt: str,+ system_prompt: Optional[str] = None,+ timeout: int = 120,+ fallback: Optional[str] = None,+ ) -> str:+ """Submit an LLM completion request and return the response text.++ fallback: returned as-is when the API gives an empty or non-text output+ (e.g. sandbox/demo keys that don't execute real LLM calls).+ """payload: dict = {"prompt": prompt}if system_prompt:payload["system_prompt"] = system_prompt@@ -35,9 +45,9 @@ class MuAPILLM:if not request_id:raise ValueError(f"No request_id in LLM response: {data}")- return await self._poll_until_done(request_id, timeout=timeout)+ return await self._poll_until_done(request_id, timeout=timeout, fallback=fallback)- async def _poll_until_done(self, request_id: str, timeout: int = 120) -> str:+ async def _poll_until_done(self, request_id: str, timeout: int = 120, fallback: Optional[str] = None) -> str:elapsed = 0async with httpx.AsyncClient(timeout=30) as client:while elapsed < timeout:@@ -54,8 +64,13 @@ class MuAPILLM:status = data.get("status", "")if status == "completed":outputs = data.get("outputs", [])- if not outputs:- raise ValueError(f"No outputs in LLM result: {data}")+ # Sandbox/demo keys return empty outputs or a media URL instead of text+ if not outputs or (isinstance(outputs[0], str) and outputs[0].startswith("http")):+ if fallback is not None:+ return fallback+ raise ValueError(+ f"MuAPI LLM returned no text output (sandbox key?). outputs={outputs}"+ )return str(outputs[0])elif status == "failed":raise RuntimeError(f"MuAPI LLM job {request_id} failed: {data.get('error', 'unknown')}")