Skip to content

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.

fix: handle sandbox LLM empty outputs with structured fallbacks

Anil Matcha632e0dc94097
diff --git a/server/agents/character_extractor.py b/server/agents/character_extractor.py
index affa055..72b47b2 100644
--- a/server/agents/character_extractor.py
+++ b/server/agents/character_extractor.py
@@ -5,13 +5,30 @@ from typing import List
from interfaces.character import CharacterInScene
from 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.py
index 424aced..a6e89b3 100644
--- a/server/agents/screenwriter.py
+++ b/server/agents/screenwriter.py
@@ -4,13 +4,49 @@ from typing import List
from 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. Includ
Write 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.py
index 2fab9d7..cfce55d 100644
--- a/server/agents/storyboard_artist.py
+++ b/server/agents/storyboard_artist.py
@@ -6,6 +6,45 @@ from interfaces.character import CharacterInScene
from interfaces.shot import ShotBriefDescription
from 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.py
index 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 = 0
async 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')}")